borg-upgrade - upgrade a repository from a previous version

Author

       The Borg Collective

                                                   2024-07-02                                    BORG-UPGRADE(1)

Description

Upgrade an existing, local Borg repository.

Whenyoudonotneedborgupgrade
Not every change requires that you run borgupgrade.

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

Borg1.x.yupgrades
Archive TAM authentication:

Use borgupgrade--archives-tamREPO to add archive TAMs to all archives that are not TAM authenticated
yet. This is a convenient method to just trust all archives present - if an archive does not have TAM
authentication yet, a TAM will be added. Archives created by old borg versions < 1.0.9 do not have TAMs.
Archives created by newer borg version should have TAMs already. If you have a high risk environment,
you should not just run this, but first verify that the archives are authentic and not malicious (== have
good content, have a good timestamp). Borg 1.2.5+ needs all archives to be TAM authenticated for safety
reasons.

This upgrade needs to be done once per repository.

Manifest TAM authentication:

Use borgupgrade--tamREPO 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 borgupgrade--tam--forceREPO 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 borgupgrade--disable-tamREPO.

See https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability
for details.

AtticandBorg0.xxtoBorg1.x
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 borgcreate (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 borgcreate and borgrecreate.

borgupgrade 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 borgdelete over the copied repository to make sure the cache files are
also removed:

borg delete borg

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.

Examples

          # 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

   Upgradingapassphraseencryptedatticrepo
       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

Name

       borg-upgrade - upgrade a repository from a previous version

Options

       See borg-common(1) for common options of Borg commands.

   argumentsREPOSITORY
              path to the repository to be upgraded

   optionalarguments-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).

       --check-tam
              check manifest authentication (in key and cache).

       --disable-tam
              Disable manifest authentication (in key and cache).

       --check-archives-tam
              check TAM authentication for all archives.

       --archives-tam
              add TAM authentication for all archives.

Synopsis

       borg [common options] upgrade [options] [REPOSITORY]