BORG-UPGRADE(1)

📦 version 2.0.0b25, in ubuntu stonking

💖 BORG-UPGRADE 💖

okay bestie, welcome to borg-upgrade(1) — the page from the borg backup tool manual that teaches you how to glow-up an old repo into a new one. this is the upgrade a repository from a previous version chapter, and yes it's giving ✨time travel but make it backups✨. grab a snack, we're doing this together 🫶

🌈 SYNOPSIS 🌈

borg [common options] upgrade [options]

that's it, that's the whole summoning ritual 💅

🦋 DESCRIPTION 🦋

so like. you have an existing, local Borg repository that's kinda old and crusty and you want it on the new version. that's what this does. Upgrade an existing, local Borg repository. slay 💖

✨ When you do not need borg upgrade ✨

okay pookie, listen — not every change requires that you run borg upgrade. like, chill. breathe. not everything is an emergency 🧘

You do not need to run it when:

  • moving your repository to a different place 📦
  • upgrading to another point release (like 1.0.x to 1.0.y) — except when noted otherwise in the changelog
  • upgrading from 1.0.x to 1.1.x — also except when noted otherwise in the changelog

see? casual. no drama, no upgrade, we love that for you 💅

🔐 Borg 1.x.y upgrades 🔐

okay this one's important, bestie, so sit up 🙈

Use borg upgrade --tam REPO to require manifest authentication, which got introduced with Borg 1.0.9 to address security issues. here's the tea though — this means that modifying the repository after doing this with a version prior to 1.0.9 will raise a validation error. 😭 so perform this upgrade only after updating all clients using the repository to 1.0.9 or newer.

⚠️ literally do the clients first, i am begging you ⚠️

This upgrade should be done on each client for safety reasons. every single one. no skipping 🫶

now, if a repository is accidentally modified with a pre-1.0.9 client after this upgrade (we've all been there, no judgment 🙈), use borg upgrade --tam --force REPO to remedy it. the --force is the "oopsie fixer", iconic behavior honestly 👑

If you routinely do this you might not want to enable this upgrade (which will leave you exposed to the security issue). yeah. it's a tradeoff, and it's giving "playing with fire" 🔥 you can reverse the upgrade by issuing borg upgrade --disable-tam REPO.

See https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability for details. go read it, i'll wait 💜

🌸 Borg 0.xx to Borg 1.x 🌸

okay so this currently supports converting Borg 0.xx to 1.0. 🎀

Currently, only LOCAL repositories can be upgraded (issue #465). remote babes, your time will come, but it is not today 💀

Please note that borg create (since 1.0.0) uses bigger chunks by default than old borg did, so the new chunks won't deduplicate with the old chunks in the upgraded repository. 😭 yeah. it's giving "we tried" but the vibes are different now. See --chunker-params option of borg create and borg recreate if you want to control that.

💅 OPTIONS 💅

See borg-common(1) for common options of Borg commands. the shared stuff lives over there, this section is our section ✨

🎀 optional arguments 🎀

  • -n, --dry-run — do not change repository. just a lil peek, a vibe check, no commitment 🫶
  • --inplace — rewrite repository in place, with no chance of going back to older versions of the repository. 💀 irreversible. main character decision energy.
  • --force — Force upgrade. when you gotta, you gotta 👑
  • --tam — Enable manifest authentication (in key and cache) (Borg 1.0.9 and later). 🔐
  • --disable-tam — Disable manifest authentication (in key and cache). turning it back off, we love a reversible queen 🌈

🔥 EXAMPLES 🔥

here's a whole real little run, copy it, love it, live it 💖

# Upgrade the borg repository to the most recent version.
$ borg upgrade -v /path/to/repo
making a hardlink copy in /path/to/repo.before-upgrade-2016-02-15-20:51:55
opening attic repository with borg and converting
no key file found for repository
converting repo index /path/to/repo/index.0
converting 1 segments...
converting borg 0.xx to borg current
no key file found for repository

see how it makes a hardlink copy first? safety first, always 🫶 and then it converts everything, one segment at a time. that's the whole glow-up in one terminal screenshot, ate 💅

👑 SEE ALSO 👑

🦋 AUTHOR 🦋

The Borg Collective — a whole collective running this, we stan a collaborative effort 💜

and that's the page, bestie!! this was BORG-UPGRADE(1) from the borg backup tool manual, dated 2022-06-25. go forth and upgrade responsibly, and pls pls pls update your clients first 😭💖🫶✨

📦 where this page comes from