Debian 13 Tutorial / Migrate a Service to a New Debian Server and Verify Cutover and Rollback
When migrating services to a new Debian server, you should first prepare the runtime environment and accounts, then restore the final backup taken while writes were stopped, and finally compare the functionality and data. Migration is not completed just by switching access, and you must decide how to preserve any data generated on the new server in order to safely revert to the original server.
Define the Migration Scope and Identify Each Server
This exercise migrates a small read-only HTTP service made with Python between two Debian 13 virtual machines (VMs). It provides the program, data, and systemd unit, and only responds on 127.0.0.1:8085. As described in the Python http.server documentation, this is not an example for use as an internet-facing production server. Database schema migration, actual Domain Name System (DNS) changes and external Transport Layer Security (TLS) transitions are not included in this exercise.
| Roles | Exercise connection | What to check |
|---|---|---|
| Source old-server | Host 127.0.0.1:22212 → Original VM SSH | Reference response, final backup, stop and restart |
| Target new-server | Host 127.0.0.1:22213 → Target VM SSH | Dedicated account · Restoration · Service response · Restart |
| Work computer | SSH/SCP that individually verifies the host keys of the two servers | Backup transfer, hash comparison, selecting the connection target |
Even if the same 10.0.2.15 address appears inside the two VMs using Network Address Translation (NAT), they are not the same server. In this example, different host loopback ports were connected via VirtualBox Network → NAT → Advanced → Port Forwarding. Replace with your actual server address and port, and separately verify the identity and host key of each server. During the exercise, the target VM's boot was stalled, so it was restarted after a normal ACPI shutdown, and restoration was carried out only after confirming that the target could successfully connect.
On the work Linux computer, you can set an alias like the following on ~/.ssh/config. Replace the private key path with your own, and do not copy passwords or private key contents into text or logs.
Host old-server
HostName 127.0.0.1
Port 22212
User lfstudent
IdentityFile ~/.ssh/id_ed25519
Host new-server
HostName 127.0.0.1
Port 22213
User lfstudent
IdentityFile ~/.ssh/id_ed25519
Each server requires Python 3, curl, and tar. If not installed, prepare them with sudo apt install python3 curl tar, and install SSH and SCP clients on the work computer. The original example below assumes the existing lfstudent account with user ID (UID) and group ID (GID) 1000 from the tutorial. If using a different account, also change the User and Group and ownership specifications. Use a new practice environment that does not overwrite existing directories or services with the same name.
Create the Complete Source Service and Back Up While Stopped
Execute on the source server. This block creates programs, data, and units, compares the responses, and then stops the service. When the last tar is created, the data reading process of this example is also in a stopped state. Other services or existing upgrade practice files are not targeted.
sudo bash <<'ROOT'
set -euo pipefail
for p in /opt/lf-migrate35 /var/lib/lf-migrate35 /var/backups/lf-migrate35 /etc/systemd/system/lf-migrate35.service; do test ! -e "$p"; done
test "$(id -u lfstudent)" = 1000
test -z "$(ss -H -ltn 'sport = :8085')"
install -d -m 755 /opt/lf-migrate35
install -d -m 750 -o lfstudent -g lfstudent /var/lib/lf-migrate35
install -d -m 700 /var/backups/lf-migrate35
cat > /opt/lf-migrate35/app.py <<'PY'
from http.server import BaseHTTPRequestHandler, HTTPServer
from pathlib import Path
class Handler(BaseHTTPRequestHandler):
def do_GET(self):
if self.path != '/':
self.send_error(404)
return
try:
body = Path('/var/lib/lf-migrate35/message.txt').read_bytes()
status = 200
except OSError:
body = b'data unavailable\n'
status = 503
self.send_response(status)
self.send_header('Content-Type', 'text/plain; charset=utf-8')
self.send_header('Content-Length', str(len(body)))
self.end_headers()
self.wfile.write(body)
HTTPServer(('127.0.0.1', 8085), Handler).serve_forever()
PY
cat > /etc/systemd/system/lf-migrate35.service <<'UNIT'
[Unit]
Description=LF migration lab 35
After=network.target
[Service]
Type=exec
User=lfstudent
Group=lfstudent
ExecStart=/usr/bin/python3 /opt/lf-migrate35/app.py
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target
UNIT
printf 'migration payload 35\n' > /var/lib/lf-migrate35/message.txt
chown lfstudent:lfstudent /var/lib/lf-migrate35/message.txt
chmod 640 /var/lib/lf-migrate35/message.txt
systemctl daemon-reload
systemctl enable --now lf-migrate35.service
sleep .4
curl -fsS http://127.0.0.1:8085/ > /var/backups/lf-migrate35/before.txt
cmp /var/lib/lf-migrate35/message.txt /var/backups/lf-migrate35/before.txt
systemctl stop lf-migrate35.service
tar --numeric-owner -cpf /var/backups/lf-migrate35/service.tar -C / opt/lf-migrate35 var/lib/lf-migrate35 etc/systemd/system/lf-migrate35.service
cd /var/backups/lf-migrate35
sha256sum service.tar > service.sha256
sha256sum -c service.sha256
echo SOURCE_STOPPED_FINAL_SAMPLE_BACKUP_READY
ROOT
If the brief startup delay is insufficient and curl fails, inspect sudo systemctl status lf-migrate35.service and sudo journalctl -u lf-migrate35.service -n 30. Check paths, ownership and port conflicts, then retry the failed request and comparison after readiness. Do not rerun the creation block over partially created resources or create the final archive before stopping the source. Ensure local curl requests bypass any configured proxy.
The expected result is service.tar: OK and a backup preparation message. The normal response is a single line migration payload 35. If there is no data or it is unreadable, this service returns 503, and it does not reveal file lists or read other paths.
For actual database or file upload services, you need to judge whether stopping just one process is sufficient. Stop batch jobs, queue consumers, writes on other servers, or use the product’s consistent dump or online backup methods. If you resynchronize the final changes after the initial bulk copy, record the two points in time and the write stop intervals.
Transfer the Backup Through the Workstation
Run the export block on the source server as lfstudent. Stop if the export directory already exists or any copy fails. On the workstation, stop if mkdir migration35, checksum verification or target import-directory creation fails; do not let later scp commands reuse an older directory.
Copy only the two example archive files you just created, without exposing the source’s root-only backup, to a dedicated directory for the practice account. For actual service backups, apply separate encryption and storage policies depending on whether they contain confidential information.
test ! -e "$HOME/lf-migrate35-export"
install -d -m 700 "$HOME/lf-migrate35-export"
sudo install -m 600 -o "$(id -un)" -g "$(id -gn)" /var/backups/lf-migrate35/service.tar /var/backups/lf-migrate35/service.sha256 "$HOME/lf-migrate35-export/"
Run on the Linux workstation. Confirm the SSH aliases point to the intended servers, then receive the files in a new dedicated local directory.
ssh old-server hostname
ssh new-server hostname
mkdir -m 700 migration35
scp old-server:lf-migrate35-export/service.tar old-server:lf-migrate35-export/service.sha256 migration35/
cd migration35
sha256sum -c service.sha256
tar -tvf service.tar
ssh new-server 'test ! -e "$HOME/lf-migrate35-import" && install -d -m 700 "$HOME/lf-migrate35-import"'
scp service.tar service.sha256 new-server:lf-migrate35-import/
The hash must match, and the list should only include opt/lf-migrate35, var/lib/lf-migrate35, and the relevant service unit. Grant restore permissions only to trusted archives you have created, and stop if there are absolute paths, upward path movements, or unexpected links. The checksum is for verifying damage during transfer and does not replace source trust. SCP options and transfer methods can be found in OpenSSH scp manual.
Restore to the target with a dedicated account
Run on the target server. First confirm /opt/lf-migrate35, /var/lib/lf-migrate35, /var/backups/lf-migrate35 and /etc/systemd/system/lf-migrate35.service are absent and getent passwd lf-migrate35 finds no existing account. If sudo ss -ltn shows port8085 is occupied, stop and investigate.
All preceding target absence checks are mandatory: the restore block assumes they passed. Also confirm getent group lf-migrate35 finds no existing group. The import path assumes the login account home is /home/lfstudent; replace it consistently if yours differs. The final UID-not-1000 assertion demonstrates differing IDs in this lab; successful production mapping is defined by the intended target identity, not a universally required number difference.
It extracts to the staging directory and installs the necessary files, so it does not completely overwrite the original service unit on the target /etc. Instead of copying the original numeric UID, it resets data ownership to the dedicated account name of the target.
sudo bash <<'ROOT'
set -euo pipefail
install -d -m 700 /var/backups/lf-migrate35
mv -- /home/lfstudent/lf-migrate35-import/service.tar /home/lfstudent/lf-migrate35-import/service.sha256 /var/backups/lf-migrate35/
rmdir /home/lfstudent/lf-migrate35-import
chown root:root /var/backups/lf-migrate35/service.tar /var/backups/lf-migrate35/service.sha256
chmod 600 /var/backups/lf-migrate35/service.tar /var/backups/lf-migrate35/service.sha256
cd /var/backups/lf-migrate35
sha256sum -c service.sha256
mkdir -m 700 staging
tar -xpf service.tar -C staging
useradd --system --user-group --home-dir /var/lib/lf-migrate35 --no-create-home --shell /usr/sbin/nologin lf-migrate35
install -d -m 755 /opt/lf-migrate35
install -m 644 staging/opt/lf-migrate35/app.py /opt/lf-migrate35/app.py
install -d -m 750 -o lf-migrate35 -g lf-migrate35 /var/lib/lf-migrate35
install -m 640 -o lf-migrate35 -g lf-migrate35 staging/var/lib/lf-migrate35/message.txt /var/lib/lf-migrate35/message.txt
cat > /etc/systemd/system/lf-migrate35.service <<'UNIT'
[Unit]
Description=LF migration lab 35
After=network.target
[Service]
Type=exec
User=lf-migrate35
Group=lf-migrate35
ExecStart=/usr/bin/python3 /opt/lf-migrate35/app.py
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target
UNIT
systemctl daemon-reload
systemctl enable --now lf-migrate35.service
sleep .4
curl -fsS http://127.0.0.1:8085/ > after.txt
cmp after.txt staging/var/lib/lf-migrate35/message.txt
cmp /opt/lf-migrate35/app.py staging/opt/lf-migrate35/app.py
test "$(stat -c %U /var/lib/lf-migrate35/message.txt)" = lf-migrate35
test "$(id -u lf-migrate35)" != 1000
id lf-migrate35
stat -c '%U:%G:%a' /var/lib/lf-migrate35/message.txt
systemctl show lf-migrate35.service -p User -p Group -p NoNewPrivileges -p ProtectSystem -p MainPID
systemctl restart lf-migrate35.service
sleep .3
curl -fsS http://127.0.0.1:8085/ | cmp - after.txt
echo TARGET_RESTORED_BY_ACCOUNT_NAME_BYTES_AND_RESTART_PASSED
ROOT
The original data owner of the verification VM was UID 1000, and the target dedicated account was UID and GID 988. Data permissions were set to lf-migrate35:lf-migrate35:640, and code bytes, HTTP responses, and responses after service restart were the same. NoNewPrivileges and read-only system protection are limitations of this example according to systemd runtime environment settings . Applying the same unit directly to a write service can block the necessary data writing as well, so permissions should be designed separately for each path.
In actual applications, runtime versions, extension modules, DB clients, environment variables, certificates, and upload paths are also compared. Do not assume that file formats and behaviors are identical just because the OS version is the same; execute the verification tools and feature requests supported by the product on the target.
Test Cutover, Rollback and Cutover Again
Currently, the original service is stopped and the target service is responding. On the working computer, use the variable for selecting the connection target to check reading. This is for selecting the SSH destination and is not an operation that changes DNS, load balancer, or public web addresses.
active=new-server
ssh "$active" 'curl --noproxy "*" -fsS http://127.0.0.1:8085/'
- Execute
sudo systemctl stop lf-migrate35.serviceon the target. - Execute
sudo systemctl start lf-migrate35.serviceon the original. - On the working computer, perform reading on the original as shown below and check if the response is the same.
active=old-server
ssh "$active" 'curl --noproxy "*" -fsS http://127.0.0.1:8085/'
To switch to the target again, first stop the source, then start the target service and verify with active=new-server. We compared all responses of target restore/restart on both VMs, source rollback, and target switchover against the reference file. This small service is read-only, so it does not reflect a scenario where new write conflicts occur after the switch.
Additional decisions to be made before an actual production switch
| Item | Judgment Criteria |
|---|---|
| DNS and load balancer | Take the current cache, existing connections, health checks, and propagation delays into account. Lowering the DNS time to live (TTL) alone does not immediately route all requests. |
| Resuming writes and rollback | Before final synchronization, block writes to the source and determine whether the data generated in the target can be reapplied to the source. Avoid a simple rollback if the schema is not backward-compatible. |
| Scheduled tasks, email, queue | If both servers run simultaneously, activate only one for tasks that would otherwise be duplicated. Verify separately from the web request switch. |
| Success Judgment | Compare the process, port, response, data, main functions, and error rates individually. Successfully reading alone does not count as normal writing. |
Set the rollback window and retention period before removing the source or backups. See the Debian GNU tar manual for numeric ownership and extraction behavior, and follow product-specific official procedures for databases or major-version data migration.
Clean Up Only the Lab Resources
After verification, clean up only the lab resources you created on each server. Stop and disable the service, delete the exact three files and remove only empty directories. Retain backups and preserve the source server's existing lfstudent account.
sudo systemctl disable --now lf-migrate35.service
sudo rm -- /etc/systemd/system/lf-migrate35.service /opt/lf-migrate35/app.py /var/lib/lf-migrate35/message.txt
sudo rmdir /opt/lf-migrate35 /var/lib/lf-migrate35
sudo systemctl daemon-reload
On the target, remove the newly created dedicated account with sudo userdel lf-migrate35 only after its processes have ended and its lab data has been removed. Apply your retention policy to the two exact transfer files on the source and workstation. For a production migration, retain the verified final backup and cutover records until the recovery window ends.




