Ubuntu Manpage: borg-transfer - archives transfer from other repository, optionally upgrade data format

Provided by: borgbackup2_2.0.0b8-2build2_amd64

NAME

       borg-transfer - archives transfer from other repository, optionally upgrade data format

SYNOPSIS

       borg [common options] transfer [options]

DESCRIPTION

       This  command  transfers  archives  from  one  repository to another repository.  Optionally, it can also
       upgrade the transferred data.  Optionally, it can also recompress the transferred data.

       It is  easiest  (and  fastest)  to  give  --compression=COMPRESSION  --recompress=never  using  the  same
       COMPRESSION  mode as in the SRC_REPO - borg will use that COMPRESSION for metadata (in any case) and keep
       data compressed "as is" (saves time as no data compression is needed).

       If  you  want  to  globally  change  compression  while  transferring  archives  to  the  DST_REPO,  give
       --compress=WANTED_COMPRESSION --recompress=always.

       Suggested use for general purpose archive transfer (not repo upgrades):

          # create a related DST_REPO (reusing key material from SRC_REPO), so that
          # chunking and chunk id generation will work in the same way as before.
          borg --repo=DST_REPO rcreate --other-repo=SRC_REPO --encryption=DST_ENC

          # transfer archives from SRC_REPO to DST_REPO
          borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run  # check what it would do
          borg --repo=DST_REPO transfer --other-repo=SRC_REPO            # do it!
          borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run  # check! anything left?

       The default is to transfer all archives, including checkpoint archives.

       You  could  use the misc. archive filter options to limit which archives it will transfer, e.g. using the
       -a option. This is recommended for big repositories with multiple data  sets  to  keep  the  runtime  per
       invocation lower.

       For repository upgrades (e.g. from a borg 1.2 repo to a related borg 2.0 repo), usage is quite similar to
       the above:

          # fast: compress metadata with zstd,3, but keep data chunks compressed as they are:
          borg --repo=DST_REPO transfer --other-repo=SRC_REPO --upgrader=From12To20 \
               --compress=zstd,3 --recompress=never

          # compress metadata and recompress data with zstd,3
          borg --repo=DST_REPO transfer --other-repo=SRC_REPO --upgrader=From12To20 \
               --compress=zstd,3 --recompress=always

OPTIONS

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

options
-n, --dry-run
do not change repository, just check

--other-repo SRC_REPOSITORY
transfer archives from the other repository

--upgrader UPGRADER
use the upgrader to convert transferred data (default: no conversion)

-C COMPRESSION, --compression COMPRESSION
select compression algorithm, see the output of the "borg help compression" command for details.

--recompress MODE
recompress data chunks according to MODE and --compression. Possible modes are always: recompress
unconditionally; and never: do not recompress (faster: re-uses compressed data chunks w/o
change).If no MODE is given, always will be used. Not passing --recompress is equivalent to
"--recompress never".

Archive filters
-a PATTERN, --match-archives PATTERN
only consider archive names matching the pattern. see "borg help match-archives".

--sort-by KEYS
Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is:
timestamp

--first N
consider first N archives after other filters were applied

--last N
consider last N archives after other filters were applied

--oldest TIMESPAN
consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.

--newest TIMESPAN
consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m.

--older TIMESPAN
consider archives older than (now - TIMESPAN), e.g. 7d or 12m.

--newer TIMESPAN
consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.

EXAMPLES

          # 0. Have borg 2.0 installed on client AND server, have a b12 repo copy for testing.

          # 1. Create a new "related" repository:
          # here, the existing borg 1.2 repo used repokey-blake2 (and aes-ctr mode),
          # thus we use repokey-blake2-aes-ocb for the new borg 2.0 repo.
          # staying with the same chunk id algorithm (blake2) and with the same
          # key material (via --other-repo <oldrepo>) will make deduplication work
          # between old archives (copied with borg transfer) and future ones.
          # the AEAD cipher does not matter (everything must be re-encrypted and
          # re-authenticated anyway), you could also choose repokey-blake2-chacha20-poly1305.
          # in case your old borg repo did not use blake2, just remove the "-blake2".
          $ borg --repo       ssh://borg2@borgbackup/./tests/b20 rcreate \
                 --other-repo ssh://borg2@borgbackup/./tests/b12 -e repokey-blake2-aes-ocb

          # 2. Check what and how much it would transfer:
          $ borg --repo       ssh://borg2@borgbackup/./tests/b20 transfer --upgrader=From12To20 \
                 --other-repo ssh://borg2@borgbackup/./tests/b12 --dry-run

          # 3. Transfer (copy) archives from old repo into new repo (takes time and space!):
          $ borg --repo       ssh://borg2@borgbackup/./tests/b20 transfer --upgrader=From12To20 \
                 --other-repo ssh://borg2@borgbackup/./tests/b12

          # 4. Check if we have everything (same as 2.):
          $ borg --repo       ssh://borg2@borgbackup/./tests/b20 transfer --upgrader=From12To20 \
                 --other-repo ssh://borg2@borgbackup/./tests/b12 --dry-run

AUTHOR