Server Migration: What to Document First

Before a server migration, you should document your current environment, including hardware and software inventory, configuration files, network settings, application dependencies, data storage details, and any custom scripts or scheduled tasks. This documentation serves as both a roadmap for the migration and a baseline for verifying that the new server works exactly like the old one. Without it, you risk missing critical settings, breaking applications, or losing data during the transition.

Why Documentation Matters

Server migrations are high-risk operations because they involve moving many interdependent components. A single undocumented setting—like a custom firewall rule or a non-default database port—can cause hours of downtime or a security vulnerability. Documentation also protects you if the migration is interrupted: you can roll back to the original configuration with confidence. For teams, it ensures that knowledge isn’t locked in one person’s head, so any team member can execute or troubleshoot the migration.

What to Inventory: Hardware and Software

Start by listing every physical or virtual server involved, including the source, target, and any intermediary systems. For each server, record:

• Operating system and version (e.g., Ubuntu 22.04, Windows Server 2019)
• CPU, RAM, and disk space (both allocated and used)
• Network interfaces, IP addresses, MAC addresses, and DNS hostnames
• Installed software, including versions and license keys
• Virtualization platform (VMware, Hyper-V, KVM) and VM settings
• Storage layout: partitions, mount points, RAID levels, and LVM configurations

Use commands like dmidecode (Linux) or systeminfo (Windows) to capture hardware details, and dpkg -l or Get-WindowsFeature for installed software. For virtual machines, export the VM configuration file or note the settings in your hypervisor.

Configuration Files and Settings

Configuration files are the most common source of post-migration issues. Document the location and contents of every configuration file, even if you think they are default. Key ones include:

• Web server: Apache httpd.conf, Nginx nginx.conf, and site-specific vhost files
• Database: MySQL my.cnf, PostgreSQL postgresql.conf, and connection strings
• Application: .env files, application.properties, and any YAML/JSON config
• Network: /etc/network/interfaces, netplan, hosts, and resolv.conf
• Security: firewall rules (iptables, firewalld, Windows Firewall), SELinux/AppArmor policies, and SSH config

Copy these files to a secure location (e.g., a version-controlled repository) and note any differences from the default installation. Also document environment variables, cron jobs (use crontab -l), and systemd services with systemctl list-units.

Data and Storage Details

You need to know exactly what data exists, where it lives, and how it’s used. Document:

• Database names, sizes, and the location of data files
• File shares, mount points, and their permissions (use ls -lR or icacls)
• Backup schedules and locations (local, remote, cloud)
• Storage quotas and inode usage (Linux) or disk quotas (Windows)
• Any encryption at rest (LUKS, BitLocker) and where keys are stored

For databases, document the exact version and any custom collation or timezone settings. For file servers, note which folders are critical and which can be excluded from the migration to save time.

Network and Security Dependencies

Applications often depend on network services that are not on the server itself. Document:

• All open ports and the services listening on them (use netstat -tulpn or Get-NetTCPConnection)
• External dependencies: LDAP/AD, SMTP relays, API endpoints, or third-party services
• DNS records and TTLs for the server’s hostname
• SSL/TLS certificates, including expiration dates and where they are installed
• Firewall rules that allow inbound/outbound traffic, and any NAT rules

Create a diagram showing how the server connects to other systems. This helps you identify what needs to be updated after the migration (e.g., IP changes) and what must remain unchanged (e.g., external API keys).

Custom Scripts and Scheduled Tasks

Many servers run custom scripts for maintenance, monitoring, or data processing. These are often undocumented and easily forgotten. To find them, check:

• Cron jobs (/etc/crontab, /var/spool/cron/) and Windows Task Scheduler
• Shell scripts in /usr/local/bin, /opt, or custom directories
• Systemd timers (systemctl list-timers)
• Startup scripts (init.d, rc.local, Windows startup folder)

For each script, document what it does, when it runs, and what it depends on (e.g., a specific Python version or a database connection). Test these scripts on the new server before cutting over.

Testing and Rollback Plan

Documentation isn’t complete until you have a testing checklist and a rollback plan. Your testing checklist should include:

• All services start and respond to health checks
• Applications can connect to databases and external APIs
• File permissions and ownership are correct
• Scheduled tasks run without errors
• Logs show no unexpected errors

Your rollback plan should specify how to revert to the old server if something fails—for example, by changing DNS back or restoring a snapshot. Document the exact steps and who is responsible for each action.

Frequently Asked Questions

How long does a server migration take?

The time depends on the size of your data and the complexity of your configuration. A small web server with a few GB of data can be migrated in a few hours, while a large database with terabytes of data may take days. Most of the time is spent copying data, not configuring the new server, so use a high-speed network connection or seed the data in advance.

Should I document everything or just the essentials?

Document everything that is non-default. If a setting is the same as the default installation, you don’t need to write it down. But any custom port, path, or permission must be recorded. It’s better to have too much documentation than too little—you can always ignore redundant notes.

What is the most common mistake during a server migration?

The most common mistake is forgetting to move scheduled tasks or cron jobs. These often run silently, and you may not notice they are missing until a report doesn’t arrive or a backup fails. Always check for scheduled tasks on the old server and replicate them on the new one, including their environment variables.

Can I use automated tools to document my server?

Yes, tools like Ansible, Puppet, or even simple scripts can capture configuration files and package lists. However, they won’t capture everything—especially manual changes or interactive settings. Use automated tools as a starting point, then manually verify the output and fill in gaps.

What if I don’t have documentation and the migration is urgent?

If you must migrate without documentation, take a full snapshot of the old server first. This gives you a safety net. Then, on the new server, install the same OS and software versions, and copy over configuration files from the snapshot. Test thoroughly before cutting over, and be prepared to roll back to the snapshot if needed.

How do I verify that the new server is identical to the old one?

Compare the output of key commands on both servers, such as systemctl status, netstat -tulpn, and df -h. Also compare checksums of configuration files and run your application’s test suite. If you have monitoring tools, compare metrics like CPU, memory, and disk I/O before and after the migration.

Related

• Sell Gift Cards for Cash: Step-by-Step
• AI Agents vs Research Assistants: What Each Can Do
• Elden Ring Lore Before the Film: A Practical Catch-Up Guide

in t | Finish time | min | 50 | 0
in d | Distance | km | 10 | 0 | 100000
out pace | Average pace | min/km | t / d | 2
out speed | Average speed | km/h | d / (t / 60) | 2