Server migration

License required

Server migration needs the Live Migration license feature. Without it the Migrate page opens, and every action on it fails.

Move a game server to another node, files and all.

The panel copies the files across and starts the server on its new node. It keeps the old copy for a while, in case you need it back.

This page is about moving a game server. To move the panel itself to a new machine, read the Migration Guide.

How a move works

A migration is a stop, a copy, and a start. The panel drives all three steps and reports the progress.

You can also turn on Copy while the server runs. The panel then copies the server files one time with the server still up. After that copy, the panel stops the server and sends only the files that changed during the copy. The target node adds these files to the copy that is already there. Downtime becomes the time to send the changes, not the time to send the whole server.

Before the cut-over, the panel makes both nodes prove that they hold the same files. If the proof fails, the panel stops the migration and leaves the server where it is.

The panel does not offer live migration. A migrated server gets a new address on the target node, so players lose their connection at the cut-over in all cases.

Prerequisites

• Both nodes are Linux nodes. The Windows daemon cannot send or receive a migration.
• Both nodes show as Online, and neither node is in maintenance mode.
• The target node has free allocations, at least one for each allocation of the server.
• The target node has enough free disk space for the server.
• The migration function is on in the daemon configuration on both nodes (see below).
• The two nodes can reach each other on the transfer port (8444 by default).

The preflight check reads the operating system and the free disk space of both nodes. It stops the migration if the target node is not a Linux node, or if the target node has too little free space.

Turning it on

The daemon does not accept migrations until you turn the function on. The install script does not turn it on, because the migration function opens a port for node-to-node transfers.

Do these steps on the source node and on the target node.

1. Open /etc/badger-daemon/config.yaml in an editor.
2. Add this migration section:

migration:
  enabled: true
  listen_port: 8444
  temp_dir: "/var/lib/badger-daemon/migration"
  identity_dir: "/var/lib/badger-daemon/migration/identity"
  max_concurrent: 2
  timeout_hours: 4
  trash_retention_hours: 72

3. Open port 8444 in the firewall of the node, for the other node only.
4. Restart the daemon:

systemctl restart badger-daemon

Disk space: temp_dir needs room for the largest server on the node, two times over.

Keep listen_port at 8444. The panel uses port 8444 for node transfers unless a different port is recorded for the node.

Start a migration

1. Navigate to Admin > Servers.
2. Open the actions menu of the server, then click Migrate. The Migrate Server page opens.
3. Under Select Target Node, click the node that receives the server. The list shows every node except the current one, with the free allocations and the free memory of each node.
4. Under Migration Options, set the options for this migration (see the next section).
5. Under Preflight Check & Migrate, click Run Preflight Check.
6. Read the result. Migration is possible means that you can continue. Migration blocked lists the reasons under Blocking Issues.
7. If the check passes, click Start Migration.
8. In the confirmation, click Migrate.

You do not stop the server first. The panel stops it at the correct moment.

The right side of the page shows the current server details, the estimates, and the Allocation Mapping. The allocation mapping shows the new address of each port. A green row keeps the same port number. A yellow row shows Port/IP will change.

The options

Option	Default	Description
Copy while the server runs	Off	Copies the server with it still up, then stops it only long enough to send what changed. Downtime becomes minutes instead of the whole transfer. The copy reads the changed files two times, and the target node holds the server for longer before the cut-over.
Notify Users	On	Sends an email to the server owner. The mail gives the new address of the server after the move. Turn the option off for a move that your customer must not hear about.
Verification Period (hours)	4	How long the panel keeps the copy on the old node after the server runs on the new node. The value must be from 1 to 72.

The checks before it starts

The preflight check stops a migration that cannot succeed. The panel runs the same check again when you click Start Migration.

These are the common blocking issues:

Blocking issue	What to do
Source and target node are the same	Select a different target node.
Server is already being migrated	Wait for the migration in progress to end.
Cannot migrate server during installation	Wait for the installation to complete.
Server has active or locked backups	Wait for the backup to complete, or unlock it.
Target node is offline	Correct the connection of the target node.
Target node is in maintenance mode	Turn off maintenance mode on the target node.
Not enough available allocations	Add allocations to the target node.
Not enough free disk space on the target node	Free space on the target node, or select another node.
Target node is not a Linux node	Select a Linux node.
Target node has reached max concurrent incoming migrations	Wait for a migration into that node to end.

