Borg Backup Migration Guide for Moving a Repository to New Storage

The safe approach is to treat quiesce writers, copy or transfer by version-appropriate method, verify the destination, and cut over with rollback as a sequence of observable gates, not a single command.

On a BorgBackup repository on local, NAS, or SSH-accessible storage, the practical risk is need to move a Borg repository without creating a split or silently incomplete copy. Record the current identity and recovery point, start with the least invasive discriminator, interpret pass and fail results before changing another variable, and stop when storage becomes unstable or the only recoverable copy would be exposed. The workflow below ends only after the original workload succeeds or the evidence reaches an escalation boundary.

Record the repository contract before copying

Save the Borg version, repository URL, repository ID, encryption mode, key location, passphrase recovery process, archive list, size, free space, append-only settings, and every client or automation job that can write. The repository is not recoverable from a local cache alone, and encrypted repositories may depend on key material stored outside the target.

The ZimaSpace article on a lost Borg cache recovery guide separates rebuildable cache state from missing keys or repository damage. Use that check before migration so a key problem is not discovered only after the old storage is gone.

Choose whether this is a byte-for-byte relocation of the same repository or a transfer into a newly initialized repository. Borg version and format decide which methods exist; do not mix Borg 1 and Borg 2 command examples or assume repository identity should change.

Quiesce writers and create a consistent source point

Disable timers, cron jobs, containers, and remote clients, then confirm no Borg process or repository lock is active. Run borg list and an appropriate borg check before copying. If the source fails check, preserve it and diagnose that condition rather than cloning uncertainty into the destination.

A Super User discussion highlights the risk of using copying a live repository with rsync while a deduplicated Borg repository changes. The safe rule is to copy a quiesced repository, or use a filesystem snapshot taken after all Borg writers stop, so indexes, segments, nonce state, and data belong to one point.

Keep backup schedules off until destination validation finishes. If downtime is too long, make an initial copy while the repository is idle, stop writers, then run a final synchronization; never allow source and destination to accept independent backups during cutover.

Copy with the method your Borg version supports

For a same-repository relocation, preserve all files, permissions, sparse-file behavior, and ownership with a suitable local or remote copy tool, and inspect its error log. Copy the repository root as a unit, not selected archives or apparently large data directories. Keep the source untouched after the final sync.

For a new repository or format migration, use the transfer capability only when it is supported by the installed Borg versions and encryption plan. A Server Fault answer describes Borg repository transfer as the repository-to-repository direction associated with Borg 2, which is not interchangeable with a Borg 1 filesystem copy.

After copying, mount or expose the destination read-only to clients at first. If repository ID, key access, permissions, or format are unexpected, stop and correct the destination; do not “initialize” over copied data or run repair to force recognition.

-15% OFF

ZimaBoard 2 - Mini Home Server for Your Big Idea

Single board computer zimaboard2

$339.00 - $519.00

Buy Now

Verify archives, cut over clients, and retain rollback

Run Borg list, info, and the appropriate repository and archive checks at the destination. Extract canary files from a recent archive and an older archive to a separate directory, then compare contents, metadata, and permissions. Test with the same Borg binary and remote path that automation will use.

Update one client to the new URL, clear or rebuild only the cache state that Borg identifies as necessary, and create a small test archive. Restore from that archive and confirm pruning or compact scheduling remains disabled until all clients use the new location.

Cutover passes when archive inventory matches, checks pass, two restores are usable, and a new backup succeeds after reboot or scheduler restart. Keep the source read-only through at least one normal cycle; delete it only after rollback time expires, or escalate if checks differ between source and destination.