clonetool

Block-level sync for a large file or block device between two machines (or two paths on the same machine), driven from a third, passive "manager" machine. Single static Go binary, no runtime dependencies beyond the system ssh client for remote endpoints.

How it works

• You run clonetool sync on the manager. Source, destination, and manager may be three entirely different machines — the manager never reads or writes a single block itself. It only spawns and talks to two control agents (clonetool agent --role control, one per side, local subprocess or over ssh) that do the stat/prepare/transfer work.
• The two agents compare content by SHA-256 hash per fixed-size block. A block is only re-read once: it's hashed from the buffer it was read into, and that same buffer is what gets sent on if it differs — never read twice.
• Bulk data goes directly between source and destination, not through the manager. Each run tries:
  1. push — the source agent connects straight to the destination host over SSH and streams changed blocks to it.
  2. pull (fallback) — if push isn't possible (no route/keys in that direction), the destination agent connects to the source host instead and pulls.
  3. If neither direction works, the job fails with both reasons named. Run the manager on the source or destination host, or set up SSH connectivity in at least one direction.
  • When source and destination are both local to the manager, no SSH is used at all — the source agent spawns the write-side helper as a plain local subprocess.
• Each named job keeps a hash table for the destination (~/.clonetool/jobs/<job>.state by default) so a re-run doesn't need to read the destination again — it just compares freshly-hashed source blocks against last known state. The destination must not be modified by anything else between syncs of the same job — that assumption is what lets the tool skip reading it. Running the same job against a different destination is refused (pass --force to deliberately rebind it, which discards the hash history).
• Sizing rules:
  • Destination is a block device: it can't be resized, so if the source is larger the job fails; otherwise exactly min(source, dest) bytes are synced and the remainder of the device is left untouched.
  • Destination is a regular file: it's truncated (created if missing) to exactly the source's size, growing or shrinking it. Shrinking an existing non-empty file prompts for confirmation unless --yes is passed.

Build

CGO_ENABLED=0 go build -o clonetool .

Copy the resulting binary to the manager, source, and destination hosts (same path, or point --remote-bin at wherever it lives on each host — clonetool does not deploy itself).

Usage

clonetool sync --job NAME --source LOC --dest LOC [options]

LOC is either a local path (/dev/sdb, ./image.bin) or [user@]host:path for a path reached over SSH.

# Same machine
clonetool sync --job disk1 --source /dev/sda --dest /dev/sdb

# Two remote machines, orchestrated from a third
clonetool sync --job backup --source db1:/dev/vdb --dest backup-host:/srv/db1.img

# Re-run any time; only changed blocks move
clonetool sync --job backup --source db1:/dev/vdb --dest backup-host:/srv/db1.img

Options:

Flag	Default	Meaning
--block-size	4M	Block size (accepts K/M/G suffixes). Changing it on an existing job discards its hash history.
--state-dir	~/.clonetool/jobs	Where job hash-tables live.
--yes	off	Don't prompt before shrinking an existing destination file.
--force	off	Rebind a job to a different source/dest, discarding its hash history.
--connect-timeout	8	SSH connect timeout (seconds) used for the push/pull direction probe.
--ssh	ssh	ssh binary to use.
--ssh-opt	—	Extra -o OPT passed to ssh (repeatable).
--remote-bin	clonetool	Path to clonetool on remote hosts.
--manager-host	local hostname	Address a peer should use to reach this machine, needed only when source or dest is local to the manager and the other side is remote and ends up needing to dial back in (pull fallback).

Caveats

• Block-device size detection (BLKGETSIZE64) is Linux-only.
• If a destination path doesn't exist yet, it's created as a regular file — clonetool won't create device nodes, so double-check device paths for typos before running.
• SSH host keys are accepted on first connect (StrictHostKeyChecking=accept-new) and rejected if they later change, same as normal SSH behavior.
• agent is an internal subcommand spawned automatically by sync; it's not meant to be run by hand, though it will work standalone for debugging.