borg-upgrade - upgrade a repository from a previous version
borg [common options] upgrade [options] [REPOSITORY]
Upgrade an existing, local Borg repository.
Not every change requires that you run
borg upgrade.
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, except when noted otherwise
in the changelog
Use
borg upgrade --tam REPO to require manifest authentication introduced
with Borg 1.0.9 to address security issues. This means that modifying the
repository after doing this with a version prior to 1.0.9 will raise a
validation error, so only perform this upgrade after updating all clients
using the repository to 1.0.9 or newer.
This upgrade should be done on each client for safety reasons.
If a repository is accidentally modified with a pre-1.0.9 client after this
upgrade, use
borg upgrade --tam --force REPO to remedy it.
If you routinely do this you might not want to enable this upgrade (which will
leave you exposed to the security issue). 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.
This currently supports converting an Attic repository to Borg and also helps
with converting Borg 0.xx to 1.0.
Currently, only LOCAL repositories can be upgraded (issue #465).
Please note that
borg create (since 1.0.0) uses bigger chunks by default
than old borg or attic did, so the new chunks won't deduplicate with the old
chunks in the upgraded repository. See
--chunker-params option of
borg create and
borg recreate.
borg upgrade will change the magic strings in the repository's segments
to match the new Borg magic strings. The keyfiles found in $ATTIC_KEYS_DIR or
~/.attic/keys/ will also be converted and copied to $BORG_KEYS_DIR or
~/.config/borg/keys.
The cache files are converted, from $ATTIC_CACHE_DIR or ~/.cache/attic to
$BORG_CACHE_DIR or ~/.cache/borg, but the cache layout between Borg and Attic
changed, so it is possible the first backup after the conversion takes longer
than expected due to the cache resync.
Upgrade should be able to resume if interrupted, although it will still iterate
over all segments. If you want to start from scratch, use
borg delete
over the copied repository to make sure the cache files are also removed:
Unless
--inplace is specified, the upgrade process first creates a backup
copy of the repository, in REPOSITORY.before-upgrade-DATETIME, using
hardlinks. This requires that the repository and its parent directory reside
on same filesystem so the hardlink copy can work. This takes longer than in
place upgrades, but is much safer and gives progress information (as opposed
to
cp -al). Once you are satisfied with the conversion, you can safely
destroy the backup copy.
WARNING: Running the upgrade in place will make the current copy unusable with
older version, with no way of going back to previous versions. This can
PERMANENTLY DAMAGE YOUR REPOSITORY! Attic CAN NOT READ BORG REPOSITORIES, as
the magic strings have changed. You have been warned.
See
borg-common(1) for common options of Borg commands.
- REPOSITORY
- path to the repository to be upgraded
- -n, --dry-run
- do not change repository
- --inplace
- rewrite repository in place, with no chance of going back
to older versions of the repository.
- --force
- Force upgrade
- --tam
- Enable manifest authentication (in key and cache) (Borg
1.0.9 and later).
- --disable-tam
- Disable manifest authentication (in key and cache).
# 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
attic offered a "passphrase" encryption mode, but this was removed in
borg 1.0 and replaced by the "repokey" mode (which stores the
passphrase-protected encryption key into the repository config).
Thus, to upgrade a "passphrase" attic repo to a "repokey"
borg repo, 2 steps are needed, in this order:
- •
- borg upgrade repo
- •
- borg key migrate-to-repokey repo
borg-common(1)
The Borg Collective