borgbackup/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-10-12 02:11:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10444 from ThomasWaldmann/rel200b25

Browse Source 
Release 2.0.0b25
This commit is contained in:
TW
2026-09-28 00:05:29 +02:00
committed by GitHub
parent 64e6f2fda3 82744708c0
commit f1ca9f8325
72 changed files with 942 additions and 496 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/changes.rst
+2 -2
View File
@@ -163,8 +163,8 @@ Compatibility notes:
Change Log 2.x
==============
Version 2.0.0b25 (not released yet)
-----------------------------------
Version 2.0.0b25 (2026-09-27)
-----------------------------
Breaking changes (you must create new repos for b25):
docs/man/borg-analyze.1
+1 -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-analyze" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-analyze" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-analyze \- Analyzes archives.
.SH SYNOPSIS
docs/man/borg-benchmark-cpu.1
+1 -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-benchmark-cpu" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-benchmark-cpu" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-benchmark-cpu \- Benchmark CPU-bound operations.
.SH SYNOPSIS
docs/man/borg-benchmark-crud.1
+1 -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-benchmark-crud" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-benchmark-crud" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.SH SYNOPSIS
docs/man/borg-benchmark.1
+1 -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-benchmark" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-benchmark" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-benchmark \- benchmark command
.SH SYNOPSIS
docs/man/borg-break-lock.1
+4 -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-break-lock" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-break-lock" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-break-lock \- Breaks the repository lock (for example, if it was left by a dead Borg process).
.SH SYNOPSIS
@@ -39,6 +39,9 @@ borg [common options] break\-lock [options]
This command breaks the repository and cache locks.
Use with care and only when no Borg process (on any machine) is
trying to access the cache or the repository.
.sp
The repository lock objects are protected by the repository key, so this
command needs the key.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
docs/man/borg-check.1
+36 -18
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-check" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-check" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-check \- Checks repository consistency.
.SH SYNOPSIS
@@ -41,15 +41,20 @@ It consists of two major steps:
.INDENT 0.0
.IP 1. 3
Checking the consistency of the repository itself. The objects in the \fBindex/\fP
and \fBpacks/\fP namespaces are named by the sha256 hash of their content, so such
and \fBpacks/\fP namespaces are named by the store hash of their content, so such
an object is intact if and only if the hash of its content still equals its name.
The check verifies the (small) index objects first and, only if they are intact,
all packs. It also cross\-checks the chunk index against the packs present in the
repository to detect referenced but missing packs. Bit rot and other types of
accidental damage can be detected this way, but as sha256 content\-addressing is
not a MAC, this step does not detect tampering. Running the repository check can
accidental damage can be detected this way, but as content\-addressing is
not a MAC, this step does not detect tampering of the packs. The index objects
are also authenticated with the key when they are loaded for that cross\-check.
A corrupt index ends the check after this step, as the archives check needs it,
unless \fB\-\-repair\fP is given (see below). This step also verifies the repository
defaults object (see \fBborg repo\-create\fP): it must be present and authenticate
with the key. Running the repository check can
be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
For rest:// repositories, the server computes the hashes, so the pack contents do
For \%<ssh://> repositories, the server computes the hashes, so the pack contents do
not have to travel over the network. For other remote backends, borg usually has
to read (download) the objects to hash them.
.IP 2. 3
@@ -73,6 +78,10 @@ Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run
repository checks only, or pass \fB\-\-archives\-only\fP to run the archive checks
only.
.sp
\fBborg check\fP always needs the key, \fB\-\-repository\-only\fP included: it loads
the key (asking for the passphrase, if needed) before it checks anything and
aborts if the key can not be loaded.
.sp
The \fB\-\-max\-age\fP option makes the check reuse the results of previous
repository checks: packs whose intact result is younger than the given
timespan (e.g. \fB\-\-max\-age=4w\fP or \fB\-\-max\-age=12m\fP) are skipped, spreading
@@ -132,16 +141,18 @@ description for more details about the format string).
If the \fBborg check\fP process receives a SIGINT signal (Ctrl\-C), it stops at the
next safe boundary, leaving the repository and its chunk index in a consistent state.
The repository check stops after the current pack; \fB\-\-verify\-data\fP and
\fB\-\-find\-lost\-archives\fP stop after the current chunk; a \fB\-\-repair\fP archive check
stops between whole archives. Results recorded before the interrupt are kept, so a later
check does not re\-verify those packs until they are due again. With \fB\-\-repair\fP, an
interrupted archive check may leave some archives already repaired and others not yet
processed, so run \fBborg check \-\-repair\fP again to finish.
\fB\-\-find\-lost\-archives\fP stop after the current chunk; the archive check stops after the
current archive item, with \fB\-\-repair\fP between whole archives. Results recorded before
the interrupt are kept, so a later check does not re\-verify those packs until they are
due again. With \fB\-\-repair\fP, an interrupted archive check may leave some archives already
repaired and others not yet processed, so run \fBborg check \-\-repair\fP again to finish.
.sp
During a \fB\-\-repair\fP run, the archive check first rebuilds the chunk index from the
packs, and, if the key must be recovered, scans chunks for it. These phases do not yet
respond to SIGINT, so on a large repository a Ctrl\-C during them may appear to have no
effect until they finish.
\fBborg check\fP rebuilds the chunk index from the packs when \fB\-\-repair\fP is given or when
the stored index cannot be used. Ctrl\-C stops that rebuild after the current object and
discards the partial index: it lacks chunks that are still in the repository, so the check
would report them as lost. After a \fB\-\-repair\fP that stored or deleted chunks, borg re\-reads the
packs the repair wrote, makes the chunk index match them and stores it; that always runs to
completion, also after a Ctrl\-C.
.SS About repair mode
.sp
The check command is a read\-only task by default. If any corruption is found,
@@ -176,10 +187,17 @@ In practice, repair mode hooks into both the repository and archive checks:
.INDENT 0.0
.IP 1. 3
When checking the repository\(aqs consistency, repair mode rebuilds the repository
index from the packs if the index is corrupt, provided every pack is intact. If
any pack is corrupt, the repository check leaves the index and the packs untouched
and reports the corruption; salvaging a corrupt pack\(aqs still\-intact objects is not
implemented yet (refs #8572).
index from the packs if the index is corrupt, provided every pack matches its
store hash. If any pack fails its store hash, the repository check leaves the
index and the packs untouched and reports it; salvaging the intact objects of
such a pack is not implemented yet (refs #8572). The rebuild authenticates
each object\(aqs header and metadata with the key, leaves an object that fails
this out of the index and reports it as an error. Repair mode also removes the
index entries of the chunks stored in missing packs (packs the index references,
but that are absent from the repository). Only a full \fBborg check \-\-repair\fP
repairs the archives that reference these chunks, \fB\-\-repository\-only\fP does not.
A missing or corrupt repository defaults object is replaced by empty defaults, so
the repository can be used again; the commands then use the built\-in defaults.
.IP 2. 3
When checking the consistency and correctness of archives, repair mode might
remove whole archives from the manifest if their archive metadata chunk is
docs/man/borg-common.1
+1 -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-common" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-common" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-common \- Common options of Borg commands
.SH SYNOPSIS
docs/man/borg-compact.1
+8 -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-compact" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-compact" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-compact \- Collects garbage in the repository.
.SH SYNOPSIS
@@ -60,6 +60,13 @@ Other bytes no index entry covers, such as packs left behind by a backup that cr
before recording its objects, are re\-indexed by \fBborg check \-\-repair\fP and reclaimed by
the next \fBborg compact\fP\&.
.sp
\fBborg compact\fP does not rewrite or merge packs that \fBborg check\fP recorded as corrupt
and warns about them. \fBborg check \-\-repair \-\-verify\-data\fP deletes the corrupt chunks by
rewriting their packs. It does not remove damage outside any chunk (e.g. bytes appended to a
pack): a pack with such damage and no corrupt chunk stays recorded corrupt and \fBborg compact\fP
warns about it on every run, a pack that also has a corrupt chunk is rewritten with that damage
copied into the new pack (refs #10026).
.sp
You usually do not want to run \fBborg compact\fP after every write operation, but
either regularly (e.g., once a month, possibly together with \fBborg check\fP) or
when disk space needs to be freed.
docs/man/borg-completion.1
+1 -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-completion" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-completion" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-completion \- Output shell completion script for the given shell.
.SH SYNOPSIS
docs/man/borg-compression.1
+5 -3
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-compression" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-compression" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-compression \- Details regarding compression
.SH DESCRIPTION
@@ -42,7 +42,9 @@ another backup that also uses this chunk will not change the stored chunk.
So if you use different compression specs for the backups, whichever stores a
chunk first determines its compression. See also \fBborg recreate\fP\&.
.sp
Compression is lz4 by default. If you want something else, you have to specify what you want.
If you do not specify a compression via \fB\-\-compression\fP (or the environment or the
default config file), the repository\(aqs default compression is used, which can be set
with \fBborg repo\-create \-\-compression\fP\&. Without a repository default, compression is lz4.
.sp
Valid compression specifiers are:
.INDENT 0.0
@@ -51,7 +53,7 @@ Valid compression specifiers are:
Do not compress.
.TP
.B lz4
Use lz4 compression. Very high speed, very low compression. (default)
Use lz4 compression. Very high speed, very low compression. (built\-in default)
.TP
.B zstd[,L]
Use zstd (\(dqzstandard\(dq) compression, a modern wide\-range algorithm.
docs/man/borg-copy.1
+1 -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-copy" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-copy" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-copy \- Copy an archive to a new archive name.
.SH SYNOPSIS
docs/man/borg-create.1
+9 -9
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-create" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-create" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-create \- Creates a new archive.
.SH SYNOPSIS
@@ -71,7 +71,8 @@ appropriate to use \-\-content\-from\-command. See the section
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
.sp
The \fB\-\-tags\fP option can be used to add a list of tags to the new archive.
The \fB\-\-tag\fP option can be used to add a tag to the new archive. To add
multiple tags, give it multiple times, e.g. \fB\-\-tag foo \-\-tag bar\fP\&.
.sp
The archive name does not need to be unique; you can and should use the same
name for a series of archives. The unique archive identifier is its ID (hash),
@@ -179,9 +180,8 @@ terminals, the compact format is used, so that the path stays readable. If the o
does not go to a terminal (e.g. into a logfile), the precise format is always used.
.sp
When using \fB\-\-stats\fP, you will get some statistics about how much data was
added \- the \(dqThis Archive\(dq deduplicated size there is most interesting as that is
how much your repository will grow. Please note that the \(dqAll archives\(dq stats refer to
the state after creation.
added \- the deduplicated size there is most interesting as that is how much your
repository will grow. \fB\-\-json\fP outputs the same statistics as JSON.
.sp
When \fB\-\-stats\fP is used together with \fB\-\-dry\-run\fP, only the number of files and the
original size are reported. They are computed from file system metadata, without reading
@@ -361,13 +361,13 @@ add a comment text to the archive
manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:MM] format, (+|\-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2
specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: the repository default (see borg repo\-create), else fastcdc,19,23,21,2
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. Default: the repository default (see borg repo\-create), else lz4.
.TP
.BI \-\-tags \ TAG
add tags to archive (comma\-separated or multiple arguments)
.BI \-\-tag \ TAG
add tag to archive (can be given multiple times)
.UNINDENT
.SH EXAMPLES
.sp
docs/man/borg-delete.1
+1 -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-delete" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-delete" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-delete \- Deletes archives.
.SH SYNOPSIS
docs/man/borg-diff.1
+48 -4
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-diff" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-diff" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-diff \- Finds differences between two archives.
.SH SYNOPSIS
@@ -69,6 +69,9 @@ specify format for differences between archives (default: \(dq{change} {path}{NL
.B \-\-json\-lines
Format output as JSON Lines.
.TP
.B \-s\fP,\fB \-\-stats
print a summary of the differences at the end
.TP
.B \-\-sort\-by
Sort output by comma\-separated fields (e.g., \(aq>size_added,path\(aq).
.TP
@@ -212,9 +215,15 @@ 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. In the latter case, borg
can only tell that a file was modified, not by how much: no byte counts are given for it, the
text output shows \(dqmodified: (can\(aqt get size)\(dq instead.
Borg compares chunk IDs quickly: it aligns the two chunk lists of a file like a text diff
aligns lines, and the byte counts are the total sizes of the chunks that are not part of that
alignment. Inserted, removed, moved and duplicated content is therefore accounted for \- a
chunk that only moved within the file shows up as removed and added again. Files with very
long or very repetitive chunk lists are not aligned (this would be too slow); for these, only
the number of occurrences of each chunk ID is compared, so moved content does not show up in
their byte counts. If chunker parameters are not comparable, Borg compares the content. In
that case, borg can only tell that a file was modified, not by how much: no byte counts
are given for it, the text output shows \(dqmodified: (can\(aqt get size)\(dq instead.
.IP \(bu 2
Metadata changes: user, group, mode, and other metadata shown inline as \(dq[old \-> new]\(dq, like
\(dq[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x]\(dq for a mode change. Use \fB\-\-content\-only\fP to suppress metadata changes.
@@ -253,6 +262,41 @@ values as \(dqitem1\(dq and \(dqitem2\(dq. Example:
.EE
.UNINDENT
.UNINDENT
.SS Statistics
.sp
With \fB\-\-stats\fP, borg prints a summary of the differences after the per\-path output:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Added items: 23
Removed items: 2
Changed items: 315
Added size: 53.70 MB
Removed size: 51.10 MB
.EE
.UNINDENT
.UNINDENT
.sp
\(dqAdded\(dq/\(dqRemoved\(dq items only exist in ARCHIVE2/ARCHIVE1, \(dqchanged\(dq items exist in both
archives but differ. \(dqAdded size\(dq/\(dqRemoved size\(dq sum up the file content (in bytes) added/removed
by all of these items, i.e. the per\-path byte counts that \fB\-\-sort\-by size_added\fP /
\fBsize_removed\fP sort by. Items whose content borg could only
compare byte by byte (see \(dqPerformance considerations\(dq below) contribute no byte counts;
if there are any, an additional \(dqItems with unknown size changes\(dq line reports how many.
.sp
Together with \fB\-\-json\-lines\fP, the summary is emitted as a final JSON line of the shape
\fB{\(dqstats\(dq: {...}}\fP instead, so it is easy to tell apart from the per\-path lines
(wrapped here for readability, borg prints it as a single line):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{\(dqstats\(dq: {\(dqadded_items\(dq: 23, \(dqchanged_items\(dq: 315, \(dqremoved_items\(dq: 2,
\(dqsize_added\(dq: 53700000, \(dqsize_removed\(dq: 51100000, \(dqunknown_size_items\(dq: 0}}
.EE
.UNINDENT
.UNINDENT
.SS Sorting
.sp
Use \fB\-\-sort\-by FIELDS\fP where FIELDS is a comma\-separated list of fields.
docs/man/borg-environment.1
+23 -17
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-environment" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-environment" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-environment \- Details regarding environment
.SH DESCRIPTION
@@ -46,17 +46,23 @@ Use this so you do not need to type \fB\-\-repo /path/to/my/repo\fP all the time
.B BORG_OTHER_REPO
Similar to BORG_REPO, but gives the default for \fB\-\-other\-repo\fP\&.
.TP
.B BORG_PASSPHRASE (and BORG_OTHER_PASSPHRASE)
.B BORG_PASSPHRASE (and BORG_NEW_PASSPHRASE, BORG_OTHER_PASSPHRASE)
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are mutually exclusive:
if more than one of them is set, borg refuses to guess and aborts with
\(dqMore than one passphrase environment variable is set\(dq. The same applies to the
\fBBORG_OTHER_*\fP variants (which are a separate, independent group).
\fBBORG_NEW_*\fP and \fBBORG_OTHER_*\fP variants (each of which is a separate,
independent group).
See also BORG_NEW_PASSPHRASE.
borg removes the passphrase\-related variables (BORG_PASSPHRASE, BORG_PASSCOMMAND,
BORG_PASSPHRASE_FD and their \fBBORG_NEW_*\fP and \fBBORG_OTHER_*\fP variants) as well as
BORGSTORE_REST_PASSWORD from the environment of the subprocesses it starts (like the
command given in BORG_PASSCOMMAND, \fB\-\-paths\-from\-command\fP / \fB\-\-content\-from\-command\fP
commands, tar filter commands and \fBborg with\-lock\fP commands).
.TP
.B BORG_PASSCOMMAND (and BORG_OTHER_PASSCOMMAND)
.B BORG_PASSCOMMAND (and BORG_NEW_PASSCOMMAND, BORG_OTHER_PASSCOMMAND)
When set, use the standard output of the command (trailing newlines are stripped) to answer the
passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
@@ -65,7 +71,7 @@ is executed without a shell. So variables, like \fB$HOME\fP will work, but \fB~\
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSPHRASE_FD, see there.
See also BORG_NEW_PASSPHRASE.
.TP
.B BORG_PASSPHRASE_FD (and BORG_OTHER_PASSPHRASE_FD)
.B BORG_PASSPHRASE_FD (and BORG_NEW_PASSPHRASE_FD, BORG_OTHER_PASSPHRASE_FD)
When set, specifies a file descriptor to read a passphrase
from. Programs starting borg may choose to open an anonymous pipe
and use it to pass a passphrase. This is safer than passing via
@@ -73,10 +79,12 @@ BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
can be examined by other processes.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSCOMMAND, see there.
.TP
.B BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE, BORG_PASSCOMMAND and
BORG_PASSPHRASE_FD are checked (in that order).
.B BORG_NEW_PASSPHRASE (and BORG_NEW_PASSCOMMAND, BORG_NEW_PASSPHRASE_FD)
When set, use these to answer the passphrase question when a \fBnew\fP passphrase is
asked for: like BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD, but for
the new passphrase.
The \fBBORG_NEW_*\fP group is checked first. If none of its variables is set,
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are checked (in that order).
Main use case for this is to fully automate \fBborg key change\-passphrase\fP\&.
.TP
.B BORG_DISPLAY_PASSPHRASE
@@ -267,7 +275,7 @@ more afterwards. (Re\-chunking in \fBborg transfer\fP is covered by \fBtransfer\
An unknown place name is an error. An empty value (\fBBORG_ASSERT_ID=\fP) verifies at none of
these places, but still where borg always verifies (see below).
.sp
Why \fBread\fP is not in the default: in the keyed modes, the envelope already authenticates
Why \fBread\fP is not in the default: the envelope already authenticates
every read \- the AEAD tag for the encrypted ciphersuites, the MAC for the (unencrypted)
\fBauthenticated\-*\fP modes \- and the chunk id is part of what that tag is computed over. So
a successful decryption resp. tag check already proves that a holder of the borg key
@@ -297,10 +305,8 @@ Independent of this variable, borg always verifies the chunk id:
in \fBborg check \-\-verify\-data\fP\&. That audit is what makes not verifying elsewhere
defensible, so it is not configurable (there is no \fBverify_data\fP place name).
.IP \(bu 2
for \fBnone\-*\fP mode repositories: they have no key, so nothing authenticates a read
there and their unkeyed checksums only detect accidental corruption. The id check is
therefore not optional there: it happens at every place, whatever this variable says.
Same for reading borg 1.x repositories (\fBborg transfer\fP).
when reading borg 1.x repositories (\fBborg transfer \-\-from\-borg1\fP): their envelope does
not cover the chunk id, so the id check is not optional there.
.UNINDENT
.TP
.B BORG_BLAKE3_MT_THRESHOLD
@@ -317,7 +323,8 @@ set it, and can optionally show a chart of the measurements in your browser
.TP
.B BORG_ZSTD_MT_WORKERS
When set to a numeric value, use that many threads to zstd\-compress a single chunk
(default: the cpu count, but at most 4). 0 or 1 means single\-threaded compression.
(default: the cpu count, but at most 4). If it is unset or empty, the default is
used. 0 or 1 means single\-threaded compression.
Only relevant when compressing with \fBzstd\fP\&.
Chunks below 768KiB are always compressed single\-threaded: libzstd will not use a
compression job smaller than 512KiB, so a small chunk gets split very unevenly and
@@ -448,8 +455,7 @@ anyway, without any key material.
Without the key, borg can not verify anything that needs it: neither the
authentication tag of the repository objects nor the chunk ids. It therefore
reads the repository \fBunverified\fP \- a corrupted or tampered repository will
not be detected. (This only concerns the \fBauthenticated\-*\fP modes; the
\fBnone\-*\fP modes need no key and keep verifying their checksums.)
not be detected.
.sp
This workaround is \fBonly\fP for emergencies and \fBonly\fP to extract data
from an affected repository (read\-only access):
docs/man/borg-export-tar.1
+1 -1
View File
@@ -29,7 +29,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" "2026-09-02" "" "borg backup tool"
.TH "borg-export-tar" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-export-tar \- Export archive contents as a tarball
.SH SYNOPSIS
docs/man/borg-extract.1
+51 -3
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-extract" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-extract" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-extract \- Extracts archive contents.
.SH SYNOPSIS
@@ -54,6 +54,33 @@ decrypting, and decompressing.
\fB\-\-progress\fP can be slower than no progress display, since it makes one additional
pass over the archive metadata.
.sp
Extracting into a non\-empty directory replaces existing files that are in the way and
leaves all other existing files as they are. The result is a mix of the files that were
there before and the extracted files, which might not be what you want \- especially not
by accident in a directory that is in use (e.g. your home directory). Thus, borg refuses
to extract into a non\-empty directory unless \fB\-\-continue\fP is given (\fB\-\-dry\-run\fP and
\fB\-\-stdout\fP do not write into the directory, so they always work). The usual way to
restore is to extract into a new, empty directory: after that, the directory has exactly
the contents of the extracted archive (or of the selected part of it).
.sp
\fB\-\-continue\fP extracts into a non\-empty directory. It is made for continuing a previously
interrupted extraction of the same archive into the same directory: an existing regular
file that has the same type, permissions (mode), size and modification time as the
archived file is considered to be fully extracted already and is skipped. Everything else
is extracted, replacing existing files. Files that are in the directory, but not in the
archive, are left as they are. \fB\-\-continue\fP is thus also needed to restore files into an
existing directory tree. Note that a file that was damaged without a change of its size
and modification time (e.g. by bit rot) is skipped, not replaced: remove it before
extracting it.
.sp
If a file\(aqs content chunks are missing from the repository or are corrupted (they fail
authentication, decryption or decompression), the extraction does not abort: each such
chunk is written as all\-zero data of the correct size, an error naming the chunk is logged,
the file is reported with a warning and the exit code is a warning. The extracted file thus
has the correct size and metadata, but wrong (all\-zero) content where the damaged chunks
were. Run \fBborg check\fP to find out which chunks and archives are affected. This also
applies to \fB\-\-dry\-run\fP (which thus can be used to find unreadable files) and \fB\-\-stdout\fP\&.
.sp
When using \fB\-\-stats\fP, borg reports the store statistics (lines prefixed with
\(dqStore\(dq) for the extraction: per\-operation call counts and timings, the load/store
data volumes and throughput, and cache hits/misses. This includes \fB\-\-dry\-run\fP
@@ -70,6 +97,24 @@ or any other reason), Borg cannot restore parent directories\(aq metadata, e.g.,
group, permissions, etc.
.UNINDENT
.UNINDENT
.sp
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
Restoring some file metadata requires root privileges (or equivalent
capabilities). This includes the owner and group of files, device nodes,
privileged file flags (like immutable or append\-only) and privileged
extended attributes (like Linux capabilities or \fBtrusted.*\fP xattrs).
.sp
When running as a normal user, borg still extracts the file contents, but
the extracted files are owned by the invoking user (the failure to restore
ownership is silently ignored: no warning, exit code unaffected), privileged
flags are skipped while the other flags are still set, and privileged xattrs
and device nodes are skipped with a warning. \fB\-\-numeric\-ids\fP does not
change this, it only selects whether the archived numeric IDs or the archived
user/group names are used. To restore all metadata, run \fBborg extract\fP as root.
.UNINDENT
.UNINDENT
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -113,7 +158,7 @@ write all extracted data to stdout
create holes in the output sparse file from all\-zero chunks
.TP
.B \-\-continue
continue a previously interrupted extraction of the same archive
extract into a non\-empty directory, e.g. to continue a previously interrupted extraction of the same archive: skip files that are fully extracted already, replace other existing files
.UNINDENT
.SS Include/Exclude options
.INDENT 0.0
@@ -138,9 +183,12 @@ Remove the specified number of leading path elements. Paths with fewer elements
.INDENT 3.5
.sp
.EX
# Extract entire archive
# Extract entire archive (into the current directory, which must be empty)
$ borg extract my\-files
# Continue an interrupted extraction (or extract into a non\-empty directory)
$ borg extract \-\-continue my\-files
# Extract entire archive and list files while processing
$ borg extract \-\-list my\-files
docs/man/borg-find.1
+1 -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-find" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-find" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-find \- Find files across archives.
.SH SYNOPSIS
docs/man/borg-import-tar.1
+16 -3
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-import-tar" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-import-tar" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-import-tar \- Create a backup archive from a tarball
.SH SYNOPSIS
@@ -66,6 +66,16 @@ stdout.
Most documentation of borg create applies. Note that this command does not
support excluding files.
.sp
\fB\-\-strip\-components\fP removes the specified number of leading path elements
from the tar member names when creating the archive items. Members whose path
has fewer or equally many elements are silently skipped. Hard link targets are
stripped accordingly, symbolic link targets are left unchanged.
.sp
The path elements are counted after normalizing the member name the same way it
is stored in the archive, so a leading \fB\&./\fP is not a path element. This differs
from \fBtar\fP, which counts it: to import \fB\&./top/dir/file\fP as \fBdir/file\fP, use
\fB\-\-strip\-components=1\fP here, while \fBtar\fP needs \fB\-\-strip\-components=2\fP\&.
.sp
A \fB\-\-sparse\fP option (as found in borg create) is not needed: sparse members in
input tarballs (old GNU and PAX sparse formats) are read correctly and their
holes are stored as deduplicated all\-zero chunks.
@@ -123,6 +133,9 @@ output stats as JSON (implies \-\-stats)
.TP
.B \-\-ignore\-zeros
ignore zero\-filled blocks in the input tarball
.TP
.BI \-\-strip\-components \ NUMBER
Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
.UNINDENT
.SS Archive options
.INDENT 0.0
@@ -134,10 +147,10 @@ add a comment text to the archive
manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:MM] format, (+|\-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: fastcdc,19,23,21,2
specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: the repository default (see borg repo\-create), else fastcdc,19,23,21,2
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. Default: the repository default (see borg repo\-create), else lz4.
.TP
.BI \-\-digests \ ALGOS
compute these hash digests over the full content of each file and store them into the archive items. Comma\-separated list of hash algorithm names, e.g. \(dqblake3\(dq, or \(dqnone\(dq. default: none
docs/man/borg-info.1
+4 -3
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-info" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-info" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-info \- Show archive details such as disk space used
.SH SYNOPSIS
@@ -42,8 +42,9 @@ The original size shown here is the total size of the archive\(aqs source data
(uncompressed, counting duplicate content per occurrence).
.sp
Deduplicated sizes are not shown here (computing them per archive is expensive).
For the deduplicated size of a set of archives, use \fBborg analyze\fP; for the
repository\-wide deduplicated size, use \fBborg compact \-\-stats\fP\&.
\fBborg create \-\-stats\fP (also with \fB\-\-json\fP) reports the deduplicated size of the
archive it has just created. For the deduplicated size of a set of archives, use
\fBborg analyze\fP; for the repository\-wide deduplicated size, use \fBborg compact \-\-stats\fP\&.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
docs/man/borg-key-add.1
+1 -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-key-add" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key-add" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key-add \- Add a new borg key (protected by an independent passphrase) to the repository.
.SH SYNOPSIS
docs/man/borg-key-change-location.1
+1 -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-key-change-location" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key-change-location" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key-change-location \- Changes the location of the borg key used to unlock this repository.
.SH SYNOPSIS
docs/man/borg-key-change-passphrase.1
+2 -2
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-key-change-passphrase" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key-change-passphrase" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key-change-passphrase \- Changes the repository key file passphrase.
.SH SYNOPSIS
@@ -78,7 +78,7 @@ Key location: /root/.config/borg/keys/4881c2f73d9f173bd4c4d30a9f397a596bc742bfa1
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
Automatically placed key files are named after the SHA\-256 hash of their own
Automatically placed key files are named after the \fIstore hash <store_hash>\fP of their own
contents, not after the repository directory name. Because changing the
passphrase re\-encrypts the key, the key file is rewritten under a new name and
the previous one is removed — that is why the two paths above differ. Use
docs/man/borg-key-export.1
+1 -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-key-export" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key-export" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key-export \- Exports a borg key of the repository for backup.
.SH SYNOPSIS
docs/man/borg-key-import.1
+1 -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-key-import" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key-import" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key-import \- Imports the repository key from backup.
.SH SYNOPSIS
docs/man/borg-key-list.1
+1 -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-key-list" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key-list" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key-list \- List the borg keys of the repository.
.SH SYNOPSIS
docs/man/borg-key-remove.1
+1 -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-key-remove" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key-remove" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key-remove \- Remove a borg key from the repository.
.SH SYNOPSIS
docs/man/borg-key.1
+1 -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-key" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-key" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-key \- Manage the keyfile or repokey of a repository
.SH SYNOPSIS
docs/man/borg-list.1
+1 -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-list" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-list" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-list \- List archive contents.
.SH SYNOPSIS
docs/man/borg-match-archives.1
+4 -3
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-match-archives" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-match-archives" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-match-archives \- Details regarding match-archives
.SH DESCRIPTION
@@ -53,7 +53,7 @@ user: exact match on the username who created the archive
.IP \(bu 2
host: exact match on the hostname where the archive was created
.IP \(bu 2
tags: match on the archive tags
tags: match archives having all the given tags (comma\-separated, e.g. tags:TAG1,TAG2)
.IP \(bu 2
date: match on the archive creation timestamp
.UNINDENT
@@ -146,8 +146,9 @@ borg delete \-a \(aqaid:d34db33f\(aq
borg delete \-a \(aquser:kenny\(aq
borg delete \-a \(aqhost:kenny\-pc\(aq
# tags match
# tags match (both lines match archives having TAG1 and TAG2)
borg delete \-a \(aqtags:TAG1\(aq \-a \(aqtags:TAG2\(aq
borg delete \-a \(aqtags:TAG1,TAG2\(aq
# archive creation date match
borg delete \-a \(aqdate:2025\-01\(aq
docs/man/borg-mount.1
+13 -4
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-mount" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-mount" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-mount \- Mounts an archive or an entire repository as a FUSE filesystem.
.SH SYNOPSIS
@@ -134,15 +134,24 @@ Additional mount options supported by Borg:
\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 the future.
.IP \(bu 2
\fBallow_damaged_files\fP: by default, damaged files (where chunks are missing)
will return EIO (I/O error) when trying to read the related parts of the file.
Set this option to replace the missing parts with all\-zero bytes.
\fBallow_damaged_files\fP: by default, damaged files (where chunks are missing or
corrupted) will return EIO (I/O error) when trying to read the related parts of the
file. Set this option to replace the damaged parts with all\-zero bytes.
.IP \(bu 2
\fBignore_permissions\fP: for security reasons the \fBdefault_permissions\fP mount
option is internally enforced by Borg. \fBignore_permissions\fP can be given to
not enforce \fBdefault_permissions\fP\&.
.UNINDENT
.sp
On Windows, \fBborg mount\fP needs WinFsp \%<https://\:winfsp\:.dev/> and mfusepy.
MOUNTPOINT must either be an unused drive (like \fBX:\fP) or a not yet existing
directory (WinFsp creates it when mounting and removes it when unmounting).
\fBborg mount\fP always stays in the foreground there and \fBborg umount\fP is not
supported: to unmount, stop \fBborg mount\fP using Ctrl\-C or Ctrl\-Break. All files
belong to the user who mounts, unless the \fBuid\fP / \fBgid\fP mount options (which
are implemented by WinFsp there, not by Borg) say otherwise. \fBignore_permissions\fP
has no effect. WinFsp does not support hard link counts (they are always 1).
.sp
The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is intended for advanced users
to tweak performance. It sets the number of cached data chunks; additional
memory usage can be up to ~8 MiB times this number. The default is the number
docs/man/borg-patterns.1
+1 -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-patterns" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-patterns" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-patterns \- Details regarding patterns
.SH DESCRIPTION
docs/man/borg-placeholders.1
+1 -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-placeholders" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-placeholders" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-placeholders \- Details regarding placeholders
.SH DESCRIPTION
docs/man/borg-prune.1
+1 -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-prune" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-prune" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-prune \- Prune archives according to specified rules.
.SH SYNOPSIS
docs/man/borg-recreate.1
+3 -3
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-recreate" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-recreate" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-recreate \- Recreate archives.
.SH SYNOPSIS
@@ -166,10 +166,10 @@ add a comment text to the archive
manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:MM] format, (+|\-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. Only applies to newly written data, e.g. when re\-chunking with \-\-chunker\-params (and to the new archive metadata); data chunks reused from the existing archive are not recompressed, use borg repo\-compress for that.
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. Only applies to newly written data, e.g. when re\-chunking with \-\-chunker\-params (and to the new archive metadata); data chunks reused from the existing archive are not recompressed, use borg repo\-compress for that. Default: the repository default (see borg repo\-create), else lz4.
.TP
.BI \-\-chunker\-params \ PARAMS
rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or \fIdefault\fP to use the chunker defaults. default: do not rechunk
rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or \fIdefault\fP to use the repository default (see borg repo\-create), else the built\-in chunker defaults. default: do not rechunk
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
docs/man/borg-rename.1
+1 -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-rename" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-rename" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-rename \- Rename an existing archive.
.SH SYNOPSIS
docs/man/borg-repo-compress.1
+12 -3
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-repo-compress" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-repo-compress" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-repo-compress \- Repository (re-)compression.
.SH SYNOPSIS
@@ -39,7 +39,9 @@ borg [common options] repo\-compress [options]
Repository (re\-)compression (and/or re\-obfuscation).
.sp
Reads all repository objects and recompresses the ones that are not already using
the compression type/level and obfuscation level given via \fB\-\-compression\fP\&.
the compression type/level and obfuscation level given via \fB\-\-compression\fP\&. Without
\fB\-\-compression\fP, that is the repository\(aqs default compression (see \fBborg repo\-create\fP),
else lz4.
.sp
The repository is processed one pack file at a time: a pack is read as a whole and,
if it holds objects that need recompression, rewritten as a whole \- objects already
@@ -49,6 +51,13 @@ Please note that the outcome of recompressing a chunk might not always be the
desired compression type/level \- if no compression gives a shorter output, that
might be chosen; such chunks are kept as they are.
.sp
\fBborg repo\-compress\fP does not rewrite packs that \fBborg check\fP recorded as corrupt
and warns about them. \fBborg check \-\-repair \-\-verify\-data\fP deletes the corrupt chunks by
rewriting their packs. It does not remove damage outside any chunk (e.g. bytes appended to a
pack): a pack with such damage and no corrupt chunk stays recorded corrupt and is not rewritten,
a pack that also has a corrupt chunk is rewritten with that damage copied into the new pack
(refs #10026).
.sp
Rewriting a pack invalidates every client\(aqs cached chunk index, so the next borg
operation of each client will re\-fetch the chunk index from the repository.
.sp
@@ -70,7 +79,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. Default: the repository default (see borg repo\-create), else lz4.
.TP
.B \-s\fP,\fB \-\-stats
print statistics
docs/man/borg-repo-create.1
+44 -20
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-repo-create" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-repo-create" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-repo-create \- Creates a new, empty repository.
.SH SYNOPSIS
@@ -105,6 +105,14 @@ a different keyboard layout.
.sp
You can change your passphrase for existing repositories at any time; it will not affect
the encryption/decryption key or other secrets.
.sp
Borg also accepts an empty passphrase. The repository is still encrypted with a random
key then, but that key is not protected: with \fBrepokey\fP storage, anybody who can read
the repository can also unlock the key, which is as good as no encryption at all (with
\fBkeyfile\fP storage, the key is only on your client, so an empty passphrase may be
acceptable if e.g. the client\(aqs disk is encrypted). You can add a passphrase later with
\fBborg key change\-passphrase\fP\&. \fBborg repo\-info\fP shows whether the key has an empty
passphrase.
.SS Choosing a crypto suite
.sp
Depending on your hardware, hashing and crypto performance may vary widely.
@@ -119,9 +127,6 @@ The easiest way to find out what is fastest is to run \fBborg benchmark cpu\fP\&
.IP \(bu 2
\fBauthenticated\-sha256\fP / \fBauthenticated\-blake3\fP: no encryption, but authentication
(tamper detection) using HMAC\-SHA\-256 resp. keyed BLAKE3.
.IP \(bu 2
\fBnone\-sha256\fP / \fBnone\-blake3\fP: neither encryption nor authentication, only
SHA\-256 resp. BLAKE3 checksums (see below).
.UNINDENT
.sp
\fB\-\-id\-hash\fP selects the id hash function of the \fBencrypted\fP modes:
@@ -150,21 +155,36 @@ You can move the key between these locations later with \fBborg key change\-loca
This also applies to the \fBauthenticated\-*\fP modes: they do not encrypt your data, but they
still have a key (used for the id hash and the authentication), so \fB\-\-key\-location\fP
selects where that key is stored, just like for the encrypted modes.
\fB\-\-key\-location\fP is only ignored for the \fBnone\-*\fP modes, which have no key at all.
.sp
The \fBnone\-*\fP modes use neither encryption nor authentication: everything in the
repository is readable by anybody, and while every repository object carries a checksum
(which detects accidental corruption, e.g. bad storage hardware), anybody who modifies an
object can just recompute that checksum. You are advised NOT to use these modes: in case
of malicious activity in the repository, they expose you to a Denial\-of\-Service risk (due
to how the \fIinternals_hashindex\fP works) and other issues (confidentiality,
tampering, ...).
.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\-sha256\fP (or \fB\-blake3\fP). These
modes are like an encrypted mode minus the data encryption.
To normally work with \fBauthenticated\-*\fP repositories, you will need the passphrase, but
there is an emergency workaround; see \fBBORG_WORKAROUNDS=authenticated_no_key\fP docs.
.SS Repository defaults
.sp
\fB\-\-compression\fP sets the repository\(aqs default compression: the commands that compress
data (\fBborg create\fP, \fBborg recreate\fP, \fBborg import\-tar\fP, \fBborg transfer\fP,
\fBborg repo\-compress\fP) use it if no compression was given via \fB\-\-compression\fP, the
environment or the default config file (\fBdefault.yaml\fP). Without a repository default,
they use lz4. See \fBborg help compression\fP for the compression specs.
.sp
\fB\-\-chunker\-params\fP sets the repository\(aqs default chunker parameters: \fBborg create\fP and
\fBborg import\-tar\fP use them if no chunker parameters were given (in the same ways as above).
\fBborg recreate\fP and \fBborg transfer\fP only rechunk if \fB\-\-chunker\-params\fP is given, with
\fB\-\-chunker\-params default\fP, they rechunk to the repository\(aqs default chunker parameters.
Without a repository default, the built\-in default chunker parameters are used.
.sp
This is useful if several clients back up into the same repository or if some commands are
run manually: they all compress and chunk the same way without having to give these options.
Using the same chunker parameters is important for deduplication.
\fBborg repo\-info\fP shows the defaults.
.sp
The defaults are stored in the repository and protected by the repository key: changing them
(e.g. removing an \fBobfuscate\fP compression) needs the key. The defaults object is always
written, also when no default was given, so removing it is noticed, too: the commands refuse
to run if it is missing or fails the authentication. \fBborg check\fP reports such an object,
\fBborg check \-\-repair\fP replaces it by empty defaults (the built\-in defaults are used then).
.SS Creating a related repository
.sp
You can use \fBborg repo\-create \-\-other\-repo ORIG_REPO ...\fP to create a related repository
@@ -197,13 +217,19 @@ reuse the key material from the other repository
other repository is Borg 1.x
.TP
.BI \-e \ ENCRYPTION\fR,\fB \ \-\-encryption \ ENCRYPTION
select the mode: \(aqaes256\-ocb\(aq, \(aqchacha20\-poly1305\(aq, \(aqauthenticated\-sha256\(aq, \(aqauthenticated\-blake3\(aq, \(aqnone\-sha256\(aq or \(aqnone\-blake3\(aq \fB(required)\fP
select the mode: \(aqaes256\-ocb\(aq, \(aqchacha20\-poly1305\(aq, \(aqauthenticated\-sha256\(aq or \(aqauthenticated\-blake3\(aq \fB(required)\fP
.TP
.BI \-i \ HASH\fR,\fB \ \-\-id\-hash \ HASH
select the id hash function of the encrypted modes: \(aqsha256\(aq or \(aqblake3\(aq. The \(aqnone\-\fI\(aq and \(aqauthenticated\-\fP\(aq modes name their hash themselves.
select the id hash function of the encrypted modes: \(aqsha256\(aq or \(aqblake3\(aq. The \(aqauthenticated\-sha256\(aq and \(aqauthenticated\-blake3\(aq modes name their hash themselves.
.TP
.BI \-\-key\-location \ LOCATION
where to store the key: \(aqrepokey\(aq (in the repository, default) or \(aqkeyfile\(aq (in the local keys directory). Ignored for the \fBnone\-*\fP modes (which have no key).
where to store the key: \(aqrepokey\(aq (in the repository, default) or \(aqkeyfile\(aq (in the local keys directory).
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
set the default compression of the repository, see the output of the \(dqborg help compression\(dq command for details. Default: no repository default (lz4 is used).
.TP
.BI \-\-chunker\-params \ PARAMS
set the default chunker parameters of the repository (same format as for borg create). Default: no repository default (fastcdc,19,23,21,2 is used).
.TP
.B \-\-copy\-crypt\-key
copy the crypt_key (used for authenticated encryption) from the key of the other repository (default: new random key).
@@ -218,9 +244,8 @@ $ export BORG_REPO=/path/to/repo
# Recommended AEAD cryptographic modes (key stored in the repository by default)
$ borg repo\-create \-\-encryption=aes256\-ocb
$ borg repo\-create \-\-encryption=chacha20\-poly1305
# No encryption (not recommended)
# No encryption, only authentication (not recommended)
$ borg repo\-create \-\-encryption=authenticated\-sha256
$ borg repo\-create \-\-encryption=none\-sha256
# For the encrypted modes, \-\-encryption (the cipher / AE algorithm) and \-\-id\-hash
# (the id hash function) are chosen independently. \-\-id\-hash defaults to sha256;
@@ -228,10 +253,9 @@ $ borg repo\-create \-\-encryption=none\-sha256
$ borg repo\-create \-\-encryption=aes256\-ocb \-\-id\-hash=blake3
$ borg repo\-create \-\-encryption=chacha20\-poly1305 \-\-id\-hash=blake3
# The \(aqauthenticated\-*\(aq and \(aqnone\-*\(aq modes name their id hash themselves, so they
# The \(aqauthenticated\-*\(aq modes name their id hash themselves, so they
# do not take a separate \-\-id\-hash.
$ borg repo\-create \-\-encryption=authenticated\-blake3
$ borg repo\-create \-\-encryption=none\-blake3
# Where the key is stored (\-\-key\-location) is also chosen independently.
# \-\-key\-location defaults to repokey.
docs/man/borg-repo-delete.1
+7 -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-repo-delete" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-repo-delete" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-repo-delete \- Deletes a repository.
.SH SYNOPSIS
@@ -43,6 +43,12 @@ When you delete a complete repository, the security info and local cache for it
with the \fB\-\-cache\-only\fP option, or keep the security info with the
\fB\-\-keep\-security\-info\fP option.
.sp
\fB\-\-force\fP also destroys a store that has no repository config, provided it looks
like a borg store (it has the packs, archives, index and config namespaces).
.sp
Deleting a repository needs its key, as locking it needs the key. If the key is lost,
the repository is useless and has to be deleted with the storage\(aqs own tools.
.sp
Always first use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
.SH OPTIONS
.sp
docs/man/borg-repo-info.1
+5 -2
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-repo-info" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-repo-info" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-repo-info \- Show repository information.
.SH SYNOPSIS
@@ -54,13 +54,16 @@ format output as JSON
$ borg repo\-info
Repository ID: 0a2744f216526be75ae14a5fa5b123127bb218558219f6203e09e4f220e45903
Location: /path/to/repo
Repository version: 4
Repository version: 5
Encrypted: Yes (repokey, aes256\-ocb, sha256)
Security directory: /home/user/.local/share/borg/security/0a2744f216526be75ae14a5fa5b123127bb218558219f6203e09e4f220e45903
Cache: /home/user/.cache/borg/0a2744f216526be75ae14a5fa5b123127bb218558219f6203e09e4f220e45903
.EE
.UNINDENT
.UNINDENT
.sp
If the key has an empty passphrase, this is shown in the \fBEncrypted:\fP line, e.g.
\fBEncrypted: Yes (repokey, aes256\-ocb, sha256, empty passphrase)\fP\&.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
docs/man/borg-repo-list.1
+1 -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-repo-list" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-repo-list" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-repo-list \- List the archives contained in a repository.
.SH SYNOPSIS
docs/man/borg-repo-space.1
+1 -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-repo-space" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-repo-space" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-repo-space \- Manages reserved space in the repository.
.SH SYNOPSIS
docs/man/borg-serve.1
+11 -11
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-serve" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-serve" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-serve \- Starts in server mode. This command is usually not used manually.
.SH SYNOPSIS
@@ -43,13 +43,14 @@ It operates in one of two modes:
.INDENT 0.0
.IP \(bu 2
default (no option): serve a \fBlegacy\fP (borg 1.x / v1) repository using the legacy
RPC protocol. This is used e.g. for \fBborg transfer \-\-from\-borg1\fP and is command\-line
compatible with borg 1.x \fBborg serve\fP\&.
RPC protocol. A borg client using an \fBssh://\fP repository together with \fB\-\-from\-borg1\fP
(e.g. \fBborg transfer \-\-from\-borg1\fP) starts this automatically via SSH. It is
command\-line compatible with borg 1.x \fBborg serve\fP\&.
.IP \(bu 2
\fB\-\-rest\fP: serve a \fBcurrent\fP (non\-legacy) repository as the server\-side component of
a \fBrest://\fP repository, talking HTTP over stdio. The repository to serve is given via
\fB\-\-backend FILE:<path>\fP\&. A borg client using a \fBrest://\fP repository starts this
automatically (over SSH if a host is given).
an \fBssh://\fP repository, talking HTTP over stdio. The repository to serve is given via
\fB\-\-backend FILE:<path>\fP\&. A borg client using an \fBssh://\fP repository starts this
automatically via SSH.
.UNINDENT
.sp
Please note that, in legacy mode, \fIborg serve\fP does not support providing a specific
@@ -81,7 +82,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.INDENT 0.0
.TP
.B \-\-rest
serve a current (non\-legacy) repository as a rest:// server (HTTP over stdio). Requires \-\-backend. Without this option, a legacy (borg 1.x) repository is served.
serve a current (non\-legacy) repository as an \%<ssh://> server (HTTP over stdio). Requires \-\-backend. Without this option, a legacy (borg 1.x) repository is served.
.TP
.BI \-\-backend \ BACKEND_URL
(with \-\-rest) backend URL of the repository to serve, e.g. \%<FILE:/\:path/\:to/\:repo>\&.
@@ -117,9 +118,8 @@ restrictions: the client\-given backend is validated against
.UNINDENT
.sp
Notably, \fB\-\-rest\fP is \fInot\fP in the allowlist, so the forced command pins the
mode (current \fBrest://\fP repositories vs. legacy Borg 1.x repositories), and
neither are \fB\-\-restrict\-to\-path\fP, \fB\-\-restrict\-to\-repository\fP, \fB\-\-umask\fP
and \fB\-\-permissions\fP\&.
mode (current repositories vs. legacy Borg 1.x repositories), and neither are
\fB\-\-restrict\-to\-path\fP, \fB\-\-restrict\-to\-repository\fP, \fB\-\-umask\fP and \fB\-\-permissions\fP\&.
.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
@@ -132,7 +132,7 @@ locations like \fB/etc/environment\fP or in the forced command itself (example b
# Allow an SSH keypair to run only 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.
# \-\-rest serves a current (rest://) repository; without it, a legacy Borg 1.x
# \-\-rest serves a current (ssh://) repository; without it, a legacy Borg 1.x
# repository would be served. The client supplies \-\-backend FILE:<path>,
# which is validated against \-\-restrict\-to\-path.
$ cat ~/.ssh/authorized_keys
docs/man/borg-tag.1
+42 -5
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-tag" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-tag" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-tag \- Manage tags.
.SH SYNOPSIS
@@ -50,7 +50,41 @@ special and users are only allowed to use known special tags:
.sp
Pre\-existing special tags cannot be removed via \fB\-\-set\fP\&. You can still use
\fB\-\-set\fP, but you must also give pre\-existing special tags (so they won\(aqt be
removed).
removed). If they are not given, borg emits a warning and does not set the tags
of that archive.
.sp
\fB\-\-clear\fP removes all normal tags, but keeps special tags. Combined with
\fB\-\-add\fP, it replaces the normal tags.
.sp
To change tags, you must select the archives: give an archive NAME or use archive
filter options like \fB\-\-match\-archives\fP\&. To change the tags of all archives, use
\fB\-\-match\-archives \(aqsh:*\(aq\fP\&.
.sp
Each of \fB\-\-set\fP, \fB\-\-add\fP and \fB\-\-remove\fP takes exactly one tag. To give
multiple tags, use the option multiple times.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# add the tags \(dqimportant\(dq and \(dqkeep\(dq to the archive with the given ID
$ borg tag \-\-add important \-\-add keep aid:1ddaae55
# remove the tag \(dqkeep\(dq from all archives named \(dqhome\(dq
$ borg tag \-\-remove keep \-\-match\-archives home
# set the tags of the archive with the given ID to exactly \(dqfoo\(dq and \(dqbar\(dq
$ borg tag \-\-set foo \-\-set bar aid:1ddaae55
# remove all normal tags (but not special tags like @PROT) from the archive with the given ID
$ borg tag \-\-clear aid:1ddaae55
# protect the archive with the given ID against deletion and pruning
$ borg tag \-\-add @PROT aid:1ddaae55
.EE
.UNINDENT
.UNINDENT
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -64,13 +98,16 @@ specify the archive name
.INDENT 0.0
.TP
.BI \-\-set \ TAG
set tags
set tags (can be given multiple times)
.TP
.B \-\-clear
remove all normal tags (keep special tags)
.TP
.BI \-\-add \ TAG
add tags
add tag (can be given multiple times)
.TP
.BI \-\-remove \ TAG
remove tags
remove tag (can be given multiple times)
.UNINDENT
.SS Archive filters
.INDENT 0.0
docs/man/borg-transfer.1
+11 -6
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-transfer" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-transfer" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-transfer \- archives transfer from other repository, optionally upgrade data format
.SH SYNOPSIS
@@ -157,13 +157,13 @@ other repository is borg 1.x
use the upgrader to convert transferred data (default: no conversion)
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. Default: the repository default (see borg repo\-create), else lz4.
.TP
.BI \-\-recompress \ MODE
recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIalways\fP: recompress unconditionally; and \fInever\fP: do not recompress (faster: re\-uses compressed data chunks w/o change).If no MODE is given, \fIalways\fP will be used. Not passing \-\-recompress is equivalent to \(dq\-\-recompress never\(dq.
.TP
.BI \-\-chunker\-params \ PARAMS
rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or \fIdefault\fP to use the chunker defaults. default: do not rechunk
rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or \fIdefault\fP to use the repository default (see borg repo\-create), else the built\-in chunker defaults. default: do not rechunk
.UNINDENT
.SS Archive filters
.INDENT 0.0
@@ -200,9 +200,9 @@ locations and passphrases first:
.INDENT 3.5
.sp
.EX
# The destination is a Borg 2 repository: use a rest:// (or local) location,
# ssh:// is only supported for the legacy Borg 1.x source repository.
export BORG_REPO=rest://borg2@borgbackup/tests/b20
# The destination is a Borg 2 repository, the source is a legacy Borg 1.x repository
# (accessed via the legacy protocol due to \-\-from\-borg1).
export BORG_REPO=ssh://borg2@borgbackup/tests/b20
export BORG_PASSPHRASE=\(aqyour\-borg2\-repo\-passphrase\(aq
export BORG_OTHER_REPO=ssh://borg2@borgbackup/./tests/b1x
export BORG_OTHER_PASSPHRASE=\(aqyour\-borg1\-repo\-passphrase\(aq
@@ -272,6 +272,11 @@ $ borg transfer \-\-from\-borg1 \-\-chunker\-params=$CHUNKER_PARAMS \-\-dry\-run
.EE
.UNINDENT
.UNINDENT
.sp
A Borg 1.x repository in \fBnone\fP mode (not encrypted, unkeyed sha256 chunk IDs) is transferred
like in the second example, re\-chunking with \fB\-\-chunker\-params\fP: all Borg 2 modes use keyed
chunk IDs. Such a repository has no key material to copy, so create the new repository without
giving the Borg 1.x repository as \fB\-\-other\-repo\fP\&.
.SS Keyfile considerations when upgrading from Borg 1.x
.sp
If you are using a \fBkeyfile\fP encryption mode (not \fBrepokey\fP), Borg 2
docs/man/borg-umount.1
+1 -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-umount" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-umount" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-umount \- Unmounts the FUSE filesystem.
.SH SYNOPSIS
docs/man/borg-undelete.1
+1 -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-undelete" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-undelete" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-undelete \- Undeletes archives.
.SH SYNOPSIS
docs/man/borg-version.1
+3 -3
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-version" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-version" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-version \- Displays the Borg client and server versions.
.SH SYNOPSIS
@@ -39,9 +39,9 @@ borg [common options] version [options]
This command displays the Borg client and server versions.
.sp
For current repositories the client code directly accesses the repository (also for
rest:// repositories), so the client version is shown as the server version, too.
\%<ssh://> repositories), so the client version is shown as the server version, too.
.sp
If a legacy (borg 1.x / v1) repository is given via ssh: together with \-\-from\-borg1,
If a legacy (borg 1.x / v1) repository is given via \%<ssh://> together with \-\-from\-borg1,
the remote Borg is queried, and its version is displayed as the server version.
.sp
Examples:
docs/man/borg-webdav.1
+1 -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-webdav" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-webdav" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-webdav \- Serve archive contents via a read-only WebDAV / HTTP server on localhost.
.SH SYNOPSIS
docs/man/borg-with-lock.1
+1 -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-with-lock" "1" "2026-09-02" "" "borg backup tool"
.TH "borg-with-lock" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg-with-lock \- Runs a user-specified command with the repository lock held.
.SH SYNOPSIS
docs/man/borg.1
+34 -34
View File
@@ -29,7 +29,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" "2026-09-02" "" "borg backup tool"
.TH "borg" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borg \- deduplicating and encrypting backup tool
.SH SYNOPSIS
@@ -229,22 +229,16 @@ Note: UNC paths (\fB//server/share/path\fP, \fB\e\eserver\eshare\epath\fP) are n
supported — mount the share (on Windows: map it to a drive letter, e.g.
\fBnet use X: \e\eserver\eshare\fP) and use the mounted path instead.
.sp
\fBRemote repositories\fP accessed via SSH \%<user@\:host> (REST http over stdio):
.sp
\fBrest://user@host:port//abs/path/to/repo\fP — absolute path
.sp
\fBrest://user@host:port/rel/path/to/repo\fP — path relative to the remote login directory
.sp
\fBRemote repositories\fP accessed via SSH \%<user@\:host> (legacy borg RPC protocol):
\fBRemote repositories\fP accessed via SSH \%<user@\:host> (borg serve on the remote host):
.sp
\fBssh://user@host:port//abs/path/to/repo\fP — absolute path
.sp
\fBssh://user@host:port/rel/path/to/repo\fP — path relative to the remote login directory
.sp
For current (non\-legacy) repositories, \fBssh://\fP is rejected; use \fBrest://\fP
instead, which can also tunnel over ssh (see above). \fBssh://\fP remains available
only for legacy borg 1.x repositories, e.g. via
\fBborg transfer \-\-from\-borg1 \-\-other\-repo ssh://...\fP\&.
Borg talks HTTP (REST) over the ssh connection\(aqs stdio to \fBborg serve \-\-rest\fP on the
remote host. Legacy borg 1.x repositories are also accessed via \fBssh://\fP URLs,
together with \fB\-\-from\-borg1\fP (e.g. \fBborg transfer \-\-from\-borg1 \-\-other\-repo ssh://...\fP):
Borg then talks the legacy borg 1.x protocol to \fBborg serve\fP on the remote host.
.sp
\fBRemote repositories\fP accessed via SFTP:
.sp
@@ -252,8 +246,8 @@ only for legacy borg 1.x repositories, e.g. via
.sp
\fBsftp://user@host:port/rel/path/to/repo\fP — path relative to the remote login directory
.sp
For REST, SSH and SFTP URLs, the \fBuser@\fP and \fB:port\fP parts are optional, but the
path is required: a URL without one, e.g. \fBrest://host\fP or \fBrest://host/\fP, is
For SSH and SFTP URLs, the \fBuser@\fP and \fB:port\fP parts are optional, but the
path is required: a URL without one, e.g. \fBssh://host\fP or \fBssh://host/\fP, is
rejected. Mind the difference between one and two slashes after the host: one slash
means a path relative to the directory the remote login lands in (usually the remote
user\(aqs home directory), two slashes mean an absolute path.
@@ -270,7 +264,7 @@ Authentication is HTTP Basic auth: credentials come from the URL if given, other
from the \fBBORGSTORE_REST_USERNAME\fP / \fBBORGSTORE_REST_PASSWORD\fP environment
variables; prefer \fBhttps://\fP over \fBhttp://\fP whenever credentials are used, since
Basic auth sends them on every request. A URL path after the host is optional and,
unlike \fBrest://\fP, is not a remote filesystem path — it does not follow the
unlike \fBssh://\fP, is not a remote filesystem path — it does not follow the
one\-vs\-two\-slash rule above and is only needed to reach the server through a reverse
proxy mounted below a sub\-path.
.sp
@@ -293,7 +287,7 @@ If you frequently need the same repository URL, it is a good idea to set the
.INDENT 3.5
.sp
.EX
export BORG_REPO=\(aqrest://user@host:port/rel/path/to/repo\(aq
export BORG_REPO=\(aqssh://user@host:port/rel/path/to/repo\(aq
.EE
.UNINDENT
.UNINDENT
@@ -592,17 +586,23 @@ Use this so you do not need to type \fB\-\-repo /path/to/my/repo\fP all the time
.B BORG_OTHER_REPO
Similar to BORG_REPO, but gives the default for \fB\-\-other\-repo\fP\&.
.TP
.B BORG_PASSPHRASE (and BORG_OTHER_PASSPHRASE)
.B BORG_PASSPHRASE (and BORG_NEW_PASSPHRASE, BORG_OTHER_PASSPHRASE)
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are mutually exclusive:
if more than one of them is set, borg refuses to guess and aborts with
\(dqMore than one passphrase environment variable is set\(dq. The same applies to the
\fBBORG_OTHER_*\fP variants (which are a separate, independent group).
\fBBORG_NEW_*\fP and \fBBORG_OTHER_*\fP variants (each of which is a separate,
independent group).
See also BORG_NEW_PASSPHRASE.
borg removes the passphrase\-related variables (BORG_PASSPHRASE, BORG_PASSCOMMAND,
BORG_PASSPHRASE_FD and their \fBBORG_NEW_*\fP and \fBBORG_OTHER_*\fP variants) as well as
BORGSTORE_REST_PASSWORD from the environment of the subprocesses it starts (like the
command given in BORG_PASSCOMMAND, \fB\-\-paths\-from\-command\fP / \fB\-\-content\-from\-command\fP
commands, tar filter commands and \fBborg with\-lock\fP commands).
.TP
.B BORG_PASSCOMMAND (and BORG_OTHER_PASSCOMMAND)
.B BORG_PASSCOMMAND (and BORG_NEW_PASSCOMMAND, BORG_OTHER_PASSCOMMAND)
When set, use the standard output of the command (trailing newlines are stripped) to answer the
passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
@@ -611,7 +611,7 @@ is executed without a shell. So variables, like \fB$HOME\fP will work, but \fB~\
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSPHRASE_FD, see there.
See also BORG_NEW_PASSPHRASE.
.TP
.B BORG_PASSPHRASE_FD (and BORG_OTHER_PASSPHRASE_FD)
.B BORG_PASSPHRASE_FD (and BORG_NEW_PASSPHRASE_FD, BORG_OTHER_PASSPHRASE_FD)
When set, specifies a file descriptor to read a passphrase
from. Programs starting borg may choose to open an anonymous pipe
and use it to pass a passphrase. This is safer than passing via
@@ -619,10 +619,12 @@ BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
can be examined by other processes.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSCOMMAND, see there.
.TP
.B BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE, BORG_PASSCOMMAND and
BORG_PASSPHRASE_FD are checked (in that order).
.B BORG_NEW_PASSPHRASE (and BORG_NEW_PASSCOMMAND, BORG_NEW_PASSPHRASE_FD)
When set, use these to answer the passphrase question when a \fBnew\fP passphrase is
asked for: like BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD, but for
the new passphrase.
The \fBBORG_NEW_*\fP group is checked first. If none of its variables is set,
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are checked (in that order).
Main use case for this is to fully automate \fBborg key change\-passphrase\fP\&.
.TP
.B BORG_DISPLAY_PASSPHRASE
@@ -813,7 +815,7 @@ more afterwards. (Re\-chunking in \fBborg transfer\fP is covered by \fBtransfer\
An unknown place name is an error. An empty value (\fBBORG_ASSERT_ID=\fP) verifies at none of
these places, but still where borg always verifies (see below).
.sp
Why \fBread\fP is not in the default: in the keyed modes, the envelope already authenticates
Why \fBread\fP is not in the default: the envelope already authenticates
every read \- the AEAD tag for the encrypted ciphersuites, the MAC for the (unencrypted)
\fBauthenticated\-*\fP modes \- and the chunk id is part of what that tag is computed over. So
a successful decryption resp. tag check already proves that a holder of the borg key
@@ -843,10 +845,8 @@ Independent of this variable, borg always verifies the chunk id:
in \fBborg check \-\-verify\-data\fP\&. That audit is what makes not verifying elsewhere
defensible, so it is not configurable (there is no \fBverify_data\fP place name).
.IP \(bu 2
for \fBnone\-*\fP mode repositories: they have no key, so nothing authenticates a read
there and their unkeyed checksums only detect accidental corruption. The id check is
therefore not optional there: it happens at every place, whatever this variable says.
Same for reading borg 1.x repositories (\fBborg transfer\fP).
when reading borg 1.x repositories (\fBborg transfer \-\-from\-borg1\fP): their envelope does
not cover the chunk id, so the id check is not optional there.
.UNINDENT
.TP
.B BORG_BLAKE3_MT_THRESHOLD
@@ -863,7 +863,8 @@ set it, and can optionally show a chart of the measurements in your browser
.TP
.B BORG_ZSTD_MT_WORKERS
When set to a numeric value, use that many threads to zstd\-compress a single chunk
(default: the cpu count, but at most 4). 0 or 1 means single\-threaded compression.
(default: the cpu count, but at most 4). If it is unset or empty, the default is
used. 0 or 1 means single\-threaded compression.
Only relevant when compressing with \fBzstd\fP\&.
Chunks below 768KiB are always compressed single\-threaded: libzstd will not use a
compression job smaller than 512KiB, so a small chunk gets split very unevenly and
@@ -994,8 +995,7 @@ anyway, without any key material.
Without the key, borg can not verify anything that needs it: neither the
authentication tag of the repository objects nor the chunk ids. It therefore
reads the repository \fBunverified\fP \- a corrupted or tampered repository will
not be detected. (This only concerns the \fBauthenticated\-*\fP modes; the
\fBnone\-*\fP modes need no key and keep verifying their checksums.)
not be detected.
.sp
This workaround is \fBonly\fP for emergencies and \fBonly\fP to extract data
from an affected repository (read\-only access):
@@ -1264,8 +1264,8 @@ Borg now uses the \fBborgstore\fP package to implement the key/value store it
uses for the repository.
.sp
For a local repository (or a locally mounted network filesystem) it uses the
\fBfile:\fP store (posixfs backend). For a remote repository it uses the \fBrest:\fP
store, talking to a \fBborg serve \-\-rest\fP process on the remote side (which in
\fBfile:\fP store (posixfs backend). For a remote \fBssh://\fP repository it uses the
REST store, talking to a \fBborg serve \-\-rest\fP process on the remote side (which in
turn uses borgstore there). Other backends (\fBsftp:\fP, \fBrclone:\fP, \fBs3:\fP/
\fBb2:\fP) do not need a filesystem on the repository side at all.
.sp
docs/man/borgfs.1
+1 -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 "borgfs" "1" "2026-09-02" "" "borg backup tool"
.TH "borgfs" "1" "2026-09-27" "" "borg backup tool"
.SH Name
borgfs \- Mounts an archive or an entire repository as a FUSE filesystem.
.SH SYNOPSIS
docs/usage/break-lock.rst.inc
+4 -1
View File
@@ -38,4 +38,7 @@ Description
This command breaks the repository and cache locks.
Use with care and only when no Borg process (on any machine) is
trying to access the cache or the repository.
trying to access the cache or the repository.
The repository lock objects are protected by the repository key, so this
command needs the key.
docs/usage/check.rst.inc
+35 -17
View File
@@ -98,15 +98,20 @@ The check command verifies the consistency of a repository and its archives.
It consists of two major steps:
1. Checking the consistency of the repository itself. The objects in the ``index/``
and ``packs/`` namespaces are named by the sha256 hash of their content, so such
and ``packs/`` namespaces are named by the store hash of their content, so such
an object is intact if and only if the hash of its content still equals its name.
The check verifies the (small) index objects first and, only if they are intact,
all packs. It also cross-checks the chunk index against the packs present in the
repository to detect referenced but missing packs. Bit rot and other types of
accidental damage can be detected this way, but as sha256 content-addressing is
not a MAC, this step does not detect tampering. Running the repository check can
accidental damage can be detected this way, but as content-addressing is
not a MAC, this step does not detect tampering of the packs. The index objects
are also authenticated with the key when they are loaded for that cross-check.
A corrupt index ends the check after this step, as the archives check needs it,
unless ``--repair`` is given (see below). This step also verifies the repository
defaults object (see ``borg repo-create``): it must be present and authenticate
with the key. Running the repository check can
be split into multiple partial checks using ``--max-duration``.
For rest:// repositories, the server computes the hashes, so the pack contents do
For ssh:// repositories, the server computes the hashes, so the pack contents do
not have to travel over the network. For other remote backends, borg usually has
to read (download) the objects to hash them.
@@ -129,6 +134,10 @@ Both steps can also be run independently. Pass ``--repository-only`` to run the
repository checks only, or pass ``--archives-only`` to run the archive checks
only.
``borg check`` always needs the key, ``--repository-only`` included: it loads
the key (asking for the passphrase, if needed) before it checks anything and
aborts if the key can not be loaded.
The ``--max-age`` option makes the check reuse the results of previous
repository checks: packs whose intact result is younger than the given
timespan (e.g. ``--max-age=4w`` or ``--max-age=12m``) are skipped, spreading
@@ -188,16 +197,18 @@ description for more details about the format string).
If the ``borg check`` process receives a SIGINT signal (Ctrl-C), it stops at the
next safe boundary, leaving the repository and its chunk index in a consistent state.
The repository check stops after the current pack; ``--verify-data`` and
``--find-lost-archives`` stop after the current chunk; a ``--repair`` archive check
stops between whole archives. Results recorded before the interrupt are kept, so a later
check does not re-verify those packs until they are due again. With ``--repair``, an
interrupted archive check may leave some archives already repaired and others not yet
processed, so run ``borg check --repair`` again to finish.
``--find-lost-archives`` stop after the current chunk; the archive check stops after the
current archive item, with ``--repair`` between whole archives. Results recorded before
the interrupt are kept, so a later check does not re-verify those packs until they are
due again. With ``--repair``, an interrupted archive check may leave some archives already
repaired and others not yet processed, so run ``borg check --repair`` again to finish.
During a ``--repair`` run, the archive check first rebuilds the chunk index from the
packs, and, if the key must be recovered, scans chunks for it. These phases do not yet
respond to SIGINT, so on a large repository a Ctrl-C during them may appear to have no
effect until they finish.
``borg check`` rebuilds the chunk index from the packs when ``--repair`` is given or when
the stored index cannot be used. Ctrl-C stops that rebuild after the current object and
discards the partial index: it lacks chunks that are still in the repository, so the check
would report them as lost. After a ``--repair`` that stored or deleted chunks, borg re-reads the
packs the repair wrote, makes the chunk index match them and stores it; that always runs to
completion, also after a Ctrl-C.
About repair mode
+++++++++++++++++
@@ -230,10 +241,17 @@ by definition, a potentially lossy task.
In practice, repair mode hooks into both the repository and archive checks:
1. When checking the repository's consistency, repair mode rebuilds the repository
index from the packs if the index is corrupt, provided every pack is intact. If
any pack is corrupt, the repository check leaves the index and the packs untouched
and reports the corruption; salvaging a corrupt pack's still-intact objects is not
implemented yet (refs #8572).
index from the packs if the index is corrupt, provided every pack matches its
store hash. If any pack fails its store hash, the repository check leaves the
index and the packs untouched and reports it; salvaging the intact objects of
such a pack is not implemented yet (refs #8572). The rebuild authenticates
each object's header and metadata with the key, leaves an object that fails
this out of the index and reports it as an error. Repair mode also removes the
index entries of the chunks stored in missing packs (packs the index references,
but that are absent from the repository). Only a full ``borg check --repair``
repairs the archives that reference these chunks, ``--repository-only`` does not.
A missing or corrupt repository defaults object is replaced by empty defaults, so
the repository can be used again; the commands then use the built-in defaults.
2. When checking the consistency and correctness of archives, repair mode might
remove whole archives from the manifest if their archive metadata chunk is
docs/usage/compact.rst.inc
+7
View File
@@ -69,6 +69,13 @@ Other bytes no index entry covers, such as packs left behind by a backup that cr
before recording its objects, are re-indexed by ``borg check --repair`` and reclaimed by
the next ``borg compact``.
``borg compact`` does not rewrite or merge packs that ``borg check`` recorded as corrupt
and warns about them. ``borg check --repair --verify-data`` deletes the corrupt chunks by
rewriting their packs. It does not remove damage outside any chunk (e.g. bytes appended to a
pack): a pack with such damage and no corrupt chunk stays recorded corrupt and ``borg compact``
warns about it on every run, a pack that also has a corrupt chunk is rewritten with that damage
copied into the new pack (refs #10026).
You usually do not want to run ``borg compact`` after every write operation, but
either regularly (e.g., once a month, possibly together with ``borg check``) or
when disk space needs to be freed.
docs/usage/create.rst.inc
+8 -7
View File
@@ -115,11 +115,11 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2 |
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: the repository default (see borg repo-create), else fastcdc,19,23,21,2 |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4. |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--tags TAG`` | add tags to archive (comma-separated or multiple arguments) |
| | ``--tag TAG`` | add tag to archive (can be given multiple times) |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -193,9 +193,9 @@ borg create
Archive options
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
--chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--tags TAG add tags to archive (comma-separated or multiple arguments)
--chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: the repository default (see borg repo-create), else fastcdc,19,23,21,2
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4.
--tag TAG add tag to archive (can be given multiple times)
Description
@@ -236,7 +236,8 @@ appropriate to use --content-from-command. See the section
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
The ``--tags`` option can be used to add a list of tags to the new archive.
The ``--tag`` option can be used to add a tag to the new archive. To add
multiple tags, give it multiple times, e.g. ``--tag foo --tag bar``.
The archive name does not need to be unique; you can and should use the same
name for a series of archives. The unique archive identifier is its ID (hash),
docs/usage/diff.rst.inc
+37 -4
View File
@@ -31,6 +31,8 @@ borg diff
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--json-lines`` | Format output as JSON Lines. |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print a summary of the differences at the end |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--sort-by`` | Sort output by comma-separated fields (e.g., '>size_added,path'). |
+-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------------+
| | ``--content-only`` | Only compare differences in content (exclude metadata differences) |
@@ -73,7 +75,8 @@ borg diff
--same-chunker-params override the check of chunker parameters
--format FORMAT specify format for differences between archives (default: "{change} {path}{NL}")
--json-lines Format output as JSON Lines.
--sort-by Sort output by comma-separated fields (e.g., '>size_added,path').
-s, --stats print a summary of the differences at the end
--sort-by Sort output by comma-separated fields (e.g., '>size_added,path').
--content-only Only compare differences in content (exclude metadata differences)
@@ -155,9 +158,15 @@ 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. In the latter case, borg
can only tell that a file was modified, not by how much: no byte counts are given for it, the
text output shows "modified: (can't get size)" instead.
Borg compares chunk IDs quickly: it aligns the two chunk lists of a file like a text diff
aligns lines, and the byte counts are the total sizes of the chunks that are not part of that
alignment. Inserted, removed, moved and duplicated content is therefore accounted for - a
chunk that only moved within the file shows up as removed and added again. Files with very
long or very repetitive chunk lists are not aligned (this would be too slow); for these, only
the number of occurrences of each chunk ID is compared, so moved content does not show up in
their byte counts. If chunker parameters are not comparable, Borg compares the content. In
that case, borg can only tell that a file was modified, not by how much: no byte counts
are given for it, the text output shows "modified: (can't get size)" instead.
- Metadata changes: user, group, mode, and other metadata shown inline as "[old -> new]", like
"[-rw-r--r-- -> -rwxr-xr-x]" for a mode change. Use ``--content-only`` to suppress metadata changes.
- Added/removed items: printed as "added: SIZE path" or "removed: SIZE path".
@@ -183,6 +192,30 @@ values as "item1" and "item2". Example::
{"changes": [{"added": 4, "removed": 0, "type": "added"}], "path": "path/to/added-file"}
{"changes": [{"added": 0, "removed": 5, "type": "removed"}], "path": "path/to/removed-file"}
Statistics
++++++++++
With ``--stats``, borg prints a summary of the differences after the per-path output::
Added items: 23
Removed items: 2
Changed items: 315
Added size: 53.70 MB
Removed size: 51.10 MB
"Added"/"Removed" items only exist in ARCHIVE2/ARCHIVE1, "changed" items exist in both
archives but differ. "Added size"/"Removed size" sum up the file content (in bytes) added/removed
by all of these items, i.e. the per-path byte counts that ``--sort-by size_added`` /
``size_removed`` sort by. Items whose content borg could only
compare byte by byte (see "Performance considerations" below) contribute no byte counts;
if there are any, an additional "Items with unknown size changes" line reports how many.
Together with ``--json-lines``, the summary is emitted as a final JSON line of the shape
``{"stats": {...}}`` instead, so it is easy to tell apart from the per-path lines
(wrapped here for readability, borg prints it as a single line)::
{"stats": {"added_items": 23, "changed_items": 315, "removed_items": 2,
"size_added": 53700000, "size_removed": 51100000, "unknown_size_items": 0}}
Sorting
++++++++
Use ``--sort-by FIELDS`` where FIELDS is a comma-separated list of fields.
docs/usage/extract.rst.inc
+89 -47
View File
@@ -12,51 +12,51 @@ borg extract
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``NAME`` | specify the archive name |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to extract; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--list`` | output a verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print store statistics for the extraction |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not actually change any files |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--numeric-ids`` | only use numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--noflags`` | do not extract/set flags (e.g. NODUMP, IMMUTABLE) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--noacls`` | do not extract/set ACLs |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--noxattrs`` | do not extract/set xattrs |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--stdout`` | write all extracted data to stdout |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--sparse`` | create holes in the output sparse file from all-zero chunks |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--continue`` | continue a previously interrupted extraction of the same archive |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| .. 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 |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``NAME`` | specify the archive name |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to extract; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output a verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print store statistics for the extraction |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not actually change any files |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--numeric-ids`` | only use numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noflags`` | do not extract/set flags (e.g. NODUMP, IMMUTABLE) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noacls`` | do not extract/set ACLs |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noxattrs`` | do not extract/set xattrs |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdout`` | write all extracted data to stdout |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sparse`` | create holes in the output sparse file from all-zero chunks |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--continue`` | extract into a non-empty directory, e.g. to continue a previously interrupted extraction of the same archive: skip files that are fully extracted already, replace other existing files |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. 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 |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -84,7 +84,7 @@ borg extract
--noxattrs do not extract/set xattrs
--stdout write all extracted data to stdout
--sparse create holes in the output sparse file from all-zero chunks
--continue continue a previously interrupted extraction of the same archive
--continue extract into a non-empty directory, e.g. to continue a previously interrupted extraction of the same archive: skip files that are fully extracted already, replace other existing files
:ref:`common_options`
@@ -119,6 +119,33 @@ decrypting, and decompressing.
``--progress`` can be slower than no progress display, since it makes one additional
pass over the archive metadata.
Extracting into a non-empty directory replaces existing files that are in the way and
leaves all other existing files as they are. The result is a mix of the files that were
there before and the extracted files, which might not be what you want - especially not
by accident in a directory that is in use (e.g. your home directory). Thus, borg refuses
to extract into a non-empty directory unless ``--continue`` is given (``--dry-run`` and
``--stdout`` do not write into the directory, so they always work). The usual way to
restore is to extract into a new, empty directory: after that, the directory has exactly
the contents of the extracted archive (or of the selected part of it).
``--continue`` extracts into a non-empty directory. It is made for continuing a previously
interrupted extraction of the same archive into the same directory: an existing regular
file that has the same type, permissions (mode), size and modification time as the
archived file is considered to be fully extracted already and is skipped. Everything else
is extracted, replacing existing files. Files that are in the directory, but not in the
archive, are left as they are. ``--continue`` is thus also needed to restore files into an
existing directory tree. Note that a file that was damaged without a change of its size
and modification time (e.g. by bit rot) is skipped, not replaced: remove it before
extracting it.
If a file's content chunks are missing from the repository or are corrupted (they fail
authentication, decryption or decompression), the extraction does not abort: each such
chunk is written as all-zero data of the correct size, an error naming the chunk is logged,
the file is reported with a warning and the exit code is a warning. The extracted file thus
has the correct size and metadata, but wrong (all-zero) content where the damaged chunks
were. Run ``borg check`` to find out which chunks and archives are affected. This also
applies to ``--dry-run`` (which thus can be used to find unreadable files) and ``--stdout``.
When using ``--stats``, borg reports the store statistics (lines prefixed with
"Store") for the extraction: per-operation call counts and timings, the load/store
data volumes and throughput, and cache hits/misses. This includes ``--dry-run``
@@ -131,4 +158,19 @@ extractions.
When parent directories are not extracted (because of using file/directory selection
or any other reason), Borg cannot restore parent directories' metadata, e.g., owner,
group, permissions, etc.
group, permissions, etc.
.. note::
Restoring some file metadata requires root privileges (or equivalent
capabilities). This includes the owner and group of files, device nodes,
privileged file flags (like immutable or append-only) and privileged
extended attributes (like Linux capabilities or ``trusted.*`` xattrs).
When running as a normal user, borg still extracts the file contents, but
the extracted files are owned by the invoking user (the failure to restore
ownership is silently ignored: no warning, exit code unaffected), privileged
flags are skipped while the other flags are still set, and privileged xattrs
and device nodes are skipped with a warning. ``--numeric-ids`` does not
change this, it only selects whether the archived numeric IDs or the archived
user/group names are used. To restore all metadata, run ``borg extract`` as root.
docs/usage/general/environment.rst.inc
+20 -15
View File
@@ -11,16 +11,22 @@ General:
Use this so you do not need to type ``--repo /path/to/my/repo`` all the time.
BORG_OTHER_REPO
Similar to BORG_REPO, but gives the default for ``--other-repo``.
BORG_PASSPHRASE (and BORG_OTHER_PASSPHRASE)
BORG_PASSPHRASE (and BORG_NEW_PASSPHRASE, BORG_OTHER_PASSPHRASE)
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are mutually exclusive:
if more than one of them is set, borg refuses to guess and aborts with
"More than one passphrase environment variable is set". The same applies to the
``BORG_OTHER_*`` variants (which are a separate, independent group).
``BORG_NEW_*`` and ``BORG_OTHER_*`` variants (each of which is a separate,
independent group).
See also BORG_NEW_PASSPHRASE.
BORG_PASSCOMMAND (and BORG_OTHER_PASSCOMMAND)
borg removes the passphrase-related variables (BORG_PASSPHRASE, BORG_PASSCOMMAND,
BORG_PASSPHRASE_FD and their ``BORG_NEW_*`` and ``BORG_OTHER_*`` variants) as well as
BORGSTORE_REST_PASSWORD from the environment of the subprocesses it starts (like the
command given in BORG_PASSCOMMAND, ``--paths-from-command`` / ``--content-from-command``
commands, tar filter commands and ``borg with-lock`` commands).
BORG_PASSCOMMAND (and BORG_NEW_PASSCOMMAND, BORG_OTHER_PASSCOMMAND)
When set, use the standard output of the command (trailing newlines are stripped) to answer the
passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
@@ -28,17 +34,19 @@ General:
is executed without a shell. So variables, like ``$HOME`` will work, but ``~`` won't.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSPHRASE_FD, see there.
See also BORG_NEW_PASSPHRASE.
BORG_PASSPHRASE_FD (and BORG_OTHER_PASSPHRASE_FD)
BORG_PASSPHRASE_FD (and BORG_NEW_PASSPHRASE_FD, BORG_OTHER_PASSPHRASE_FD)
When set, specifies a file descriptor to read a passphrase
from. Programs starting borg may choose to open an anonymous pipe
and use it to pass a passphrase. This is safer than passing via
BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
can be examined by other processes.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSCOMMAND, see there.
BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a **new** passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE, BORG_PASSCOMMAND and
BORG_PASSPHRASE_FD are checked (in that order).
BORG_NEW_PASSPHRASE (and BORG_NEW_PASSCOMMAND, BORG_NEW_PASSPHRASE_FD)
When set, use these to answer the passphrase question when a **new** passphrase is
asked for: like BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD, but for
the new passphrase.
The ``BORG_NEW_*`` group is checked first. If none of its variables is set,
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are checked (in that order).
Main use case for this is to fully automate ``borg key change-passphrase``.
BORG_DISPLAY_PASSPHRASE
When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
@@ -186,7 +194,7 @@ General:
An unknown place name is an error. An empty value (``BORG_ASSERT_ID=``) verifies at none of
these places, but still where borg always verifies (see below).
Why ``read`` is not in the default: in the keyed modes, the envelope already authenticates
Why ``read`` is not in the default: the envelope already authenticates
every read - the AEAD tag for the encrypted ciphersuites, the MAC for the (unencrypted)
``authenticated-*`` modes - and the chunk id is part of what that tag is computed over. So
a successful decryption resp. tag check already proves that a holder of the borg key
@@ -208,10 +216,8 @@ General:
- in ``borg check --verify-data``. That audit is what makes not verifying elsewhere
defensible, so it is not configurable (there is no ``verify_data`` place name).
- for ``none-*`` mode repositories: they have no key, so nothing authenticates a read
there and their unkeyed checksums only detect accidental corruption. The id check is
therefore not optional there: it happens at every place, whatever this variable says.
Same for reading borg 1.x repositories (``borg transfer``).
- when reading borg 1.x repositories (``borg transfer --from-borg1``): their envelope does
not cover the chunk id, so the id check is not optional there.
BORG_BLAKE3_MT_THRESHOLD
When set to a numeric value, chunks of at least that many KiB get their id computed by
multi-threaded BLAKE3, smaller ones single-threaded (default: 256, i.e. 256KiB).
@@ -341,8 +347,7 @@ General:
Without the key, borg can not verify anything that needs it: neither the
authentication tag of the repository objects nor the chunk ids. It therefore
reads the repository **unverified** - a corrupted or tampered repository will
not be detected. (This only concerns the ``authenticated-*`` modes; the
``none-*`` modes need no key and keep verifying their checksums.)
not be detected.
This workaround is **only** for emergencies and **only** to extract data
from an affected repository (read-only access)::
docs/usage/help.rst.inc
+7 -4
View File
@@ -324,7 +324,7 @@ The patterns can have a prefix of:
- aid: prefix match on the archive id (only one result allowed)
- user: exact match on the username who created the archive
- host: exact match on the hostname where the archive was created
- tags: match on the archive tags
- tags: match archives having all the given tags (comma-separated, e.g. tags:TAG1,TAG2)
- date: match on the archive creation timestamp
In case of a name pattern match,
@@ -399,8 +399,9 @@ Examples::
borg delete -a 'user:kenny'
borg delete -a 'host:kenny-pc'
# tags match
# tags match (both lines match archives having TAG1 and TAG2)
borg delete -a 'tags:TAG1' -a 'tags:TAG2'
borg delete -a 'tags:TAG1,TAG2'
# archive creation date match
borg delete -a 'date:2025-01'
@@ -494,7 +495,9 @@ another backup that also uses this chunk will not change the stored chunk.
So if you use different compression specs for the backups, whichever stores a
chunk first determines its compression. See also ``borg recreate``.
Compression is lz4 by default. If you want something else, you have to specify what you want.
If you do not specify a compression via ``--compression`` (or the environment or the
default config file), the repository's default compression is used, which can be set
with ``borg repo-create --compression``. Without a repository default, compression is lz4.
Valid compression specifiers are:
@@ -502,7 +505,7 @@ none
Do not compress.
lz4
Use lz4 compression. Very high speed, very low compression. (default)
Use lz4 compression. Very high speed, very low compression. (built-in default)
zstd[,L]
Use zstd ("zstandard") compression, a modern wide-range algorithm.
docs/usage/import-tar.rst.inc
+52 -39
View File
@@ -12,43 +12,45 @@ borg import-tar
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``NAME`` | specify the archive name |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``TARFILE`` | input tar file. "-" to read from stdin instead. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--tar-filter`` | filter program to pipe data through |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the created archive |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON (implies --stats) |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--ignore-zeros`` | ignore zero-filled blocks in the input tarball |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: fastcdc,19,23,21,2 |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--digests ALGOS`` | compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``NAME`` | specify the archive name |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``TARFILE`` | input tar file. "-" to read from stdin instead. |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--tar-filter`` | filter program to pipe data through |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the created archive |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON (implies --stats) |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--ignore-zeros`` | ignore zero-filled blocks in the input tarball |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: the repository default (see borg repo-create), else fastcdc,19,23,21,2 |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4. |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--digests ALGOS`` | compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none |
+-------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -73,6 +75,7 @@ borg import-tar
--filter STATUSCHARS only display items with the given status characters
--json output stats as JSON (implies --stats)
--ignore-zeros ignore zero-filled blocks in the input tarball
--strip-components NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
:ref:`common_options`
@@ -81,8 +84,8 @@ borg import-tar
Archive options
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
--chunker-params PARAMS specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: fastcdc,19,23,21,2
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--chunker-params PARAMS specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: the repository default (see borg repo-create), else fastcdc,19,23,21,2
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4.
--digests ALGOS compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none
@@ -113,6 +116,16 @@ stdout.
Most documentation of borg create applies. Note that this command does not
support excluding files.
``--strip-components`` removes the specified number of leading path elements
from the tar member names when creating the archive items. Members whose path
has fewer or equally many elements are silently skipped. Hard link targets are
stripped accordingly, symbolic link targets are left unchanged.
The path elements are counted after normalizing the member name the same way it
is stored in the archive, so a leading ``./`` is not a path element. This differs
from ``tar``, which counts it: to import ``./top/dir/file`` as ``dir/file``, use
``--strip-components=1`` here, while ``tar`` needs ``--strip-components=2``.
A ``--sparse`` option (as found in borg create) is not needed: sparse members in
input tarballs (old GNU and PAX sparse formats) are read correctly and their
holes are stored as deduplicated all-zero chunks.
docs/usage/mount.rst.inc
+12 -3
View File
@@ -195,13 +195,22 @@ 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 the future.
- ``allow_damaged_files``: by default, damaged files (where chunks are missing)
will return EIO (I/O error) when trying to read the related parts of the file.
Set this option to replace the missing parts with all-zero bytes.
- ``allow_damaged_files``: by default, damaged files (where chunks are missing or
corrupted) will return EIO (I/O error) when trying to read the related parts of the
file. Set this option to replace the damaged parts with all-zero bytes.
- ``ignore_permissions``: for security reasons the ``default_permissions`` mount
option is internally enforced by Borg. ``ignore_permissions`` can be given to
not enforce ``default_permissions``.
On Windows, ``borg mount`` needs `WinFsp <https://winfsp.dev/>`_ and mfusepy.
MOUNTPOINT must either be an unused drive (like ``X:``) or a not yet existing
directory (WinFsp creates it when mounting and removes it when unmounting).
``borg mount`` always stays in the foreground there and ``borg umount`` is not
supported: to unmount, stop ``borg mount`` using Ctrl-C or Ctrl-Break. All files
belong to the user who mounts, unless the ``uid`` / ``gid`` mount options (which
are implemented by WinFsp there, not by Borg) say otherwise. ``ignore_permissions``
has no effect. WinFsp does not support hard link counts (they are always 1).
The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is intended for advanced users
to tweak performance. It sets the number of cached data chunks; additional
memory usage can be up to ~8 MiB times this number. The default is the number
docs/usage/recreate.rst.inc
+65 -65
View File
@@ -12,69 +12,69 @@ borg recreate
.. class:: borg-options-table
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to recreate; patterns are supported |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters (listed in borg create --help) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change anything |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics at end |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. 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 |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (https://www.bford.info/cachedir/spec.html) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--target TARGET`` | create a new archive with the name TARGET, do not replace existing archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. Only applies to newly written data, e.g. when re-chunking with --chunker-params (and to the new archive metadata); data chunks reused from the existing archive are not recompressed, use borg repo-compress for that. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to recreate; patterns are supported |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters (listed in borg create --help) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change anything |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics at end |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. 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 |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (https://www.bford.info/cachedir/spec.html) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--target TARGET`` | create a new archive with the name TARGET, do not replace existing archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. Only applies to newly written data, e.g. when re-chunking with --chunker-params (and to the new archive metadata); data chunks reused from the existing archive are not recompressed, use borg repo-compress for that. Default: the repository default (see borg repo-create), else lz4. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the repository default (see borg repo-create), else the built-in chunker defaults. default: do not rechunk |
+-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -122,8 +122,8 @@ borg recreate
--target TARGET create a new archive with the name TARGET, do not replace existing archive
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. Only applies to newly written data, e.g. when re-chunking with --chunker-params (and to the new archive metadata); data chunks reused from the existing archive are not recompressed, use borg repo-compress for that.
--chunker-params PARAMS rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. Only applies to newly written data, e.g. when re-chunking with --chunker-params (and to the new archive metadata); data chunks reused from the existing archive are not recompressed, use borg repo-compress for that. Default: the repository default (see borg repo-create), else lz4.
--chunker-params PARAMS rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the repository default (see borg repo-create), else the built-in chunker defaults. default: do not rechunk
Description
docs/usage/repo-compress.rst.inc
+22 -13
View File
@@ -12,17 +12,17 @@ borg repo-compress
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4. |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -37,7 +37,7 @@ borg repo-compress
options
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4.
-s, --stats print statistics
@@ -50,7 +50,9 @@ Description
Repository (re-)compression (and/or re-obfuscation).
Reads all repository objects and recompresses the ones that are not already using
the compression type/level and obfuscation level given via ``--compression``.
the compression type/level and obfuscation level given via ``--compression``. Without
``--compression``, that is the repository's default compression (see ``borg repo-create``),
else lz4.
The repository is processed one pack file at a time: a pack is read as a whole and,
if it holds objects that need recompression, rewritten as a whole - objects already
@@ -60,6 +62,13 @@ Please note that the outcome of recompressing a chunk might not always be the
desired compression type/level - if no compression gives a shorter output, that
might be chosen; such chunks are kept as they are.
``borg repo-compress`` does not rewrite packs that ``borg check`` recorded as corrupt
and warns about them. ``borg check --repair --verify-data`` deletes the corrupt chunks by
rewriting their packs. It does not remove damage outside any chunk (e.g. bytes appended to a
pack): a pack with such damage and no corrupt chunk stays recorded corrupt and is not rewritten,
a pack that also has a corrupt chunk is rewritten with that damage copied into the new pack
(refs #10026).
Rewriting a pack invalidates every client's cached chunk index, so the next borg
operation of each client will re-fetch the chunk index from the repository.
docs/usage/repo-create.rst.inc
+62 -33
View File
@@ -12,25 +12,29 @@ borg repo-create
.. class:: borg-options-table
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | reuse the key material from the other repository |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--from-borg1`` | other repository is Borg 1.x |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e ENCRYPTION``, ``--encryption ENCRYPTION`` | select the mode: 'aes256-ocb', 'chacha20-poly1305', 'authenticated-sha256', 'authenticated-blake3', 'none-sha256' or 'none-blake3' **(required)** |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-i HASH``, ``--id-hash HASH`` | select the id hash function of the encrypted modes: 'sha256' or 'blake3'. The 'none-*' and 'authenticated-*' modes name their hash themselves. |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--key-location LOCATION`` | where to store the key: 'repokey' (in the repository, default) or 'keyfile' (in the local keys directory). Ignored for the ``none-*`` modes (which have no key). |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--copy-crypt-key`` | copy the crypt_key (used for authenticated encryption) from the key of the other repository (default: new random key). |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | reuse the key material from the other repository |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--from-borg1`` | other repository is Borg 1.x |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e ENCRYPTION``, ``--encryption ENCRYPTION`` | select the mode: 'aes256-ocb', 'chacha20-poly1305', 'authenticated-sha256' or 'authenticated-blake3' **(required)** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-i HASH``, ``--id-hash HASH`` | select the id hash function of the encrypted modes: 'sha256' or 'blake3'. The 'authenticated-sha256' and 'authenticated-blake3' modes name their hash themselves. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--key-location LOCATION`` | where to store the key: 'repokey' (in the repository, default) or 'keyfile' (in the local keys directory). |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | set the default compression of the repository, see the output of the "borg help compression" command for details. Default: no repository default (lz4 is used). |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | set the default chunker parameters of the repository (same format as for borg create). Default: no repository default (fastcdc,19,23,21,2 is used). |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--copy-crypt-key`` | copy the crypt_key (used for authenticated encryption) from the key of the other repository (default: new random key). |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -47,9 +51,11 @@ borg repo-create
options
--other-repo SRC_REPOSITORY reuse the key material from the other repository
--from-borg1 other repository is Borg 1.x
-e ENCRYPTION, --encryption ENCRYPTION select the mode: 'aes256-ocb', 'chacha20-poly1305', 'authenticated-sha256', 'authenticated-blake3', 'none-sha256' or 'none-blake3' **(required)**
-i HASH, --id-hash HASH select the id hash function of the encrypted modes: 'sha256' or 'blake3'. The 'none-*' and 'authenticated-*' modes name their hash themselves.
--key-location LOCATION where to store the key: 'repokey' (in the repository, default) or 'keyfile' (in the local keys directory). Ignored for the ``none-*`` modes (which have no key).
-e ENCRYPTION, --encryption ENCRYPTION select the mode: 'aes256-ocb', 'chacha20-poly1305', 'authenticated-sha256' or 'authenticated-blake3' **(required)**
-i HASH, --id-hash HASH select the id hash function of the encrypted modes: 'sha256' or 'blake3'. The 'authenticated-sha256' and 'authenticated-blake3' modes name their hash themselves.
--key-location LOCATION where to store the key: 'repokey' (in the repository, default) or 'keyfile' (in the local keys directory).
-C COMPRESSION, --compression COMPRESSION set the default compression of the repository, see the output of the "borg help compression" command for details. Default: no repository default (lz4 is used).
--chunker-params PARAMS set the default chunker parameters of the repository (same format as for borg create). Default: no repository default (fastcdc,19,23,21,2 is used).
--copy-crypt-key copy the crypt_key (used for authenticated encryption) from the key of the other repository (default: new random key).
@@ -118,6 +124,14 @@ a different keyboard layout.
You can change your passphrase for existing repositories at any time; it will not affect
the encryption/decryption key or other secrets.
Borg also accepts an empty passphrase. The repository is still encrypted with a random
key then, but that key is not protected: with ``repokey`` storage, anybody who can read
the repository can also unlock the key, which is as good as no encryption at all (with
``keyfile`` storage, the key is only on your client, so an empty passphrase may be
acceptable if e.g. the client's disk is encrypted). You can add a passphrase later with
``borg key change-passphrase``. ``borg repo-info`` shows whether the key has an empty
passphrase.
Choosing a crypto suite
+++++++++++++++++++++++
@@ -130,8 +144,6 @@ The easiest way to find out what is fastest is to run ``borg benchmark cpu``.
- ``chacha20-poly1305``: ChaCha20 + Poly1305 (encryption + authentication).
- ``authenticated-sha256`` / ``authenticated-blake3``: no encryption, but authentication
(tamper detection) using HMAC-SHA-256 resp. keyed BLAKE3.
- ``none-sha256`` / ``none-blake3``: neither encryption nor authentication, only
SHA-256 resp. BLAKE3 checksums (see below).
``--id-hash`` selects the id hash function of the **encrypted** modes:
@@ -153,15 +165,6 @@ You can move the key between these locations later with ``borg key change-locati
This also applies to the ``authenticated-*`` modes: they do not encrypt your data, but they
still have a key (used for the id hash and the authentication), so ``--key-location``
selects where that key is stored, just like for the encrypted modes.
``--key-location`` is only ignored for the ``none-*`` modes, which have no key at all.
The ``none-*`` modes use neither encryption nor authentication: everything in the
repository is readable by anybody, and while every repository object carries a checksum
(which detects accidental corruption, e.g. bad storage hardware), anybody who modifies an
object can just recompute that checksum. You are advised NOT to use these modes: in case
of malicious activity in the repository, they expose you to a Denial-of-Service risk (due
to how the :ref:`internals_hashindex` works) and other issues (confidentiality,
tampering, ...).
If you do **not** want to encrypt the contents of your backups, but still want to detect
malicious tampering, use ``--encryption authenticated-sha256`` (or ``-blake3``). These
@@ -169,6 +172,32 @@ modes are like an encrypted mode minus the data encryption.
To normally work with ``authenticated-*`` repositories, you will need the passphrase, but
there is an emergency workaround; see ``BORG_WORKAROUNDS=authenticated_no_key`` docs.
Repository defaults
+++++++++++++++++++
``--compression`` sets the repository's default compression: the commands that compress
data (``borg create``, ``borg recreate``, ``borg import-tar``, ``borg transfer``,
``borg repo-compress``) use it if no compression was given via ``--compression``, the
environment or the default config file (``default.yaml``). Without a repository default,
they use lz4. See ``borg help compression`` for the compression specs.
``--chunker-params`` sets the repository's default chunker parameters: ``borg create`` and
``borg import-tar`` use them if no chunker parameters were given (in the same ways as above).
``borg recreate`` and ``borg transfer`` only rechunk if ``--chunker-params`` is given, with
``--chunker-params default``, they rechunk to the repository's default chunker parameters.
Without a repository default, the built-in default chunker parameters are used.
This is useful if several clients back up into the same repository or if some commands are
run manually: they all compress and chunk the same way without having to give these options.
Using the same chunker parameters is important for deduplication.
``borg repo-info`` shows the defaults.
The defaults are stored in the repository and protected by the repository key: changing them
(e.g. removing an ``obfuscate`` compression) needs the key. The defaults object is always
written, also when no default was given, so removing it is noticed, too: the commands refuse
to run if it is missing or fails the authentication. ``borg check`` reports such an object,
``borg check --repair`` replaces it by empty defaults (the built-in defaults are used then).
Creating a related repository
+++++++++++++++++++++++++++++
docs/usage/repo-delete.rst.inc
+6
View File
@@ -63,4 +63,10 @@ When you delete a complete repository, the security info and local cache for it
with the ``--cache-only`` option, or keep the security info with the
``--keep-security-info`` option.
``--force`` also destroys a store that has no repository config, provided it looks
like a borg store (it has the packs, archives, index and config namespaces).
Deleting a repository needs its key, as locking it needs the key. If the key is lost,
the repository is useless and has to be deleted with the storage's own tools.
Always first use ``--dry-run --list`` to see what would be deleted.
docs/usage/serve.rst.inc
+8 -7
View File
@@ -15,7 +15,7 @@ borg serve
+-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--rest`` | serve a current (non-legacy) repository as a rest:// server (HTTP over stdio). Requires --backend. Without this option, a legacy (borg 1.x) repository is served. |
| | ``--rest`` | serve a current (non-legacy) repository as an ssh:// server (HTTP over stdio). Requires --backend. Without this option, a legacy (borg 1.x) repository is served. |
+-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--backend BACKEND_URL`` | (with --rest) backend URL of the repository to serve, e.g. FILE:/path/to/repo. |
+-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -43,7 +43,7 @@ borg serve
options
--rest serve a current (non-legacy) repository as a rest:// server (HTTP over stdio). Requires --backend. Without this option, a legacy (borg 1.x) repository is served.
--rest serve a current (non-legacy) repository as an ssh:// server (HTTP over stdio). Requires --backend. Without this option, a legacy (borg 1.x) repository is served.
--backend BACKEND_URL (with --rest) backend URL of the repository to serve, e.g. FILE:/path/to/repo.
--restrict-to-path PATH Restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all subdirectories is granted implicitly; PATH does not need to point directly to a repository.
--restrict-to-repository PATH Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path``, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
@@ -62,13 +62,14 @@ SSH by a borg client and runs until that SSH connection is terminated.
It operates in one of two modes:
- default (no option): serve a **legacy** (borg 1.x / v1) repository using the legacy
RPC protocol. This is used e.g. for ``borg transfer --from-borg1`` and is command-line
compatible with borg 1.x ``borg serve``.
RPC protocol. A borg client using an ``ssh://`` repository together with ``--from-borg1``
(e.g. ``borg transfer --from-borg1``) starts this automatically via SSH. It is
command-line compatible with borg 1.x ``borg serve``.
- ``--rest``: serve a **current** (non-legacy) repository as the server-side component of
a ``rest://`` repository, talking HTTP over stdio. The repository to serve is given via
``--backend FILE:<path>``. A borg client using a ``rest://`` repository starts this
automatically (over SSH if a host is given).
an ``ssh://`` repository, talking HTTP over stdio. The repository to serve is given via
``--backend FILE:<path>``. A borg client using an ``ssh://`` repository starts this
automatically via SSH.
Please note that, in legacy mode, `borg serve` does not support providing a specific
repository via the `--repo` option or the `BORG_REPO` environment variable - it is the
docs/usage/tag.rst.inc
+38 -7
View File
@@ -19,11 +19,13 @@ borg tag
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--set TAG`` | set tags |
| | ``--set TAG`` | set tags (can be given multiple times) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--add TAG`` | add tags |
| | ``--clear`` | remove all normal tags (keep special tags) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--remove TAG`` | remove tags |
| | ``--add TAG`` | add tag (can be given multiple times) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| | ``--remove TAG`` | remove tag (can be given multiple times) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -63,9 +65,10 @@ borg tag
options
--set TAG set tags
--add TAG add tags
--remove TAG remove tags
--set TAG set tags (can be given multiple times)
--clear remove all normal tags (keep special tags)
--add TAG add tag (can be given multiple times)
--remove TAG remove tag (can be given multiple times)
:ref:`common_options`
@@ -99,4 +102,32 @@ special and users are only allowed to use known special tags:
Pre-existing special tags cannot be removed via ``--set``. You can still use
``--set``, but you must also give pre-existing special tags (so they won't be
removed).
removed). If they are not given, borg emits a warning and does not set the tags
of that archive.
``--clear`` removes all normal tags, but keeps special tags. Combined with
``--add``, it replaces the normal tags.
To change tags, you must select the archives: give an archive NAME or use archive
filter options like ``--match-archives``. To change the tags of all archives, use
``--match-archives 'sh:*'``.
Each of ``--set``, ``--add`` and ``--remove`` takes exactly one tag. To give
multiple tags, use the option multiple times.
Examples::
# add the tags "important" and "keep" to the archive with the given ID
$ borg tag --add important --add keep aid:1ddaae55
# remove the tag "keep" from all archives named "home"
$ borg tag --remove keep --match-archives home
# set the tags of the archive with the given ID to exactly "foo" and "bar"
$ borg tag --set foo --set bar aid:1ddaae55
# remove all normal tags (but not special tags like @PROT) from the archive with the given ID
$ borg tag --clear aid:1ddaae55
# protect the archive with the given ID against deletion and pruning
$ borg tag --add @PROT aid:1ddaae55
docs/usage/transfer.rst.inc
+41 -41
View File
@@ -12,45 +12,45 @@ borg transfer
.. class:: borg-options-table
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository, just check |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | transfer archives from the other repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--from-borg1`` | other repository is borg 1.x |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--upgrader UPGRADER`` | use the upgrader to convert transferred data (default: no conversion) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository, just check |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | transfer archives from the other repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--from-borg1`` | other repository is borg 1.x |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--upgrader UPGRADER`` | use the upgrader to convert transferred data (default: no conversion) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never". |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the repository default (see borg repo-create), else the built-in chunker defaults. default: do not rechunk |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -69,9 +69,9 @@ borg transfer
--other-repo SRC_REPOSITORY transfer archives from the other repository
--from-borg1 other repository is borg 1.x
--upgrader UPGRADER use the upgrader to convert transferred data (default: no conversion)
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. Default: the repository default (see borg repo-create), else lz4.
--recompress MODE recompress data chunks according to `MODE` and ``--compression``. Possible modes are `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never".
--chunker-params PARAMS rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk
--chunker-params PARAMS rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the repository default (see borg repo-create), else the built-in chunker defaults. default: do not rechunk
:ref:`common_options`
docs/usage/version.rst.inc
+2 -2
View File
@@ -50,9 +50,9 @@ Description
This command displays the Borg client and server versions.
For current repositories the client code directly accesses the repository (also for
rest:// repositories), so the client version is shown as the server version, too.
ssh:// repositories), so the client version is shown as the server version, too.
If a legacy (borg 1.x / v1) repository is given via ssh: together with --from-borg1,
If a legacy (borg 1.x / v1) repository is given via ssh:// together with --from-borg1,
the remote Borg is queried, and its version is displayed as the server version.
Examples::
src/borg/archiver/repo_create_cmd.py
+1 -1
View File
@@ -284,7 +284,7 @@ class RepoCreateMixIn:
default=None, # None: not given. Do not default to sha256 here, see key_creator.
action=Highlander,
help="select the id hash function of the encrypted modes: 'sha256' or 'blake3'. "
"The 'authenticated-*' modes name their hash themselves.",
"The 'authenticated-sha256' and 'authenticated-blake3' modes name their hash themselves.",
)
subparser.add_argument(
"--key-location",