Warnings do not stop a migration. A suspended server stays suspended after the move. A large server can need administrator approval.

The Estimates panel gives a rough number only. The estimate comes from the disk limit of the server and the network path between the two nodes. Your real time can differ.

While it runs

The Migrate Server page replaces the form with a progress panel. The panel shows the current stage, a percentage, and the bytes sent.

You can leave the page. The migration continues, and the page shows the progress again when you return.

These are the stages, in order:

Stage	Meaning
Queued, waiting to start	The migration is in the queue.
Preparing the target node	The panel makes the target node ready.
Copying files with the server still running	The first copy runs. This stage happens only with Copy while the server runs.
Stopping the server	The server stops. Downtime starts here.
Copying files to the target node	The files go to the target node.
Restoring on the target node	The target node writes the files into place.
Starting the server on the target node	The server starts on the new node. Downtime ends here.
Checking the server came up	The panel makes sure that the server runs.
Running on the target, keeping the old copy for now	The verification period runs.
Removing the old copy	The old node deletes its copy.
Finished	The migration is complete.

The byte count starts at zero and stays there until the source node finishes packing the files. During the verification period, the panel shows when it removes the old copy.

Downtime

The server is down from Stopping the server to Starting the server on the target node.

• Without Copy while the server runs, the whole file transfer happens in that window. A large server on a slow link is down for a long time.
• With Copy while the server runs, only the files that changed during the first copy go across in that window. The downtime is usually a few minutes.

Players are disconnected in both cases, because the server address changes.

What moves, and what does not

The panel copies the server data directory. It leaves out these paths:

logs/, *.log, crash-reports/, world_backup/, .cache, .tmp, .git/, node_modules/, __pycache__/

If you keep data in world_backup/, copy it yourself before the migration.

Backups that live on the local disk of the source node do not move. Move them to shared backup storage first, or accept the loss.

After the migration

• The server belongs to the target node.
• The server gets new allocations on the target node. The panel keeps the same port numbers when the target node has them free. The IP address changes.
• Give the new address to the players. The old address does not work. If you point a DNS record at the old node, change that record.
• Databases, schedules, subusers, and the owner of the server do not change. A database on a host that only the old node can reach stops working.
• The copy on the old node stays until the verification period ends. The old node then removes the container and moves the files aside.
• The old node deletes the files that it moved aside 72 hours later. The trash_retention_hours setting controls this time.

When a move fails

The panel shows the error message and the stage that failed, as Failed while: [stage].

The result depends on when the failure happened:

• Before the cut-over. The server stays on the original node, and the panel starts it again. The files on the old node are untouched.
• After the cut-over. The server is on the target node. The copy on the old node stays for the verification period.

A failed migration is final. To try again, start a new migration.

The panel retries a transfer that stops partway. A transfer that starts again continues from the point that it reached, so a long transfer does not start from zero. The panel abandons a transfer that makes no progress for 30 minutes, and it abandons any migration that runs for more than 48 hours.

WARNING

Do not delete the source node during the verification period. The copy on that node is what makes a bad migration recoverable.

Cancel and rollback

Two actions sit on the progress panel of a migration that runs:

Action	When it works
Cancel	Before the server starts on the target node.
Rollback	While the panel checks the server, and during the verification period.

A cancel stops the transfer and starts the server again on the old node. A rollback stops the server on the target node, starts it on the old node, and deletes the target copy.

A rollback is not possible after the panel removes the source copy.

Limits

Limit	Default
Migrations for one user in one day	10
Migrations at the same time for one user	2
Migrations into one node at the same time	2
Migrations on one daemon at the same time (in and out)	2
Wait time before you migrate the same server again	30 minutes
Time the panel waits for the server to come up on the target node	10 minutes
Age limit of a first copy before the second round refuses	24 hours
Whole-migration time limit	48 hours

Next steps

• Server Management - day-to-day server tasks
• Allocations - add ports to the target node
• Daemon Configuration - the full daemon configuration reference