borg-upgrade(1) - Man pages

dwww Home | Manual pages | Find package

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 intro-
duced with Borg 1.0.9 to address security issues. This means that modi-
fying the repository after doing this with a version prior to 1.0.9
will raise a validation error, so only perform this upgrade after up-
dating 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 de-
fault 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 $AT-
TIC_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 conver-
sion 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 di-
rectory 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 unus-
able with older version, with no way of going back to previous ver-
sions. 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

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