mirror of
https://github.com/borgbackup/borg.git
synced 2025-03-09 05:16:35 +00:00
build_man / build_usage
This commit is contained in:
Thomas Waldmann
parent
65a2fe8502
commit
b419b6ad03
45 changed files with 654 additions and 430 deletions
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-BENCHMARK-CRUD" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-BENCHMARK-CRUD" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-BENCHMARK" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-BENCHMARK" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-benchmark \- benchmark command
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-BREAK-LOCK" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-BREAK-LOCK" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-CHECK" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-CHECK" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-check \- Check repository consistency
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -35,94 +35,123 @@ borg-check \- Check repository consistency
|
|||
borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
|
||||
.SH DESCRIPTION
|
||||
.sp
|
||||
The check command verifies the consistency of a repository and the corresponding archives.
|
||||
The check command verifies the consistency of a repository and its archives.
|
||||
It consists of two major steps:
|
||||
.INDENT 0.0
|
||||
.IP 1. 3
|
||||
Checking the consistency of the repository itself. This includes checking
|
||||
the segment magic headers, and both the metadata and data of all objects in
|
||||
the segments. The read data is checked by size and CRC. Bit rot and other
|
||||
types of accidental damage can be detected this way. Running the repository
|
||||
check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
|
||||
When checking a remote repository, please note that the checks run on the
|
||||
server and do not cause significant network traffic.
|
||||
.IP 2. 3
|
||||
Checking consistency and correctness of the archive metadata and optionally
|
||||
archive data (requires \fB\-\-verify\-data\fP). This includes ensuring that the
|
||||
repository manifest exists, the archive metadata chunk is present, and that
|
||||
all chunks referencing files (items) in the archive exist. This requires
|
||||
reading archive and file metadata, but not data. To cryptographically verify
|
||||
the file (content) data integrity pass \fB\-\-verify\-data\fP, but keep in mind
|
||||
that this requires reading all data and is hence very time consuming. When
|
||||
checking archives of a remote repository, archive checks run on the client
|
||||
machine because they require decrypting data and therefore the encryption
|
||||
key.
|
||||
.UNINDENT
|
||||
.sp
|
||||
check \-\-repair is a potentially dangerous function and might lead to data loss
|
||||
(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL!
|
||||
Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run the
|
||||
repository checks only, or pass \fB\-\-archives\-only\fP to run the archive checks
|
||||
only.
|
||||
.sp
|
||||
The \fB\-\-max\-duration\fP option can be used to split a long\-running repository
|
||||
check into multiple partial checks. After the given number of seconds the check
|
||||
is interrupted. The next partial check will continue where the previous one
|
||||
stopped, until the full repository has been checked. Assuming a complete check
|
||||
would take 7 hours, then running a daily check with \fB\-\-max\-duration=3600\fP
|
||||
(1 hour) would result in one full repository check per week. Doing a full
|
||||
repository check aborts any previous partial check; the next partial check will
|
||||
restart from the beginning. With partial repository checks you can run neither
|
||||
archive checks, nor enable repair mode. Consequently, if you want to use
|
||||
\fB\-\-max\-duration\fP you must also pass \fB\-\-repository\-only\fP, and must not pass
|
||||
\fB\-\-archives\-only\fP, nor \fB\-\-repair\fP\&.
|
||||
.sp
|
||||
\fBWarning:\fP Please note that partial repository checks (i.e. running it with
|
||||
\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
|
||||
segment files. A full repository check (i.e. without \fB\-\-max\-duration\fP) can
|
||||
also do a repository index check. Enabling partial repository checks excepts
|
||||
archive checks for the same reason. Therefore partial checks may be useful with
|
||||
very large repositories only where a full check would take too long.
|
||||
.sp
|
||||
The \fB\-\-verify\-data\fP option will perform a full integrity verification (as
|
||||
opposed to checking the CRC32 of the segment) of data, which means reading the
|
||||
data from the repository, decrypting and decompressing it. It is a complete
|
||||
cryptographic verification and hence very time consuming, but will detect any
|
||||
accidental and malicious corruption. Tamper\-resistance is only guaranteed for
|
||||
encrypted repositories against attackers without access to the keys. You can
|
||||
not use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
|
||||
.SS About repair mode
|
||||
.sp
|
||||
The check command is a readonly task by default. If any corruption is found,
|
||||
Borg will report the issue and proceed with checking. To actually repair the
|
||||
issues found, pass \fB\-\-repair\fP\&.
|
||||
.sp
|
||||
\fBNOTE:\fP
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
\fB\-\-repair\fP is a \fBPOTENTIALLY DANGEROUS FEATURE\fP and might lead to data
|
||||
loss! This does not just include data that was previously lost anyway, but
|
||||
might include more data for kinds of corruption it is not capable of
|
||||
dealing with. \fBBE VERY CAREFUL!\fP
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
Pursuant to the previous warning it is also highly recommended to test the
|
||||
reliability of the hardware running this software with stress testing software
|
||||
such as memory testers. Unreliable hardware can also lead to data loss especially
|
||||
when this command is run in repair mode.
|
||||
reliability of the hardware running Borg with stress testing software. This
|
||||
especially includes storage and memory testers. Unreliable hardware might lead
|
||||
to additional data loss.
|
||||
.sp
|
||||
First, the underlying repository data files are checked:
|
||||
It is highly recommended to create a backup of your repository before running
|
||||
in repair mode (i.e. running it with \fB\-\-repair\fP).
|
||||
.sp
|
||||
Repair mode will attempt to fix any corruptions found. Fixing corruptions does
|
||||
not mean recovering lost data: Borg can not magically restore data lost due to
|
||||
e.g. a hardware failure. Repairing a repository means sacrificing some data
|
||||
for the sake of the repository as a whole and the remaining data. Hence it is,
|
||||
by definition, a potentially lossy task.
|
||||
.sp
|
||||
In practice, repair mode hooks into both the repository and archive checks:
|
||||
.INDENT 0.0
|
||||
.IP \(bu 2
|
||||
For all segments, the segment magic header is checked.
|
||||
.IP \(bu 2
|
||||
For all objects stored in the segments, all metadata (e.g. CRC and size) and
|
||||
all data is read. The read data is checked by size and CRC. Bit rot and other
|
||||
types of accidental damage can be detected this way.
|
||||
.IP \(bu 2
|
||||
In repair mode, if an integrity error is detected in a segment, try to recover
|
||||
as many objects from the segment as possible.
|
||||
.IP \(bu 2
|
||||
In repair mode, make sure that the index is consistent with the data stored in
|
||||
the segments.
|
||||
.IP \(bu 2
|
||||
If checking a remote repo via \fBssh:\fP, the repo check is executed on the server
|
||||
without causing significant network traffic.
|
||||
.IP \(bu 2
|
||||
The repository check can be skipped using the \fB\-\-archives\-only\fP option.
|
||||
.IP \(bu 2
|
||||
A repository check can be time consuming. Partial checks are possible with the
|
||||
\fB\-\-max\-duration\fP option.
|
||||
.IP 1. 3
|
||||
When checking the repository\(aqs consistency, repair mode will try to recover
|
||||
as many objects from segments with integrity errors as possible, and ensure
|
||||
that the index is consistent with the data stored in the segments.
|
||||
.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
|
||||
corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
|
||||
will replace corrupt or lost chunks with a same\-size replacement chunk of
|
||||
zeroes. If a previously zeroed chunk reappears, repair mode will restore
|
||||
this lost chunk using the new chunk. Lastly, repair mode will also delete
|
||||
orphaned chunks (e.g. caused by read errors while creating the archive).
|
||||
.UNINDENT
|
||||
.sp
|
||||
Second, the consistency and correctness of the archive metadata is verified:
|
||||
.INDENT 0.0
|
||||
.IP \(bu 2
|
||||
Is the repo manifest present? If not, it is rebuilt from archive metadata
|
||||
chunks (this requires reading and decrypting of all metadata and data).
|
||||
.IP \(bu 2
|
||||
Check if archive metadata chunk is present; if not, remove archive from manifest.
|
||||
.IP \(bu 2
|
||||
For all files (items) in the archive, for all chunks referenced by these
|
||||
files, check if chunk is present. In repair mode, if a chunk is not present,
|
||||
replace it with a same\-size replacement chunk of zeroes. If a previously lost
|
||||
chunk reappears (e.g. via a later backup), in repair mode the all\-zero replacement
|
||||
chunk will be replaced by the correct chunk. This requires reading of archive and
|
||||
file metadata, but not data.
|
||||
.IP \(bu 2
|
||||
In repair mode, when all the archives were checked, orphaned chunks are deleted
|
||||
from the repo. One cause of orphaned chunks are input file related errors (like
|
||||
read errors) in the archive creation process.
|
||||
.IP \(bu 2
|
||||
In verify\-data mode, a complete cryptographic verification of the archive data
|
||||
integrity is performed. This conflicts with \fB\-\-repository\-only\fP as this mode
|
||||
only makes sense if the archive checks are enabled. The full details of this mode
|
||||
are documented below.
|
||||
.IP \(bu 2
|
||||
If checking a remote repo via \fBssh:\fP, the archive check is executed on the
|
||||
client machine because it requires decryption, and this is always done client\-side
|
||||
as key access is needed.
|
||||
.IP \(bu 2
|
||||
The archive checks can be time consuming; they can be skipped using the
|
||||
\fB\-\-repository\-only\fP option.
|
||||
.UNINDENT
|
||||
Most steps taken by repair mode have a one\-time effect on the repository, like
|
||||
removing a lost archive from the repository. However, replacing a corrupt or
|
||||
lost chunk with an all\-zero replacement will have an ongoing effect on the
|
||||
repository: When attempting to extract a file referencing an all\-zero chunk,
|
||||
the \fBextract\fP command will distinctly warn about it. The FUSE filesystem
|
||||
created by the \fBmount\fP command will reject reading such a \(dqzero\-patched\(dq
|
||||
file unless a special mount option is given.
|
||||
.sp
|
||||
The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check
|
||||
into multiple partial checks. After the given number of seconds the check is
|
||||
interrupted. The next partial check will continue where the previous one stopped,
|
||||
until the complete repository has been checked. Example: Assuming a complete check took 7
|
||||
hours, then running a daily check with \-\-max\-duration=3600 (1 hour) resulted in one
|
||||
completed check per week.
|
||||
.sp
|
||||
Attention: A partial \-\-repository\-only check can only do way less checking than a full
|
||||
\-\-repository\-only check: only the non\-cryptographic checksum checks on segment file
|
||||
entries are done, while a full \-\-repository\-only check would also do a repo index check.
|
||||
A partial check cannot be combined with the \fB\-\-repair\fP option. Partial checks
|
||||
may therefore be useful only with very large repositories where a full check would take
|
||||
too long.
|
||||
Doing a full repository check aborts a partial check; the next partial check will restart
|
||||
from the beginning.
|
||||
.sp
|
||||
The \fB\-\-verify\-data\fP option will perform a full integrity verification (as opposed to
|
||||
checking the CRC32 of the segment) of data, which means reading the data from the
|
||||
repository, decrypting and decompressing it. This is a cryptographic verification,
|
||||
which will detect (accidental) corruption. For encrypted repositories it is
|
||||
tamper\-resistant as well, unless the attacker has access to the keys. It is also very
|
||||
slow.
|
||||
As mentioned earlier, Borg might be able to \(dqheal\(dq a \(dqzero\-patched\(dq file in
|
||||
repair mode, if all its previously lost chunks reappear (e.g. via a later
|
||||
backup). This is achieved by Borg not only keeping track of the all\-zero
|
||||
replacement chunks, but also by keeping metadata about the lost chunks. In
|
||||
repair mode Borg will check whether a previously lost chunk reappeared and will
|
||||
replace the all\-zero replacement chunk by the reappeared chunk. If all lost
|
||||
chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file.
|
||||
Consequently, if lost chunks were repaired earlier, it is advised to run
|
||||
\fB\-\-repair\fP a second time after creating some new backups.
|
||||
.SH OPTIONS
|
||||
.sp
|
||||
See \fIborg\-common(1)\fP for common options of Borg commands.
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-COMMON" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-COMMON" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-common \- Common options of Borg commands
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-COMPACT" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-COMPACT" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-compact \- compact segment files in the repository
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-COMPRESSION" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-COMPRESSION" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-compression \- Details regarding compression
|
||||
.SH DESCRIPTION
|
||||
|
|
@ -82,29 +82,70 @@ being any valid compression specifier.
|
|||
.TP
|
||||
.B obfuscate,SPEC,C[,L]
|
||||
Use compressed\-size obfuscation to make fingerprinting attacks based on
|
||||
the observable stored chunk size more difficult.
|
||||
Note:
|
||||
\- you must combine this with encryption or it won\(aqt make any sense.
|
||||
\- your repo size will be bigger, of course.
|
||||
the observable stored chunk size more difficult. Note:
|
||||
.INDENT 7.0
|
||||
.IP \(bu 2
|
||||
You must combine this with encryption, or it won\(aqt make any sense.
|
||||
.IP \(bu 2
|
||||
Your repo size will be bigger, of course.
|
||||
.IP \(bu 2
|
||||
A chunk is limited by the constant \fBMAX_DATA_SIZE\fP (cur. ~20MiB).
|
||||
.UNINDENT
|
||||
.sp
|
||||
The SPEC value will determine how the size obfuscation will work:
|
||||
The SPEC value determines how the size obfuscation works:
|
||||
.sp
|
||||
\fIRelative random reciprocal size variation\fP (multiplicative)
|
||||
.sp
|
||||
Relative random reciprocal size variation:
|
||||
Size will increase by a factor, relative to the compressed data size.
|
||||
Smaller factors are often used, larger factors rarely.
|
||||
1: factor 0.01 .. 100.0
|
||||
2: factor 0.1 .. 1000.0
|
||||
3: factor 1.0 .. 10000.0
|
||||
4: factor 10.0 .. 100000.0
|
||||
5: factor 100.0 .. 1000000.0
|
||||
6: factor 1000.0 .. 10000000.0
|
||||
Smaller factors are used often, larger factors rarely.
|
||||
.sp
|
||||
Add a randomly sized padding up to the given size:
|
||||
110: 1kiB
|
||||
Available factors:
|
||||
.INDENT 7.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
1: 0.01 .. 100
|
||||
2: 0.1 .. 1,000
|
||||
3: 1 .. 10,000
|
||||
4: 10 .. 100,000
|
||||
5: 100 .. 1,000,000
|
||||
6: 1,000 .. 10,000,000
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
Example probabilities for SPEC \fB1\fP:
|
||||
.INDENT 7.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
90 % 0.01 .. 0.1
|
||||
9 % 0.1 .. 1
|
||||
0.9 % 1 .. 10
|
||||
0.09% 10 .. 100
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
\fIRandomly sized padding up to the given size\fP (additive)
|
||||
.INDENT 7.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
110: 1kiB (2 ^ (SPEC \- 100))
|
||||
\&...
|
||||
120: 1MiB
|
||||
\&...
|
||||
123: 8MiB (max.)
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
Examples:
|
||||
|
|
@ -120,7 +161,7 @@ borg create \-\-compression zlib REPO::ARCHIVE data
|
|||
borg create \-\-compression zlib,1 REPO::ARCHIVE data
|
||||
borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data
|
||||
borg create \-\-compression auto,lzma ...
|
||||
borg create \-\-compression obfuscate,3,none ...
|
||||
borg create \-\-compression obfuscate,110,none ...
|
||||
borg create \-\-compression obfuscate,3,auto,zstd,10 ...
|
||||
borg create \-\-compression obfuscate,2,zstd,6 ...
|
||||
.ft P
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-CONFIG" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-CONFIG" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-config \- get, set, and delete values in a repository or cache config file
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-CREATE" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-CREATE" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-create \- Create new archive
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -169,15 +169,15 @@ set mode to M in archive for stdin data (default: 0660)
|
|||
interpret PATH as command and store its stdout. See also section Reading from stdin below.
|
||||
.TP
|
||||
.B \-\-paths\-from\-stdin
|
||||
read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories.
|
||||
read DELIM\-separated list of paths to backup from stdin. All control is external: it will back up all files given \- no more, no less.
|
||||
.TP
|
||||
.B \-\-paths\-from\-command
|
||||
interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
|
||||
.TP
|
||||
.BI \-\-paths\-delimiter \ DELIM
|
||||
set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: n)
|
||||
set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: \fB\en\fP)
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
@ -208,7 +208,7 @@ exclude files flagged NODUMP
|
|||
.INDENT 0.0
|
||||
.TP
|
||||
.B \-x\fP,\fB \-\-one\-file\-system
|
||||
stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs.
|
||||
stay in the same file system and do not store mount points of other file systems \- this might behave different from your expectations, see the description below.
|
||||
.TP
|
||||
.B \-\-numeric\-owner
|
||||
deprecated, use \fB\-\-numeric\-ids\fP instead
|
||||
|
|
@ -376,13 +376,13 @@ through using the \fB\-\-keep\-exclude\-tags\fP option.
|
|||
The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
|
||||
It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
|
||||
parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
|
||||
from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
|
||||
with device number different from their parent, which the kernel does not consider a mountpoint and also the
|
||||
other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
|
||||
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
|
||||
using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using
|
||||
btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
|
||||
installer.
|
||||
from the device number of their parent.
|
||||
In general: be aware that there are directories with device number different from their parent, which the kernel
|
||||
does not consider a mountpoint and also the other way around.
|
||||
Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL
|
||||
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
|
||||
macOS examples are the apfs mounts of a typical macOS installation.
|
||||
Therefore, when using \fB\-\-one\-file\-system\fP, you should double\-check that the backup works as intended.
|
||||
.SS Item flags
|
||||
.sp
|
||||
\fB\-\-list\fP outputs a list of all files, directories and other
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-DELETE" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-DELETE" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-delete \- Delete an existing repository or archives
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-DIFF" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-DIFF" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-diff \- Diff contents of two archives
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -87,7 +87,7 @@ Only compare differences in content (exclude metadata differences)
|
|||
.B \-\-json\-lines
|
||||
Format output as JSON Lines.
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-EXPORT-TAR" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-EXPORT-TAR" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-export-tar \- Export archive contents as a tarball
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -100,7 +100,7 @@ filter program to pipe data through
|
|||
.B \-\-list
|
||||
output verbose list of items (files, dirs, ...)
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-EXTRACT" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-EXTRACT" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-extract \- Extract archive contents
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -105,7 +105,7 @@ write all extracted data to stdout
|
|||
.B \-\-sparse
|
||||
create holes in output sparse file from all\-zero chunks
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-IMPORT-TAR" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-IMPORT-TAR" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-import-tar \- Create a backup archive from a tarball
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-INFO" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-INFO" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-info \- Show archive details such as disk space used
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-INIT" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-INIT" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-init \- Initialize an empty repository
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -124,6 +124,8 @@ The key will be stored in your home directory (in \fB~/.config/borg/keys\fP).
|
|||
.sp
|
||||
If you do \fBnot\fP want to encrypt the contents of your backups, but still
|
||||
want to detect malicious tampering use \fB\-\-encryption authenticated\fP\&.
|
||||
To normally work with \fBauthenticated\fP repos, you will need the passphrase, but
|
||||
there is an emergency workaround, see \fBBORG_WORKAROUNDS=authenticated_no_key\fP docs.
|
||||
.sp
|
||||
If \fBBLAKE2b\fP is faster than \fBSHA\-256\fP on your hardware, use \fB\-\-encryption authenticated\-blake2\fP,
|
||||
\fB\-\-encryption repokey\-blake2\fP or \fB\-\-encryption keyfile\-blake2\fP\&. Note: for remote backups
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-key-change-passphrase \- Change repository key file passphrase
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-KEY-EXPORT" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-KEY-EXPORT" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-key-export \- Export the repository key for backup
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-KEY-IMPORT" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-KEY-IMPORT" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-key-import \- Import the repository key from backup
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-KEY" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-KEY" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-key \- Manage a keyfile or repokey of a repository
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-LIST" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-LIST" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-list \- List archive or repository contents
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -86,7 +86,7 @@ consider first N archives after other filters were applied
|
|||
.BI \-\-last \ N
|
||||
consider last N archives after other filters were applied
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
@ -137,11 +137,11 @@ drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject
|
|||
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
|
||||
\&...
|
||||
|
||||
$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:\e.ext$\(aq
|
||||
$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:\e.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
|
||||
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
|
||||
\&...
|
||||
|
||||
$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:.ext$\(aq
|
||||
$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
|
||||
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
|
||||
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
|
||||
\&...
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-MOUNT" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-MOUNT" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -143,7 +143,7 @@ consider first N archives after other filters were applied
|
|||
.BI \-\-last \ N
|
||||
consider last N archives after other filters were applied
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-PATTERNS" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-PATTERNS" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-patterns \- Details regarding patterns
|
||||
.SH DESCRIPTION
|
||||
|
|
@ -36,34 +36,20 @@ The path/filenames used as input for the pattern matching start from the
|
|||
currently active recursion root. You usually give the recursion root(s)
|
||||
when invoking borg and these can be either relative or absolute paths.
|
||||
.sp
|
||||
If you give \fI/absolute/\fP as root, the paths going into the matcher will
|
||||
look relative like \fIabsolute/.../file.ext\fP, because file paths in Borg
|
||||
archives are always stored normalized and relative. This means that e.g.
|
||||
\fBborg create /path/to/repo ../some/path\fP will store all files as
|
||||
\fIsome/path/.../file.ext\fP and \fBborg create /path/to/repo /home/user\fP
|
||||
will store all files as \fIhome/user/.../file.ext\fP\&.
|
||||
Starting with Borg 1.2, paths that are matched against patterns always
|
||||
appear relative. If you give \fB/absolute/\fP as root, the paths going
|
||||
into the matcher will start with \fBabsolute/\fP\&.
|
||||
If you give \fB\&../../relative\fP as root, the paths will be normalized
|
||||
as \fBrelative/\fP\&.
|
||||
.sp
|
||||
A directory exclusion pattern can end either with or without a slash (\(aq/\(aq).
|
||||
If it ends with a slash, such as \fIsome/path/\fP, the directory will be
|
||||
included but not its content. If it does not end with a slash, such as
|
||||
\fIsome/path\fP, both the directory and content will be excluded.
|
||||
.sp
|
||||
File patterns support these styles: fnmatch, shell, regular expressions,
|
||||
path prefixes and path full\-matches. By default, fnmatch is used for
|
||||
\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP
|
||||
option. For commands that support patterns in their \fBPATH\fP argument
|
||||
like (\fBborg list\fP), the default pattern is path prefix.
|
||||
.sp
|
||||
Starting with Borg 1.2, discovered fs paths are normalised, have leading
|
||||
slashes removed and then are matched against your patterns.
|
||||
Note: You need to review your include / exclude patterns and make
|
||||
sure they do not expect leading slashes. Borg can only deal with this
|
||||
for some very simple patterns by removing leading slashes there also.
|
||||
.sp
|
||||
If followed by a colon (\(aq:\(aq) the first two characters of a pattern are
|
||||
used as a style selector. Explicit style selection is necessary when a
|
||||
non\-default style is desired or when the desired pattern starts with
|
||||
two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
|
||||
Borg supports different pattern styles. To define a non\-default
|
||||
style for a specific pattern, prefix it with two characters followed
|
||||
by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP).
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B \fI\%Fnmatch\fP, selector \fIfm:\fP
|
||||
|
|
@ -186,12 +172,37 @@ $ borg create \-\-exclude\-from exclude.txt backup /
|
|||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
A more general and easier to use way to define filename matching patterns exists
|
||||
with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you may
|
||||
specify the backup roots (starting points) and patterns for inclusion/exclusion.
|
||||
A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a
|
||||
file pattern). An include rule starts with the prefix +, an exclude rule starts
|
||||
with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern.
|
||||
A more general and easier to use way to define filename matching patterns
|
||||
exists with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using
|
||||
these, you may specify the backup roots, default pattern styles and
|
||||
patterns for inclusion and exclusion.
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.B Root path prefix \fBR\fP
|
||||
A recursion root path starts with the prefix \fBR\fP, followed by a path
|
||||
(a plain path, not a file pattern). Use this prefix to have the root
|
||||
paths in the patterns file rather than as command line arguments.
|
||||
.TP
|
||||
.B Pattern style prefix \fBP\fP
|
||||
To change the default pattern style, use the \fBP\fP prefix, followed by
|
||||
the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
|
||||
All patterns following this line will use this style until another style
|
||||
is specified.
|
||||
.TP
|
||||
.B Exclude pattern prefix \fB\-\fP
|
||||
Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.
|
||||
This has the same effect as the \fB\-\-exclude\fP option.
|
||||
.TP
|
||||
.B Exclude no\-recurse pattern prefix \fB!\fP
|
||||
Use the prefix \fB!\fP, followed by a pattern, to define an exclusion
|
||||
that does not recurse into subdirectories. This saves time, but
|
||||
prevents include patterns to match any files in subdirectories.
|
||||
.TP
|
||||
.B Include pattern prefix \fB+\fP
|
||||
Use the prefix \fB+\fP, followed by a pattern, to define inclusions.
|
||||
This is useful to include paths that are covered in an exclude
|
||||
pattern and would otherwise not be backed up.
|
||||
.UNINDENT
|
||||
.sp
|
||||
\fBNOTE:\fP
|
||||
.INDENT 0.0
|
||||
|
|
@ -202,11 +213,37 @@ of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP a
|
|||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
Inclusion patterns are useful to include paths that are contained in an excluded
|
||||
path. The first matching pattern is used so if an include pattern matches before
|
||||
an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matches
|
||||
a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for
|
||||
include rules below that directory.
|
||||
The first matching pattern is used, so if an include pattern matches
|
||||
before an exclude pattern, the file is backed up. Note that a no\-recurse
|
||||
exclude stops examination of subdirectories so that potential includes
|
||||
will not match \- use normal excludes for such use cases.
|
||||
.sp
|
||||
Example:
|
||||
.INDENT 0.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
# Define the recursion root
|
||||
R /
|
||||
# Exclude all iso files in any directory
|
||||
\- **/*.iso
|
||||
# Explicitly include all inside etc and root
|
||||
+ etc/**
|
||||
+ root/**
|
||||
# Exclude a specific directory under each user\(aqs home directories
|
||||
\- home/*/.cache
|
||||
# Explicitly include everything in /home
|
||||
+ home/**
|
||||
# Explicitly exclude some directories without recursing into them
|
||||
! re:^(dev|proc|run|sys|tmp)
|
||||
# Exclude all other files and directories
|
||||
# that are not specifically included earlier.
|
||||
\- **
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
\fBNOTE:\fP
|
||||
.INDENT 0.0
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-PLACEHOLDERS" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-PLACEHOLDERS" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-placeholders \- Details regarding placeholders
|
||||
.SH DESCRIPTION
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-PRUNE" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-PRUNE" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-prune \- Prune repository archives according to specified rules
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-RECREATE" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-RECREATE" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-recreate \- Re-create archives
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -112,7 +112,7 @@ do not change anything
|
|||
.B \-s\fP,\fB \-\-stats
|
||||
print statistics at end
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-RENAME" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-RENAME" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-rename \- Rename an existing archive
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-SERVE" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-SERVE" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-serve \- Start in server mode. This command is usually not used manually.
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-UMOUNT" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-UMOUNT" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-umount \- un-mount the FUSE filesystem
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-UPGRADE" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-UPGRADE" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-upgrade \- upgrade a repository from a previous version
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG-WITH-LOCK" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG-WITH-LOCK" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg-with-lock \- run a user specified command with the repository lock held
|
||||
.SH SYNOPSIS
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORG" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORG" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borg \- deduplicating and encrypting backup tool
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -507,6 +507,38 @@ write to disk behaviour (not continuously streaming to disk).
|
|||
Retry opening a file without O_NOATIME if opening a file with O_NOATIME
|
||||
caused EROFS. You will need this to make archives from volume shadow copies
|
||||
in WSL1 (Windows Subsystem for Linux 1).
|
||||
.TP
|
||||
.B authenticated_no_key
|
||||
Work around a lost passphrase or key for an \fBauthenticated\fP mode repository
|
||||
(these are only authenticated, but not encrypted).
|
||||
If the key is missing in the repository config, add \fBkey = anything\fP there.
|
||||
.sp
|
||||
This workaround is \fBonly\fP for emergencies and \fBonly\fP to extract data
|
||||
from an affected repository (read\-only access):
|
||||
.INDENT 7.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
After you have extracted all data you need, you MUST delete the repository:
|
||||
.INDENT 7.0
|
||||
.INDENT 3.5
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
BORG_WORKAROUNDS=authenticated_no_key borg delete repo
|
||||
.ft P
|
||||
.fi
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.sp
|
||||
Now you can init a fresh repo. Make sure you do not use the workaround any more.
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
.TP
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||||
..
|
||||
.TH "BORGFS" 1 "2023-03-22" "" "borg backup tool"
|
||||
.TH "BORGFS" 1 "2023-07-20" "" "borg backup tool"
|
||||
.SH NAME
|
||||
borgfs \- Mount archive or an entire repository as a FUSE filesystem
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -146,7 +146,7 @@ consider first N archives after other filters were applied
|
|||
.BI \-\-last \ N
|
||||
consider last N archives after other filters were applied
|
||||
.UNINDENT
|
||||
.SS Exclusion options
|
||||
.SS Include/Exclude options
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
|
||||
|
|
|
|||
|
|
@ -85,75 +85,115 @@ borg check
|
|||
Description
|
||||
~~~~~~~~~~~
|
||||
|
||||
The check command verifies the consistency of a repository and the corresponding archives.
|
||||
The check command verifies the consistency of a repository and its archives.
|
||||
It consists of two major steps:
|
||||
|
||||
check --repair is a potentially dangerous function and might lead to data loss
|
||||
(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL!
|
||||
1. Checking the consistency of the repository itself. This includes checking
|
||||
the segment magic headers, and both the metadata and data of all objects in
|
||||
the segments. The read data is checked by size and CRC. Bit rot and other
|
||||
types of accidental damage can be detected this way. Running the repository
|
||||
check can be split into multiple partial checks using ``--max-duration``.
|
||||
When checking a remote repository, please note that the checks run on the
|
||||
server and do not cause significant network traffic.
|
||||
|
||||
2. Checking consistency and correctness of the archive metadata and optionally
|
||||
archive data (requires ``--verify-data``). This includes ensuring that the
|
||||
repository manifest exists, the archive metadata chunk is present, and that
|
||||
all chunks referencing files (items) in the archive exist. This requires
|
||||
reading archive and file metadata, but not data. To cryptographically verify
|
||||
the file (content) data integrity pass ``--verify-data``, but keep in mind
|
||||
that this requires reading all data and is hence very time consuming. When
|
||||
checking archives of a remote repository, archive checks run on the client
|
||||
machine because they require decrypting data and therefore the encryption
|
||||
key.
|
||||
|
||||
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.
|
||||
|
||||
The ``--max-duration`` option can be used to split a long-running repository
|
||||
check into multiple partial checks. After the given number of seconds the check
|
||||
is interrupted. The next partial check will continue where the previous one
|
||||
stopped, until the full repository has been checked. Assuming a complete check
|
||||
would take 7 hours, then running a daily check with ``--max-duration=3600``
|
||||
(1 hour) would result in one full repository check per week. Doing a full
|
||||
repository check aborts any previous partial check; the next partial check will
|
||||
restart from the beginning. With partial repository checks you can run neither
|
||||
archive checks, nor enable repair mode. Consequently, if you want to use
|
||||
``--max-duration`` you must also pass ``--repository-only``, and must not pass
|
||||
``--archives-only``, nor ``--repair``.
|
||||
|
||||
**Warning:** Please note that partial repository checks (i.e. running it with
|
||||
``--max-duration``) can only perform non-cryptographic checksum checks on the
|
||||
segment files. A full repository check (i.e. without ``--max-duration``) can
|
||||
also do a repository index check. Enabling partial repository checks excepts
|
||||
archive checks for the same reason. Therefore partial checks may be useful with
|
||||
very large repositories only where a full check would take too long.
|
||||
|
||||
The ``--verify-data`` option will perform a full integrity verification (as
|
||||
opposed to checking the CRC32 of the segment) of data, which means reading the
|
||||
data from the repository, decrypting and decompressing it. It is a complete
|
||||
cryptographic verification and hence very time consuming, but will detect any
|
||||
accidental and malicious corruption. Tamper-resistance is only guaranteed for
|
||||
encrypted repositories against attackers without access to the keys. You can
|
||||
not use ``--verify-data`` with ``--repository-only``.
|
||||
|
||||
About repair mode
|
||||
+++++++++++++++++
|
||||
|
||||
The check command is a readonly task by default. If any corruption is found,
|
||||
Borg will report the issue and proceed with checking. To actually repair the
|
||||
issues found, pass ``--repair``.
|
||||
|
||||
.. note::
|
||||
|
||||
``--repair`` is a **POTENTIALLY DANGEROUS FEATURE** and might lead to data
|
||||
loss! This does not just include data that was previously lost anyway, but
|
||||
might include more data for kinds of corruption it is not capable of
|
||||
dealing with. **BE VERY CAREFUL!**
|
||||
|
||||
Pursuant to the previous warning it is also highly recommended to test the
|
||||
reliability of the hardware running this software with stress testing software
|
||||
such as memory testers. Unreliable hardware can also lead to data loss especially
|
||||
when this command is run in repair mode.
|
||||
reliability of the hardware running Borg with stress testing software. This
|
||||
especially includes storage and memory testers. Unreliable hardware might lead
|
||||
to additional data loss.
|
||||
|
||||
First, the underlying repository data files are checked:
|
||||
It is highly recommended to create a backup of your repository before running
|
||||
in repair mode (i.e. running it with ``--repair``).
|
||||
|
||||
- For all segments, the segment magic header is checked.
|
||||
- For all objects stored in the segments, all metadata (e.g. CRC and size) and
|
||||
all data is read. The read data is checked by size and CRC. Bit rot and other
|
||||
types of accidental damage can be detected this way.
|
||||
- In repair mode, if an integrity error is detected in a segment, try to recover
|
||||
as many objects from the segment as possible.
|
||||
- In repair mode, make sure that the index is consistent with the data stored in
|
||||
the segments.
|
||||
- If checking a remote repo via ``ssh:``, the repo check is executed on the server
|
||||
without causing significant network traffic.
|
||||
- The repository check can be skipped using the ``--archives-only`` option.
|
||||
- A repository check can be time consuming. Partial checks are possible with the
|
||||
``--max-duration`` option.
|
||||
Repair mode will attempt to fix any corruptions found. Fixing corruptions does
|
||||
not mean recovering lost data: Borg can not magically restore data lost due to
|
||||
e.g. a hardware failure. Repairing a repository means sacrificing some data
|
||||
for the sake of the repository as a whole and the remaining data. Hence it is,
|
||||
by definition, a potentially lossy task.
|
||||
|
||||
Second, the consistency and correctness of the archive metadata is verified:
|
||||
In practice, repair mode hooks into both the repository and archive checks:
|
||||
|
||||
- Is the repo manifest present? If not, it is rebuilt from archive metadata
|
||||
chunks (this requires reading and decrypting of all metadata and data).
|
||||
- Check if archive metadata chunk is present; if not, remove archive from manifest.
|
||||
- For all files (items) in the archive, for all chunks referenced by these
|
||||
files, check if chunk is present. In repair mode, if a chunk is not present,
|
||||
replace it with a same-size replacement chunk of zeroes. If a previously lost
|
||||
chunk reappears (e.g. via a later backup), in repair mode the all-zero replacement
|
||||
chunk will be replaced by the correct chunk. This requires reading of archive and
|
||||
file metadata, but not data.
|
||||
- In repair mode, when all the archives were checked, orphaned chunks are deleted
|
||||
from the repo. One cause of orphaned chunks are input file related errors (like
|
||||
read errors) in the archive creation process.
|
||||
- In verify-data mode, a complete cryptographic verification of the archive data
|
||||
integrity is performed. This conflicts with ``--repository-only`` as this mode
|
||||
only makes sense if the archive checks are enabled. The full details of this mode
|
||||
are documented below.
|
||||
- If checking a remote repo via ``ssh:``, the archive check is executed on the
|
||||
client machine because it requires decryption, and this is always done client-side
|
||||
as key access is needed.
|
||||
- The archive checks can be time consuming; they can be skipped using the
|
||||
``--repository-only`` option.
|
||||
1. When checking the repository's consistency, repair mode will try to recover
|
||||
as many objects from segments with integrity errors as possible, and ensure
|
||||
that the index is consistent with the data stored in the segments.
|
||||
|
||||
The ``--max-duration`` option can be used to split a long-running repository check
|
||||
into multiple partial checks. After the given number of seconds the check is
|
||||
interrupted. The next partial check will continue where the previous one stopped,
|
||||
until the complete repository has been checked. Example: Assuming a complete check took 7
|
||||
hours, then running a daily check with --max-duration=3600 (1 hour) resulted in one
|
||||
completed check per week.
|
||||
2. When checking the consistency and correctness of archives, repair mode might
|
||||
remove whole archives from the manifest if their archive metadata chunk is
|
||||
corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
|
||||
will replace corrupt or lost chunks with a same-size replacement chunk of
|
||||
zeroes. If a previously zeroed chunk reappears, repair mode will restore
|
||||
this lost chunk using the new chunk. Lastly, repair mode will also delete
|
||||
orphaned chunks (e.g. caused by read errors while creating the archive).
|
||||
|
||||
Attention: A partial --repository-only check can only do way less checking than a full
|
||||
--repository-only check: only the non-cryptographic checksum checks on segment file
|
||||
entries are done, while a full --repository-only check would also do a repo index check.
|
||||
A partial check cannot be combined with the ``--repair`` option. Partial checks
|
||||
may therefore be useful only with very large repositories where a full check would take
|
||||
too long.
|
||||
Doing a full repository check aborts a partial check; the next partial check will restart
|
||||
from the beginning.
|
||||
Most steps taken by repair mode have a one-time effect on the repository, like
|
||||
removing a lost archive from the repository. However, replacing a corrupt or
|
||||
lost chunk with an all-zero replacement will have an ongoing effect on the
|
||||
repository: When attempting to extract a file referencing an all-zero chunk,
|
||||
the ``extract`` command will distinctly warn about it. The FUSE filesystem
|
||||
created by the ``mount`` command will reject reading such a "zero-patched"
|
||||
file unless a special mount option is given.
|
||||
|
||||
The ``--verify-data`` option will perform a full integrity verification (as opposed to
|
||||
checking the CRC32 of the segment) of data, which means reading the data from the
|
||||
repository, decrypting and decompressing it. This is a cryptographic verification,
|
||||
which will detect (accidental) corruption. For encrypted repositories it is
|
||||
tamper-resistant as well, unless the attacker has access to the keys. It is also very
|
||||
slow.
|
||||
As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in
|
||||
repair mode, if all its previously lost chunks reappear (e.g. via a later
|
||||
backup). This is achieved by Borg not only keeping track of the all-zero
|
||||
replacement chunks, but also by keeping metadata about the lost chunks. In
|
||||
repair mode Borg will check whether a previously lost chunk reappeared and will
|
||||
replace the all-zero replacement chunk by the reappeared chunk. If all lost
|
||||
chunks of a "zero-patched" file reappear, this effectively "heals" the file.
|
||||
Consequently, if lost chunks were repaired earlier, it is advised to run
|
||||
``--repair`` a second time after creating some new backups.
|
||||
|
|
@ -12,107 +12,107 @@ borg create
|
|||
|
||||
.. class:: borg-options-table
|
||||
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **positional arguments** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``PATH`` | paths to archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **options** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-n``, ``--dry-run`` | do not create a backup archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-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 (see description) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--json`` | output stats as JSON. Implies ``--stats``. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies not using the files cache. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'wheel') |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--paths-from-stdin`` | read DELIM-separated list of paths to backup from stdin. Will not recurse into directories. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| .. class:: borg-common-opt-ref |
|
||||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Exclusion 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 (http://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``, don't omit the tag objects themselves from the backup archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--exclude-nodump`` | exclude files flagged NODUMP |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Filesystem options** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--numeric-ids`` | only store numeric user and group identifiers |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noatime`` | do not store atime into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--atime`` | do store atime into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noctime`` | do not store ctime into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--nobirthtime`` | do not store birthtime (creation date) into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--nobsdflags`` | deprecated, use ``--noflags`` instead |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noacls`` | do not read and store ACLs into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noxattrs`` | do not read and store xattrs into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--sparse`` | detect sparse holes in input (supported only by fixed chunker) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--read-special`` | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Archive options** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--comment COMMENT`` | add a comment text to the archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **positional arguments** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``PATH`` | paths to archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **options** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-n``, ``--dry-run`` | do not create a backup archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-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 (see description) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--json`` | output stats as JSON. Implies ``--stats``. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies not using the files cache. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'wheel') |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--paths-from-stdin`` | read DELIM-separated list of paths to backup from stdin. All control is external: it will back up all files given - no more, no less. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| .. 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 (http://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``, don't omit the tag objects themselves from the backup archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--exclude-nodump`` | exclude files flagged NODUMP |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Filesystem options** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--numeric-ids`` | only store numeric user and group identifiers |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noatime`` | do not store atime into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--atime`` | do store atime into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noctime`` | do not store ctime into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--nobirthtime`` | do not store birthtime (creation date) into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--nobsdflags`` | deprecated, use ``--noflags`` instead |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noacls`` | do not read and store ACLs into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--noxattrs`` | do not read and store xattrs into archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--sparse`` | detect sparse holes in input (supported only by fixed chunker) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--read-special`` | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Archive options** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--comment COMMENT`` | add a comment text to the archive |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
|
@ -142,15 +142,15 @@ borg create
|
|||
--stdin-group GROUP set group GROUP in archive for stdin data (default: 'wheel')
|
||||
--stdin-mode M set mode to M in archive for stdin data (default: 0660)
|
||||
--content-from-command interpret PATH as command and store its stdout. See also section Reading from stdin below.
|
||||
--paths-from-stdin read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.
|
||||
--paths-from-stdin read DELIM-separated list of paths to backup from stdin. All control is external: it will back up all files given - no more, no less.
|
||||
--paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin``
|
||||
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n)
|
||||
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)
|
||||
|
||||
|
||||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Exclusion 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
|
||||
|
|
@ -162,7 +162,7 @@ borg create
|
|||
|
||||
|
||||
Filesystem options
|
||||
-x, --one-file-system stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs.
|
||||
-x, --one-file-system stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below.
|
||||
--numeric-owner deprecated, use ``--numeric-ids`` instead
|
||||
--numeric-ids only store numeric user and group identifiers
|
||||
--noatime do not store atime into archive
|
||||
|
|
@ -282,13 +282,13 @@ through using the ``--keep-exclude-tags`` option.
|
|||
The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them).
|
||||
It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its
|
||||
parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different
|
||||
from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
|
||||
with device number different from their parent, which the kernel does not consider a mountpoint and also the
|
||||
other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
|
||||
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
|
||||
using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using
|
||||
btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
|
||||
installer.
|
||||
from the device number of their parent.
|
||||
In general: be aware that there are directories with device number different from their parent, which the kernel
|
||||
does not consider a mountpoint and also the other way around.
|
||||
Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL
|
||||
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint).
|
||||
macOS examples are the apfs mounts of a typical macOS installation.
|
||||
Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended.
|
||||
|
||||
|
||||
.. _list_item_flags:
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ borg diff
|
|||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
|
||||
| **Exclusion options** |
|
||||
| **Include/Exclude options** |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
|
||||
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
|
||||
|
|
@ -80,7 +80,7 @@ borg diff
|
|||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Exclusion 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
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ borg export-tar
|
|||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
| **Exclusion options** |
|
||||
| **Include/Exclude options** |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
|
|
@ -70,7 +70,7 @@ borg export-tar
|
|||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Exclusion 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
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ borg extract
|
|||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
| **Exclusion options** |
|
||||
| **Include/Exclude options** |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
|
||||
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
|
|
@ -90,7 +90,7 @@ borg extract
|
|||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Exclusion 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
|
||||
|
|
|
|||
|
|
@ -10,34 +10,20 @@ The path/filenames used as input for the pattern matching start from the
|
|||
currently active recursion root. You usually give the recursion root(s)
|
||||
when invoking borg and these can be either relative or absolute paths.
|
||||
|
||||
If you give `/absolute/` as root, the paths going into the matcher will
|
||||
look relative like `absolute/.../file.ext`, because file paths in Borg
|
||||
archives are always stored normalized and relative. This means that e.g.
|
||||
``borg create /path/to/repo ../some/path`` will store all files as
|
||||
`some/path/.../file.ext` and ``borg create /path/to/repo /home/user``
|
||||
will store all files as `home/user/.../file.ext`.
|
||||
Starting with Borg 1.2, paths that are matched against patterns always
|
||||
appear relative. If you give ``/absolute/`` as root, the paths going
|
||||
into the matcher will start with ``absolute/``.
|
||||
If you give ``../../relative`` as root, the paths will be normalized
|
||||
as ``relative/``.
|
||||
|
||||
A directory exclusion pattern can end either with or without a slash ('/').
|
||||
If it ends with a slash, such as `some/path/`, the directory will be
|
||||
included but not its content. If it does not end with a slash, such as
|
||||
`some/path`, both the directory and content will be excluded.
|
||||
|
||||
File patterns support these styles: fnmatch, shell, regular expressions,
|
||||
path prefixes and path full-matches. By default, fnmatch is used for
|
||||
``--exclude`` patterns and shell-style is used for the ``--pattern``
|
||||
option. For commands that support patterns in their ``PATH`` argument
|
||||
like (``borg list``), the default pattern is path prefix.
|
||||
|
||||
Starting with Borg 1.2, discovered fs paths are normalised, have leading
|
||||
slashes removed and then are matched against your patterns.
|
||||
Note: You need to review your include / exclude patterns and make
|
||||
sure they do not expect leading slashes. Borg can only deal with this
|
||||
for some very simple patterns by removing leading slashes there also.
|
||||
|
||||
If followed by a colon (':') the first two characters of a pattern are
|
||||
used as a style selector. Explicit style selection is necessary when a
|
||||
non-default style is desired or when the desired pattern starts with
|
||||
two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
|
||||
Borg supports different pattern styles. To define a non-default
|
||||
style for a specific pattern, prefix it with two characters followed
|
||||
by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``).
|
||||
|
||||
`Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
|
||||
This is the default style for ``--exclude`` and ``--exclude-from``.
|
||||
|
|
@ -147,12 +133,35 @@ Examples::
|
|||
EOF
|
||||
$ borg create --exclude-from exclude.txt backup /
|
||||
|
||||
A more general and easier to use way to define filename matching patterns exists
|
||||
with the ``--pattern`` and ``--patterns-from`` options. Using these, you may
|
||||
specify the backup roots (starting points) and patterns for inclusion/exclusion.
|
||||
A root path starts with the prefix `R`, followed by a path (a plain path, not a
|
||||
file pattern). An include rule starts with the prefix +, an exclude rule starts
|
||||
with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
|
||||
A more general and easier to use way to define filename matching patterns
|
||||
exists with the ``--pattern`` and ``--patterns-from`` options. Using
|
||||
these, you may specify the backup roots, default pattern styles and
|
||||
patterns for inclusion and exclusion.
|
||||
|
||||
Root path prefix ``R``
|
||||
A recursion root path starts with the prefix ``R``, followed by a path
|
||||
(a plain path, not a file pattern). Use this prefix to have the root
|
||||
paths in the patterns file rather than as command line arguments.
|
||||
|
||||
Pattern style prefix ``P``
|
||||
To change the default pattern style, use the ``P`` prefix, followed by
|
||||
the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``).
|
||||
All patterns following this line will use this style until another style
|
||||
is specified.
|
||||
|
||||
Exclude pattern prefix ``-``
|
||||
Use the prefix ``-``, followed by a pattern, to define an exclusion.
|
||||
This has the same effect as the ``--exclude`` option.
|
||||
|
||||
Exclude no-recurse pattern prefix ``!``
|
||||
Use the prefix ``!``, followed by a pattern, to define an exclusion
|
||||
that does not recurse into subdirectories. This saves time, but
|
||||
prevents include patterns to match any files in subdirectories.
|
||||
|
||||
Include pattern prefix ``+``
|
||||
Use the prefix ``+``, followed by a pattern, to define inclusions.
|
||||
This is useful to include paths that are covered in an exclude
|
||||
pattern and would otherwise not be backed up.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -160,11 +169,29 @@ with the prefix -, an exclude-norecurse rule starts with !, all followed by a pa
|
|||
of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
|
||||
``--exclude-from`` ONLY excludes are defined.
|
||||
|
||||
Inclusion patterns are useful to include paths that are contained in an excluded
|
||||
path. The first matching pattern is used so if an include pattern matches before
|
||||
an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
|
||||
a directory, it won't recurse into it and won't discover any potential matches for
|
||||
include rules below that directory.
|
||||
The first matching pattern is used, so if an include pattern matches
|
||||
before an exclude pattern, the file is backed up. Note that a no-recurse
|
||||
exclude stops examination of subdirectories so that potential includes
|
||||
will not match - use normal excludes for such use cases.
|
||||
|
||||
Example::
|
||||
|
||||
# Define the recursion root
|
||||
R /
|
||||
# Exclude all iso files in any directory
|
||||
- **/*.iso
|
||||
# Explicitly include all inside etc and root
|
||||
+ etc/**
|
||||
+ root/**
|
||||
# Exclude a specific directory under each user's home directories
|
||||
- home/*/.cache
|
||||
# Explicitly include everything in /home
|
||||
+ home/**
|
||||
# Explicitly exclude some directories without recursing into them
|
||||
! re:^(dev|proc|run|sys|tmp)
|
||||
# Exclude all other files and directories
|
||||
# that are not specifically included earlier.
|
||||
- **
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -346,29 +373,44 @@ auto,C[,L]
|
|||
|
||||
obfuscate,SPEC,C[,L]
|
||||
Use compressed-size obfuscation to make fingerprinting attacks based on
|
||||
the observable stored chunk size more difficult.
|
||||
Note:
|
||||
- you must combine this with encryption or it won't make any sense.
|
||||
- your repo size will be bigger, of course.
|
||||
the observable stored chunk size more difficult. Note:
|
||||
|
||||
The SPEC value will determine how the size obfuscation will work:
|
||||
- You must combine this with encryption, or it won't make any sense.
|
||||
- Your repo size will be bigger, of course.
|
||||
- A chunk is limited by the constant ``MAX_DATA_SIZE`` (cur. ~20MiB).
|
||||
|
||||
The SPEC value determines how the size obfuscation works:
|
||||
|
||||
*Relative random reciprocal size variation* (multiplicative)
|
||||
|
||||
Relative random reciprocal size variation:
|
||||
Size will increase by a factor, relative to the compressed data size.
|
||||
Smaller factors are often used, larger factors rarely.
|
||||
1: factor 0.01 .. 100.0
|
||||
2: factor 0.1 .. 1000.0
|
||||
3: factor 1.0 .. 10000.0
|
||||
4: factor 10.0 .. 100000.0
|
||||
5: factor 100.0 .. 1000000.0
|
||||
6: factor 1000.0 .. 10000000.0
|
||||
Smaller factors are used often, larger factors rarely.
|
||||
|
||||
Add a randomly sized padding up to the given size:
|
||||
110: 1kiB
|
||||
...
|
||||
120: 1MiB
|
||||
...
|
||||
123: 8MiB (max.)
|
||||
Available factors::
|
||||
|
||||
1: 0.01 .. 100
|
||||
2: 0.1 .. 1,000
|
||||
3: 1 .. 10,000
|
||||
4: 10 .. 100,000
|
||||
5: 100 .. 1,000,000
|
||||
6: 1,000 .. 10,000,000
|
||||
|
||||
Example probabilities for SPEC ``1``::
|
||||
|
||||
90 % 0.01 .. 0.1
|
||||
9 % 0.1 .. 1
|
||||
0.9 % 1 .. 10
|
||||
0.09% 10 .. 100
|
||||
|
||||
*Randomly sized padding up to the given size* (additive)
|
||||
|
||||
::
|
||||
|
||||
110: 1kiB (2 ^ (SPEC - 100))
|
||||
...
|
||||
120: 1MiB
|
||||
...
|
||||
123: 8MiB (max.)
|
||||
|
||||
Examples::
|
||||
|
||||
|
|
@ -379,7 +421,7 @@ Examples::
|
|||
borg create --compression zlib,1 REPO::ARCHIVE data
|
||||
borg create --compression auto,lzma,6 REPO::ARCHIVE data
|
||||
borg create --compression auto,lzma ...
|
||||
borg create --compression obfuscate,3,none ...
|
||||
borg create --compression obfuscate,110,none ...
|
||||
borg create --compression obfuscate,3,auto,zstd,10 ...
|
||||
borg create --compression obfuscate,2,zstd,6 ...
|
||||
|
||||
|
|
|
|||
|
|
@ -128,6 +128,8 @@ The key will be stored in your home directory (in ``~/.config/borg/keys``).
|
|||
|
||||
If you do **not** want to encrypt the contents of your backups, but still
|
||||
want to detect malicious tampering use ``--encryption authenticated``.
|
||||
To normally work with ``authenticated`` repos, you will need the passphrase, but
|
||||
there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs.
|
||||
|
||||
If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``,
|
||||
``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ borg list
|
|||
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--last N`` | consider last N archives after other filters were applied |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Exclusion options** |
|
||||
| **Include/Exclude options** |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
|
@ -93,7 +93,7 @@ borg list
|
|||
--last N consider last N archives after other filters were applied
|
||||
|
||||
|
||||
Exclusion 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
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ borg mount
|
|||
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
| | ``--last N`` | consider last N archives after other filters were applied |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
| **Exclusion options** |
|
||||
| **Include/Exclude options** |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
|
||||
|
|
@ -99,7 +99,7 @@ borg mount
|
|||
--last N consider last N archives after other filters were applied
|
||||
|
||||
|
||||
Exclusion 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
|
||||
|
|
|
|||
|
|
@ -126,6 +126,12 @@ If you have multiple sequences of archives with different data sets (e.g.
|
|||
from different machines) in one shared repository, use one prune call per
|
||||
data set that matches only the respective archives using the -P option.
|
||||
|
||||
The ``--keep-within`` option takes an argument of the form "<int><char>",
|
||||
where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means
|
||||
to keep all archives that were created within the past 48 hours.
|
||||
"1m" is taken to mean "31d". The archives kept with this option do not
|
||||
count towards the totals specified by any other options.
|
||||
|
||||
A good procedure is to thin out more and more the older your backups get.
|
||||
As an example, ``--keep-daily 7`` means to keep the latest backup on each day,
|
||||
up to 7 most recent days with backups (days without backups do not count).
|
||||
|
|
@ -139,13 +145,6 @@ hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet
|
|||
its retention target. This enables the first chronological archive to continue
|
||||
aging until it is replaced by a newer archive that meets the retention criteria.
|
||||
|
||||
The ``--keep-within`` option takes an argument of the form "<int><char>",
|
||||
where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means
|
||||
to keep all archives that were created within the past 48 hours.
|
||||
"1m" is taken to mean "31d". This option is applied before the secondly option
|
||||
and like the other options any archives kept by this option do not count towards
|
||||
the later rules.
|
||||
|
||||
The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will
|
||||
keep the last N archives under the assumption that you do not create more than one
|
||||
backup archive in the same second).
|
||||
|
|
@ -153,4 +152,4 @@ backup archive in the same second).
|
|||
When using ``--stats``, you will get some statistics about how much data was
|
||||
deleted - the "Deleted data" deduplicated size there is most interesting as
|
||||
that is how much your repository will shrink.
|
||||
Please note that the "All archives" stats refer to the state after pruning.
|
||||
Please note that the "All archives" stats refer to the state after pruning.
|
||||
|
|
@ -33,7 +33,7 @@ borg recreate
|
|||
| |
|
||||
| :ref:`common_options` |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **Exclusion options** |
|
||||
| **Include/Exclude options** |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
|
||||
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
|
@ -92,7 +92,7 @@ borg recreate
|
|||
:ref:`common_options`
|
||||
|
|
||||
|
||||
Exclusion 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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue