upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-02-20 00:10:35 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

build_usage build_man

Browse source
This commit is contained in:
Thomas Waldmann 2025-10-31 19:12:42 +01:00
parent 92486d82e9
commit 8e1a4248c0
No known key found for this signature in database
GPG key ID: 243ACFA951F78E01
60 changed files with 1008 additions and 602 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
docs/man/borg-benchmark-crud.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-BENCHMARK-CRUD" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-BENCHMARK-CRUD" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.SH SYNOPSIS
@ -37,7 +37,7 @@ borg [common options] benchmark crud [options] REPOSITORY PATH
.sp
This command benchmarks borg CRUD (create, read, update, delete) operations.
.sp
It creates input data below the given PATH and backups this data into the given REPO.
It creates input data below the given PATH and backs up this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg\-benchmark\-crud* there.
.sp
@ -60,17 +60,17 @@ Also, due to the kind of content used, no compression is used in these benchmark
.INDENT 0.0
.TP
.B C\- == borg create (1st archive creation, no compression, do not use files cache)
C\-Z\- == all\-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
C\-R\- == random files. no dedup, measuring throughput through all processing stages.
C\-Z\- == all\-zero files. full deduplication; this primarily measures reader/chunker/hasher.
C\-R\- == random files. no deduplication, measuring throughput through all processing stages.
.TP
.B R\- == borg extract (extract archive, dry\-run, do everything, but do not write files to disk)
R\-Z\- == all zero files. Measuring heavily duplicated files.
R\-Z\- == all\-zero files. Measuring heavily duplicated files.
R\-R\- == random files. No duplication here, measuring throughput through all processing
stages, except writing to disk.
.TP
.B U\- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
The throughput value is kind of virtual here, it does not actually read the file.
U\-Z\- == needs to check the 2 all\-zero chunks\(aq existence in the repo.
U\-Z\- == needs to check the two all\-zero chunks\(aq existence in the repo.
U\-R\- == needs to check existence of a lot of different chunks in the repo.
.TP
.B D\- == borg delete archive (delete last remaining archive, measure deletion + compaction)
@ -79,7 +79,7 @@ D\-R\- == many chunks to delete / many segments to compact/remove.
.UNINDENT
.sp
Please note that there might be quite some variance in these measurements.
Try multiple measurements and having a otherwise idle machine (and network, if you use it).
Try multiple measurements and have an otherwise idle machine (and network, if you use it).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@ -90,7 +90,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
repository to use for benchmark (must exist)
.TP
.B PATH
path were to create benchmark input data
path where to create benchmark input data
.UNINDENT
.SH SEE ALSO
.sp

4
docs/man/borg-benchmark.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-BENCHMARK" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-BENCHMARK" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-benchmark \- benchmark command
.SH SYNOPSIS
@ -37,7 +37,7 @@ borg [common options] benchmark crud ...
.sp
.SH DESCRIPTION
.sp
These commands do various benchmarks.
These commands perform various benchmarks.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP

6
docs/man/borg-break-lock.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-BREAK-LOCK" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-BREAK-LOCK" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.SH SYNOPSIS
@ -36,8 +36,8 @@ borg [common options] break\-lock [options] [REPOSITORY]
.SH DESCRIPTION
.sp
This command breaks the repository and cache locks.
Please use carefully and only while no borg process (on any machine) is
trying to access the Cache or the Repository.
Please use with care and only when no borg process (on any machine) is
trying to access the cache or the repository.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.

10
docs/man/borg-check.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-CHECK" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-CHECK" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.SH SYNOPSIS
@ -78,7 +78,7 @@ archive checks, nor enable repair mode. Consequently, if you want to use
\fBWarning:\fP Please note that partial repository checks (i.e. running it with
\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
segment files. A full repository check (i.e. without \fB\-\-max\-duration\fP) can
also do a repository index check. Enabling partial repository checks excepts
also do a repository index check. Enabling partial repository checks excludes
archive checks for the same reason. Therefore partial checks may be useful with
very large repositories only where a full check would take too long.
.sp
@ -87,11 +87,11 @@ opposed to checking the CRC32 of the segment) of data, which means reading the
data from the repository, decrypting and decompressing it. It is a complete
cryptographic verification and hence very time consuming, but will detect any
accidental and malicious corruption. Tamper\-resistance is only guaranteed for
encrypted repositories against attackers without access to the keys. You can
not use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
encrypted repositories against attackers without access to the keys. You cannot
use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
.SS About repair mode
.sp
The check command is a readonly task by default. If any corruption is found,
The check command is a read\-only task by default. If any corruption is found,
Borg will report the issue and proceed with checking. To actually repair the
issues found, pass \fB\-\-repair\fP\&.
.sp

2
docs/man/borg-common.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-COMMON" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-COMMON" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.SH SYNOPSIS

13
docs/man/borg-compact.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-COMPACT" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-COMPACT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-compact \- compact segment files in the repository
.SH SYNOPSIS
@ -51,8 +51,15 @@ A segment is compacted if the amount of saved space is above the percentage valu
given by the \fB\-\-threshold\fP option. If omitted, a threshold of 10% is used.
When using \fB\-\-verbose\fP, borg will output an estimate of the freed space.
.sp
For maximum compaction, use \fB\-\-threshold 0\fP\&. This will compact whenever any
space can be saved and thus rewrites the most data; it can be much slower on
large repositories. Using \fB\-\-threshold 1\fP usually achieves nearly the same
result significantly faster. Higher thresholds (e.g. the default 10) trade
compaction thoroughness for speed. Note: \fB\-\-threshold 100\fP will effectively
compact nothing.
.sp
After upgrading borg (server) to 1.2+, you can use \fBborg compact \-\-cleanup\-commits\fP
to clean up the numerous 17byte commit\-only segments that borg 1.1 did not clean up
to clean up the numerous 17\-byte commit\-only segments that borg 1.1 did not clean up
due to a bug. It is enough to do that once per repository. After cleaning up the
commits, borg will also do a normal compaction.
.sp
@ -86,7 +93,7 @@ set minimum threshold for saved space in PERCENT (Default: 10)
# compact segments and free repo disk space
$ borg compact /path/to/repo
# same as above plus clean up 17byte commit\-only segments
# same as above plus clean up 17\-byte commit\-only segments
$ borg compact \-\-cleanup\-commits /path/to/repo
.EE
.UNINDENT

2
docs/man/borg-compression.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-COMPRESSION" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-COMPRESSION" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.SH DESCRIPTION

4
docs/man/borg-config.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-CONFIG" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-CONFIG" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-config \- get, set, and delete values in a repository or cache config file
.SH SYNOPSIS
@ -39,7 +39,7 @@ This command gets and sets options in a local repository or cache config file.
For security reasons, this command only works on local repositories.
.sp
To delete a config value entirely, use \fB\-\-delete\fP\&. To list the values
of the configuration file or the default values, use \fB\-\-list\fP\&. To get an existing
of the configuration file or the default values, use \fB\-\-list\fP\&. To get an existing
key, pass only the key name. To set a key, pass both the key name and
the new value. Keys can be specified in the format \(dqsection.name\(dq or
simply \(dqname\(dq; the section will default to \(dqrepository\(dq and \(dqcache\(dq for

69
docs/man/borg-create.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-CREATE" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-CREATE" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.SH SYNOPSIS
@ -37,18 +37,18 @@ borg [common options] create [options] ARCHIVE [PATH...]
.sp
This command creates a backup archive containing all files found while recursively
traversing all paths specified. Paths are added to the archive as they are given,
that means if relative paths are desired, the command has to be run from the correct
which means that if relative paths are desired, the command has to be run from the correct
directory.
.sp
The slashdot hack in paths (recursion roots) is triggered by using \fB/./\fP:
\fB/this/gets/stripped/./this/gets/archived\fP means to process that fs object, but
\fB/this/gets/stripped/./this/gets/archived\fP means to process that filesystem object, but
strip the prefix on the left side of \fB\&./\fP from the archived items (in this case,
\fBthis/gets/archived\fP will be the path in the archived item).
.sp
When giving \(aq\-\(aq as path, borg will read data from standard input and create a
file \(aqstdin\(aq in the created archive from that data. In some cases it\(aqs more
appropriate to use \-\-content\-from\-command, however. See section \fIReading from
stdin\fP below for details.
When giving \(aq\-\(aq as a path, Borg will read data from standard input and create a
file \(aqstdin\(aq in the created archive from that data. In some cases, it is more
appropriate to use \fB\-\-content\-from\-command\fP\&. See section \(dqReading from stdin\(dq
below for details.
.sp
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
@ -70,7 +70,7 @@ This comparison can operate in different modes as given by \fB\-\-files\-cache\f
.IP \(bu 2
ctime,size,inode (default)
.IP \(bu 2
mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4)
mtime,size,inode (default behavior of borg versions older than 1.1.0rc4)
.IP \(bu 2
ctime,size (ignore the inode number)
.IP \(bu 2
@ -83,37 +83,49 @@ rechunk,mtime (all files are considered modified \- rechunk, cache mtime)
disabled (disable the files cache, all files considered modified \- rechunk)
.UNINDENT
.sp
inode number: better safety, but often unstable on network filesystems
inode number: better safety, but often unstable on network file systems
.sp
Normally, detecting file modifications will take inode information into
consideration to improve the reliability of file change detection.
This is problematic for files located on sshfs and similar network file
systems which do not provide stable inode numbers, such files will always
This is problematic for files located on SSHFS and similar network file
systems which do not provide stable inode numbers; such files will always
be considered modified. You can use modes without \fIinode\fP in this case to
improve performance, but reliability of change detection might be reduced.
improve performance, but the reliability of change detection might be reduced.
.sp
ctime vs. mtime: safety vs. speed
.INDENT 0.0
.IP \(bu 2
ctime is a rather safe way to detect changes to a file (metadata and contents)
as it can not be set from userspace. But, a metadata\-only change will already
as it cannot be set from user space. However, a metadata\-only change will already
update the ctime, so there might be some unnecessary chunking/hashing even
without content changes. Some filesystems do not support ctime (change time).
E.g. doing a chown or chmod to a file will change its ctime.
without content changes. Some file systems do not support ctime (change time).
For example, doing a chown or chmod to a file will change its ctime.
.IP \(bu 2
mtime usually works and only updates if file contents were changed. But mtime
can be arbitrarily set from userspace, e.g. to set mtime back to the same value
can be arbitrarily set from user space, e.g., to set mtime back to the same value
it had before a content change happened. This can be used maliciously as well as
well\-meant, but in both cases mtime based cache modes can be problematic.
well\-meant, but in both cases mtime\-based cache modes can be problematic.
.UNINDENT
.sp
The mount points of filesystems or filesystem snapshots should be the same for every
The \fB\-\-files\-changed\fP option controls how Borg detects if a file has changed during backup:
.INDENT 0.0
.IP \(bu 2
ctime (default): Use ctime to detect changes. This is the safest option.
.IP \(bu 2
mtime: Use mtime to detect changes.
.IP \(bu 2
disabled: Disable the \(dqfile has changed while we backed it up\(dq detection completely.
This is not recommended unless you know what you\(aqre doing, as it could lead to
inconsistent backups if files change during the backup process.
.UNINDENT
.sp
The mount points of file systems or file system snapshots should be the same for every
creation of a new archive to ensure fast operation. This is because the file cache that
is used to determine changed files quickly uses absolute filenames.
is used to determine changed files quickly uses absolute file names.
If this is not possible, consider creating a bind mount to a stable location.
.sp
The \fB\-\-progress\fP option shows (from left to right) Original, Compressed and Deduplicated
(O, C and D, respectively), then the Number of files (N) processed so far, followed by
(O, C and D, respectively), then the number of files (N) processed so far, followed by
the currently processed path.
.sp
When using \fB\-\-stats\fP, you will get some statistics about how much data was
@ -251,6 +263,9 @@ detect sparse holes in input (supported only by fixed chunker)
.BI \-\-files\-cache \ MODE
operate files cache in MODE. default: ctime,size,inode
.TP
.BI \-\-files\-changed \ MODE
specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime
.TP
.B \-\-read\-special
open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
.UNINDENT
@ -379,15 +394,15 @@ only include the objects specified by \fB\-\-exclude\-if\-present\fP in your bac
and not include any other contents of the containing folder, this can be enabled
through using the \fB\-\-keep\-exclude\-tags\fP option.
.sp
The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories that are mount points (and everything in them).
It detects mount points by comparing the device number from the output of \fBstat()\fP of the directory and its
parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
from the device number of their parent.
In general: be aware that there are directories with device number different from their parent, which the kernel
does not consider a mountpoint and also the other way around.
Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
macOS examples are the apfs mounts of a typical macOS installation.
In general: be aware that there are directories with device numbers different from their parent, which the kernel
does not consider mount points, and vice versa.
Linux examples for this are bind mounts (possibly same device number, but always a mount point) and all
subvolumes of a Btrfs file system (different device numbers from the parent but not necessarily mount points).
macOS examples are the APFS mounts of a typical macOS installation.
Therefore, when using \fB\-\-one\-file\-system\fP, you should double\-check that the backup works as intended.
.SS Item flags
.sp

4
docs/man/borg-delete.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-DELETE" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-DELETE" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.SH SYNOPSIS
@ -132,7 +132,7 @@ $ borg delete \-\-glob\-archives \(aq{hostname}\-*\(aq /path/to/repo
# delete all archives whose names contain \(dq\-2012\-\(dq
$ borg delete \-\-glob\-archives \(aq*\-2012\-*\(aq /path/to/repo
# see what would be deleted if delete was run without \-\-dry\-run
# see what would be deleted if delete were run without \-\-dry\-run
$ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq /path/to/repo
# delete the whole repository and the related local cache:

105
docs/man/borg-diff.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-DIFF" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-DIFF" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.SH SYNOPSIS
@ -38,17 +38,84 @@ borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
This command finds differences (file contents, user/group/mode) between archives.
.sp
A repository location and an archive name must be specified for REPO::ARCHIVE1.
ARCHIVE2 is just another archive name in same repository (no repository location
ARCHIVE2 is just another archive name in the same repository (no repository location
allowed).
.SS What is compared
.sp
For archives created with Borg 1.1 or newer diff automatically detects whether
the archives are created with the same chunker params. If so, only chunk IDs
For each matching item in both archives, Borg reports:
.INDENT 0.0
.IP \(bu 2
Content changes: total added/removed bytes within files. If chunker parameters are comparable,
Borg compares chunk IDs quickly; otherwise, it compares the content.
.IP \(bu 2
Metadata changes: user, group, mode, and other metadata shown inline like
\(dq[old_mode \-> new_mode]\(dq for mode changes. Use \fB\-\-content\-only\fP to suppress metadata changes.
.IP \(bu 2
Added/removed items: printed as \(dqadded SIZE path\(dq or \(dqremoved SIZE path\(dq.
.UNINDENT
.SS Output formats
.sp
The default (text) output shows one line per changed path, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
+135 B \-252 B [ \-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x ] path/to/file
.EE
.UNINDENT
.UNINDENT
.sp
JSON Lines output (\fB\-\-json\-lines\fP) prints one JSON object per changed path, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{\(dqpath\(dq: \(dqPATH\(dq, \(dqchanges\(dq: [
{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: BYTES, \(dqremoved\(dq: BYTES},
{\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq},
{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: SIZE},
{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: SIZE}
]}
.EE
.UNINDENT
.UNINDENT
.sp
Only actual changes are included in the \(dqchanges\(dq list. For example, a modified entry with
added=0 and removed=0 is omitted.
.SS Sorting
.sp
Use \fB\-\-sort\-by FIELDS\fP where FIELDS is a comma\-separated list of fields.
Sorts are applied stably from last to first in the given list. Prepend \(dq>\(dq for
descending, \(dq<\(dq (or no prefix) for ascending, for example \fB\-\-sort\-by=\(dq>size_added,path\(dq\fP\&.
Supported fields include:
.INDENT 0.0
.IP \(bu 2
path: the item path
.IP \(bu 2
size_added: total bytes added for the item content
.IP \(bu 2
size_removed: total bytes removed for the item content
.IP \(bu 2
size_diff: size_added \- size_removed (net content change)
.IP \(bu 2
size: size of the item as stored in ARCHIVE2 (0 for removed items)
.IP \(bu 2
user, group, uid, gid, ctime, mtime: taken from the item state in ARCHIVE2 when present
.IP \(bu 2
ctime_diff, mtime_diff: timestamp difference (archive2 \- archive1)
.UNINDENT
.sp
The \fB\-\-sort\fP option is deprecated and only sorts by path.
.SS Performance considerations
.sp
For archives created with Borg 1.1 or newer, diff automatically detects whether
the archives were created with the same chunker parameters. If so, only chunk IDs
are compared, which is very fast.
.sp
For archives prior to Borg 1.1 chunk contents are compared by default.
If you did not create the archives with different chunker params,
For archives prior to Borg 1.1, chunk contents are compared by default.
If you did not create the archives with different chunker parameters,
pass \fB\-\-same\-chunker\-params\fP\&.
Note that the chunker params changed from Borg 0.xx to 1.0.
Note that the chunker parameters changed from Borg 0.xx to 1.0.
.sp
For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
.SH OPTIONS
@ -79,14 +146,14 @@ only consider numeric user and group identifiers
Override check of chunker parameters.
.TP
.B \-\-sort
Sort the output lines by file path.
.TP
.B \-\-content\-only
Only compare differences in content (exclude metadata differences)
.TP
.B \-\-json\-lines
Format output as JSON Lines.
Sort the output by path (deprecated, use \-\-sort\-by=path).
.UNINDENT
.IP "System Message: WARNING/2 (docs/borg-diff.rst:, line 119)"
Option list ends without a blank line; unexpected unindent.
.sp
\-\-sort\-by FIELD[,FIELD...] Advanced sorting: specify field(s) to sort by. Accepts a comma\-separated list. Prefix with > for descending or < for ascending (default).
\-\-content\-only Only compare differences in content (exclude metadata differences)
\-\-json\-lines Format output as JSON Lines.
.SS Include/Exclude options
.INDENT 0.0
.TP
@ -144,7 +211,15 @@ $ borg diff \-\-json\-lines testrepo::archive1 archive3
{\(dqpath\(dq: \(dqfile1\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 17, \(dqremoved\(dq: 5}, {\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq}]}
{\(dqpath\(dq: \(dqfile2\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 135, \(dqremoved\(dq: 252}]}
{\(dqpath\(dq: \(dqfile4\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: 0}]}
{\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]
{\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]}
# Use \-\-sort\-by with a comma\-separated list; sorts apply stably from last to first.
# Here: primary by net size change descending, tie\-breaker by path ascending
$ borg diff \-\-sort\-by=\(dq>size_diff,path\(dq testrepo::archive1 archive3
+17 B \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
removed 0 B file3
added 0 B file4
+135 B \-252 B file2
.EE
.UNINDENT
.UNINDENT

14
docs/man/borg-export-tar.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-EXPORT-TAR" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-EXPORT-TAR" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.SH SYNOPSIS
@ -66,7 +66,7 @@ BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
Timestamp resolution is limited to whole seconds, not the nanosecond resolution
otherwise supported by Borg.
.sp
A \fB\-\-sparse\fP option (as found in borg extract) is not supported.
A \fB\-\-sparse\fP option (as found in \fBborg extract\fP) is not supported.
.sp
By default the entire archive is extracted but a subset of files and directories
can be selected by passing a list of \fBPATHs\fP as arguments.
@ -123,20 +123,20 @@ Remove the specified number of leading path elements. Paths with fewer elements
.INDENT 3.5
.sp
.EX
# export as uncompressed tar
# Export as an uncompressed tar.
$ borg export\-tar /path/to/repo::Monday Monday.tar
# exclude some types, compress using gzip
# Exclude some types; compress using gzip.
$ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
# use higher compression level with gzip
# Use a higher compression level with gzip.
$ borg export\-tar \-\-tar\-filter=\(dqgzip \-9\(dq testrepo::linux Monday.tar.gz
# export a tar, but instead of storing it on disk,
# Export a tar, but instead of storing it on disk,
# upload it to a remote site using curl.
$ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
# remote extraction via \(dqtarpipe\(dq
# Remote extraction via \(dqtarpipe\(dq.
$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere \(dqcd extracted; tar x\(dq
.EE
.UNINDENT

25
docs/man/borg-extract.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-EXTRACT" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-EXTRACT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.SH SYNOPSIS
@ -35,16 +35,20 @@ borg-extract \- Extract archive contents
borg [common options] extract [options] ARCHIVE [PATH...]
.SH DESCRIPTION
.sp
This command extracts the contents of an archive. By default the entire
archive is extracted but a subset of files and directories can be selected
by passing a list of \fBPATHs\fP as arguments. The file selection can further
be restricted by using the \fB\-\-exclude\fP option.
This command extracts the contents of an archive.
.sp
By default, the entire archive is extracted, but a subset of files and directories
can be selected by passing a list of \fBPATH\fP arguments. The default interpretation
for the paths to extract is \fIpp:\fP which is a literal path\-prefix match. If you want
to use e.g. a wildcard, you must select a different pattern style such as \fIsh:\fP or
\fIfm:\fP\&. See \fIborg_patterns\fP for more information.
.sp
The file selection can be further restricted by using the \fB\-\-exclude\fP option.
For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
.sp
By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the
output data: reading metadata and data chunks from the repo, checking the hash/hmac,
decrypting, decompressing.
output data: reading metadata and data chunks from the repository, checking the hash/HMAC,
decrypting, and decompressing.
.sp
\fB\-\-progress\fP can be slower than no progress display, since it makes one additional
pass over the archive metadata.
@ -56,8 +60,8 @@ Currently, extract always writes into the current working directory (\(dq.\(dq),
so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&.
.sp
When parent directories are not extracted (because of using file/directory selection
or any other reason), borg can not restore parent directories\(aq metadata, e.g. owner,
group, permission, etc.
or any other reason), Borg cannot restore parent directories\(aq metadata, e.g., owner,
group, permissions, etc.
.UNINDENT
.UNINDENT
.SH OPTIONS
@ -143,6 +147,9 @@ $ borg extract /path/to/repo::my\-files home/USERNAME/src
# Extract the \(dqsrc\(dq directory but exclude object files
$ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
# Extract only the C files
$ borg extract /path/to/repo::my\-files \(aqsh:home/USERNAME/src/*.c\(aq
# Restore a raw device (must not be active/in use/mounted at that time)
$ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
.EE

10
docs/man/borg-import-tar.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-IMPORT-TAR" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-IMPORT-TAR" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-import-tar \- Create a backup archive from a tarball
.SH SYNOPSIS
@ -37,9 +37,9 @@ borg [common options] import\-tar [options] ARCHIVE TARFILE
.sp
This command creates a backup archive from a tarball.
.sp
When giving \(aq\-\(aq as path, Borg will read a tar stream from standard input.
When giving \(aq\-\(aq as a path, Borg will read a tar stream from standard input.
.sp
By default (\-\-tar\-filter=auto) Borg will detect whether the file is compressed
By default (\fB\-\-tar\-filter=auto\fP) Borg will detect whether the file is compressed
based on its file extension and pipe the file through an appropriate filter:
.INDENT 0.0
.IP \(bu 2
@ -54,11 +54,11 @@ based on its file extension and pipe the file through an appropriate filter:
\&.tar.lz4: lz4 \-d
.UNINDENT
.sp
Alternatively, a \-\-tar\-filter program may be explicitly specified. It should
Alternatively, a \fB\-\-tar\-filter\fP program may be explicitly specified. It should
read compressed data from stdin and output an uncompressed tar stream on
stdout.
.sp
Most documentation of borg create applies. Note that this command does not
Most documentation of \fBborg create\fP applies. Note that this command does not
support excluding files.
.sp
import\-tar is a lossy conversion:

6
docs/man/borg-info.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-INFO" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-INFO" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.SH SYNOPSIS
@ -39,11 +39,11 @@ This command displays detailed information about the specified archive or reposi
.sp
Please note that the deduplicated sizes of the individual archives do not add
up to the deduplicated size of the repository (\(dqall archives\(dq), because the two
are meaning different things:
mean different things:
.sp
This archive / deduplicated size = amount of data stored ONLY for this archive
= unique chunks of this archive.
All archives / deduplicated size = amount of data stored in the repo
All archives / deduplicated size = amount of data stored in the repository
= all chunks in the repository.
.sp
Borg archives can only contain a limited amount of file metadata.

291
docs/man/borg-init.1
View file

@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-INIT" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-INIT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.SH SYNOPSIS
@ -36,97 +36,115 @@ borg-init \- Initialize an empty repository
borg [common options] init [options] [REPOSITORY]
.SH DESCRIPTION
.sp
This command initializes an empty repository. A repository is a filesystem
directory containing the deduplicated data from zero or more archives.
.SS Encryption mode TLDR
This command initializes an empty repository. A repository is a
filesystem directory containing the deduplicated data from zero or more
archives.
.SS Encryption mode TL;DR
.sp
The encryption mode can only be configured when creating a new repository \-
you can neither configure it on a per\-archive basis nor change the
encryption mode of an existing repository.
The encryption mode can only be configured when creating a new
repository. You can neither configure encryption on a per\-archive
basis, nor change the encryption mode of an existing repository. You
should thus take possible future use into account when deciding on an
encryption mode.
.sp
Use \fBrepokey\fP:
As a general rule of thumb, use \fBrepokey\fP with a strong passphrase:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
borg init \-\-encryption repokey /path/to/repo
.EE
.UNINDENT
.UNINDENT
.sp
Or \fBrepokey\-blake2\fP depending on which is faster on your client machines (see below):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
borg init \-\-encryption repokey\-blake2 /path/to/repo
.EE
.UNINDENT
.UNINDENT
.sp
Borg will:
However, there are many reasons to choose differently. See the section
below for details. In any case, Borg will:
.INDENT 0.0
.IP 1. 3
Ask you to come up with a passphrase.
Ask you to enter a unique and strong passphrase.
.IP 2. 3
Create a borg key (which contains 3 random secrets. See \fIkey_files\fP).
Create a random Borg key (which actually consists of three random
secrets, see \fIkey_files\fP for details).
.IP 3. 3
Encrypt the key with your passphrase.
Encrypt the Borg key with your passphrase.
.IP 4. 3
Store the encrypted borg key inside the repository directory (in the repo config).
This is why it is essential to use a secure passphrase.
Store the encrypted Borg key inside the repository directory (with
\fBrepokey\fP and \fBrepokey\-blake2\fP modes; with \fBkeyfile\fP and
\fBkeyfile\-blake2\fP modes the Borg key is stored in your home
directory instead, see below). Since we usually have to assume that
an attacker could gain access to the repository (that\(aqs why we
encrypt the data in the first place), choosing a strong and unique
passphrase is absolutely crucial.
.IP 5. 3
Encrypt and sign your backups to prevent anyone from reading or forging them unless they
have the key and know the passphrase. Make sure to keep a backup of
your key \fBoutside\fP the repository \- do not lock yourself out by
\(dqleaving your keys inside your car\(dq (see \fIborg_key_export\fP).
For remote backups the encryption is done locally \- the remote machine
never sees your passphrase, your unencrypted key or your unencrypted files.
Chunking and id generation are also based on your key to improve
your privacy.
Encrypt and sign your backups with the Borg key to prevent anyone
from reading or forging them unless they have the Borg key \fIand\fP
know the passphrase.
.IP 6. 3
Use the key when extracting files to decrypt them and to verify that the contents of
the backups have not been accidentally or maliciously altered.
Use the Borg key to decrypt and thus access the data stored in your
repository, e.g. when extracting files. The contents can also be
verified to detect accidental corruption or malicious tampering.
.UNINDENT
.sp
As you can see, you always need \fIboth\fP the Borg key and passphrase to
access your data. Thus it\(aqs crucial to keep a backup of your key
\fIoutside\fP both the repository and the system you create backups of.
You can easily run into a \(dqleaving your keys inside your car\(dq situation
otherwise. See \fIborg_key_export\fP to create a backup of your key
(e.g., by printing it on paper).
.sp
Encryption is done locally \- i.e., if you back up to a remote machine,
the remote machine neither sees your passphrase, nor your unencrypted
Borg key, nor your unencrypted files. Chunking and ID generation are
based on your key to improve privacy.
.sp
\fBAbout hardware acceleration:\fP
.sp
Borg encrypts data with AES, which is pretty fast thanks to hardware
acceleration on basically all modern Intel, AMD, and ARM CPUs since
around the early 2010s (very cheap models since the mid\-2010s).
.sp
As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM
CPUs support hardware\-accelerated SHA256 hashing since ARMv7 with NEON
(around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1
(around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since Ice
Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop
(11th gen, around 2021). Very cheap models have received support a few
years later. If your CPU doesn\(aqt support hardware\-accelerated SHA256
hashing, you might want to give BLAKE2b hashing a try \- it\(aqs likely
faster then. So, instead of \fBrepokey\fP mode, use \fBrepokey\-blake2\fP
(or any of the other \fB\-blake2\fP modes for that matter).
.sp
Hardware acceleration is always used automatically when available.
.SS Picking a passphrase
.sp
Make sure you use a good passphrase. Not too short, not too simple. The real
encryption / decryption key is encrypted with / locked by your passphrase.
If an attacker gets your key, he can\(aqt unlock and use it without knowing the
passphrase.
Make sure you use a good passphrase. Not too short, not too simple. The
real encryption / decryption key is encrypted with / locked by your
passphrase. If an attacker gets your borg key, they can\(aqt unlock and use
it without knowing the passphrase.
.sp
Be careful with special or non\-ascii characters in your passphrase:
Be careful with special or non\-ASCII characters in your passphrase:
.INDENT 0.0
.IP \(bu 2
Borg processes the passphrase as unicode (and encodes it as utf\-8),
so it does not have problems dealing with even the strangest characters.
Borg processes the passphrase as Unicode (and encodes it as UTF\-8), so
it does not have problems dealing with even the strangest characters.
.IP \(bu 2
BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
BUT: that does not necessarily apply to your OS / VM / keyboard
configuration.
.UNINDENT
.sp
So better use a long passphrase made from simple ascii chars than one that
includes non\-ascii stuff or characters that are hard/impossible to enter on
a different keyboard layout.
So it is better to use a long passphrase made from simple ASCII
characters than one that includes non\-ASCII characters or characters
that are hard or impossible to enter on a different keyboard layout.
.sp
You can change your passphrase for existing repos at any time, it won\(aqt affect
the encryption/decryption key or other secrets.
.SS More encryption modes
You can change your passphrase for existing repositories at any time; it
won\(aqt affect the encryption/decryption key or other secrets. See
\fIborg_key_change\-passphrase\fP\&.
.SS More about encryption modes
.sp
Only use \fB\-\-encryption none\fP if you are OK with anyone who has access to
your repository being able to read your backups and tamper with their
contents without you noticing.
Choosing the right encryption mode isn\(aqt always easy and many factors
can change which mode is best for you. However, note that you can\(aqt
really do anything \fIwrong\fP if you choose \fBrepokey\fP with a strong
passphrase. So, if you\(aqre not sure, choose \fBrepokey\fP (or
\fBrepokey\-blake2\fP, depending on your hardware, see above).
.sp
If you want \(dqpassphrase and having\-the\-key\(dq security, use \fB\-\-encryption keyfile\fP\&.
The key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
.sp
If you do \fBnot\fP want to encrypt the contents of your backups, but still
want to detect malicious tampering use \fB\-\-encryption authenticated\fP\&.
To normally work with \fBauthenticated\fP repos, you will need the passphrase, but
there is an emergency workaround, see \fBBORG_WORKAROUNDS=authenticated_no_key\fP docs.
.sp
If \fBBLAKE2b\fP is faster than \fBSHA\-256\fP on your hardware, use \fB\-\-encryption authenticated\-blake2\fP,
\fB\-\-encryption repokey\-blake2\fP or \fB\-\-encryption keyfile\-blake2\fP\&. Note: for remote backups
the hashing is done on your local machine.
Borg supports the following encryption modes:
.\" nanorst: inline-fill
.
.TS
@ -135,25 +153,26 @@ l|l|l|l.
T{
Hash/MAC
T} T{
Not encrypted
no auth
T} T{
Not encrypted,
but authenticated
Not Encrypted
T} T{
Encrypted (AEAD w/ AES)
and authenticated
T}
_
T{
Not Authenticated
T} T{
Authenticated
T}
_
T{
SHA\-256
T} T{
none
\fBnone\fP
T} T{
\fIauthenticated\fP
\fBauthenticated\fP
T} T{
repokey
keyfile
\fBrepokey\fP
\fBkeyfile\fP
T}
_
T{
@ -161,56 +180,106 @@ BLAKE2b
T} T{
n/a
T} T{
\fIauthenticated\-blake2\fP
\fBauthenticated\-blake2\fP
T} T{
\fIrepokey\-blake2\fP
\fIkeyfile\-blake2\fP
\fBrepokey\-blake2\fP
\fBkeyfile\-blake2\fP
T}
.TE
.\" nanorst: inline-replace
.
.sp
Modes \fImarked like this\fP in the above table are new in Borg 1.1 and are not
backwards\-compatible with Borg 1.0.x.
Borg 1.0 and older support \fBnone\fP, \fBrepokey\fP, and \fBkeyfile\fP
modes only. If you need such old clients to be able to access your
repo, you can\(aqt use any of the other modes.
.sp
On modern Intel/AMD CPUs (except very cheap ones), AES is usually
hardware\-accelerated.
BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs
(except AMD Ryzen and future CPUs with SHA extensions),
which makes \fIauthenticated\-blake2\fP faster than \fInone\fP and \fIauthenticated\fP\&.
\fBAbout modes without encryption:\fP
.sp
On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
than BLAKE2b\-256 there. NEON accelerates AES as well.
Avoid using \fBnone\fP mode. If you think about using \fBnone\fP mode,
please reconsider and be absolutely sure. Using any mode other than
\fBnone\fP allows Borg to detect accidental corruption or malicious
tampering with the repo. It also prevents denial\-of\-service attacks
against clients. Instead of \fBnone\fP mode, you likely want to use
\fBauthenticated\fP mode, or \fBrepokey\fP or \fBkeyfile\fP modes with an
empty passphrase instead (see below).
.sp
Hardware acceleration is always used automatically when available.
If you don\(aqt want to encrypt your data, use \fBauthenticated\fP or
\fBauthenticated\-blake2\fP modes. These modes require a passphrase in
normal operation, but in emergency situations you can access the repo
without the passphrase with \fBBORG_WORKAROUNDS=authenticated_no_key\fP
(see \fIenvironment\-variables\fP).
.sp
\fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for
authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash
is HMAC\-SHA256 as well (with a separate key).
These modes are compatible with Borg 1.0.x.
If you just don\(aqt want to choose a passphrase, use \fBkeyfile\fP or
\fBkeyfile\-blake2\fP modes with an empty passphrase. These modes are
generally safe even without a passphrase, but keeping an offsite
backup of the Borg key is also important then. See below for details.
.sp
\fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes,
but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID
hash is a keyed BLAKE2b\-256 hash.
These modes are new and \fInot\fP compatible with Borg 1.0.x.
If you can assure that an attacker can\(aqt gain access to your repo, e.g.
when independently encrypting your repository disk or filesystem, you
can think about using \fBrepokey\fP or \fBrepokey\-blake2\fP modes with an
empty passphrase. However, keep in mind that if an attacker still
somehow manages to gain access, they have full access to your repo. In
such situations choosing \fBrepokey\fP over \fBauthenticated\fP mode has
the advantage of allowing you to add a passphrase later using
\fIborg_key_change\-passphrase\fP\&.
.sp
\fIauthenticated\fP mode uses no encryption, but authenticates repository contents
through the same HMAC\-SHA256 hash as the \fIrepokey\fP and \fIkeyfile\fP modes (it uses it
as the chunk ID hash). The key is stored like \fIrepokey\fP\&.
This mode is new and \fInot\fP compatible with Borg 1.0.x.
\fBAbout modes with encryption:\fP
.sp
\fIauthenticated\-blake2\fP is like \fIauthenticated\fP, but uses the keyed BLAKE2b\-256 hash
from the other blake2 modes.
This mode is new and \fInot\fP compatible with Borg 1.0.x.
With \fBrepokey\fP and \fBrepokey\-blake2\fP modes the key is stored with
the repo and encrypted with your passphrase. If an attacker gains
access to your repo and knows the passphrase, he can access and tamper
with the repo. The repo\(aqs security thus relies on the strength of your
passphrase. Creating an offsite backup of your Borg key (e.g., by
printing it on paper) is recommended, see \fIborg_key_export\fP\&.
.sp
\fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk
ID hash. This mode is not recommended, you should rather consider using an authenticated
or authenticated/encrypted mode. This mode has possible denial\-of\-service issues
when running \fBborg create\fP on contents controlled by an attacker.
Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility
with 1.0.x is important. If compatibility with 1.0.x is not important, use
\fIauthenticated\-blake2\fP or \fIauthenticated\fP instead.
This mode is compatible with Borg 1.0.x.
If you\(aqre thinking about storing the passphrase on the disk of the
system you\(aqre backing up, consider using the \fBkeyfile\fP method
instead. It generally provides the same or better security then.
.sp
With \fBkeyfile\fP and \fBkeyfile\-blake2\fP modes the key is stored on your
local machine (in \fB~/.config/borg/keys\fP) instead. An attacker gaining
access to your repo then needs both the Borg key, and your passphrase to
access and tamper with the repo. However, if you lose the key, you lose
access to the repo, too. You \fBmust\fP create an offsite backup of your
Borg key, e.g. by printing it on paper. Storing a copy of the Borg key
on the system you\(aqre creating backups of is \fBNOT\fP sufficient. Use
\fIborg_key_export\fP to create the backup.
.sp
The \fBkeyfile\fP and \fBkeyfile\-blake2\fP modes allow for \(dqpassphrase and
having\-the\-key\(dq security when using a strong passphrase, but can also
be used with an empty passphrase. Storing a (easily readable)
passphrase on the disk of the system you\(aqre backing up with
\fBkeyfile\fP and \fBkeyfile\-blake2\fP modes adds no security over using an
empty passphrase.
.sp
\fBTechnical details:\fP
.sp
\fBrepokey\fP and \fBkeyfile\fP use AES\-CTR\-256 for encryption and
HMAC\-SHA256 for authentication in an encrypt\-then\-MAC (EtM)
construction. The chunk ID hash is HMAC\-SHA256 (with a separate key).
These modes are compatible with all Borg versions.
.sp
\fBrepokey\-blake2\fP and \fBkeyfile\-blake2\fP are also authenticated
encryption modes, but use BLAKE2b\-256 instead of HMAC\-SHA256 for
authentication. The chunk ID hash is a keyed BLAKE2b\-256 hash. These
modes are only compatible with Borg 1.1 and later.
.sp
\fBauthenticated\fP mode uses no encryption, but authenticates repo
contents through the same HMAC\-SHA256 hash as the \fBrepokey\fP and
\fBkeyfile\fP modes (it uses it as the chunk ID hash). The key is stored
like \fBrepokey\fP within the repo. This mode is only compatible with
Borg 1.1 and later.
.sp
\fBauthenticated\-blake2\fP is like \fBauthenticated\fP, but uses the keyed
BLAKE2b\-256 hash from the other BLAKE2b modes. This mode is only
compatible with Borg 1.1 and later.
.sp
\fBnone\fP mode uses no encryption and no authentication. It uses SHA256
as chunk ID hash. This mode is not recommended. You should instead
consider using an authenticated or authenticated/encrypted mode. This
mode has possible denial\-of\-service issues when running \fBborg create\fP
on contents controlled by an attacker. See above for alternatives.
This mode is compatible with all Borg versions.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.

8
docs/man/borg-key-change-passphrase.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-KEY-CHANGE-PASSPHRASE" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-KEY-CHANGE-PASSPHRASE" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.SH SYNOPSIS
@ -35,12 +35,12 @@ borg-key-change-passphrase \- Change repository key file passphrase
borg [common options] key change\-passphrase [options] [REPOSITORY]
.SH DESCRIPTION
.sp
The key files used for repository encryption are optionally passphrase
The key files used for repository encryption are optionally passphrase\-
protected. This command can be used to change this passphrase.
.sp
Please note that this command only changes the passphrase, but not any
secret protected by it (like e.g. encryption/MAC keys or chunker seed).
Thus, changing the passphrase after passphrase and borg key got compromised
secret protected by it (e.g., encryption/MAC keys or the chunker seed).
Thus, changing the passphrase after the passphrase and Borg key were compromised
does not protect future (nor past) backups to the same repository.
.SH OPTIONS
.sp

14
docs/man/borg-key-export.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-KEY-EXPORT" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-KEY-EXPORT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.SH SYNOPSIS
@ -36,15 +36,15 @@ borg [common options] key export [options] [REPOSITORY] [PATH]
.SH DESCRIPTION
.sp
If repository encryption is used, the repository is inaccessible
without the key. This command allows one to backup this essential key.
without the key. This command allows one to back up this essential key.
Note that the backup produced does not include the passphrase itself
(i.e. the exported key stays encrypted). In order to regain access to a
(i.e., the exported key stays encrypted). In order to regain access to a
repository, one needs both the exported key and the original passphrase.
.sp
There are three backup formats. The normal backup format is suitable for
digital storage as a file. The \fB\-\-paper\fP backup format is optimized
for printing and typing in while importing, with per line checks to
reduce problems with manual input. The \fB\-\-qr\-html\fP creates a printable
for printing and typing in while importing, with per\-line checks to
reduce problems with manual input. The \fB\-\-qr\-html\fP option creates a printable
HTML template with a QR code and a copy of the \fB\-\-paper\fP\-formatted key.
.sp
For repositories using keyfile encryption the key is saved locally
@ -52,9 +52,9 @@ on the system that is capable of doing backups. To guard against loss
of this key, the key needs to be backed up independently of the main
data backup.
.sp
For repositories using the repokey encryption the key is saved in the
For repositories using repokey encryption, the key is saved in the
repository in the config file. A backup is thus not strictly needed,
but guards against the repository becoming inaccessible if the file
but it guards against the repository becoming inaccessible if the file
is damaged for some reason.
.sp
Examples:

6
docs/man/borg-key-import.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-KEY-IMPORT" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-KEY-IMPORT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.SH SYNOPSIS
@ -39,12 +39,12 @@ This command restores a key previously backed up with the export command.
.sp
If the \fB\-\-paper\fP option is given, the import will be an interactive
process in which each line is checked for plausibility before
proceeding to the next line. For this format PATH must not be given.
proceeding to the next line. For this format, PATH must not be provided.
.sp
For repositories using keyfile encryption, the key file which \fBborg key
import\fP writes to depends on several factors. If the \fBBORG_KEY_FILE\fP
environment variable is set and non\-empty, \fBborg key import\fP creates
or overwrites that file named by \fB$BORG_KEY_FILE\fP\&. Otherwise, \fBborg
or overwrites the file named by \fB$BORG_KEY_FILE\fP\&. Otherwise, \fBborg
key import\fP searches in the \fB$BORG_KEYS_DIR\fP directory for a key file
associated with the repository. If a key file is found in
\fB$BORG_KEYS_DIR\fP, \fBborg key import\fP overwrites it; otherwise, \fBborg

10
docs/man/borg-key-migrate-to-repokey.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-KEY-MIGRATE-TO-REPOKEY" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-KEY-MIGRATE-TO-REPOKEY" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
.SH SYNOPSIS
@ -38,10 +38,10 @@ borg [common options] key migrate\-to\-repokey [options] [REPOSITORY]
This command migrates a repository from passphrase mode (removed in Borg 1.0)
to repokey mode.
.sp
You will be first asked for the repository passphrase (to open it in passphrase
mode). This is the same passphrase as you used to use for this repo before 1.0.
You will first be asked for the repository passphrase (to open it in passphrase
mode). This is the same passphrase you used for this repository before 1.0.
.sp
It will then derive the different secrets from this passphrase.
The different secrets will then be derived from this passphrase.
.sp
Then you will be asked for a new passphrase (twice, for safety). This
passphrase will be used to protect the repokey (which contains these same
@ -49,7 +49,7 @@ secrets in encrypted form). You may use the same passphrase as you used to
use, but you may also use a different one.
.sp
After migrating to repokey mode, you can change the passphrase at any time.
But please note: the secrets will always stay the same and they could always
Please note: the secrets will always stay the same, and they could always
be derived from your (old) passphrase\-mode passphrase.
.SH OPTIONS
.sp

2
docs/man/borg-key.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-KEY" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-KEY" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.SH SYNOPSIS

4
docs/man/borg-list.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-LIST" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-LIST" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.SH SYNOPSIS
@ -150,7 +150,7 @@ $ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern
.SH NOTES
.SS The FORMAT specifier syntax
.sp
The \fB\-\-format\fP option uses python\(aqs format string syntax <https://docs.python.org/3.9/library/string.html#formatstrings>
The \fB\-\-format\fP option uses Python\(aqs format string syntax <https://docs.python.org/3.9/library/string.html#formatstrings>
\&.
.sp
Examples:

19
docs/man/borg-mount.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-MOUNT" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-MOUNT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.SH SYNOPSIS
@ -39,20 +39,20 @@ This command mounts a repository or an archive as a FUSE filesystem.
This can be useful for browsing or restoring individual files.
.sp
When restoring, take into account that the current FUSE implementation does
not support special fs flags and ACLs.
not support special filesystem flags and ACLs.
.sp
When mounting a repository, the top directories will be named like the
archives and the directory structure below these will be loaded on\-demand from
the repository when entering these directories, so expect some delay.
.sp
Unless the \fB\-\-foreground\fP option is given the command will run in the
background until the filesystem is \fBumounted\fP\&.
background until the filesystem is \fBunmounted\fP\&.
.sp
Performance tips:
.INDENT 0.0
.IP \(bu 2
when doing a \(dqwhole repository\(dq mount:
do not enter archive dirs if not needed, this avoids on\-demand loading.
do not enter archive directories if not needed; this avoids on\-demand loading.
.IP \(bu 2
only mount a specific archive, not the whole repository.
.IP \(bu 2
@ -78,7 +78,7 @@ override the user and group ids of all files (i.e., \fBborg mount \-o
uid=1000,gid=1000\fP).
.sp
The man page references \fBuser_id\fP and \fBgroup_id\fP mount options
(implemented by fuse) which specify the user and group id of the mount owner
(implemented by FUSE) which specify the user and group id of the mount owner
(aka, the user who does the mounting). It is set automatically by libfuse (or
the filesystem if libfuse is not used). However, you should not specify these
manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all files,
@ -89,7 +89,7 @@ Additional mount options supported by borg:
.INDENT 0.0
.IP \(bu 2
\fBversions\fP: when used with a repository mount, this gives a merged, versioned
view of the files in the archives. EXPERIMENTAL, layout may change in future.
view of the files in the archives. EXPERIMENTAL; the layout may change in the future.
.IP \(bu 2
\fBallow_damaged_files\fP: by default damaged files (where missing chunks were
replaced with runs of zeros by \fBborg check \-\-repair\fP) are not readable and
@ -111,6 +111,13 @@ to unintentionally delete data.
.sp
When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
but other signals or crashes do not.
.sp
Debugging:
.sp
\fBborg mount\fP usually daemonizes and the daemon process sends stdout/stderr
to /dev/null. Thus, you need to either use \fB\-f / \-\-foreground\fP to make it stay
in the foreground and not daemonize, or use \fBBORG_LOGGING_CONF\fP to reconfigure
the logger to output to a file.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.

52
docs/man/borg-patterns.1
View file

@ -27,20 +27,31 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-PATTERNS" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-PATTERNS" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.SH DESCRIPTION
.sp
The path/filenames used as input for the pattern matching start from the
The path/filenames used as input for the pattern matching start with the
currently active recursion root. You usually give the recursion root(s)
when invoking borg and these can be either relative or absolute paths.
.sp
Starting with Borg 1.2, paths that are matched against patterns always
appear relative. If you give \fB/absolute/\fP as root, the paths going
into the matcher will start with \fBabsolute/\fP\&.
If you give \fB\&../../relative\fP as root, the paths will be normalized
as \fBrelative/\fP\&.
Be careful, your patterns must match the archived paths:
.INDENT 0.0
.IP \(bu 2
Archived paths never start with a leading slash (\(aq/\(aq), nor with \(aq.\(aq, nor with \(aq..\(aq.
.INDENT 2.0
.IP \(bu 2
When you back up absolute paths like \fB/home/user\fP, the archived
paths start with \fBhome/user\fP\&.
.IP \(bu 2
When you back up relative paths like \fB\&./src\fP, the archived paths
start with \fBsrc\fP\&.
.IP \(bu 2
When you back up relative paths like \fB\&../../src\fP, the archived paths
start with \fBsrc\fP\&.
.UNINDENT
.UNINDENT
.sp
A directory exclusion pattern can end either with or without a slash (\(aq/\(aq).
If it ends with a slash, such as \fIsome/path/\fP, the directory will be
@ -50,6 +61,8 @@ included but not its content. If it does not end with a slash, such as
Borg supports different pattern styles. To define a non\-default
style for a specific pattern, prefix it with two characters followed
by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP).
.sp
The default pattern style for \fB\-\-exclude\fP differs from \fB\-\-pattern\fP, see below.
.INDENT 0.0
.TP
.B Fnmatch <https://docs.python.org/3/library/fnmatch.html>
@ -148,6 +161,17 @@ Examples:
.INDENT 3.5
.sp
.EX
# Exclude a directory anywhere in the tree named \(ga\(gasteamapps/common\(ga\(ga
# (and everything below it), regardless of where it appears:
$ borg create \-e \(aqsh:**/steamapps/common/**\(aq backup /
# Exclude the contents of \(ga\(ga/home/user/.cache\(ga\(ga:
$ borg create \-e \(aqsh:home/user/.cache/**\(aq backup /home/user
$ borg create \-e home/user/.cache/ backup /home/user
# The file \(aq/home/user/.cache/important\(aq is *not* backed up:
$ borg create \-e home/user/.cache/ backup / /home/user/.cache/important
# Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
$ borg create \-e \(aq*.o\(aq backup /
@ -155,12 +179,6 @@ $ borg create \-e \(aq*.o\(aq backup /
# not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq:
$ borg create \-e \(aqhome/*/junk\(aq backup /
# Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
$ borg create \-e home/user/cache/ backup /
# The file \(aq/home/user/cache/important\(aq is *not* backed up:
$ borg create \-e home/user/cache/ backup / /home/user/cache/important
# The contents of directories in \(aq/home\(aq are not backed up when their name
# ends in \(aq.tmp\(aq
$ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq backup /
@ -192,11 +210,13 @@ A recursion root path starts with the prefix \fBR\fP, followed by a path
(a plain path, not a file pattern). Use this prefix to have the root
paths in the patterns file rather than as command line arguments.
.TP
.B Pattern style prefix \fBP\fP
.B Pattern style prefix \fBP\fP (only useful within patterns files)
To change the default pattern style, use the \fBP\fP prefix, followed by
the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
All patterns following this line will use this style until another style
is specified.
All patterns following this line in the same patterns file will use this
style until another style is specified or the end of the file is reached.
When the current patterns file is finished, the default pattern style will
reset.
.TP
.B Exclude pattern prefix \fB\-\fP
Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.

2
docs/man/borg-placeholders.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-PLACEHOLDERS" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-PLACEHOLDERS" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.SH DESCRIPTION

34
docs/man/borg-prune.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-PRUNE" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-PRUNE" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.SH SYNOPSIS
@ -74,9 +74,9 @@ up to 7 most recent days with backups (days without backups do not count).
The rules are applied from secondly to yearly, and backups selected by previous
rules do not count towards those of later rules. The time that each backup
starts is used for pruning purposes. Dates and times are interpreted in
the local timezone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit. As of borg
1.2.0, borg will retain the oldest archive if any of the secondly, minutely,
the local time zone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit. As of Borg
1.2.0, Borg will retain the oldest archive if any of the secondly, minutely,
hourly, daily, weekly, monthly, quarterly, or yearly rules was not otherwise
able to meet its retention target. This enables the first chronological archive
to continue aging until it is replaced by a newer archive that meets the
@ -164,42 +164,42 @@ only consider archive names matching the glob. sh: rules apply (without actually
.UNINDENT
.SH EXAMPLES
.sp
Be careful, prune is a potentially dangerous command, it will remove backup
Be careful: prune is a potentially dangerous command; it will remove backup
archives.
.sp
The default of prune is to apply to \fBall archives in the repository\fP unless
you restrict its operation to a subset of the archives using \fB\-\-glob\-archives\fP\&.
When using \fB\-\-glob\-archives\fP, be careful to choose a good matching pattern \-
e.g. do not use \(dqfoo*\(dq if you do not also want to match \(dqfoobar\(dq.
By default, prune applies to \fBall archives in the repository\fP unless you
restrict its operation to a subset of the archives using \fB\-\-glob\-archives\fP\&.
When using \fB\-\-glob\-archives\fP, be careful to choose a good matching pattern —
for example, do not use \(dqfoo*\(dq if you do not also want to match \(dqfoobar\(dq.
.sp
It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP
first so you will see what it would do without it actually doing anything.
first, so you can see what it would do without actually doing anything.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Keep 7 end of day and 4 additional end of week archives.
# Keep 7 end\-of\-day and 4 additional end\-of\-week archives.
# Do a dry\-run without actually deleting anything.
$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo
# Same as above but only apply to archive names starting with the hostname
# of the machine followed by a \(dq\-\(dq character:
$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-glob\-archives=\(aq{hostname}\-*\(aq /path/to/repo
# actually free disk space:
# Actually free disk space:
$ borg compact /path/to/repo
# Keep 7 end of day, 4 additional end of week archives,
# and an end of month archive for every month:
# Keep 7 end\-of\-day, 4 additional end\-of\-week archives,
# and an end\-of\-month archive for every month:
$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
# Keep all backups in the last 10 days, 4 additional end of week archives,
# and an end of month archive for every month:
# Keep all backups in the last 10 days, 4 additional end\-of\-week archives,
# and an end\-of\-month archive for every month:
$ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
.EE
.UNINDENT
.UNINDENT
.sp
There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\&.
There is also a visual example of pruning in \fBdocs/misc/prune\-example.txt\fP\&.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-compact(1)\fP

30
docs/man/borg-recreate.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-RECREATE" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-RECREATE" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.SH SYNOPSIS
@ -37,7 +37,7 @@ borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
.sp
Recreate the contents of existing archives.
.sp
recreate is a potentially dangerous function and might lead to data loss
Recreate is a potentially dangerous operation and might lead to data loss
(if used wrongly). BE VERY CAREFUL!
.sp
Important: Repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&.
@ -55,34 +55,34 @@ Due to how Borg stores compressed size information this might display
incorrect information for archives that were not recreated at the same time.
There is no risk of data loss by this.
.sp
\fB\-\-chunker\-params\fP will re\-chunk all files in the archive, this can be
\fB\-\-chunker\-params\fP will re\-chunk all files in the archive; this can be
used to have upgraded Borg 0.xx or Attic archives deduplicate with
Borg 1.x archives.
.sp
\fBUSE WITH CAUTION.\fP
Depending on the PATHs and patterns given, recreate can be used to permanently
delete files from archives.
When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are
When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHs are
interpreted. See \fIlist_item_flags\fP in \fBborg create\fP for details.
.sp
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
\(dq<ARCHIVE>.recreate\(dq. The new archive will have a different archive ID.
.sp
With \fB\-\-target\fP the original archive is not replaced, instead a new archive is created.
With \fB\-\-target\fP the original archive is not replaced; instead, a new archive is created.
.sp
When rechunking (or recompressing), space usage can be substantial \- expect
at least the entire deduplicated size of the archives using the previous
chunker (or compression) params.
chunker (or compression) parameters.
.sp
If you recently ran borg check \-\-repair and it had to fix lost chunks with all\-zero
If you recently ran \fBborg check \-\-repair\fP and it had to fix lost chunks with all\-zero
replacement chunks, please first run another backup for the same data and re\-run
borg check \-\-repair afterwards to heal any archives that had lost chunks which are
\fBborg check \-\-repair\fP afterwards to heal any archives that had lost chunks which are
still generated from the input data.
.sp
Important: running borg recreate to re\-chunk will remove the chunks_healthy
Important: running \fBborg recreate\fP to re\-chunk will remove the \fBchunks_healthy\fP
metadata of all items with replacement chunks, so healing will not be possible
any more after re\-chunking (it is also unlikely it would ever work: due to the
anymore after re\-chunking (it is also unlikely it would ever work: due to the
change of chunking parameters, the missing chunk likely will never be seen again
even if you still have the data that produced it).
.SH OPTIONS
@ -165,22 +165,22 @@ rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH
.INDENT 3.5
.sp
.EX
# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
# Make old (Attic/Borg 0.xx) archives deduplicate with Borg 1.x archives.
# Archives created with Borg 1.1+ and the default chunker params are skipped
# (archive ID stays the same).
$ borg recreate /mnt/backup \-\-chunker\-params default \-\-progress
# Create a backup with little but fast compression
# Create a backup with low but fast compression.
$ borg create /mnt/backup::archive /some/files \-\-compression lz4
# Then compress it \- this might take longer, but the backup has already completed,
# Then compress it — this might take longer, but the backup has already completed,
# so no inconsistencies from a long\-running backup job.
$ borg recreate /mnt/backup::archive \-\-recompress \-\-compression zlib,9
# Remove unwanted files from all archives in a repository.
# Note the relative path for the \-\-exclude option \- archives only contain relative paths.
# Note the relative path for the \-\-exclude option — archives only contain relative paths.
$ borg recreate /mnt/backup \-\-exclude home/icke/Pictures/drunk_photos
# Change archive comment
# Change the archive comment.
$ borg create \-\-comment \(dqThis is a comment\(dq /mnt/backup::archivename ~
$ borg info /mnt/backup::archivename
Name: archivename

2
docs/man/borg-rename.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-RENAME" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-RENAME" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.SH SYNOPSIS

57
docs/man/borg-serve.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-SERVE" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-SERVE" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.SH SYNOPSIS
@ -56,7 +56,7 @@ Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository
.UNINDENT
.SH EXAMPLES
.sp
\fBborg serve\fP has special support for ssh forced commands (see \fBauthorized_keys\fP
\fBborg serve\fP has special support for SSH forced commands (see \fBauthorized_keys\fP
example below): if the environment variable SSH_ORIGINAL_COMMAND is set it will
ignore some options given on the command line and use the values from the
variable instead. This only applies to a carefully controlled allowlist of safe
@ -71,22 +71,22 @@ giving up and aborting the operation when another process is holding a lock.
.UNINDENT
.sp
Environment variables (such as BORG_XXX) contained in the original
command sent by the client are \fInot\fP interpreted, but ignored. If BORG_XXX environment
variables should be set on the \fBborg serve\fP side, then these must be set in system\-specific
command sent by the client are \fInot\fP interpreted; they are ignored. If BORG_XXX environment
variables need to be set on the \fBborg serve\fP side, then these must be set in system\-specific
locations like \fB/etc/environment\fP or in the forced command itself (example below).
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
# Allow an SSH key pair to only run borg, and only have access to /path/to/repo.
# Use key options to disable unneeded and potentially dangerous SSH functionality.
# This will help to secure an automated remote backup system.
# This helps secure an automated remote backup system.
$ cat ~/.ssh/authorized_keys
command=\(dqborg serve \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rsa AAAAB3[...]
# Set a BORG_XXX environment variable on the \(dqborg serve\(dq side
# Set a BORG_XXX environment variable on the \(ga\(gaborg serve\(ga\(ga side.
$ cat ~/.ssh/authorized_keys
command=\(dqexport BORG_XXX=value; borg serve [...]\(dq,restrict ssh\-rsa [...]
command=\(dqBORG_XXX=value borg serve [...]\(dq,restrict ssh\-rsa [...]
.EE
.UNINDENT
.UNINDENT
@ -94,13 +94,14 @@ command=\(dqexport BORG_XXX=value; borg serve [...]\(dq,restrict ssh\-rsa [...]
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The examples above use the \fBrestrict\fP directive. This does automatically
block potential dangerous ssh features, even when they are added in a future
update. Thus, this option should be preferred.
The examples above use the \fBrestrict\fP directive and assume a POSIX\-compliant
shell set as the user\(aqs login shell.
This automatically blocks potentially dangerous SSH features, even when
they are added in a future update. Thus, this option should be preferred.
.sp
If you\(aqre using openssh\-server < 7.2, however, you have to explicitly specify
the ssh features to restrict and cannot simply use the restrict option as it
has been introduced in v7.2. We recommend to use
If you\(aqre using OpenSSH server < 7.2, however, you have to explicitly specify
the SSH features to restrict and cannot simply use the \fBrestrict\fP option as it
was introduced in v7.2. We recommend using
\fBno\-port\-forwarding,no\-X11\-forwarding,no\-pty,no\-agent\-forwarding,no\-user\-rc\fP
in this case.
.UNINDENT
@ -126,9 +127,9 @@ Host backupserver
.UNINDENT
.UNINDENT
.sp
Replacing \fBbackupserver\fP with the hostname, FQDN or IP address of the borg server.
Replace \fBbackupserver\fP with the hostname, FQDN, or IP address of the Borg server.
.sp
This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the ssh client process will be terminated, causing the borg process to terminate gracefully.
This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the SSH client process will be terminated, causing the Borg process to terminate gracefully.
.sp
On the server side\(aqs \fBsshd\fP configuration file (typically \fB/etc/ssh/sshd_config\fP):
.INDENT 0.0
@ -141,11 +142,31 @@ ClientAliveCountMax 30
.UNINDENT
.UNINDENT
.sp
This will cause the server to send a keep alive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository.
This will cause the server to send a keepalive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository.
.sp
If you then run borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the borg serve processes to terminate after the SSH connection is torn down after the 300 second wait for the keepalives to fail.
If you then run Borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the \fBborg serve\fP processes to terminate after the SSH connection is torn down following the 300\-second wait for the keepalives to fail.
.sp
You may, of course, modify the timeout values demonstrated above to values that suit your environment and use case.
.sp
When the client is untrusted, it is a good idea to set the backup
user\(aqs shell to a simple implementation (\fB/bin/sh\fP is only an example and may or may
not be such a simple implementation):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
chsh \-s /bin/sh BORGUSER
.EE
.UNINDENT
.UNINDENT
.sp
Because the configured shell is used by openssh <https://www.openssh.com/>
to execute the command configured through the \fBauthorized_keys\fP file
using \fB\(dq$SHELL\(dq \-c \(dq$COMMAND\(dq\fP,
setting a minimal shell implementation reduces the attack surface
compared to when a feature\-rich and complex shell implementation is
used.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP

6
docs/man/borg-umount.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-UMOUNT" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-UMOUNT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.SH SYNOPSIS
@ -35,7 +35,7 @@ borg-umount \- un-mount the FUSE filesystem
borg [common options] umount [options] MOUNTPOINT
.SH DESCRIPTION
.sp
This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
This command unmounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.
.sp
This is a convenience wrapper that just calls the platform\-specific shell
command \- usually this is either umount or fusermount \-u.
@ -106,7 +106,7 @@ $ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,n
$ mount /tmp/myrepo
$ mount /tmp/myarchive
$ ls /tmp/myrepo
root\-2016\-02\-01 root\-2016\-02\-2015
root\-2016\-02\-01 root\-2016\-02\-15
$ ls /tmp/myarchive
bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
.EE

20
docs/man/borg-upgrade.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-UPGRADE" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-UPGRADE" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-upgrade \- upgrade a repository from a previous version
.SH SYNOPSIS
@ -60,8 +60,8 @@ 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,
Archives created by newer borg versions 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.
@ -101,7 +101,7 @@ with the old chunks in the upgraded repository.
See \fB\-\-chunker\-params\fP option of \fBborg create\fP and \fBborg recreate\fP\&.
.sp
\fBborg upgrade\fP will change the magic strings in the repository\(aqs
segments to match the new Borg magic strings. The keyfiles found in
segments to match the new Borg magic strings. The key files found in
$ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
.sp
@ -109,11 +109,11 @@ 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.
due to the cache re\-sync.
.sp
Upgrade should be able to resume if interrupted, although it
will still iterate over all segments. If you want to start
from scratch, use \fIborg delete\fP over the copied repository to
from scratch, use \fBborg delete\fP over the copied repository to
make sure the cache files are also removed:
.INDENT 0.0
.INDENT 3.5
@ -190,13 +190,13 @@ no key file found for repository
.EE
.UNINDENT
.UNINDENT
.SS Upgrading a passphrase encrypted attic repo
.SS Upgrading a passphrase\-encrypted Attic repo
.sp
attic offered a \(dqpassphrase\(dq encryption mode, but this was removed in borg 1.0
Attic offered a \(dqpassphrase\(dq encryption mode, but this was removed in Borg 1.0
and replaced by the \(dqrepokey\(dq mode (which stores the passphrase\-protected
encryption key into the repository config).
encryption key in the repository config).
.sp
Thus, to upgrade a \(dqpassphrase\(dq attic repo to a \(dqrepokey\(dq borg repo, 2 steps
Thus, to upgrade a \(dqpassphrase\(dq Attic repo to a \(dqrepokey\(dq Borg repo, two steps
are needed, in this order:
.INDENT 0.0
.IP \(bu 2

14
docs/man/borg-version.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-VERSION" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-VERSION" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-version \- Display the borg client / borg server version
.SH SYNOPSIS
@ -35,12 +35,12 @@ borg-version \- Display the borg client / borg server version
borg [common options] version [options] [REPOSITORY]
.SH DESCRIPTION
.sp
This command displays the borg client version / borg server version.
This command displays the Borg client version / Borg server version.
.sp
If a local repo is given, the client code directly accesses the repository,
If a local repository is given, the client code directly accesses the repository,
thus we show the client version also as the server version.
.sp
If a remote repo is given (e.g. ssh:), the remote borg is queried and
If a remote repository is given (e.g., ssh:), the remote Borg is queried and
its version is displayed as the server version.
.sp
Examples:
@ -59,10 +59,10 @@ $ borg version ssh://borg@borgbackup:repo
.UNINDENT
.UNINDENT
.sp
Due to the version tuple format used in borg client/server negotiation, only
a simplified version is displayed (as provided by borg.version.format_version).
Due to the version tuple format used in Borg client/server negotiation, only
a simplified version is displayed (as provided by \fBborg.version.format_version\fP).
.sp
There is also borg \-\-version to display a potentially more precise client version.
There is also \fBborg \-\-version\fP to display a potentially more precise client version.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.

10
docs/man/borg-with-lock.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG-WITH-LOCK" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG-WITH-LOCK" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.SH SYNOPSIS
@ -46,15 +46,15 @@ $ borg with\-lock /mnt/borgrepo rsync \-av /mnt/borgrepo /somewhere/else/borgrep
.UNINDENT
.sp
It will first try to acquire the lock (make sure that no other operation is
running in the repo), then execute the given command as a subprocess and wait
for its termination, release the lock and return the user command\(aqs return
code as borg\(aqs return code.
running in the repository), then execute the given command as a subprocess and wait
for its termination, release the lock, and return the user command\(aqs return
code as Borg\(aqs return code.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you copy a repository with the lock held, the lock will be present in
the copy. Thus, before using borg on the copy from a different host,
the copy. Thus, before using Borg on the copy from a different host,
you need to use \(dqborg break\-lock\(dq on the copied repository, because
Borg is cautious and does not automatically remove stale locks made by a different host.
.UNINDENT

10
docs/man/borg.1
View file

@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORG" "1" "2025-04-18" "" "borg backup tool"
.TH "BORG" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.SH SYNOPSIS
@ -461,6 +461,12 @@ When set to no (default: yes), system information (like OS, Python version, ...)
exceptions is not shown.
Please only use for good reasons as it makes issues harder to analyze.
.TP
.B BORG_MSGPACK_VERSION_CHECK
Controls whether Borg checks the \fBmsgpack\fP version.
The default is \fByes\fP (strict check). Set to \fBno\fP to disable the version check and
allow any installed \fBmsgpack\fP version. Use this at your own risk; malfunctioning or
incompatible \fBmsgpack\fP versions may cause subtle bugs or repository data corruption.
.TP
.B BORG_FUSE_IMPL
Choose the lowlevel FUSE implementation borg shall use for \fBborg mount\fP\&.
This is a comma\-separated list of implementation names, they are tried in the
@ -957,7 +963,7 @@ aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms.
The BSDs define additional flags.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP for common command line options
\fIborg\-common(1)\fP for common command\-line options
.sp
\fIborg\-init(1)\fP,
\fIborg\-create(1)\fP, \fIborg\-mount(1)\fP, \fIborg\-extract(1)\fP,

19
docs/man/borgfs.1
View file

@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BORGFS" "1" "2025-04-18" "" "borg backup tool"
.TH "BORGFS" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borgfs \- Mount archive or an entire repository as a FUSE filesystem
.SH SYNOPSIS
@ -39,20 +39,20 @@ This command mounts a repository or an archive as a FUSE filesystem.
This can be useful for browsing or restoring individual files.
.sp
When restoring, take into account that the current FUSE implementation does
not support special fs flags and ACLs.
not support special filesystem flags and ACLs.
.sp
When mounting a repository, the top directories will be named like the
archives and the directory structure below these will be loaded on\-demand from
the repository when entering these directories, so expect some delay.
.sp
Unless the \fB\-\-foreground\fP option is given the command will run in the
background until the filesystem is \fBumounted\fP\&.
background until the filesystem is \fBunmounted\fP\&.
.sp
Performance tips:
.INDENT 0.0
.IP \(bu 2
when doing a \(dqwhole repository\(dq mount:
do not enter archive dirs if not needed, this avoids on\-demand loading.
do not enter archive directories if not needed; this avoids on\-demand loading.
.IP \(bu 2
only mount a specific archive, not the whole repository.
.IP \(bu 2
@ -78,7 +78,7 @@ override the user and group ids of all files (i.e., \fBborg mount \-o
uid=1000,gid=1000\fP).
.sp
The man page references \fBuser_id\fP and \fBgroup_id\fP mount options
(implemented by fuse) which specify the user and group id of the mount owner
(implemented by FUSE) which specify the user and group id of the mount owner
(aka, the user who does the mounting). It is set automatically by libfuse (or
the filesystem if libfuse is not used). However, you should not specify these
manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all files,
@ -89,7 +89,7 @@ Additional mount options supported by borg:
.INDENT 0.0
.IP \(bu 2
\fBversions\fP: when used with a repository mount, this gives a merged, versioned
view of the files in the archives. EXPERIMENTAL, layout may change in future.
view of the files in the archives. EXPERIMENTAL; the layout may change in the future.
.IP \(bu 2
\fBallow_damaged_files\fP: by default damaged files (where missing chunks were
replaced with runs of zeros by \fBborg check \-\-repair\fP) are not readable and
@ -111,6 +111,13 @@ to unintentionally delete data.
.sp
When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
but other signals or crashes do not.
.sp
Debugging:
.sp
\fBborg mount\fP usually daemonizes and the daemon process sends stdout/stderr
to /dev/null. Thus, you need to either use \fB\-f / \-\-foreground\fP to make it stay
in the foreground and not daemonize, or use \fBBORG_LOGGING_CONF\fP to reconfigure
the logger to output to a file.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.

16
docs/usage/benchmark_crud.rst.inc
View file

@ -17,7 +17,7 @@ borg benchmark crud
+-------------------------------------------------------+----------------+----------------------------------------------+
| | ``REPOSITORY`` | repository to use for benchmark (must exist) |
+-------------------------------------------------------+----------------+----------------------------------------------+
| | ``PATH`` | path were to create benchmark input data |
| | ``PATH`` | path where to create benchmark input data |
+-------------------------------------------------------+----------------+----------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@ -37,7 +37,7 @@ borg benchmark crud
REPOSITORY
repository to use for benchmark (must exist)
PATH
path were to create benchmark input data
path where to create benchmark input data
:ref:`common_options`
@ -48,7 +48,7 @@ Description
This command benchmarks borg CRUD (create, read, update, delete) operations.
It creates input data below the given PATH and backups this data into the given REPO.
It creates input data below the given PATH and backs up this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg-benchmark-crud\* there.
@ -64,17 +64,17 @@ thus the measurement results do not necessarily reflect performance with real da
Also, due to the kind of content used, no compression is used in these benchmarks.
C- == borg create (1st archive creation, no compression, do not use files cache)
C-Z- == all-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
C-R- == random files. no dedup, measuring throughput through all processing stages.
C-Z- == all-zero files. full deduplication; this primarily measures reader/chunker/hasher.
C-R- == random files. no deduplication, measuring throughput through all processing stages.
R- == borg extract (extract archive, dry-run, do everything, but do not write files to disk)
R-Z- == all zero files. Measuring heavily duplicated files.
R-Z- == all-zero files. Measuring heavily duplicated files.
R-R- == random files. No duplication here, measuring throughput through all processing
stages, except writing to disk.
U- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
The throughput value is kind of virtual here, it does not actually read the file.
U-Z- == needs to check the 2 all-zero chunks' existence in the repo.
U-Z- == needs to check the two all-zero chunks' existence in the repo.
U-R- == needs to check existence of a lot of different chunks in the repo.
D- == borg delete archive (delete last remaining archive, measure deletion + compaction)
@ -82,4 +82,4 @@ D- == borg delete archive (delete last remaining archive, measure deletion + com
D-R- == many chunks to delete / many segments to compact/remove.
Please note that there might be quite some variance in these measurements.
Try multiple measurements and having a otherwise idle machine (and network, if you use it).
Try multiple measurements and have an otherwise idle machine (and network, if you use it).

4
docs/usage/break-lock.rst.inc
View file

@ -43,5 +43,5 @@ Description
~~~~~~~~~~~
This command breaks the repository and cache locks.
Please use carefully and only while no borg process (on any machine) is
trying to access the Cache or the Repository.
Please use with care and only when no borg process (on any machine) is
trying to access the cache or the repository.

8
docs/usage/check.rst.inc
View file

@ -126,7 +126,7 @@ archive checks, nor enable repair mode. Consequently, if you want to use
**Warning:** Please note that partial repository checks (i.e. running it with
``--max-duration``) can only perform non-cryptographic checksum checks on the
segment files. A full repository check (i.e. without ``--max-duration``) can
also do a repository index check. Enabling partial repository checks excepts
also do a repository index check. Enabling partial repository checks excludes
archive checks for the same reason. Therefore partial checks may be useful with
very large repositories only where a full check would take too long.
@ -135,13 +135,13 @@ opposed to checking the CRC32 of the segment) of data, which means reading the
data from the repository, decrypting and decompressing it. It is a complete
cryptographic verification and hence very time consuming, but will detect any
accidental and malicious corruption. Tamper-resistance is only guaranteed for
encrypted repositories against attackers without access to the keys. You can
not use ``--verify-data`` with ``--repository-only``.
encrypted repositories against attackers without access to the keys. You cannot
use ``--verify-data`` with ``--repository-only``.
About repair mode
+++++++++++++++++
The check command is a readonly task by default. If any corruption is found,
The check command is a read-only task by default. If any corruption is found,
Borg will report the issue and proceed with checking. To actually repair the
issues found, pass ``--repair``.

9
docs/usage/compact.rst.inc
View file

@ -72,8 +72,15 @@ A segment is compacted if the amount of saved space is above the percentage valu
given by the ``--threshold`` option. If omitted, a threshold of 10% is used.
When using ``--verbose``, borg will output an estimate of the freed space.
For maximum compaction, use ``--threshold 0``. This will compact whenever any
space can be saved and thus rewrites the most data; it can be much slower on
large repositories. Using ``--threshold 1`` usually achieves nearly the same
result significantly faster. Higher thresholds (e.g. the default 10) trade
compaction thoroughness for speed. Note: ``--threshold 100`` will effectively
compact nothing.
After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``
to clean up the numerous 17byte commit-only segments that borg 1.1 did not clean up
to clean up the numerous 17-byte commit-only segments that borg 1.1 did not clean up
due to a bug. It is enough to do that once per repository. After cleaning up the
commits, borg will also do a normal compaction.

2
docs/usage/config.rst.inc
View file

@ -68,7 +68,7 @@ This command gets and sets options in a local repository or cache config file.
For security reasons, this command only works on local repositories.
To delete a config value entirely, use ``--delete``. To list the values
of the configuration file or the default values, use ``--list``. To get an existing
of the configuration file or the default values, use ``--list``. To get an existing
key, pass only the key name. To set a key, pass both the key name and
the new value. Keys can be specified in the format "section.name" or
simply "name"; the section will default to "repository" and "cache" for

63
docs/usage/create.rst.inc
View file

@ -99,6 +99,8 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--files-changed MODE`` | specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--read-special`` | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
@ -175,6 +177,7 @@ borg create
--noxattrs do not read and store xattrs into archive
--sparse detect sparse holes in input (supported only by fixed chunker)
--files-cache MODE operate files cache in MODE. default: ctime,size,inode
--files-changed MODE specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime
--read-special open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
@ -191,18 +194,18 @@ Description
This command creates a backup archive containing all files found while recursively
traversing all paths specified. Paths are added to the archive as they are given,
that means if relative paths are desired, the command has to be run from the correct
which means that if relative paths are desired, the command has to be run from the correct
directory.
The slashdot hack in paths (recursion roots) is triggered by using ``/./``:
``/this/gets/stripped/./this/gets/archived`` means to process that fs object, but
``/this/gets/stripped/./this/gets/archived`` means to process that filesystem object, but
strip the prefix on the left side of ``./`` from the archived items (in this case,
``this/gets/archived`` will be the path in the archived item).
When giving '-' as path, borg will read data from standard input and create a
file 'stdin' in the created archive from that data. In some cases it's more
appropriate to use --content-from-command, however. See section *Reading from
stdin* below for details.
When giving '-' as a path, Borg will read data from standard input and create a
file 'stdin' in the created archive from that data. In some cases, it is more
appropriate to use ``--content-from-command``. See section "Reading from stdin"
below for details.
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
@ -222,41 +225,49 @@ the files cache.
This comparison can operate in different modes as given by ``--files-cache``:
- ctime,size,inode (default)
- mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4)
- mtime,size,inode (default behavior of borg versions older than 1.1.0rc4)
- ctime,size (ignore the inode number)
- mtime,size (ignore the inode number)
- rechunk,ctime (all files are considered modified - rechunk, cache ctime)
- rechunk,mtime (all files are considered modified - rechunk, cache mtime)
- disabled (disable the files cache, all files considered modified - rechunk)
inode number: better safety, but often unstable on network filesystems
inode number: better safety, but often unstable on network file systems
Normally, detecting file modifications will take inode information into
consideration to improve the reliability of file change detection.
This is problematic for files located on sshfs and similar network file
systems which do not provide stable inode numbers, such files will always
This is problematic for files located on SSHFS and similar network file
systems which do not provide stable inode numbers; such files will always
be considered modified. You can use modes without `inode` in this case to
improve performance, but reliability of change detection might be reduced.
improve performance, but the reliability of change detection might be reduced.
ctime vs. mtime: safety vs. speed
- ctime is a rather safe way to detect changes to a file (metadata and contents)
as it can not be set from userspace. But, a metadata-only change will already
as it cannot be set from user space. However, a metadata-only change will already
update the ctime, so there might be some unnecessary chunking/hashing even
without content changes. Some filesystems do not support ctime (change time).
E.g. doing a chown or chmod to a file will change its ctime.
without content changes. Some file systems do not support ctime (change time).
For example, doing a chown or chmod to a file will change its ctime.
- mtime usually works and only updates if file contents were changed. But mtime
can be arbitrarily set from userspace, e.g. to set mtime back to the same value
can be arbitrarily set from user space, e.g., to set mtime back to the same value
it had before a content change happened. This can be used maliciously as well as
well-meant, but in both cases mtime based cache modes can be problematic.
well-meant, but in both cases mtime-based cache modes can be problematic.
The mount points of filesystems or filesystem snapshots should be the same for every
The ``--files-changed`` option controls how Borg detects if a file has changed during backup:
- ctime (default): Use ctime to detect changes. This is the safest option.
- mtime: Use mtime to detect changes.
- disabled: Disable the "file has changed while we backed it up" detection completely.
This is not recommended unless you know what you're doing, as it could lead to
inconsistent backups if files change during the backup process.
The mount points of file systems or file system snapshots should be the same for every
creation of a new archive to ensure fast operation. This is because the file cache that
is used to determine changed files quickly uses absolute filenames.
is used to determine changed files quickly uses absolute file names.
If this is not possible, consider creating a bind mount to a stable location.
The ``--progress`` option shows (from left to right) Original, Compressed and Deduplicated
(O, C and D, respectively), then the Number of files (N) processed so far, followed by
(O, C and D, respectively), then the number of files (N) processed so far, followed by
the currently processed path.
When using ``--stats``, you will get some statistics about how much data was
@ -284,15 +295,15 @@ only include the objects specified by ``--exclude-if-present`` in your backup,
and not include any other contents of the containing folder, this can be enabled
through using the ``--keep-exclude-tags`` option.
The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them).
It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its
The ``-x`` or ``--one-file-system`` option excludes directories that are mount points (and everything in them).
It detects mount points by comparing the device number from the output of ``stat()`` of the directory and its
parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different
from the device number of their parent.
In general: be aware that there are directories with device number different from their parent, which the kernel
does not consider a mountpoint and also the other way around.
Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
macOS examples are the apfs mounts of a typical macOS installation.
In general: be aware that there are directories with device numbers different from their parent, which the kernel
does not consider mount points, and vice versa.
Linux examples for this are bind mounts (possibly same device number, but always a mount point) and all
subvolumes of a Btrfs file system (different device numbers from the parent but not necessarily mount points).
macOS examples are the APFS mounts of a typical macOS installation.
Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended.

148
docs/usage/diff.rst.inc
View file

@ -12,43 +12,45 @@ borg diff
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``REPO::ARCHIVE1`` | repository location and ARCHIVE1 name |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``ARCHIVE2`` | ARCHIVE2 name (no repository location allowed) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``PATH`` | paths of items inside the archives to compare; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--numeric-ids`` | only consider numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--same-chunker-params`` | Override check of chunker parameters. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--sort`` | Sort the output lines by file path. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--content-only`` | Only compare differences in content (exclude metadata differences) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--json-lines`` | Format output as JSON Lines. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| **Include/Exclude options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--pattern PATTERN`` | include/exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``REPO::ARCHIVE1`` | repository location and ARCHIVE1 name |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``ARCHIVE2`` | ARCHIVE2 name (no repository location allowed) |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths of items inside the archives to compare; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--numeric-ids`` | only consider numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--same-chunker-params`` | Override check of chunker parameters. |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort`` | Sort the output by path (deprecated, use --sort-by=path). |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by FIELD[,FIELD...]`` | Advanced sorting: specify field(s) to sort by. Accepts a comma-separated list. Prefix with > for descending or < for ascending (default). |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--content-only`` | Only compare differences in content (exclude metadata differences) |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json-lines`` | Format output as JSON Lines. |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| **Include/Exclude options** |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--pattern PATTERN`` | include/exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line |
+-------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@ -69,12 +71,13 @@ borg diff
options
--numeric-owner deprecated, use ``--numeric-ids`` instead
--numeric-ids only consider numeric user and group identifiers
--same-chunker-params Override check of chunker parameters.
--sort Sort the output lines by file path.
--content-only Only compare differences in content (exclude metadata differences)
--json-lines Format output as JSON Lines.
--numeric-owner deprecated, use ``--numeric-ids`` instead
--numeric-ids only consider numeric user and group identifiers
--same-chunker-params Override check of chunker parameters.
--sort Sort the output by path (deprecated, use --sort-by=path).
--sort-by FIELD[,FIELD...] Advanced sorting: specify field(s) to sort by. Accepts a comma-separated list. Prefix with > for descending or < for ascending (default).
--content-only Only compare differences in content (exclude metadata differences)
--json-lines Format output as JSON Lines.
:ref:`common_options`
@ -93,16 +96,63 @@ Description
This command finds differences (file contents, user/group/mode) between archives.
A repository location and an archive name must be specified for REPO::ARCHIVE1.
ARCHIVE2 is just another archive name in same repository (no repository location
ARCHIVE2 is just another archive name in the same repository (no repository location
allowed).
For archives created with Borg 1.1 or newer diff automatically detects whether
the archives are created with the same chunker params. If so, only chunk IDs
What is compared
+++++++++++++++++
For each matching item in both archives, Borg reports:
- Content changes: total added/removed bytes within files. If chunker parameters are comparable,
Borg compares chunk IDs quickly; otherwise, it compares the content.
- Metadata changes: user, group, mode, and other metadata shown inline like
"[old_mode -> new_mode]" for mode changes. Use ``--content-only`` to suppress metadata changes.
- Added/removed items: printed as "added SIZE path" or "removed SIZE path".
Output formats
++++++++++++++
The default (text) output shows one line per changed path, e.g.::
+135 B -252 B [ -rw-r--r-- -> -rwxr-xr-x ] path/to/file
JSON Lines output (``--json-lines``) prints one JSON object per changed path, e.g.::
{"path": "PATH", "changes": [
{"type": "modified", "added": BYTES, "removed": BYTES},
{"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"},
{"type": "added", "size": SIZE},
{"type": "removed", "size": SIZE}
]}
Only actual changes are included in the "changes" list. For example, a modified entry with
added=0 and removed=0 is omitted.
Sorting
++++++++
Use ``--sort-by FIELDS`` where FIELDS is a comma-separated list of fields.
Sorts are applied stably from last to first in the given list. Prepend ">" for
descending, "<" (or no prefix) for ascending, for example ``--sort-by=">size_added,path"``.
Supported fields include:
- path: the item path
- size_added: total bytes added for the item content
- size_removed: total bytes removed for the item content
- size_diff: size_added - size_removed (net content change)
- size: size of the item as stored in ARCHIVE2 (0 for removed items)
- user, group, uid, gid, ctime, mtime: taken from the item state in ARCHIVE2 when present
- ctime_diff, mtime_diff: timestamp difference (archive2 - archive1)
The ``--sort`` option is deprecated and only sorts by path.
Performance considerations
++++++++++++++++++++++++++
For archives created with Borg 1.1 or newer, diff automatically detects whether
the archives were created with the same chunker parameters. If so, only chunk IDs
are compared, which is very fast.
For archives prior to Borg 1.1 chunk contents are compared by default.
If you did not create the archives with different chunker params,
For archives prior to Borg 1.1, chunk contents are compared by default.
If you did not create the archives with different chunker parameters,
pass ``--same-chunker-params``.
Note that the chunker params changed from Borg 0.xx to 1.0.
Note that the chunker parameters changed from Borg 0.xx to 1.0.
For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.

2
docs/usage/export-tar.rst.inc
View file

@ -106,7 +106,7 @@ BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
Timestamp resolution is limited to whole seconds, not the nanosecond resolution
otherwise supported by Borg.
A ``--sparse`` option (as found in borg extract) is not supported.
A ``--sparse`` option (as found in ``borg extract``) is not supported.
By default the entire archive is extracted but a subset of files and directories
can be selected by passing a list of ``PATHs`` as arguments.

20
docs/usage/extract.rst.inc
View file

@ -101,16 +101,20 @@ borg extract
Description
~~~~~~~~~~~
This command extracts the contents of an archive. By default the entire
archive is extracted but a subset of files and directories can be selected
by passing a list of ``PATHs`` as arguments. The file selection can further
be restricted by using the ``--exclude`` option.
This command extracts the contents of an archive.
By default, the entire archive is extracted, but a subset of files and directories
can be selected by passing a list of ``PATH`` arguments. The default interpretation
for the paths to extract is `pp:` which is a literal path-prefix match. If you want
to use e.g. a wildcard, you must select a different pattern style such as `sh:` or
`fm:`. See :ref:`borg_patterns` for more information.
The file selection can be further restricted by using the ``--exclude`` option.
For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
By using ``--dry-run``, you can do all extraction steps except actually writing the
output data: reading metadata and data chunks from the repo, checking the hash/hmac,
decrypting, decompressing.
output data: reading metadata and data chunks from the repository, checking the hash/HMAC,
decrypting, and decompressing.
``--progress`` can be slower than no progress display, since it makes one additional
pass over the archive metadata.
@ -121,5 +125,5 @@ pass over the archive metadata.
so make sure you ``cd`` to the right place before calling ``borg extract``.
When parent directories are not extracted (because of using file/directory selection
or any other reason), borg can not restore parent directories' metadata, e.g. owner,
group, permission, etc.
or any other reason), Borg cannot restore parent directories' metadata, e.g., owner,
group, permissions, etc.

44
docs/usage/help.rst.inc
View file

@ -6,15 +6,20 @@ borg help patterns
~~~~~~~~~~~~~~~~~~
The path/filenames used as input for the pattern matching start from the
The path/filenames used as input for the pattern matching start with the
currently active recursion root. You usually give the recursion root(s)
when invoking borg and these can be either relative or absolute paths.
Starting with Borg 1.2, paths that are matched against patterns always
appear relative. If you give ``/absolute/`` as root, the paths going
into the matcher will start with ``absolute/``.
If you give ``../../relative`` as root, the paths will be normalized
as ``relative/``.
Be careful, your patterns must match the archived paths:
- Archived paths never start with a leading slash ('/'), nor with '.', nor with '..'.
- When you back up absolute paths like ``/home/user``, the archived
paths start with ``home/user``.
- When you back up relative paths like ``./src``, the archived paths
start with ``src``.
- When you back up relative paths like ``../../src``, the archived paths
start with ``src``.
A directory exclusion pattern can end either with or without a slash ('/').
If it ends with a slash, such as `some/path/`, the directory will be
@ -25,6 +30,8 @@ Borg supports different pattern styles. To define a non-default
style for a specific pattern, prefix it with two characters followed
by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
The default pattern style for ``--exclude`` differs from ``--pattern``, see below.
`Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
This is the default style for ``--exclude`` and ``--exclude-from``.
These patterns use a variant of shell pattern syntax, with '\*' matching
@ -112,6 +119,17 @@ run ``borg create --list --dry-run ...``.
Examples::
# Exclude a directory anywhere in the tree named ``steamapps/common``
# (and everything below it), regardless of where it appears:
$ borg create -e 'sh:**/steamapps/common/**' backup /
# Exclude the contents of ``/home/user/.cache``:
$ borg create -e 'sh:home/user/.cache/**' backup /home/user
$ borg create -e home/user/.cache/ backup /home/user
# The file '/home/user/.cache/important' is *not* backed up:
$ borg create -e home/user/.cache/ backup / /home/user/.cache/important
# Exclude '/home/user/file.o' but not '/home/user/file.odt':
$ borg create -e '*.o' backup /
@ -119,12 +137,6 @@ Examples::
# not '/home/user/importantjunk' or '/etc/junk':
$ borg create -e 'home/*/junk' backup /
# Exclude the contents of '/home/user/cache' but not the directory itself:
$ borg create -e home/user/cache/ backup /
# The file '/home/user/cache/important' is *not* backed up:
$ borg create -e home/user/cache/ backup / /home/user/cache/important
# The contents of directories in '/home' are not backed up when their name
# ends in '.tmp'
$ borg create --exclude 're:^home/[^/]+\.tmp/' backup /
@ -152,11 +164,13 @@ Root path prefix ``R``
(a plain path, not a file pattern). Use this prefix to have the root
paths in the patterns file rather than as command line arguments.
Pattern style prefix ``P``
Pattern style prefix ``P`` (only useful within patterns files)
To change the default pattern style, use the ``P`` prefix, followed by
the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``).
All patterns following this line will use this style until another style
is specified.
All patterns following this line in the same patterns file will use this
style until another style is specified or the end of the file is reached.
When the current patterns file is finished, the default pattern style will
reset.
Exclude pattern prefix ``-``
Use the prefix ``-``, followed by a pattern, to define an exclusion.

8
docs/usage/import-tar.rst.inc
View file

@ -91,9 +91,9 @@ Description
This command creates a backup archive from a tarball.
When giving '-' as path, Borg will read a tar stream from standard input.
When giving '-' as a path, Borg will read a tar stream from standard input.
By default (--tar-filter=auto) Borg will detect whether the file is compressed
By default (``--tar-filter=auto``) Borg will detect whether the file is compressed
based on its file extension and pipe the file through an appropriate filter:
- .tar.gz or .tgz: gzip -d
@ -102,11 +102,11 @@ based on its file extension and pipe the file through an appropriate filter:
- .tar.zstd or .tar.zst: zstd -d
- .tar.lz4: lz4 -d
Alternatively, a --tar-filter program may be explicitly specified. It should
Alternatively, a ``--tar-filter`` program may be explicitly specified. It should
read compressed data from stdin and output an uncompressed tar stream on
stdout.
Most documentation of borg create applies. Note that this command does not
Most documentation of ``borg create`` applies. Note that this command does not
support excluding files.
import-tar is a lossy conversion:

4
docs/usage/info.rst.inc
View file

@ -74,11 +74,11 @@ This command displays detailed information about the specified archive or reposi
Please note that the deduplicated sizes of the individual archives do not add
up to the deduplicated size of the repository ("all archives"), because the two
are meaning different things:
mean different things:
This archive / deduplicated size = amount of data stored ONLY for this archive
= unique chunks of this archive.
All archives / deduplicated size = amount of data stored in the repo
All archives / deduplicated size = amount of data stored in the repository
= all chunks in the repository.
Borg archives can only contain a limited amount of file metadata.

275
docs/usage/init.rst.inc
View file

@ -59,135 +59,214 @@ borg init
Description
~~~~~~~~~~~
This command initializes an empty repository. A repository is a filesystem
directory containing the deduplicated data from zero or more archives.
This command initializes an empty repository. A repository is a
filesystem directory containing the deduplicated data from zero or more
archives.
Encryption mode TLDR
++++++++++++++++++++
Encryption mode TL;DR
+++++++++++++++++++++
The encryption mode can only be configured when creating a new repository -
you can neither configure it on a per-archive basis nor change the
encryption mode of an existing repository.
The encryption mode can only be configured when creating a new
repository. You can neither configure encryption on a per-archive
basis, nor change the encryption mode of an existing repository. You
should thus take possible future use into account when deciding on an
encryption mode.
Use ``repokey``::
As a general rule of thumb, use ``repokey`` with a strong passphrase:
borg init --encryption repokey /path/to/repo
Or ``repokey-blake2`` depending on which is faster on your client machines (see below)::
However, there are many reasons to choose differently. See the section
below for details. In any case, Borg will:
borg init --encryption repokey-blake2 /path/to/repo
1. Ask you to enter a unique and strong passphrase.
2. Create a random Borg key (which actually consists of three random
secrets, see :ref:`key_files` for details).
3. Encrypt the Borg key with your passphrase.
4. Store the encrypted Borg key inside the repository directory (with
``repokey`` and ``repokey-blake2`` modes; with ``keyfile`` and
``keyfile-blake2`` modes the Borg key is stored in your home
directory instead, see below). Since we usually have to assume that
an attacker could gain access to the repository (that's why we
encrypt the data in the first place), choosing a strong and unique
passphrase is absolutely crucial.
5. Encrypt and sign your backups with the Borg key to prevent anyone
from reading or forging them unless they have the Borg key *and*
know the passphrase.
6. Use the Borg key to decrypt and thus access the data stored in your
repository, e.g. when extracting files. The contents can also be
verified to detect accidental corruption or malicious tampering.
Borg will:
As you can see, you always need *both* the Borg key and passphrase to
access your data. Thus it's crucial to keep a backup of your key
*outside* both the repository and the system you create backups of.
You can easily run into a "leaving your keys inside your car" situation
otherwise. See :ref:`borg_key_export` to create a backup of your key
(e.g., by printing it on paper).
1. Ask you to come up with a passphrase.
2. Create a borg key (which contains 3 random secrets. See :ref:`key_files`).
3. Encrypt the key with your passphrase.
4. Store the encrypted borg key inside the repository directory (in the repo config).
This is why it is essential to use a secure passphrase.
5. Encrypt and sign your backups to prevent anyone from reading or forging them unless they
have the key and know the passphrase. Make sure to keep a backup of
your key **outside** the repository - do not lock yourself out by
"leaving your keys inside your car" (see :ref:`borg_key_export`).
For remote backups the encryption is done locally - the remote machine
never sees your passphrase, your unencrypted key or your unencrypted files.
Chunking and id generation are also based on your key to improve
your privacy.
6. Use the key when extracting files to decrypt them and to verify that the contents of
the backups have not been accidentally or maliciously altered.
Encryption is done locally - i.e., if you back up to a remote machine,
the remote machine neither sees your passphrase, nor your unencrypted
Borg key, nor your unencrypted files. Chunking and ID generation are
based on your key to improve privacy.
**About hardware acceleration:**
Borg encrypts data with AES, which is pretty fast thanks to hardware
acceleration on basically all modern Intel, AMD, and ARM CPUs since
around the early 2010s (very cheap models since the mid-2010s).
As the hashing algorithm, Borg can use either SHA256 or BLAKE2b. ARM
CPUs support hardware-accelerated SHA256 hashing since ARMv7 with NEON
(around 2011), or ARMv8 (around 2013). AMD CPUs support it since Zen 1
(around 2017), i.e. all AMD Ryzen CPUs. Intel CPUs support it since Ice
Lake on mobile (10th gen, around 2021), and Rocket Lake on desktop
(11th gen, around 2021). Very cheap models have received support a few
years later. If your CPU doesn't support hardware-accelerated SHA256
hashing, you might want to give BLAKE2b hashing a try - it's likely
faster then. So, instead of ``repokey`` mode, use ``repokey-blake2``
(or any of the other ``-blake2`` modes for that matter).
Hardware acceleration is always used automatically when available.
Picking a passphrase
++++++++++++++++++++
Make sure you use a good passphrase. Not too short, not too simple. The real
encryption / decryption key is encrypted with / locked by your passphrase.
If an attacker gets your key, he can't unlock and use it without knowing the
passphrase.
Make sure you use a good passphrase. Not too short, not too simple. The
real encryption / decryption key is encrypted with / locked by your
passphrase. If an attacker gets your borg key, they can't unlock and use
it without knowing the passphrase.
Be careful with special or non-ascii characters in your passphrase:
Be careful with special or non-ASCII characters in your passphrase:
- Borg processes the passphrase as unicode (and encodes it as utf-8),
so it does not have problems dealing with even the strangest characters.
- BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
- Borg processes the passphrase as Unicode (and encodes it as UTF-8), so
it does not have problems dealing with even the strangest characters.
- BUT: that does not necessarily apply to your OS / VM / keyboard
configuration.
So better use a long passphrase made from simple ascii chars than one that
includes non-ascii stuff or characters that are hard/impossible to enter on
a different keyboard layout.
So it is better to use a long passphrase made from simple ASCII
characters than one that includes non-ASCII characters or characters
that are hard or impossible to enter on a different keyboard layout.
You can change your passphrase for existing repos at any time, it won't affect
the encryption/decryption key or other secrets.
You can change your passphrase for existing repositories at any time; it
won't affect the encryption/decryption key or other secrets. See
:ref:`borg_key_change-passphrase`.
More encryption modes
+++++++++++++++++++++
More about encryption modes
+++++++++++++++++++++++++++
Only use ``--encryption none`` if you are OK with anyone who has access to
your repository being able to read your backups and tamper with their
contents without you noticing.
Choosing the right encryption mode isn't always easy and many factors
can change which mode is best for you. However, note that you can't
really do anything *wrong* if you choose ``repokey`` with a strong
passphrase. So, if you're not sure, choose ``repokey`` (or
``repokey-blake2``, depending on your hardware, see above).
If you want "passphrase and having-the-key" security, use ``--encryption keyfile``.
The key will be stored in your home directory (in ``~/.config/borg/keys``).
If you do **not** want to encrypt the contents of your backups, but still
want to detect malicious tampering use ``--encryption authenticated``.
To normally work with ``authenticated`` repos, you will need the passphrase, but
there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs.
If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``,
``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups
the hashing is done on your local machine.
Borg supports the following encryption modes:
.. nanorst: inline-fill
.. class:: borg-encryption-table
+----------+---------------+------------------------+--------------------------+
| Hash/MAC | Not encrypted | Not encrypted, | Encrypted (AEAD w/ AES) |
| | no auth | but authenticated | and authenticated |
+----------+---------------+------------------------+--------------------------+
| SHA-256 | none | `authenticated` | repokey |
| | | | keyfile |
+----------+---------------+------------------------+--------------------------+
| BLAKE2b | n/a | `authenticated-blake2` | `repokey-blake2` |
| | | | `keyfile-blake2` |
+----------+---------------+------------------------+--------------------------+
+----------+-------------------+--------------------------+-------------------------+
| Hash/MAC | Not Encrypted | Encrypted (AEAD w/ AES) |
+ +-------------------+--------------------------+-------------------------+
| | Not Authenticated | Authenticated |
+==========+===================+==========================+=========================+
| SHA-256 | ``none`` | ``authenticated`` | ``repokey`` |
| | | | ``keyfile`` |
+----------+-------------------+--------------------------+-------------------------+
| BLAKE2b | n/a | ``authenticated-blake2`` | ``repokey-blake2`` |
| | | | ``keyfile-blake2`` |
+----------+-------------------+--------------------------+-------------------------+
.. nanorst: inline-replace
Modes `marked like this` in the above table are new in Borg 1.1 and are not
backwards-compatible with Borg 1.0.x.
Borg 1.0 and older support ``none``, ``repokey``, and ``keyfile``
modes only. If you need such old clients to be able to access your
repo, you can't use any of the other modes.
On modern Intel/AMD CPUs (except very cheap ones), AES is usually
hardware-accelerated.
BLAKE2b is faster than SHA256 on Intel/AMD 64-bit CPUs
(except AMD Ryzen and future CPUs with SHA extensions),
which makes `authenticated-blake2` faster than `none` and `authenticated`.
**About modes without encryption:**
On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster
than BLAKE2b-256 there. NEON accelerates AES as well.
Avoid using ``none`` mode. If you think about using ``none`` mode,
please reconsider and be absolutely sure. Using any mode other than
``none`` allows Borg to detect accidental corruption or malicious
tampering with the repo. It also prevents denial-of-service attacks
against clients. Instead of ``none`` mode, you likely want to use
``authenticated`` mode, or ``repokey`` or ``keyfile`` modes with an
empty passphrase instead (see below).
Hardware acceleration is always used automatically when available.
If you don't want to encrypt your data, use ``authenticated`` or
``authenticated-blake2`` modes. These modes require a passphrase in
normal operation, but in emergency situations you can access the repo
without the passphrase with ``BORG_WORKAROUNDS=authenticated_no_key``
(see :ref:`environment-variables`).
`repokey` and `keyfile` use AES-CTR-256 for encryption and HMAC-SHA256 for
authentication in an encrypt-then-MAC (EtM) construction. The chunk ID hash
is HMAC-SHA256 as well (with a separate key).
These modes are compatible with Borg 1.0.x.
If you just don't want to choose a passphrase, use ``keyfile`` or
``keyfile-blake2`` modes with an empty passphrase. These modes are
generally safe even without a passphrase, but keeping an offsite
backup of the Borg key is also important then. See below for details.
`repokey-blake2` and `keyfile-blake2` are also authenticated encryption modes,
but use BLAKE2b-256 instead of HMAC-SHA256 for authentication. The chunk ID
hash is a keyed BLAKE2b-256 hash.
These modes are new and *not* compatible with Borg 1.0.x.
If you can assure that an attacker can't gain access to your repo, e.g.
when independently encrypting your repository disk or filesystem, you
can think about using ``repokey`` or ``repokey-blake2`` modes with an
empty passphrase. However, keep in mind that if an attacker still
somehow manages to gain access, they have full access to your repo. In
such situations choosing ``repokey`` over ``authenticated`` mode has
the advantage of allowing you to add a passphrase later using
:ref:`borg_key_change-passphrase`.
`authenticated` mode uses no encryption, but authenticates repository contents
through the same HMAC-SHA256 hash as the `repokey` and `keyfile` modes (it uses it
as the chunk ID hash). The key is stored like `repokey`.
This mode is new and *not* compatible with Borg 1.0.x.
**About modes with encryption:**
`authenticated-blake2` is like `authenticated`, but uses the keyed BLAKE2b-256 hash
from the other blake2 modes.
This mode is new and *not* compatible with Borg 1.0.x.
With ``repokey`` and ``repokey-blake2`` modes the key is stored with
the repo and encrypted with your passphrase. If an attacker gains
access to your repo and knows the passphrase, he can access and tamper
with the repo. The repo's security thus relies on the strength of your
passphrase. Creating an offsite backup of your Borg key (e.g., by
printing it on paper) is recommended, see :ref:`borg_key_export`.
`none` mode uses no encryption and no authentication. It uses SHA256 as chunk
ID hash. This mode is not recommended, you should rather consider using an authenticated
or authenticated/encrypted mode. This mode has possible denial-of-service issues
when running ``borg create`` on contents controlled by an attacker.
Use it only for new repositories where no encryption is wanted **and** when compatibility
with 1.0.x is important. If compatibility with 1.0.x is not important, use
`authenticated-blake2` or `authenticated` instead.
This mode is compatible with Borg 1.0.x.
If you're thinking about storing the passphrase on the disk of the
system you're backing up, consider using the ``keyfile`` method
instead. It generally provides the same or better security then.
With ``keyfile`` and ``keyfile-blake2`` modes the key is stored on your
local machine (in ``~/.config/borg/keys``) instead. An attacker gaining
access to your repo then needs both the Borg key, and your passphrase to
access and tamper with the repo. However, if you lose the key, you lose
access to the repo, too. You **must** create an offsite backup of your
Borg key, e.g. by printing it on paper. Storing a copy of the Borg key
on the system you're creating backups of is **NOT** sufficient. Use
:ref:`borg_key_export` to create the backup.
The ``keyfile`` and ``keyfile-blake2`` modes allow for "passphrase and
having-the-key" security when using a strong passphrase, but can also
be used with an empty passphrase. Storing a (easily readable)
passphrase on the disk of the system you're backing up with
``keyfile`` and ``keyfile-blake2`` modes adds no security over using an
empty passphrase.
**Technical details:**
``repokey`` and ``keyfile`` use AES-CTR-256 for encryption and
HMAC-SHA256 for authentication in an encrypt-then-MAC (EtM)
construction. The chunk ID hash is HMAC-SHA256 (with a separate key).
These modes are compatible with all Borg versions.
``repokey-blake2`` and ``keyfile-blake2`` are also authenticated
encryption modes, but use BLAKE2b-256 instead of HMAC-SHA256 for
authentication. The chunk ID hash is a keyed BLAKE2b-256 hash. These
modes are only compatible with Borg 1.1 and later.
``authenticated`` mode uses no encryption, but authenticates repo
contents through the same HMAC-SHA256 hash as the ``repokey`` and
``keyfile`` modes (it uses it as the chunk ID hash). The key is stored
like ``repokey`` within the repo. This mode is only compatible with
Borg 1.1 and later.
``authenticated-blake2`` is like ``authenticated``, but uses the keyed
BLAKE2b-256 hash from the other BLAKE2b modes. This mode is only
compatible with Borg 1.1 and later.
``none`` mode uses no encryption and no authentication. It uses SHA256
as chunk ID hash. This mode is not recommended. You should instead
consider using an authenticated or authenticated/encrypted mode. This
mode has possible denial-of-service issues when running ``borg create``
on contents controlled by an attacker. See above for alternatives.
This mode is compatible with all Borg versions.

6
docs/usage/key_change-passphrase.rst.inc
View file

@ -42,10 +42,10 @@ borg key change-passphrase
Description
~~~~~~~~~~~
The key files used for repository encryption are optionally passphrase
The key files used for repository encryption are optionally passphrase-
protected. This command can be used to change this passphrase.
Please note that this command only changes the passphrase, but not any
secret protected by it (like e.g. encryption/MAC keys or chunker seed).
Thus, changing the passphrase after passphrase and borg key got compromised
secret protected by it (e.g., encryption/MAC keys or the chunker seed).
Thus, changing the passphrase after the passphrase and Borg key were compromised
does not protect future (nor past) backups to the same repository.

12
docs/usage/key_export.rst.inc
View file

@ -58,15 +58,15 @@ Description
~~~~~~~~~~~
If repository encryption is used, the repository is inaccessible
without the key. This command allows one to backup this essential key.
without the key. This command allows one to back up this essential key.
Note that the backup produced does not include the passphrase itself
(i.e. the exported key stays encrypted). In order to regain access to a
(i.e., the exported key stays encrypted). In order to regain access to a
repository, one needs both the exported key and the original passphrase.
There are three backup formats. The normal backup format is suitable for
digital storage as a file. The ``--paper`` backup format is optimized
for printing and typing in while importing, with per line checks to
reduce problems with manual input. The ``--qr-html`` creates a printable
for printing and typing in while importing, with per-line checks to
reduce problems with manual input. The ``--qr-html`` option creates a printable
HTML template with a QR code and a copy of the ``--paper``-formatted key.
For repositories using keyfile encryption the key is saved locally
@ -74,9 +74,9 @@ on the system that is capable of doing backups. To guard against loss
of this key, the key needs to be backed up independently of the main
data backup.
For repositories using the repokey encryption the key is saved in the
For repositories using repokey encryption, the key is saved in the
repository in the config file. A backup is thus not strictly needed,
but guards against the repository becoming inaccessible if the file
but it guards against the repository becoming inaccessible if the file
is damaged for some reason.
Examples::

4
docs/usage/key_import.rst.inc
View file

@ -58,12 +58,12 @@ This command restores a key previously backed up with the export command.
If the ``--paper`` option is given, the import will be an interactive
process in which each line is checked for plausibility before
proceeding to the next line. For this format PATH must not be given.
proceeding to the next line. For this format, PATH must not be provided.
For repositories using keyfile encryption, the key file which ``borg key
import`` writes to depends on several factors. If the ``BORG_KEY_FILE``
environment variable is set and non-empty, ``borg key import`` creates
or overwrites that file named by ``$BORG_KEY_FILE``. Otherwise, ``borg
or overwrites the file named by ``$BORG_KEY_FILE``. Otherwise, ``borg
key import`` searches in the ``$BORG_KEYS_DIR`` directory for a key file
associated with the repository. If a key file is found in
``$BORG_KEYS_DIR``, ``borg key import`` overwrites it; otherwise, ``borg

8
docs/usage/key_migrate-to-repokey.rst.inc
View file

@ -45,10 +45,10 @@ Description
This command migrates a repository from passphrase mode (removed in Borg 1.0)
to repokey mode.
You will be first asked for the repository passphrase (to open it in passphrase
mode). This is the same passphrase as you used to use for this repo before 1.0.
You will first be asked for the repository passphrase (to open it in passphrase
mode). This is the same passphrase you used for this repository before 1.0.
It will then derive the different secrets from this passphrase.
The different secrets will then be derived from this passphrase.
Then you will be asked for a new passphrase (twice, for safety). This
passphrase will be used to protect the repokey (which contains these same
@ -56,5 +56,5 @@ secrets in encrypted form). You may use the same passphrase as you used to
use, but you may also use a different one.
After migrating to repokey mode, you can change the passphrase at any time.
But please note: the secrets will always stay the same and they could always
Please note: the secrets will always stay the same, and they could always
be derived from your (old) passphrase-mode passphrase.

2
docs/usage/list.rst.inc
View file

@ -112,7 +112,7 @@ For more help on include/exclude patterns, see the :ref:`borg_patterns` command
The FORMAT specifier syntax
+++++++++++++++++++++++++++
The ``--format`` option uses python's `format string syntax
The ``--format`` option uses Python's `format string syntax
<https://docs.python.org/3.9/library/string.html#formatstrings>`_.
Examples:

19
docs/usage/mount.rst.inc
View file

@ -114,19 +114,19 @@ This command mounts a repository or an archive as a FUSE filesystem.
This can be useful for browsing or restoring individual files.
When restoring, take into account that the current FUSE implementation does
not support special fs flags and ACLs.
not support special filesystem flags and ACLs.
When mounting a repository, the top directories will be named like the
archives and the directory structure below these will be loaded on-demand from
the repository when entering these directories, so expect some delay.
Unless the ``--foreground`` option is given the command will run in the
background until the filesystem is ``umounted``.
background until the filesystem is ``unmounted``.
Performance tips:
- when doing a "whole repository" mount:
do not enter archive dirs if not needed, this avoids on-demand loading.
do not enter archive directories if not needed; this avoids on-demand loading.
- only mount a specific archive, not the whole repository.
- only mount specific paths in a specific archive, not the complete archive.
@ -149,7 +149,7 @@ override the user and group ids of all files (i.e., ``borg mount -o
uid=1000,gid=1000``).
The man page references ``user_id`` and ``group_id`` mount options
(implemented by fuse) which specify the user and group id of the mount owner
(implemented by FUSE) which specify the user and group id of the mount owner
(aka, the user who does the mounting). It is set automatically by libfuse (or
the filesystem if libfuse is not used). However, you should not specify these
manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
@ -159,7 +159,7 @@ manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
Additional mount options supported by borg:
- ``versions``: when used with a repository mount, this gives a merged, versioned
view of the files in the archives. EXPERIMENTAL, layout may change in future.
view of the files in the archives. EXPERIMENTAL; the layout may change in the future.
- ``allow_damaged_files``: by default damaged files (where missing chunks were
replaced with runs of zeros by ``borg check --repair``) are not readable and
return EIO (I/O error). Set this option to read such files.
@ -177,4 +177,11 @@ Unmounting in these cases could cause an active rsync or similar process
to unintentionally delete data.
When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
but other signals or crashes do not.
but other signals or crashes do not.
Debugging:
``borg mount`` usually daemonizes and the daemon process sends stdout/stderr
to /dev/null. Thus, you need to either use ``-f / --foreground`` to make it stay
in the foreground and not daemonize, or use ``BORG_LOGGING_CONF`` to reconfigure
the logger to output to a file.

6
docs/usage/prune.rst.inc
View file

@ -144,9 +144,9 @@ up to 7 most recent days with backups (days without backups do not count).
The rules are applied from secondly to yearly, and backups selected by previous
rules do not count towards those of later rules. The time that each backup
starts is used for pruning purposes. Dates and times are interpreted in
the local timezone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit. As of borg
1.2.0, borg will retain the oldest archive if any of the secondly, minutely,
the local time zone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit. As of Borg
1.2.0, Borg will retain the oldest archive if any of the secondly, minutely,
hourly, daily, weekly, monthly, quarterly, or yearly rules was not otherwise
able to meet its retention target. This enables the first chronological archive
to continue aging until it is replaced by a newer archive that meets the

18
docs/usage/recreate.rst.inc
View file

@ -117,7 +117,7 @@ Description
Recreate the contents of existing archives.
recreate is a potentially dangerous function and might lead to data loss
Recreate is a potentially dangerous operation and might lead to data loss
(if used wrongly). BE VERY CAREFUL!
Important: Repository disk space is **not** freed until you run ``borg compact``.
@ -135,33 +135,33 @@ Due to how Borg stores compressed size information this might display
incorrect information for archives that were not recreated at the same time.
There is no risk of data loss by this.
``--chunker-params`` will re-chunk all files in the archive, this can be
``--chunker-params`` will re-chunk all files in the archive; this can be
used to have upgraded Borg 0.xx or Attic archives deduplicate with
Borg 1.x archives.
**USE WITH CAUTION.**
Depending on the PATHs and patterns given, recreate can be used to permanently
delete files from archives.
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHs are
interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
"<ARCHIVE>.recreate". The new archive will have a different archive ID.
With ``--target`` the original archive is not replaced, instead a new archive is created.
With ``--target`` the original archive is not replaced; instead, a new archive is created.
When rechunking (or recompressing), space usage can be substantial - expect
at least the entire deduplicated size of the archives using the previous
chunker (or compression) params.
chunker (or compression) parameters.
If you recently ran borg check --repair and it had to fix lost chunks with all-zero
If you recently ran ``borg check --repair`` and it had to fix lost chunks with all-zero
replacement chunks, please first run another backup for the same data and re-run
borg check --repair afterwards to heal any archives that had lost chunks which are
``borg check --repair`` afterwards to heal any archives that had lost chunks which are
still generated from the input data.
Important: running borg recreate to re-chunk will remove the chunks_healthy
Important: running ``borg recreate`` to re-chunk will remove the ``chunks_healthy``
metadata of all items with replacement chunks, so healing will not be possible
any more after re-chunking (it is also unlikely it would ever work: due to the
anymore after re-chunking (it is also unlikely it would ever work: due to the
change of chunking parameters, the missing chunk likely will never be seen again
even if you still have the data that produced it).

2
docs/usage/umount.rst.inc
View file

@ -42,7 +42,7 @@ borg umount
Description
~~~~~~~~~~~
This command un-mounts a FUSE filesystem that was mounted with ``borg mount``.
This command unmounts a FUSE filesystem that was mounted with ``borg mount``.
This is a convenience wrapper that just calls the platform-specific shell
command - usually this is either umount or fusermount -u.

10
docs/usage/upgrade.rst.inc
View file

@ -96,8 +96,8 @@ 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,
Archives created by newer borg versions 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.
@ -139,7 +139,7 @@ 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
segments to match the new Borg magic strings. The key files found in
$ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
@ -147,11 +147,11 @@ 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.
due to the cache re-sync.
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
from scratch, use ``borg delete`` over the copied repository to
make sure the cache files are also removed::
borg delete borg

12
docs/usage/version.rst.inc
View file

@ -42,12 +42,12 @@ borg version
Description
~~~~~~~~~~~
This command displays the borg client version / borg server version.
This command displays the Borg client version / Borg server version.
If a local repo is given, the client code directly accesses the repository,
If a local repository is given, the client code directly accesses the repository,
thus we show the client version also as the server version.
If a remote repo is given (e.g. ssh:), the remote borg is queried and
If a remote repository is given (e.g., ssh:), the remote Borg is queried and
its version is displayed as the server version.
Examples::
@ -60,7 +60,7 @@ Examples::
$ borg version ssh://borg@borgbackup:repo
1.4.0a / 1.2.7
Due to the version tuple format used in borg client/server negotiation, only
a simplified version is displayed (as provided by borg.version.format_version).
Due to the version tuple format used in Borg client/server negotiation, only
a simplified version is displayed (as provided by ``borg.version.format_version``).
There is also borg --version to display a potentially more precise client version.
There is also ``borg --version`` to display a potentially more precise client version.

8
docs/usage/with-lock.rst.inc
View file

@ -57,13 +57,13 @@ This command runs a user-specified command while locking the repository. For exa
$ borg with-lock /mnt/borgrepo rsync -av /mnt/borgrepo /somewhere/else/borgrepo
It will first try to acquire the lock (make sure that no other operation is
running in the repo), then execute the given command as a subprocess and wait
for its termination, release the lock and return the user command's return
code as borg's return code.
running in the repository), then execute the given command as a subprocess and wait
for its termination, release the lock, and return the user command's return
code as Borg's return code.
.. note::
If you copy a repository with the lock held, the lock will be present in
the copy. Thus, before using borg on the copy from a different host,
the copy. Thus, before using Borg on the copy from a different host,
you need to use "borg break-lock" on the copied repository, because
Borg is cautious and does not automatically remove stale locks made by a different host.