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