mirror of
https://github.com/borgbackup/borg.git
synced 2026-04-07 10:08:57 -04:00
c8f8defc0f
The move to platformdirs and its current usage _does_ honor XDG_* variables on macOS if they are set. Tests were set up to assume this to be untrue and the docs matched that. This commit adds tests asserting that XDG_* variables are used when they are present on macOS, with default locations still in ~/Library.
312 lines
17 KiB
PHP
312 lines
17 KiB
PHP
Environment Variables
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Borg uses some environment variables for automation:
|
|
|
|
General:
|
|
BORG_REPO
|
|
When set, use the value to give the default repository location.
|
|
Use this so you do not need to type ``--repo /path/to/my/repo`` all the time.
|
|
BORG_OTHER_REPO
|
|
Similar to BORG_REPO, but gives the default for ``--other-repo``.
|
|
BORG_PASSPHRASE (and BORG_OTHER_PASSPHRASE)
|
|
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 (and BORG_OTHER_PASSCOMMAND)
|
|
When set, use the standard output of the command (trailing newlines are stripped) to answer the
|
|
passphrase question for encrypted repositories.
|
|
It is used when a passphrase is needed to access an encrypted repo as well as when a new
|
|
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 (and BORG_OTHER_PASSPHRASE_FD)
|
|
When set, specifies a file descriptor to read a passphrase
|
|
from. Programs starting borg may choose to open an anonymous pipe
|
|
and use it to pass a passphrase. This is safer than passing via
|
|
BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
|
|
can be examined by other processes.
|
|
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 use case 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_DEBUG_PASSPHRASE
|
|
When set to YES, display debugging information that includes passphrases used and passphrase related env vars set.
|
|
BORG_EXIT_CODES
|
|
When set to "modern", the borg process will return more specific exit codes (rc).
|
|
When set to "legacy", the borg process will return rc 2 for all errors, 1 for all warnings, 0 for success.
|
|
Default is "modern".
|
|
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 an all-zero MAC address or other reasons to better control the host id externally, 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_LOCK_WAIT
|
|
You can set the default value for the ``--lock-wait`` option with this, so
|
|
you do not need to give it as a command line option.
|
|
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`` command line 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 the ``--remote-path PATH`` command line option overrides the environment variable.
|
|
BORG_REPO_PERMISSIONS
|
|
Set repository permissions, see also: :ref:`borg_serve`
|
|
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: 2). The files cache is used to determine quickly whether a file is unchanged.
|
|
BORG_USE_CHUNKS_ARCHIVE
|
|
When set to no (default: yes), the ``chunks.archive.d`` folder will not be used. This reduces
|
|
disk space usage but slows down cache resyncs.
|
|
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_MSGPACK_VERSION_CHECK
|
|
Controls whether Borg checks the ``msgpack`` version.
|
|
The default is ``yes`` (strict check). Set to ``no`` to disable the version check and
|
|
allow any installed ``msgpack`` version. Use this at your own risk; malfunctioning or
|
|
incompatible ``msgpack`` versions may cause subtle bugs or repository data corruption.
|
|
BORG_FUSE_IMPL
|
|
Choose the low-level 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.:
|
|
|
|
- ``mfusepy,pyfuse3,llfuse``: default, first try to load mfusepy, then pyfuse3, then llfuse.
|
|
- ``llfuse,pyfuse3``: first try to load llfuse, then try to load pyfuse3.
|
|
- ``mfusepy``: only try to load mfusepy
|
|
- ``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 built-in 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
|
|
self-tests 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 behavior (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 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.
|
|
|
|
Output formatting:
|
|
BORG_LIST_FORMAT
|
|
Giving the default value for ``borg list --format=X``.
|
|
BORG_REPO_LIST_FORMAT
|
|
Giving the default value for ``borg repo-list --format=X``.
|
|
BORG_PRUNE_FORMAT
|
|
Giving the default value for ``borg prune --format=X``.
|
|
|
|
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 DELETE the repository completely *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:
|
|
|
|
.. note::
|
|
|
|
Borg 2 uses the `platformdirs <https://pypi.org/project/platformdirs/>`_ library to determine
|
|
default directory locations. This means that default paths are **platform-specific**:
|
|
|
|
- **Linux**: Uses XDG Base Directory Specification paths (e.g., ``~/.config/borg``,
|
|
``~/.cache/borg``, ``~/.local/share/borg``). `XDG env var`_ variables are honoured.
|
|
- **macOS**: Uses native macOS directories by default (e.g., ``~/Library/Application Support/borg``,
|
|
``~/Library/Caches/borg``). `XDG env var`_ variables are honoured if set.
|
|
- **Windows**: Uses Windows AppData directories (e.g., ``C:\Users\<user>\AppData\Roaming\borg``,
|
|
``C:\Users\<user>\AppData\Local\borg``). `XDG env var`_ variables are **not** honoured.
|
|
|
|
On all platforms, you can override each directory individually using the specific environment
|
|
variables described below. You can also set ``BORG_BASE_DIR`` to force borg to use
|
|
``BORG_BASE_DIR/.config/borg``, ``BORG_BASE_DIR/.cache/borg``, etc., regardless of the platform.
|
|
|
|
Default directory locations by platform (when no ``BORG_*`` environment variables are set):
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 15 25 30 30
|
|
|
|
* - Directory
|
|
- Linux
|
|
- macOS
|
|
- Windows
|
|
* - Config
|
|
- ``~/.config/borg``
|
|
- ``~/Library/Application Support/borg``
|
|
- ``%APPDATA%\borg``
|
|
* - Cache
|
|
- ``~/.cache/borg``
|
|
- ``~/Library/Caches/borg``
|
|
- ``%LOCALAPPDATA%\borg\Cache``
|
|
* - Data
|
|
- ``~/.local/share/borg``
|
|
- ``~/Library/Application Support/borg``
|
|
- ``%LOCALAPPDATA%\borg``
|
|
* - Runtime
|
|
- ``/run/user/<uid>/borg``
|
|
- ``~/Library/Caches/TemporaryItems/borg``
|
|
- ``%TEMP%\borg``
|
|
* - Keys
|
|
- ``<config_dir>/keys``
|
|
- ``<config_dir>/keys``
|
|
- ``<config_dir>\keys``
|
|
* - Security
|
|
- ``<data_dir>/security``
|
|
- ``<data_dir>/security``
|
|
- ``<data_dir>\security``
|
|
|
|
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 the platform-specific cache directory (see table above).
|
|
If ``BORG_BASE_DIR`` is set, defaults to ``$BORG_BASE_DIR/.cache/borg``.
|
|
On Linux and macOS, `XDG env var`_ ``XDG_CACHE_HOME`` is also honoured if ``BORG_BASE_DIR`` is not set.
|
|
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 the platform-specific config directory (see table above).
|
|
If ``BORG_BASE_DIR`` is set, defaults to ``$BORG_BASE_DIR/.config/borg``.
|
|
On Linux and macOS, `XDG env var`_ ``XDG_CONFIG_HOME`` is also honoured if ``BORG_BASE_DIR`` is not set.
|
|
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_DATA_DIR
|
|
Defaults to the platform-specific data directory (see table above).
|
|
If ``BORG_BASE_DIR`` is set, defaults to ``$BORG_BASE_DIR/.local/share/borg``.
|
|
On Linux and macOS, `XDG env var`_ ``XDG_DATA_HOME`` is also honoured if ``BORG_BASE_DIR`` is not set.
|
|
This directory contains all borg data directories, see the FAQ
|
|
for a security advisory about the data in this directory: :ref:`home_data_borg`
|
|
BORG_RUNTIME_DIR
|
|
Defaults to the platform-specific runtime directory (see table above).
|
|
If ``BORG_BASE_DIR`` is set, defaults to ``$BORG_BASE_DIR/.cache/borg``.
|
|
On Linux and macOS, `XDG env var`_ ``XDG_RUNTIME_DIR`` is also honoured if ``BORG_BASE_DIR`` is not set.
|
|
This directory contains borg runtime files, like e.g. the socket file.
|
|
BORG_SECURITY_DIR
|
|
Defaults to ``$BORG_DATA_DIR/security``.
|
|
This directory contains 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 repo-create``).
|
|
- 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_NAME
|
|
Defines the subdirectory name for OpenSSL (setup.py).
|
|
BORG_OPENSSL_PREFIX
|
|
Adds given OpenSSL header file directory to the default locations (setup.py).
|
|
BORG_LIBACL_PREFIX
|
|
Adds given prefix directory to the default locations. If an 'include/acl/libacl.h' is found
|
|
Borg will be linked against the system libacl instead of a bundled implementation. (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)
|
|
|
|
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
|
|
|
|
|
|
Automatically generated Environment Variables (jsonargparse)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Borg uses jsonargparse_ with ``default_env=True``, which means that every
|
|
command-line option can also be set via an environment variable.
|
|
|
|
The environment variable name is derived from the program name (``borg``),
|
|
the subcommand (if any), and the option name, all converted to uppercase
|
|
with dashes replaced by underscores.
|
|
|
|
For **top-level options** (not specific to a subcommand), the pattern is::
|
|
|
|
BORG_<OPTION>
|
|
|
|
For example, ``--lock-wait`` can be set via ``BORG_LOCK_WAIT``.
|
|
|
|
For **subcommand options**, the subcommand and option are separated by a
|
|
double underscore::
|
|
|
|
BORG_<SUBCOMMAND>__<OPTION>
|
|
|
|
For example, ``borg create --comment`` can be set via ``BORG_CREATE__COMMENT``.
|
|
|
|
.. _jsonargparse: https://jsonargparse.readthedocs.io/
|