1Environment Variables
2~~~~~~~~~~~~~~~~~~~~~
3
4Borg uses some environment variables for automation:
5
6General:
7    BORG_REPO
8        When set, use the value to give the default repository location. If a command needs an archive
9        parameter, you can abbreviate as ``::archive``. If a command needs a repository parameter, you
10        can either leave it away or abbreviate as ``::``, if a positional parameter is required.
11    BORG_PASSPHRASE
12        When set, use the value to answer the passphrase question for encrypted repositories.
13        It is used when a passphrase is needed to access an encrypted repo as well as when a new
14        passphrase should be initially set when initializing an encrypted repo.
15        See also BORG_NEW_PASSPHRASE.
16    BORG_PASSCOMMAND
17        When set, use the standard output of the command (trailing newlines are stripped) to answer the
18        passphrase question for encrypted repositories.
19        It is used when a passphrase is needed to access an encrypted repo as well as when a new
20        passphrase should be initially set when initializing an encrypted repo. Note that the command
21        is executed without a shell. So variables, like ``$HOME`` will work, but ``~`` won't.
22        If BORG_PASSPHRASE is also set, it takes precedence.
23        See also BORG_NEW_PASSPHRASE.
24    BORG_PASSPHRASE_FD
25        When set, specifies a file descriptor to read a passphrase
26        from. Programs starting borg may choose to open an anonymous pipe
27        and use it to pass a passphrase. This is safer than passing via
28        BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
29        can be examined by other processes.
30        If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence.
31    BORG_NEW_PASSPHRASE
32        When set, use the value to answer the passphrase question when a **new** passphrase is asked for.
33        This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
34        be checked.
35        Main usecase for this is to fully automate ``borg change-passphrase``.
36    BORG_DISPLAY_PASSPHRASE
37        When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
38    BORG_HOSTNAME_IS_UNIQUE=no
39        Borg assumes that it can derive a unique hostname / identity (see ``borg debug info``).
40        If this is not the case or you do not want Borg to automatically remove stale locks,
41        set this to *no*.
42    BORG_HOST_ID
43        Borg usually computes a host id from the FQDN plus the results of ``uuid.getnode()`` (which usually returns
44        a unique id based on the MAC address of the network interface. Except if that MAC happens to be all-zero - in
45        that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
46        So, if you have a all-zero MAC address or other reasons to better externally control the host id, just set this
47        environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
48        use fqdn@uniqueid.
49    BORG_LOGGING_CONF
50        When set, use the given filename as INI_-style logging configuration.
51        A basic example conf can be found at ``docs/misc/logging.conf``.
52    BORG_RSH
53        When set, use this command instead of ``ssh``. This can be used to specify ssh options, such as
54        a custom identity file ``ssh -i /path/to/private/key``. See ``man ssh`` for other options. Using
55        the ``--rsh CMD`` commandline option overrides the environment variable.
56    BORG_REMOTE_PATH
57        When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
58        Using ``--remote-path PATH`` commandline option overrides the environment variable.
59    BORG_FILES_CACHE_SUFFIX
60        When set to a value at least one character long, instructs borg to use a specifically named
61        (based on the suffix) alternative files cache. This can be used to avoid loading and saving
62        cache entries for backup sources other than the current sources.
63    BORG_FILES_CACHE_TTL
64        When set to a numeric value, this determines the maximum "time to live" for the files cache
65        entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
66        The FAQ explains this more detailed in: :ref:`always_chunking`
67    BORG_SHOW_SYSINFO
68        When set to no (default: yes), system information (like OS, Python version, ...) in
69        exceptions is not shown.
70        Please only use for good reasons as it makes issues harder to analyze.
71    BORG_LIBC
72        borg uses ``ctypes.util.find_library`` to locate the 'c' library (aka libc).
73        find_library needs a shell and will invoke some tools like ldconfig, gcc/cc or objdump.
74        If a shell or these tools are not available, you can give the name of your libc via
75        BORG_LIBC=libc.so.6 (for example) and borg will not try the ``find_library`` call.
76    BORG_SELFTEST
77        This can be used to influence borg's builtin self-tests. The default is to execute the tests
78        at the beginning of each borg command invocation.
79
80        BORG_SELFTEST=disabled can be used to switch off the tests and rather save some time.
81        Disabling is not recommended for normal borg users, but large scale borg storage providers can
82        use this to optimize production servers after at least doing a one-time test borg (with
83        selftests not disabled) when installing or upgrading machines / OS / borg.
84    BORG_WORKAROUNDS
85        A list of comma separated strings that trigger workarounds in borg,
86        e.g. to work around bugs in other software.
87
88        Currently known strings are:
89
90        basesyncfile
91            Use the more simple BaseSyncFile code to avoid issues with sync_file_range.
92            You might need this to run borg on WSL (Windows Subsystem for Linux) or
93            in systemd.nspawn containers on some architectures (e.g. ARM).
94            Using this does not affect data safety, but might result in a more bursty
95            write to disk behaviour (not continuously streaming to disk).
96
97Some automatic "answerers" (if set, they automatically answer confirmation questions):
98    BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
99        For "Warning: Attempting to access a previously unknown unencrypted repository"
100    BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
101        For "Warning: The repository at location ... was previously located at ..."
102    BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
103        For "This is a potentially dangerous function..." (check --repair)
104    BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
105        For "You requested to completely DELETE the repository *including* all archives it contains:"
106
107    Note: answers are case sensitive. setting an invalid answer value might either give the default
108    answer or ask you interactively, depending on whether retries are allowed (they by default are
109    allowed). So please test your scripts interactively before making them a non-interactive script.
110
111.. _XDG env var: https://specifications.freedesktop.org/basedir-spec/0.6/ar01s03.html
112
113Directories and files:
114    BORG_BASE_DIR
115        Defaults to ``$HOME`` or ``~$USER`` or ``~`` (in that order).
116        If you want to move all borg-specific folders to a custom path at once, all you need to do is
117        to modify ``BORG_BASE_DIR``: the other paths for cache, config etc. will adapt accordingly
118        (assuming you didn't set them to a different custom value).
119    BORG_CACHE_DIR
120        Defaults to ``$BORG_BASE_DIR/.cache/borg``. If ``BORG_BASE_DIR`` is not explicitly set while
121        `XDG env var`_ ``XDG_CACHE_HOME`` is set, then ``$XDG_CACHE_HOME/borg`` is being used instead.
122        This directory contains the local cache and might need a lot
123        of space for dealing with big repositories. Make sure you're aware of the associated
124        security aspects of the cache location: :ref:`cache_security`
125    BORG_CONFIG_DIR
126        Defaults to ``$BORG_BASE_DIR/.config/borg``. If ``BORG_BASE_DIR`` is not explicitly set while
127        `XDG env var`_ ``XDG_CONFIG_HOME`` is set, then ``$XDG_CONFIG_HOME/borg`` is being used instead.
128        This directory contains all borg configuration directories, see the FAQ
129        for a security advisory about the data in this directory: :ref:`home_config_borg`
130    BORG_SECURITY_DIR
131        Defaults to ``$BORG_CONFIG_DIR/security``.
132        This directory contains information borg uses to track its usage of NONCES ("numbers used
133        once" - usually in encryption context) and other security relevant data.
134    BORG_KEYS_DIR
135        Defaults to ``$BORG_CONFIG_DIR/keys``.
136        This directory contains keys for encrypted repositories.
137    BORG_KEY_FILE
138        When set, use the given filename as repository key file.
139    TMPDIR
140        This is where temporary files are stored (might need a lot of temporary space for some
141        operations), see tempfile_ for details.
142
143Building:
144    BORG_OPENSSL_PREFIX
145        Adds given OpenSSL header file directory to the default locations (setup.py).
146    BORG_LIBLZ4_PREFIX
147        Adds given prefix directory to the default locations. If a 'include/lz4.h' is found Borg
148        will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
149    BORG_LIBB2_PREFIX
150        Adds given prefix directory to the default locations. If a 'include/blake2.h' is found Borg
151        will be linked against the system libb2 instead of a bundled implementation. (setup.py)
152    BORG_LIBZSTD_PREFIX
153        Adds given prefix directory to the default locations. If a 'include/zstd.h' is found Borg
154        will be linked against the system libzstd instead of a bundled implementation. (setup.py)
155
156Please note:
157
158- Be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data's security/safety.
159- Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g.
160  mode 600, root:root).
161
162.. _INI: https://docs.python.org/3/library/logging.config.html#configuration-file-format
163
164.. _tempfile: https://docs.python.org/3/library/tempfile.html#tempfile.gettempdir
165