borg-upgrade

BORG-UPGRADE(1) borg backup tool BORG-UPGRADE(1)

NAME

   borg-upgrade - upgrade a repository from a previous version

SYNOPSIS

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

DESCRIPTION

   Upgrade an existing, local Borg repository.

When you do not need borg upgrade

   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

Borg 1.x.y upgrades

   Use  borg  upgrade --tam REPO to require manifest authentication introduced with Borg 1.0.9 to address security issues. This means that modifying the reposi‐
   tory 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  reposi‐
   tory 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 issu‐
   ing borg upgrade --disable-tam REPO.

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

Attic and Borg 0.xx to Borg 1.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 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 ~/.at‐
   tic/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:

      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 up‐
   grades, 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 PERMA‐
   NENTLY DAMAGE YOUR REPOSITORY!  Attic CAN NOT READ BORG REPOSITORIES, as the magic strings have changed. You have been warned.

OPTIONS

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

arguments

   REPOSITORY
          path to the repository to be upgraded

options

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

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

Upgrading a passphrase encrypted attic repo

   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  en‐
   cryption 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