Every option, in one place

The command line

reloca.to [-n] [-y] [-i KEYFILE] [-d DISK] [-s STEP] [-o key=value]… [DONOR]. DONOR is [root@]host[:port] of the old server: in the Live OS for an off-line move, or running its own system for an on-line one. The mode is detected from the answer.

Flag	What it does
-n, --dry-run	Print every command, change nothing — on either machine. State goes to /run/reloca.to/dry/, so a real run afterwards starts clean.
-y, --yes	Answer yes to every question, including the one that asks you to type the disk name. For scripts; without a terminal and without -y any question is a refusal.
-i KEYFILE, --key	The ssh key for the old server. Without it the tool makes a session key and asks for the password once.
-d DISK, --disk	The target disk on this machine when it has several: /dev/sda, /dev/nvme0n1, /dev/disk/by-id/…. Two disks separated by a comma with -o raid=1.
-s STEP, --step	Run one phase instead of the whole migration. Phases are idempotent: finished work is skipped.
-o key=value, --option	The options below, one -o each. An unknown key is refused, so a typo cannot quietly do nothing, and so is a line that joins two options with a comma.
-V, --version	The version of the tool, the library path and the build id of the Live it runs on.
-h, --help	The same reference, in the terminal.

Phases you can run on their own

Without -s the tool runs them in this order and asks twice: before the first write and before the cutover. With -s it runs one, which is how you retry a phase or inspect the plan before anything happens.

Phase	What it does
plan DONOR	Read-only: inventory both machines, write /run/reloca.to/plan, print the summary. Nothing is written to either disk.
check [PLAN]	Validate a plan you have edited by hand, and refuse it with a reason if it cannot work.
apply	Partition, LVM, swap, mkfs on this machine, after you have read what is on the disk and typed its name and size.
transfer	Copy the volumes: off-line with partclone and tar, on-line with reloca-agent in passes under load.
postfix [ROOT]	In a chroot on the copy: fstab, mdadm, initramfs with the new drivers, grub, the network. Every edit is logged as a diff.
verify [ROOT]	Dozens of checks that the copy will boot: boot entry, initramfs, cmdline, fstab, network. Exit 3 means do not reboot yet.
cutover	The switch itself: the old server leaves the network, the new one comes up as the migrated system.
inventory [DONOR]	The raw records of this machine, or of the donor: what the plan is built from.
attach	Back into the running tmux session after a dropped ssh, or a tail of the log when there is none.
cleanup	Undo what the tool left behind: mounts, activated volume groups, read-only marks, snapshots of a pre-check.

Options

-o key=value, repeated for every key you set: -o compress=none -o patience=600. A comma belongs to the value (driver=mod1,mod2, console=ttyS0,115200), so options are never joined by one, and a line that tries to is refused. The default is in bold; a key with no default does nothing until you set it. “on-line” and “off-line” mark the keys that belong to one mode only.

