mirror of https://github.com/borgbackup/borg.git
1009 lines
32 KiB
Groff
1009 lines
32 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "BORG" 1 "2024-02-20" "" "borg backup tool"
|
|
.SH NAME
|
|
borg \- deduplicating and encrypting backup tool
|
|
.SH SYNOPSIS
|
|
.sp
|
|
borg [common options] <command> [options] [arguments]
|
|
.SH DESCRIPTION
|
|
.\" we don't include the README.rst here since we want to keep this terse.
|
|
.
|
|
.sp
|
|
BorgBackup (short: Borg) is a deduplicating backup program.
|
|
Optionally, it supports compression and authenticated encryption.
|
|
.sp
|
|
The main goal of Borg is to provide an efficient and secure way to back data up.
|
|
The data deduplication technique used makes Borg suitable for daily backups
|
|
since only changes are stored.
|
|
The authenticated encryption technique makes it suitable for backups to targets not
|
|
fully trusted.
|
|
.sp
|
|
Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collection
|
|
of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not
|
|
distinguish archives from each other in any way other than their name,
|
|
it does not matter when or where archives were created (e.g. different hosts).
|
|
.SH EXAMPLES
|
|
.SS A step\-by\-step example
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
Before a backup can be made, a repository has to be initialized:
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo rcreate \-\-encryption=repokey\-aes\-ocb
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.IP 2. 3
|
|
Back up the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
|
|
\fIMonday\fP:
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo create Monday ~/src ~/Documents
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.IP 3. 3
|
|
The next day create a new archive called \fITuesday\fP:
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo create \-\-stats Tuesday ~/src ~/Documents
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
This backup will be a lot quicker and a lot smaller since only new, never
|
|
before seen data is stored. The \fB\-\-stats\fP option causes Borg to
|
|
output statistics about the newly created archive such as the deduplicated
|
|
size (the amount of unique data not shared with other archives):
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
Repository: /path/to/repo
|
|
Archive name: Tuesday
|
|
Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc1877718d
|
|
Time (start): Sat, 2022\-06\-25 20:21:43
|
|
Time (end): Sat, 2022\-06\-25 20:21:43
|
|
Duration: 0.07 seconds
|
|
Utilization of max. archive size: 0%
|
|
Number of files: 699
|
|
Original size: 31.14 MB
|
|
Deduplicated size: 502 B
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.IP 4. 3
|
|
List all archives in the repository:
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo rlist
|
|
Monday Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298]
|
|
Tuesday Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d]
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.IP 5. 3
|
|
List the contents of the \fIMonday\fP archive:
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo list Monday
|
|
drwxr\-xr\-x user group 0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
|
|
\-rw\-r\-\-r\-\- user group 7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
|
|
\&...
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.IP 6. 3
|
|
Restore the \fIMonday\fP archive by extracting the files relative to the current directory:
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo extract Monday
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.IP 7. 3
|
|
Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo disk space):
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo delete \-a Monday
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Please note the \fB\-a\fP option here (short for \fB\-\-match\-archives\fP) which enables you
|
|
to give a pattern to delete multiple archives, like \fB\-a \(aqsh:oldcrap\-*\(aq\fP\&.
|
|
You can also combine this with \fB\-\-first\fP, \fB\-\-last\fP and \fB\-\-sort\-by\fP\&.
|
|
Be careful, always first use with \fB\-\-dry\-run\fP and \fB\-\-list\fP!
|
|
.IP 8. 3
|
|
Recover disk space by compacting the segment files in the repo:
|
|
.INDENT 3.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
$ borg \-r /path/to/repo compact
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Borg is quiet by default (it defaults to WARNING log level).
|
|
You can use options like \fB\-\-progress\fP or \fB\-\-list\fP to get specific
|
|
reports during command execution. You can also add the \fB\-v\fP (or
|
|
\fB\-\-verbose\fP or \fB\-\-info\fP) option to adjust the log level to INFO to
|
|
get other informational messages.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH NOTES
|
|
.SS Positional Arguments and Options: Order matters
|
|
.sp
|
|
Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example)
|
|
to the left or right of all positional arguments (\fBrepo::archive\fP and \fBpath\fP
|
|
in the example), but not in between them:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
borg create \-s \-\-progress archive path # good and preferred
|
|
borg create archive path \-s \-\-progress # also works
|
|
borg create \-s archive path \-\-progress # works, but ugly
|
|
borg create archive \-s \-\-progress path # BAD
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP
|
|
.SS Repository URLs
|
|
.sp
|
|
\fBLocal filesystem\fP (or locally mounted network filesystem):
|
|
.sp
|
|
\fB/path/to/repo\fP \- filesystem path to repo directory, absolute path
|
|
.sp
|
|
\fBpath/to/repo\fP \- filesystem path to repo directory, relative path
|
|
.sp
|
|
Also, stuff like \fB~/path/to/repo\fP or \fB~other/path/to/repo\fP works (this is
|
|
expanded by your shell).
|
|
.sp
|
|
Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style.
|
|
.sp
|
|
\fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
|
|
.sp
|
|
\fBssh://user@host:port/path/to/repo\fP \- absolute path\(ga
|
|
.sp
|
|
\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
|
|
.sp
|
|
\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
|
|
.sp
|
|
If you frequently need the same repo URL, it is a good idea to set the
|
|
\fBBORG_REPO\fP environment variable to set a default for the repo URL:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Then just leave away the \fB\-\-repo\fP option if you want
|
|
to use the default \- it will be read from BORG_REPO then.
|
|
.SS Repository Locations / Archive names
|
|
.sp
|
|
Many commands need to know the repository location, give it via \fB\-r\fP / \fB\-\-repo\fP
|
|
or use the \fBBORG_REPO\fP environment variable.
|
|
.sp
|
|
Commands needing one or two archive names usually get them as positional argument.
|
|
.sp
|
|
Commands working with an arbitrary amount of archives, usually take \fB\-a ARCH_GLOB\fP\&.
|
|
.sp
|
|
Archive names must not contain the \fB/\fP (slash) character. For simplicity,
|
|
maybe also avoid blanks or other characters that have special meaning on the
|
|
shell or in a filesystem (borg mount will use the archive name as directory
|
|
name).
|
|
.SS Logging
|
|
.sp
|
|
Borg writes all log output to stderr by default. But please note that something
|
|
showing up on stderr does \fInot\fP indicate an error condition just because it is
|
|
on stderr. Please check the log levels of the messages and the return code of
|
|
borg for determining error, warning or success conditions.
|
|
.sp
|
|
If you want to capture the log output to a file, just redirect it:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
borg create repo::archive myfiles 2>> logfile
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Custom logging configurations can be implemented via BORG_LOGGING_CONF.
|
|
.sp
|
|
The log level of the builtin logging configuration defaults to WARNING.
|
|
This is because we want Borg to be mostly silent and only output
|
|
warnings, errors and critical messages, unless output has been requested
|
|
by supplying an option that implies output (e.g. \fB\-\-list\fP or \fB\-\-progress\fP).
|
|
.sp
|
|
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
|
|
.sp
|
|
Use \fB\-\-debug\fP to set DEBUG log level \-
|
|
to get debug, info, warning, error and critical level output.
|
|
.sp
|
|
Use \fB\-\-info\fP (or \fB\-v\fP or \fB\-\-verbose\fP) to set INFO log level \-
|
|
to get info, warning, error and critical level output.
|
|
.sp
|
|
Use \fB\-\-warning\fP (default) to set WARNING log level \-
|
|
to get warning, error and critical level output.
|
|
.sp
|
|
Use \fB\-\-error\fP to set ERROR log level \-
|
|
to get error and critical level output.
|
|
.sp
|
|
Use \fB\-\-critical\fP to set CRITICAL log level \-
|
|
to get critical level output.
|
|
.sp
|
|
While you can set misc. log levels, do not expect that every command will
|
|
give different output on different log levels \- it\(aqs just a possibility.
|
|
.sp
|
|
\fBWARNING:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
Options \fB\-\-critical\fP and \fB\-\-error\fP are provided for completeness,
|
|
their usage is not recommended as you might miss important information.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Return codes
|
|
.sp
|
|
Borg can exit with the following return codes (rc):
|
|
.TS
|
|
center;
|
|
|l|l|.
|
|
_
|
|
T{
|
|
Return code
|
|
T} T{
|
|
Meaning
|
|
T}
|
|
_
|
|
T{
|
|
0
|
|
T} T{
|
|
success (logged as INFO)
|
|
T}
|
|
_
|
|
T{
|
|
1
|
|
T} T{
|
|
generic warning (operation reached its normal end, but there were warnings \-\-
|
|
you should check the log, logged as WARNING)
|
|
T}
|
|
_
|
|
T{
|
|
2
|
|
T} T{
|
|
generic error (like a fatal error, a local or remote exception, the operation
|
|
did not reach its normal end, logged as ERROR)
|
|
T}
|
|
_
|
|
T{
|
|
3..99
|
|
T} T{
|
|
specific error (enabled by BORG_EXIT_CODES=modern)
|
|
T}
|
|
_
|
|
T{
|
|
100..127
|
|
T} T{
|
|
specific warning (enabled by BORG_EXIT_CODES=modern)
|
|
T}
|
|
_
|
|
T{
|
|
128+N
|
|
T} T{
|
|
killed by signal N (e.g. 137 == kill \-9)
|
|
T}
|
|
_
|
|
.TE
|
|
.sp
|
|
If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated
|
|
level as the last log entry.
|
|
.SS Environment Variables
|
|
.sp
|
|
Borg uses some environment variables for automation:
|
|
.INDENT 0.0
|
|
.TP
|
|
.B General:
|
|
.INDENT 7.0
|
|
.TP
|
|
.B BORG_REPO
|
|
When set, use the value to give the default repository location.
|
|
Use this so you do not need to type \fB\-\-repo /path/to/my/repo\fP all the time.
|
|
.TP
|
|
.B BORG_OTHER_REPO
|
|
Similar to BORG_REPO, but gives the default for \fB\-\-other\-repo\fP\&.
|
|
.TP
|
|
.B BORG_PASSPHRASE
|
|
When set, use the value to answer the passphrase question for encrypted repositories.
|
|
It is used when a passphrase is needed to access an encrypted repo as well as when a new
|
|
passphrase should be initially set when initializing an encrypted repo.
|
|
See also BORG_NEW_PASSPHRASE.
|
|
.TP
|
|
.B BORG_PASSCOMMAND
|
|
When set, use the standard output of the command (trailing newlines are stripped) to answer the
|
|
passphrase question for encrypted repositories.
|
|
It is used when a passphrase is needed to access an encrypted repo as well as when a new
|
|
passphrase should be initially set when initializing an encrypted repo. Note that the command
|
|
is executed without a shell. So variables, like \fB$HOME\fP will work, but \fB~\fP won\(aqt.
|
|
If BORG_PASSPHRASE is also set, it takes precedence.
|
|
See also BORG_NEW_PASSPHRASE.
|
|
.TP
|
|
.B BORG_PASSPHRASE_FD
|
|
When set, specifies a file descriptor to read a passphrase
|
|
from. Programs starting borg may choose to open an anonymous pipe
|
|
and use it to pass a passphrase. This is safer than passing via
|
|
BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
|
|
can be examined by other processes.
|
|
If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence.
|
|
.TP
|
|
.B BORG_NEW_PASSPHRASE
|
|
When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
|
|
This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
|
|
be checked.
|
|
Main usecase for this is to automate fully \fBborg change\-passphrase\fP\&.
|
|
.TP
|
|
.B BORG_DISPLAY_PASSPHRASE
|
|
When set, use the value to answer the \(dqdisplay the passphrase for verification\(dq question when defining a new passphrase for encrypted repositories.
|
|
.TP
|
|
.B BORG_EXIT_CODES
|
|
When set to \(dqmodern\(dq, the borg process will return more specific exit codes (rc).
|
|
Default is \(dqlegacy\(dq and returns rc 2 for all errors, 1 for all warnings, 0 for success.
|
|
.TP
|
|
.B BORG_HOST_ID
|
|
Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns
|
|
a unique id based on the MAC address of the network interface. Except if that MAC happens to be all\-zero \- in
|
|
that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
|
|
So, if you have a all\-zero MAC address or other reasons to control better externally the host id, just set this
|
|
environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
|
|
use \fI\%fqdn@uniqueid\fP\&.
|
|
.TP
|
|
.B BORG_LOCK_WAIT
|
|
You can set the default value for the \fB\-\-lock\-wait\fP option with this, so
|
|
you do not need to give it as a commandline option.
|
|
.TP
|
|
.B BORG_LOGGING_CONF
|
|
When set, use the given filename as \fI\%INI\fP\-style logging configuration.
|
|
A basic example conf can be found at \fBdocs/misc/logging.conf\fP\&.
|
|
.TP
|
|
.B BORG_RSH
|
|
When set, use this command instead of \fBssh\fP\&. This can be used to specify ssh options, such as
|
|
a custom identity file \fBssh \-i /path/to/private/key\fP\&. See \fBman ssh\fP for other options. Using
|
|
the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
|
|
.TP
|
|
.B BORG_REMOTE_PATH
|
|
When set, use the given path as borg executable on the remote (defaults to \(dqborg\(dq if unset).
|
|
Using \fB\-\-remote\-path PATH\fP commandline option overrides the environment variable.
|
|
.TP
|
|
.B BORG_FILES_CACHE_SUFFIX
|
|
When set to a value at least one character long, instructs borg to use a specifically named
|
|
(based on the suffix) alternative files cache. This can be used to avoid loading and saving
|
|
cache entries for backup sources other than the current sources.
|
|
.TP
|
|
.B BORG_FILES_CACHE_TTL
|
|
When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache
|
|
entries (default: 20). The files cache is used to determine quickly whether a file is unchanged.
|
|
The FAQ explains this more detailed in: \fIalways_chunking\fP
|
|
.TP
|
|
.B BORG_SHOW_SYSINFO
|
|
When set to no (default: yes), system information (like OS, Python version, ...) in
|
|
exceptions is not shown.
|
|
Please only use for good reasons as it makes issues harder to analyze.
|
|
.TP
|
|
.B BORG_FUSE_IMPL
|
|
Choose the lowlevel FUSE implementation borg shall use for \fBborg mount\fP\&.
|
|
This is a comma\-separated list of implementation names, they are tried in the
|
|
given order, e.g.:
|
|
.INDENT 7.0
|
|
.IP \(bu 2
|
|
\fBpyfuse3,llfuse\fP: default, first try to load pyfuse3, then try to load llfuse.
|
|
.IP \(bu 2
|
|
\fBllfuse,pyfuse3\fP: first try to load llfuse, then try to load pyfuse3.
|
|
.IP \(bu 2
|
|
\fBpyfuse3\fP: only try to load pyfuse3
|
|
.IP \(bu 2
|
|
\fBllfuse\fP: only try to load llfuse
|
|
.IP \(bu 2
|
|
\fBnone\fP: do not try to load an implementation
|
|
.UNINDENT
|
|
.TP
|
|
.B BORG_SELFTEST
|
|
This can be used to influence borg\(aqs builtin self\-tests. The default is to execute the tests
|
|
at the beginning of each borg command invocation.
|
|
.sp
|
|
BORG_SELFTEST=disabled can be used to switch off the tests and rather save some time.
|
|
Disabling is not recommended for normal borg users, but large scale borg storage providers can
|
|
use this to optimize production servers after at least doing a one\-time test borg (with
|
|
selftests not disabled) when installing or upgrading machines / OS / borg.
|
|
.TP
|
|
.B BORG_WORKAROUNDS
|
|
A list of comma separated strings that trigger workarounds in borg,
|
|
e.g. to work around bugs in other software.
|
|
.sp
|
|
Currently known strings are:
|
|
.INDENT 7.0
|
|
.TP
|
|
.B basesyncfile
|
|
Use the more simple BaseSyncFile code to avoid issues with sync_file_range.
|
|
You might need this to run borg on WSL (Windows Subsystem for Linux) or
|
|
in systemd.nspawn containers on some architectures (e.g. ARM).
|
|
Using this does not affect data safety, but might result in a more bursty
|
|
write to disk behaviour (not continuously streaming to disk).
|
|
.TP
|
|
.B retry_erofs
|
|
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
|
|
.B Output formatting:
|
|
.INDENT 7.0
|
|
.TP
|
|
.B BORG_LIST_FORMAT
|
|
Giving the default value for \fBborg list \-\-format=X\fP\&.
|
|
.TP
|
|
.B BORG_RLIST_FORMAT
|
|
Giving the default value for \fBborg rlist \-\-format=X\fP\&.
|
|
.TP
|
|
.B BORG_PRUNE_FORMAT
|
|
Giving the default value for \fBborg prune \-\-format=X\fP\&.
|
|
.UNINDENT
|
|
.TP
|
|
.B Some automatic \(dqanswerers\(dq (if set, they automatically answer confirmation questions):
|
|
.INDENT 7.0
|
|
.TP
|
|
.B BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
|
|
For \(dqWarning: Attempting to access a previously unknown unencrypted repository\(dq
|
|
.TP
|
|
.B BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
|
|
For \(dqWarning: The repository at location ... was previously located at ...\(dq
|
|
.TP
|
|
.B BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
|
|
For \(dqThis is a potentially dangerous function...\(dq (check \-\-repair)
|
|
.TP
|
|
.B BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
|
|
For \(dqYou requested to DELETE the repository completely \fIincluding\fP all archives it contains:\(dq
|
|
.UNINDENT
|
|
.sp
|
|
Note: answers are case sensitive. setting an invalid answer value might either give the default
|
|
answer or ask you interactively, depending on whether retries are allowed (they by default are
|
|
allowed). So please test your scripts interactively before making them a non\-interactive script.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B Directories and files:
|
|
.INDENT 7.0
|
|
.TP
|
|
.B BORG_BASE_DIR
|
|
Defaults to \fB$HOME\fP or \fB~$USER\fP or \fB~\fP (in that order).
|
|
If you want to move all borg\-specific folders to a custom path at once, all you need to do is
|
|
to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt accordingly
|
|
(assuming you didn\(aqt set them to a different custom value).
|
|
.TP
|
|
.B BORG_CACHE_DIR
|
|
Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
|
|
\fI\%XDG env var\fP \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
|
|
This directory contains the local cache and might need a lot
|
|
of space for dealing with big repositories. Make sure you\(aqre aware of the associated
|
|
security aspects of the cache location: \fIcache_security\fP
|
|
.TP
|
|
.B BORG_CONFIG_DIR
|
|
Defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
|
|
\fI\%XDG env var\fP \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
|
|
This directory contains all borg configuration directories, see the FAQ
|
|
for a security advisory about the data in this directory: \fIhome_config_borg\fP
|
|
.TP
|
|
.B BORG_DATA_DIR
|
|
Defaults to \fB$BORG_BASE_DIR/.local/share/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
|
|
\fI\%XDG env var\fP \fBXDG_DATA_HOME\fP is set, then \fB$XDG_DATA_HOME/borg\fP is being used instead.
|
|
This directory contains all borg data directories, see the FAQ
|
|
for a security advisory about the data in this directory: \fIhome_data_borg\fP
|
|
.TP
|
|
.B BORG_RUNTIME_DIR
|
|
Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
|
|
\fI\%XDG env var\fP \fBXDG_RUNTIME_DIR\fP is set, then \fB$XDG_RUNTIME_DIR/borg\fP is being used instead.
|
|
This directory contains borg runtime files, like e.g. the socket file.
|
|
.TP
|
|
.B BORG_SECURITY_DIR
|
|
Defaults to \fB$BORG_DATA_DIR/security\fP\&.
|
|
This directory contains security relevant data.
|
|
.TP
|
|
.B BORG_KEYS_DIR
|
|
Defaults to \fB$BORG_CONFIG_DIR/keys\fP\&.
|
|
This directory contains keys for encrypted repositories.
|
|
.TP
|
|
.B BORG_KEY_FILE
|
|
When set, use the given path as repository key file. Please note that this is only
|
|
for rather special applications that externally fully manage the key files:
|
|
.INDENT 7.0
|
|
.IP \(bu 2
|
|
this setting only applies to the keyfile modes (not to the repokey modes).
|
|
.IP \(bu 2
|
|
using a full, absolute path to the key file is recommended.
|
|
.IP \(bu 2
|
|
all directories in the given path must exist.
|
|
.IP \(bu 2
|
|
this setting forces borg to use the key file at the given location.
|
|
.IP \(bu 2
|
|
the key file must either exist (for most commands) or will be created (\fBborg rcreate\fP).
|
|
.IP \(bu 2
|
|
you need to give a different path for different repositories.
|
|
.IP \(bu 2
|
|
you need to point to the correct key file matching the repository the command will operate on.
|
|
.UNINDENT
|
|
.TP
|
|
.B TMPDIR
|
|
This is where temporary files are stored (might need a lot of temporary space for some
|
|
operations), see \fI\%tempfile\fP for details.
|
|
.UNINDENT
|
|
.TP
|
|
.B Building:
|
|
.INDENT 7.0
|
|
.TP
|
|
.B BORG_OPENSSL_PREFIX
|
|
Adds given OpenSSL header file directory to the default locations (setup.py).
|
|
.TP
|
|
.B BORG_LIBACL_PREFIX
|
|
Adds given prefix directory to the default locations. If an \(aqinclude/acl/libacl.h\(aq is found
|
|
Borg will be linked against the system libacl instead of a bundled implementation. (setup.py)
|
|
.TP
|
|
.B BORG_LIBLZ4_PREFIX
|
|
Adds given prefix directory to the default locations. If a \(aqinclude/lz4.h\(aq is found Borg
|
|
will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
|
|
.TP
|
|
.B BORG_LIBZSTD_PREFIX
|
|
Adds given prefix directory to the default locations. If a \(aqinclude/zstd.h\(aq is found Borg
|
|
will be linked against the system libzstd instead of a bundled implementation. (setup.py)
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Please note:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Be very careful when using the \(dqyes\(dq sayers, the warnings with prompt exist for your / your data\(aqs security/safety.
|
|
.IP \(bu 2
|
|
Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g.
|
|
mode 600, root:root).
|
|
.UNINDENT
|
|
.SS File systems
|
|
.sp
|
|
We strongly recommend against using Borg (or any other database\-like
|
|
software) on non\-journaling file systems like FAT, since it is not
|
|
possible to assume any consistency in case of power failures (or a
|
|
sudden disconnect of an external drive or similar failures).
|
|
.sp
|
|
While Borg uses a data store that is resilient against these failures
|
|
when used on journaling file systems, it is not possible to guarantee
|
|
this with some hardware \-\- independent of the software used. We don\(aqt
|
|
know a list of affected hardware.
|
|
.sp
|
|
If you are suspicious whether your Borg repository is still consistent
|
|
and readable after one of the failures mentioned above occurred, run
|
|
\fBborg check \-\-verify\-data\fP to make sure it is consistent.
|
|
Requirements for Borg repository file systems
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Long file names
|
|
.IP \(bu 2
|
|
At least three directory levels with short names
|
|
.IP \(bu 2
|
|
Typically, file sizes up to a few hundred MB.
|
|
Large repositories may require large files (>2 GB).
|
|
.IP \(bu 2
|
|
Up to 1000 files per directory.
|
|
.IP \(bu 2
|
|
rename(2) / MoveFile(Ex) should work as specified, i.e. on the same file system
|
|
it should be a move (not a copy) operation, and in case of a directory
|
|
it should fail if the destination exists and is not an empty directory,
|
|
since this is used for locking.
|
|
.IP \(bu 2
|
|
Also hardlinks are used for more safe and secure file updating (e.g. of the repo
|
|
config file), but the code tries to work also if hardlinks are not supported.
|
|
.UNINDENT
|
|
.SS Units
|
|
.sp
|
|
To display quantities, Borg takes care of respecting the
|
|
usual conventions of scale. Disk sizes are displayed in \fI\%decimal\fP, using powers of ten (so
|
|
\fBkB\fP means 1000 bytes). For memory usage, \fI\%binary prefixes\fP are used, and are
|
|
indicated using the \fI\%IEC binary prefixes\fP,
|
|
using powers of two (so \fBKiB\fP means 1024 bytes).
|
|
.SS Date and Time
|
|
.sp
|
|
We format date and time conforming to ISO\-8601, that is: YYYY\-MM\-DD and
|
|
HH:MM:SS (24h clock).
|
|
.sp
|
|
For more information about that, see: \fI\%https://xkcd.com/1179/\fP
|
|
.sp
|
|
Unless otherwise noted, we display local date and time.
|
|
Internally, we store and process date and time as UTC.
|
|
.SS Resource Usage
|
|
.sp
|
|
Borg might use a lot of resources depending on the size of the data set it is dealing with.
|
|
.sp
|
|
If one uses Borg in a client/server way (with a ssh: repository),
|
|
the resource usage occurs in part on the client and in another part on the
|
|
server.
|
|
.sp
|
|
If one uses Borg as a single process (with a filesystem repo),
|
|
all the resource usage occurs in that one process, so just add up client +
|
|
server to get the approximate resource usage.
|
|
.INDENT 0.0
|
|
.TP
|
|
.B CPU client:
|
|
.INDENT 7.0
|
|
.IP \(bu 2
|
|
\fBborg create:\fP does chunking, hashing, compression, crypto (high CPU usage)
|
|
.IP \(bu 2
|
|
\fBchunks cache sync:\fP quite heavy on CPU, doing lots of hashtable operations.
|
|
.IP \(bu 2
|
|
\fBborg extract:\fP crypto, decompression (medium to high CPU usage)
|
|
.IP \(bu 2
|
|
\fBborg check:\fP similar to extract, but depends on options given.
|
|
.IP \(bu 2
|
|
\fBborg prune / borg delete archive:\fP low to medium CPU usage
|
|
.IP \(bu 2
|
|
\fBborg delete repo:\fP done on the server
|
|
.UNINDENT
|
|
.sp
|
|
It won\(aqt go beyond 100% of 1 core as the code is currently single\-threaded.
|
|
Especially higher zlib and lzma compression levels use significant amounts
|
|
of CPU cycles. Crypto might be cheap on the CPU (if hardware accelerated) or
|
|
expensive (if not).
|
|
.TP
|
|
.B CPU server:
|
|
It usually doesn\(aqt need much CPU, it just deals with the key/value store
|
|
(repository) and uses the repository index for that.
|
|
.sp
|
|
borg check: the repository check computes the checksums of all chunks
|
|
(medium CPU usage)
|
|
borg delete repo: low CPU usage
|
|
.TP
|
|
.B CPU (only for client/server operation):
|
|
When using borg in a client/server way with a \fI\%ssh:\-type\fP repo, the ssh
|
|
processes used for the transport layer will need some CPU on the client and
|
|
on the server due to the crypto they are doing \- esp. if you are pumping
|
|
big amounts of data.
|
|
.TP
|
|
.B Memory (RAM) client:
|
|
The chunks index and the files index are read into memory for performance
|
|
reasons. Might need big amounts of memory (see below).
|
|
Compression, esp. lzma compression with high levels might need substantial
|
|
amounts of memory.
|
|
.TP
|
|
.B Memory (RAM) server:
|
|
The server process will load the repository index into memory. Might need
|
|
considerable amounts of memory, but less than on the client (see below).
|
|
.TP
|
|
.B Chunks index (client only):
|
|
Proportional to the amount of data chunks in your repo. Lots of chunks
|
|
in your repo imply a big chunks index.
|
|
It is possible to tweak the chunker params (see create options).
|
|
.TP
|
|
.B Files index (client only):
|
|
Proportional to the amount of files in your last backups. Can be switched
|
|
off (see create options), but next backup might be much slower if you do.
|
|
The speed benefit of using the files cache is proportional to file size.
|
|
.TP
|
|
.B Repository index (server only):
|
|
Proportional to the amount of data chunks in your repo. Lots of chunks
|
|
in your repo imply a big repository index.
|
|
It is possible to tweak the chunker params (see create options) to
|
|
influence the amount of chunks being created.
|
|
.TP
|
|
.B Temporary files (client):
|
|
Reading data and metadata from a FUSE mounted repository will consume up to
|
|
the size of all deduplicated, small chunks in the repository. Big chunks
|
|
won\(aqt be locally cached.
|
|
.TP
|
|
.B Temporary files (server):
|
|
A non\-trivial amount of data will be stored on the remote temp directory
|
|
for each client that connects to it. For some remotes, this can fill the
|
|
default temporary directory at /tmp. This can be remediated by ensuring the
|
|
$TMPDIR, $TEMP, or $TMP environment variable is properly set for the sshd
|
|
process.
|
|
For some OSes, this can be done just by setting the correct value in the
|
|
\&.bashrc (or equivalent login config file for other shells), however in
|
|
other cases it may be necessary to first enable \fBPermitUserEnvironment yes\fP
|
|
in your \fBsshd_config\fP file, then add \fBenvironment=\(dqTMPDIR=/my/big/tmpdir\(dq\fP
|
|
at the start of the public key to be used in the \fBauthorized_hosts\fP file.
|
|
.TP
|
|
.B Cache files (client only):
|
|
Contains the chunks index and files index (plus a collection of single\-
|
|
archive chunk indexes which might need huge amounts of disk space,
|
|
depending on archive count and size \- see FAQ about how to reduce).
|
|
.TP
|
|
.B Network (only for client/server operation):
|
|
If your repository is remote, all deduplicated (and optionally compressed/
|
|
encrypted) data of course has to go over the connection (\fBssh://\fP repo url).
|
|
If you use a locally mounted network filesystem, additionally some copy
|
|
operations used for transaction support also go over the connection. If
|
|
you back up multiple sources to one target repository, additional traffic
|
|
happens for cache resynchronization.
|
|
.UNINDENT
|
|
.SS Support for file metadata
|
|
.sp
|
|
Besides regular file and directory structures, Borg can preserve
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
symlinks (stored as symlink, the symlink is not followed)
|
|
.IP \(bu 2
|
|
special files:
|
|
.INDENT 2.0
|
|
.IP \(bu 2
|
|
character and block device files (restored via mknod)
|
|
.IP \(bu 2
|
|
FIFOs (\(dqnamed pipes\(dq)
|
|
.IP \(bu 2
|
|
special file \fIcontents\fP can be backed up in \fB\-\-read\-special\fP mode.
|
|
By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored.
|
|
.UNINDENT
|
|
.IP \(bu 2
|
|
hardlinked regular files, devices, symlinks, FIFOs (considering all items in the same archive)
|
|
.IP \(bu 2
|
|
timestamps in nanosecond precision: mtime, atime, ctime
|
|
.IP \(bu 2
|
|
other timestamps: birthtime (on platforms supporting it)
|
|
.IP \(bu 2
|
|
permissions:
|
|
.INDENT 2.0
|
|
.IP \(bu 2
|
|
IDs of owning user and owning group
|
|
.IP \(bu 2
|
|
names of owning user and owning group (if the IDs can be resolved)
|
|
.IP \(bu 2
|
|
Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky)
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
On some platforms additional features are supported:
|
|
.\" Yes/No's are grouped by reason/mechanism/reference.
|
|
.
|
|
.TS
|
|
center;
|
|
|l|l|l|l|.
|
|
_
|
|
T{
|
|
Platform
|
|
T} T{
|
|
ACLs
|
|
[5]
|
|
T} T{
|
|
xattr
|
|
[6]
|
|
T} T{
|
|
Flags
|
|
[7]
|
|
T}
|
|
_
|
|
T{
|
|
Linux
|
|
T} T{
|
|
Yes
|
|
T} T{
|
|
Yes
|
|
T} T{
|
|
Yes [1]
|
|
T}
|
|
_
|
|
T{
|
|
macOS
|
|
T} T{
|
|
Yes
|
|
T} T{
|
|
Yes
|
|
T} T{
|
|
Yes (all)
|
|
T}
|
|
_
|
|
T{
|
|
FreeBSD
|
|
T} T{
|
|
Yes
|
|
T} T{
|
|
Yes
|
|
T} T{
|
|
Yes (all)
|
|
T}
|
|
_
|
|
T{
|
|
OpenBSD
|
|
T} T{
|
|
n/a
|
|
T} T{
|
|
n/a
|
|
T} T{
|
|
Yes (all)
|
|
T}
|
|
_
|
|
T{
|
|
NetBSD
|
|
T} T{
|
|
n/a
|
|
T} T{
|
|
No [2]
|
|
T} T{
|
|
Yes (all)
|
|
T}
|
|
_
|
|
T{
|
|
Solaris and derivatives
|
|
T} T{
|
|
No [3]
|
|
T} T{
|
|
No [3]
|
|
T} T{
|
|
n/a
|
|
T}
|
|
_
|
|
T{
|
|
Windows (cygwin)
|
|
T} T{
|
|
No [4]
|
|
T} T{
|
|
No
|
|
T} T{
|
|
No
|
|
T}
|
|
_
|
|
.TE
|
|
.sp
|
|
Other Unix\-like operating systems may work as well, but have not been tested at all.
|
|
.sp
|
|
Note that most of the platform\-dependent features also depend on the file system.
|
|
For example, ntfs\-3g on Linux isn\(aqt able to convey NTFS ACLs.
|
|
.IP [1] 5
|
|
Only \(dqnodump\(dq, \(dqimmutable\(dq, \(dqcompressed\(dq and \(dqappend\(dq are supported.
|
|
Feature request #618 for more flags.
|
|
.IP [2] 5
|
|
Feature request #1332
|
|
.IP [3] 5
|
|
Feature request #1337
|
|
.IP [4] 5
|
|
Cygwin tries to map NTFS ACLs to permissions with varying degrees of success.
|
|
.IP [5] 5
|
|
The native access control list mechanism of the OS. This normally limits access to
|
|
non\-native ACLs. For example, NTFS ACLs aren\(aqt completely accessible on Linux with ntfs\-3g.
|
|
.IP [6] 5
|
|
extended attributes; key\-value pairs attached to a file, mainly used by the OS.
|
|
This includes resource forks on Mac OS X.
|
|
.IP [7] 5
|
|
aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms.
|
|
The BSDs define additional flags.
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fIborg\-common(1)\fP for common command line options
|
|
.sp
|
|
\fIborg\-rcreate(1)\fP, \fIborg\-rdelete(1)\fP, \fIborg\-rlist(1)\fP, \fIborg\-rinfo(1)\fP,
|
|
\fIborg\-create(1)\fP, \fIborg\-mount(1)\fP, \fIborg\-extract(1)\fP,
|
|
\fIborg\-list(1)\fP, \fIborg\-info(1)\fP,
|
|
\fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-compact(1)\fP,
|
|
\fIborg\-recreate(1)\fP
|
|
.sp
|
|
\fIborg\-compression(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Main web site \fI\%https://www.borgbackup.org/\fP
|
|
.IP \(bu 2
|
|
Releases \fI\%https://github.com/borgbackup/borg/releases\fP
|
|
.IP \(bu 2
|
|
Changelog \fI\%https://github.com/borgbackup/borg/blob/master/docs/changes.rst\fP
|
|
.IP \(bu 2
|
|
GitHub \fI\%https://github.com/borgbackup/borg\fP
|
|
.IP \(bu 2
|
|
Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#security\-contact\fP
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
The Borg Collective
|
|
|
|
orphan:
|
|
.\" Generated by docutils manpage writer.
|
|
.
|