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

   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 ~/.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:

          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.

OPTIONS

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

   arguments
       REPOSITORY
              path to the repository to be upgraded

   optional arguments
       -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 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

SEE ALSO

       borg-common(1)

AUTHOR

       The Borg Collective

                                                   2022-02-19                                    BORG-UPGRADE(1)