Borg consists of a number of commands. Each command accepts a number of arguments and options and interprets various environment variables. The following sections will describe each command in detail.
Commands, options, parameters, paths and such are set in fixed-width
.
Option values are underlined. Borg has few options accepting a fixed set
of values (e.g. --encryption
of borg rcreate).
Experimental features are marked with red stripes on the sides, like this paragraph.
Experimental features are not stable, which means that they may be changed in incompatible ways or even removed entirely without prior notice in following releases.
Borg only supports taking options (-s
and --progress
in the example)
to the left or right of all positional arguments (repo::archive
and path
in the example), but not in between them:
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
This is due to a problem in the argparse module: https://bugs.python.org/issue15112
Local filesystem (or locally mounted network filesystem):
/path/to/repo
- filesystem path to repo directory, absolute path
path/to/repo
- filesystem path to repo directory, relative path
Also, stuff like ~/path/to/repo
or ~other/path/to/repo
works (this is
expanded by your shell).
Note: you may also prepend a file://
to a filesystem path to get URL style.
Remote repositories accessed via ssh user@host:
ssh://user@host:port/path/to/repo
- absolute path`
ssh://user@host:port/./path/to/repo
- path relative to current directory
ssh://user@host:port/~/path/to/repo
- path relative to user’s home directory
If you frequently need the same repo URL, it is a good idea to set the
BORG_REPO
environment variable to set a default for the repo URL:
export BORG_REPO='ssh://user@host:port/path/to/repo'
Then just leave away the --repo
option if you want
to use the default - it will be read from BORG_REPO then.
Many commands need to know the repository location, give it via -r
/ --repo
or use the BORG_REPO
environment variable.
Commands needing one or two archive names usually get them as positional argument.
Commands working with an arbitrary amount of archives, usually take -a ARCH_GLOB
.
Archive names must not contain the /
(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).
Borg writes all log output to stderr by default. But please note that something showing up on stderr does not 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.
If you want to capture the log output to a file, just redirect it:
borg create repo::archive myfiles 2>> logfile
Custom logging configurations can be implemented via BORG_LOGGING_CONF.
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. --list
or --progress
).
Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
Use --debug
to set DEBUG log level -
to get debug, info, warning, error and critical level output.
Use --info
(or -v
or --verbose
) to set INFO log level -
to get info, warning, error and critical level output.
Use --warning
(default) to set WARNING log level -
to get warning, error and critical level output.
Use --error
to set ERROR log level -
to get error and critical level output.
Use --critical
to set CRITICAL log level -
to get critical level output.
While you can set misc. log levels, do not expect that every command will give different output on different log levels - it’s just a possibility.
Warning
Options --critical
and --error
are provided for completeness,
their usage is not recommended as you might miss important information.
Borg can exit with the following return codes (rc):
Return code | Meaning |
---|---|
0 | success (logged as INFO) |
1 | warning (operation reached its normal end, but there were warnings -- you should check the log, logged as WARNING) |
2 | error (like a fatal error, a local or remote exception, the operation did not reach its normal end, logged as ERROR) |
128+N | killed by signal N (e.g. 137 == kill -9) |
If you use --show-rc
, the return code is also logged at the indicated
level as the last log entry.
Borg uses some environment variables for automation:
--repo /path/to/my/repo
all the time.--other-repo
.$HOME
will work, but ~
won’t.
If BORG_PASSPHRASE is also set, it takes precedence.
See also BORG_NEW_PASSPHRASE.borg change-passphrase
.uuid.getnode()
(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 fqdn@uniqueid.--lock-wait
option with this, so
you do not need to give it as a commandline option.docs/misc/logging.conf
.ssh
. This can be used to specify ssh options, such as
a custom identity file ssh -i /path/to/private/key
. See man ssh
for other options. Using
the --rsh CMD
commandline option overrides the environment variable.--remote-path PATH
commandline option overrides the environment variable.Choose the lowlevel FUSE implementation borg shall use for borg mount
.
This is a comma-separated list of implementation names, they are tried in the
given order, e.g.:
pyfuse3,llfuse
: default, first try to load pyfuse3, then try to load llfuse.llfuse,pyfuse3
: first try to load llfuse, then try to load pyfuse3.pyfuse3
: only try to load pyfuse3llfuse
: only try to load llfusenone
: do not try to load an implementationThis can be used to influence borg’s builtin self-tests. The default is to execute the tests at the beginning of each borg command invocation.
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.
A list of comma separated strings that trigger workarounds in borg, e.g. to work around bugs in other software.
Currently known strings are:
borg list --format=X
.borg rlist --format=X
.borg prune --format=X
.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.
$HOME
or ~$USER
or ~
(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 BORG_BASE_DIR
: the other paths for cache, config etc. will adapt accordingly
(assuming you didn’t set them to a different custom value).$BORG_BASE_DIR/.cache/borg
. If BORG_BASE_DIR
is not explicitly set while
XDG env var XDG_CACHE_HOME
is set, then $XDG_CACHE_HOME/borg
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’re aware of the associated
security aspects of the cache location: Do I need to take security precautions regarding the cache?$BORG_BASE_DIR/.config/borg
. If BORG_BASE_DIR
is not explicitly set while
XDG env var XDG_CONFIG_HOME
is set, then $XDG_CONFIG_HOME/borg
is being used instead.
This directory contains all borg configuration directories, see the FAQ
for a security advisory about the data in this directory: How important is the $HOME/.config/borg directory?$BORG_BASE_DIR/.local/share/borg
. If BORG_BASE_DIR
is not explicitly set while
XDG env var XDG_DATA_HOME
is set, then $XDG_DATA_HOME/borg
is being used instead.
This directory contains all borg data directories, see the FAQ
for a security advisory about the data in this directory: How important is the $HOME/.local/share/borg directory?$BORG_BASE_DIR/.cache/borg
. If BORG_BASE_DIR
is not explicitly set while
XDG env var XDG_RUNTIME_DIR
is set, then $XDG_RUNTIME_DIR/borg
is being used instead.
This directory contains borg runtime files, like e.g. the socket file.$BORG_DATA_DIR/security
.
This directory contains security relevant data.$BORG_CONFIG_DIR/keys
.
This directory contains keys for encrypted repositories.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:
borg rcreate
).Please note:
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).
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’t know a list of affected hardware.
If you are suspicious whether your Borg repository is still consistent
and readable after one of the failures mentioned above occurred, run
borg check --verify-data
to make sure it is consistent.
Requirements for Borg repository file systems
To display quantities, Borg takes care of respecting the
usual conventions of scale. Disk sizes are displayed in decimal, using powers of ten (so
kB
means 1000 bytes). For memory usage, binary prefixes are used, and are
indicated using the IEC binary prefixes,
using powers of two (so KiB
means 1024 bytes).
We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and HH:MM:SS (24h clock).
For more information about that, see: https://xkcd.com/1179/
Unless otherwise noted, we display local date and time. Internally, we store and process date and time as UTC.
Borg might use a lot of resources depending on the size of the data set it is dealing with.
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.
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.
It won’t 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).
It usually doesn’t need much CPU, it just deals with the key/value store (repository) and uses the repository index for that.
borg check: the repository check computes the checksums of all chunks (medium CPU usage) borg delete repo: low CPU usage
PermitUserEnvironment yes
in your sshd_config
file, then add environment="TMPDIR=/my/big/tmpdir"
at the start of the public key to be used in the authorized_hosts
file.ssh://
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.Besides regular file and directory structures, Borg can preserve
--read-special
mode.
By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored.On some platforms additional features are supported:
Platform | ACLs [5] | xattr [6] | Flags [7] |
---|---|---|---|
Linux | Yes | Yes | Yes [1] |
Mac OS X | Yes | Yes | Yes (all) |
FreeBSD | Yes | Yes | Yes (all) |
OpenBSD | n/a | n/a | Yes (all) |
NetBSD | n/a | No [2] | Yes (all) |
Solaris and derivatives | No [3] | No [3] | n/a |
Windows (cygwin) | No [4] | No | No |
Other Unix-like operating systems may work as well, but have not been tested at all.
Note that most of the platform-dependent features also depend on the file system. For example, ntfs-3g on Linux isn’t able to convey NTFS ACLs.
[1] | (1, 2) Only “nodump”, “immutable”, “compressed” and “append” are supported. Feature request #%s618 for more flags. |
[2] | Feature request #%s1332 |
[3] | (1, 2) Feature request #%s1337 |
[4] | Cygwin tries to map NTFS ACLs to permissions with varying degrees of success. |
[5] | The native access control list mechanism of the OS. This normally limits access to non-native ACLs. For example, NTFS ACLs aren’t completely accessible on Linux with ntfs-3g. |
[6] | extended attributes; key-value pairs attached to a file, mainly used by the OS. This includes resource forks on Mac OS X. |
[7] | aka BSD flags. The Linux set of flags [1] is portable across platforms. The BSDs define additional flags. |
In case you are interested in more details (like formulas), please see Internals. For details on the available JSON output, refer to All about JSON: How to develop frontends.
All Borg commands share these options:
-h, --help | show this help message and exit |
--critical | work on log level CRITICAL |
--error | work on log level ERROR |
--warning | work on log level WARNING (default) |
--info, -v, --verbose | work on log level INFO |
--debug | enable debug output, work on log level DEBUG |
--debug-topic TOPIC | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified. |
-p, --progress | show progress information |
--iec | format using IEC units (1KiB = 1024B) |
--log-json | Output one JSON object per log line instead of formatted text. |
--lock-wait SECONDS | wait at most SECONDS for acquiring a repository/cache lock (default: 1). |
--bypass-lock | Bypass locking mechanism |
--show-version | show/log the borg version |
--show-rc | show/log the return code (rc) |
--umask M | set umask to M (local only, default: 0077) |
--remote-path PATH | use PATH as borg executable on the remote (default: “borg”) |
--upload-ratelimit RATE | set network upload rate limit in kiByte/s (default: 0=unlimited) |
--upload-buffer UPLOAD_BUFFER | set network upload buffer size in MiB. (default: 0=no buffer) |
--debug-profile FILE | Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with “.pyprof”. |
--rsh RSH | Use this command to connect to the ‘borg serve’ process (default: ‘ssh’) |
-r REPO, --repo REPO | repository to use |
Option --bypass-lock
allows you to access the repository while bypassing
borg’s locking mechanism. This is necessary if your repository is on a read-only
storage where you don’t have write permissions or capabilities and therefore
cannot create a lock. Examples are repositories stored on a Bluray disc or a
read-only network storage. Avoid this option if you are able to use locks as
that is the safer way; see the warning below.
Warning
If you do use --bypass-lock
, you are responsible to ensure that no other
borg instances have write access to the repository. Otherwise, you might
experience errors and read broken data if changes to that repository are
being made at the same time.
Option --help
when used as a command works as expected on subcommands (e.g., borg help compact
).
But it does not work when the help command is being used on sub-sub-commands (e.g., borg help key export
).
The workaround for this to use the help command as a flag (e.g., borg key export --help
).
# Create an archive and log: borg version, files list, return code
$ borg -r /path/to/repo create --show-version --list --show-rc my-files files