Option	Values	What it does
Mode, channel and compression
mode=	detected | online | offline	Which mode to use instead of letting the tool detect it. The donor answers either from the Live OS (off-line relocation) or from its own running system (on-line relocation).
compress=	auto | zstd[:LEVEL] | lz4 | none	On-line: every data frame is compressed on the donor, and auto picks the level (1 to 7) from the donor cpu and link rate it measures as it copies. Off-line: the stream compressor, lz4 by default. none for a 10 GbE link, where one core cannot compress as fast as the wire carries.
cipher=	aes128-gcm@openssh.com | chacha20-poly1305@openssh.com	Cipher of the data channel. chacha20 is for a cpu without AES-NI, where it is the faster of the two.
data=off-line	ssh | raw	The data channel of an off-line move: a second sshd on the donor, or busybox nc under a watchdog for a trusted link where encryption is the bottleneck.
sshd-port=off-line	2222	Port of the data sshd on the donor, when 2222 is already taken there.
watchdog=off-line	15 min	Minutes without progress on a data=raw volume before it is killed and retried: an nc stream has nothing of its own to notice a dead peer with.
Layout on the new server
root=	auto | block | files	How the root filesystem travels: block by block when it fits the new disk, or file by file into a freshly made filesystem. auto decides by size.
label=	auto | gpt | dos	Partition table of the new disk. auto follows the donor, and turns dos into gpt above 2 TiB or under UEFI.
raid=	1	Two identical disks in the new server become md RAID1 pairs, slot by slot, with grub and the ESP on both. -d /dev/sda,/dev/sdb names them; with exactly two candidates the pair is taken by itself.
fsck=	quick | full	After a block copy: a read-only check of the copy (e2fsck -n, xfs_repair -n), or a full e2fsck -f on the volumes that were not changed.
redo=	N	How many times a failed volume is restarted: a block volume from zero, a file volume after a fresh mkfs.
boot-part=	SIZE	Ask for a separate /boot slot of this size at the start of the disk, for a BIOS target above 2 TiB whose donor has none. Not implemented yet: the plan phase refuses it and says so.
On-line relocation
chunk=on-line	64K	Granularity of the write tracker, a power of two. Smaller means less data re-sent in the next pass and a larger bitmap in the donor's memory.
tracker=on-line	auto | bpf | ftrace	How writes are watched on the donor: an eBPF program on the block layer's tracepoint, or ftrace where the kernel is too old for it (CentOS 7). auto tries bpf and falls back.
converge=on-line	10 s	The freeze you are asking for: the agent keeps re-sending deltas until the one still pending would take this many seconds or less at the rate it has measured, and freezes then.
passes=on-line	8	Delta passes at most. The agent raises this limit by itself when its measurements say a few more passes would reach the window you asked for and fit the patience budget.
patience=on-line	1800 s	How much extra copying is worth a shorter freeze. The agent measures how fast the donor writes and how fast the link carries, prints how many passes and minutes a shorter freeze would cost, and stops at this budget instead of copying all night.
max-est=on-line	100 s	The longest freeze this run may take when the deltas stop shrinking: at or below the estimate it freezes anyway, above it the run refuses, nothing is frozen and the donor is left untouched.
precheck=on-line	1 | 0	Before the real cutover: freeze, take a snapshot of the copy, thaw the donor, and run the fix-up and the verify on that snapshot while the donor serves on. Only then catch up and freeze for real. Costs one extra delta pass and finds a target that would not boot while you still have both machines.
precheck-dir=on-line	/var/tmp/reloca.to	Where the pre-check keeps the copy-on-write files of its snapshots.
precheck-cow=on-line	2G	Copy-on-write space per volume for the pre-check snapshots: it has to hold everything the fix-up writes into the copy.
verify-hash=on-line	1	With the donor frozen, read every volume on both sides again and compare sha256. The strongest check there is, and it costs a full read of both.
stall=on-line	300 s	Complete silence from the donor for this long counts as a wedged path: the transfer fails with a message instead of hanging until morning. 0 never gives up.
settle=on-line	1000 ms	After each epoch of the tracker is closed, wait at least this long for the writes already in flight, so a block that was queued before the flip lands in the right pass.
cutover-port=on-line	2223	The port on the new server that the frozen donor polls for its last instruction. The donor connects outward, so nothing has to log in to a server whose filesystems are frozen.
The migrated system: boot and network
nic=	eth0	The name the main interface gets on the new server. The migrated system is pinned to it, so its network configuration keeps working whatever the new card is called.
donor-nic=	IFACE	Which interface of the old server to treat as the main one, when the inventory cannot tell. By default it is the one with the default route.
nic-pin=	1 | 0	Write a udev rule that pins eth0 to the MAC of the new server's boot interface. Turn it off for a target whose MAC will change again, such as a VM you are about to clone.
driver=	MOD[,MOD]	Extra modules for the initramfs of the migrated system, when autodetection from the new hardware's modalias is not enough to reach the root.
console=	ttyS0,115200	Add a serial console to the kernel command line of the migrated system, so a server with a BMC or a serial port can be watched as it boots.
bootorder=	pxe | local	UEFI only: leave PXE first in the new server's NVRAM (the way it boots the Live, so a second attempt is always possible) or put the disk first.
cloudinit=	disable | keep	A donor installed from a cloud image has cloud-init, which would rewrite the network on first boot and could rename the host. disable turns off only its network config and hostname handling; keep leaves it alone.
Cutover and guards
cutover=	netdown | poweroff | kexec | none	What the last phase does. netdown takes the donor off the network and reboots the new server into the migrated system; poweroff shuts the donor down instead; kexec starts the migrated kernel without a firmware pass; none leaves both machines as they are and prints what you would do by hand.
expect=	SERIAL | MAC	The donor must have this DMI serial or this boot MAC, or the run stops before it touches anything. The guard against pointing the tool at the wrong machine.
force=	1	Skip two refusals: “the inventory changed since the plan” and “this target is already migrated”. Both exist to stop a half-finished run from writing over a finished one.
offline=	1	Work without apt, on a Live that cannot reach a mirror: a documented degradation, where XFS off-line is refused outright and tmux and pv are not there.
raw=	DIR	-s inventory only: write the raw inventory files into this directory. This is how the test fixtures of the tool are made.

Exit codes

What the shell gets back. Code 3 is the one that matters: the disk is written, so fix the cause and re-run the verify instead of rebooting.

Code	Meaning
0	done
1	runtime failure, see /run/reloca.to/log
2	environment: not the full Live, apt or ssh failed, the donor is this very machine
3	verify failed: the disk is written, do not reboot; fix and re-run -s verify
4	the plan is infeasible or an edited plan was rejected; nothing was written

Anything missing or unclear here is a bug in this page. Write to us and we will fix it.

Back to the main page