forked from borgbackup/borg
-
Notifications
You must be signed in to change notification settings - Fork 1
/
environment.rst.inc
200 lines (174 loc) · 11.8 KB
/
environment.rst.inc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
Environment Variables
~~~~~~~~~~~~~~~~~~~~~
Borg uses some environment variables for automation:
General:
BORG_REPO
When set, use the value to give the default repository location. If a command needs an archive
parameter, you can abbreviate as ``::archive``. If a command needs a repository parameter, you
can either leave it away or abbreviate as ``::``, if a positional parameter is required.
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.
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 ``$HOME`` will work, but ``~`` won't.
If BORG_PASSPHRASE is also set, it takes precedence.
See also BORG_NEW_PASSPHRASE.
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.
BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a **new** passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
be checked.
Main usecase for this is to fully automate ``borg change-passphrase``.
BORG_DISPLAY_PASSPHRASE
When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
BORG_HOST_ID
Borg usually computes a host id from the FQDN plus the results of ``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 better externally control 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.
BORG_LOGGING_CONF
When set, use the given filename as INI_-style logging configuration.
A basic example conf can be found at ``docs/misc/logging.conf``.
BORG_RSH
When set, use this command instead of ``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.
BORG_REMOTE_PATH
When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
Using ``--remote-path PATH`` commandline option overrides the environment variable.
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.
BORG_FILES_CACHE_TTL
When set to a numeric value, this determines the maximum "time to live" for the files cache
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
The FAQ explains this more detailed in: :ref:`always_chunking`
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.
BORG_FUSE_IMPL
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 pyfuse3
- ``llfuse``: only try to load llfuse
- ``none``: do not try to load an implementation
BORG_SELFTEST
This 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.
BORG_WORKAROUNDS
A list of comma separated strings that trigger workarounds in borg,
e.g. to work around bugs in other software.
Currently known strings are:
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).
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).
authenticated_no_key
Work around a lost passphrase or key for an ``authenticated`` mode repository
(these are only authenticated, but not encrypted).
If the key is missing in the repository config, add ``key = anything`` there.
This workaround is **only** for emergencies and **only** to extract data
from an affected repository (read-only access)::
BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
After you have extracted all data you need, you MUST delete the repository::
BORG_WORKAROUNDS=authenticated_no_key borg delete repo
Now you can init a fresh repo. Make sure you do not use the workaround any more.
ignore_invalid_archive_tam
Work around invalid archive TAMs created by borg < 1.2.5, see issue #7791.
This workaround likely needs to get used only once when following the upgrade
instructions for CVE-2023-36811, see :ref:`archives_tam_vuln`.
In normal production operations, this workaround should never be used.
Some automatic "answerers" (if set, they automatically answer confirmation questions):
BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: Attempting to access a previously unknown unencrypted repository"
BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
For "Warning: The repository at location ... was previously located at ..."
BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "This is a potentially dangerous function..." (check --repair)
BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
For "You requested to completely DELETE the repository *including* all archives it contains:"
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.
.. _XDG env var: https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html
Directories and files:
BORG_BASE_DIR
Defaults to ``$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_CACHE_DIR
Defaults to ``$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: :ref:`cache_security`
BORG_CONFIG_DIR
Defaults to ``$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: :ref:`home_config_borg`
BORG_SECURITY_DIR
Defaults to ``$BORG_CONFIG_DIR/security``.
This directory contains information borg uses to track its usage of NONCES ("numbers used
once" - usually in encryption context) and other security relevant data.
BORG_KEYS_DIR
Defaults to ``$BORG_CONFIG_DIR/keys``.
This directory contains keys for encrypted repositories.
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:
- this setting only applies to the keyfile modes (not to the repokey modes).
- using a full, absolute path to the key file is recommended.
- all directories in the given path must exist.
- this setting forces borg to use the key file at the given location.
- the key file must either exist (for most commands) or will be created (``borg init``).
- you need to give a different path for different repositories.
- you need to point to the correct key file matching the repository the command will operate on.
TMPDIR
This is where temporary files are stored (might need a lot of temporary space for some
operations), see tempfile_ for details.
Building:
BORG_OPENSSL_PREFIX
Adds given OpenSSL header file directory to the default locations (setup.py).
BORG_LIBLZ4_PREFIX
Adds given prefix directory to the default locations. If a 'include/lz4.h' is found Borg
will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
BORG_LIBZSTD_PREFIX
Adds given prefix directory to the default locations. If a 'include/zstd.h' is found Borg
will be linked against the system libzstd instead of a bundled implementation. (setup.py)
Please note:
- Be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data's security/safety.
- Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g.
mode 600, root:root).
.. _INI: https://docs.python.org/3/library/logging.config.html#configuration-file-format
.. _tempfile: https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir