1BORG(1) Borg - Deduplicating Archiver BORG(1)
2
6 borg - BorgBackup is a deduplicating backup program with optional com‐
7 pression and authenticated encryption.
8
10 Borg consists of a number of commands. Each command accepts a number of
11 arguments and options and interprets various environment variables.
12 The following sections will describe each command in detail.
13 Commands, options, parameters, paths and such are set in fixed-width.
15 Option values are underlined. Borg has few options accepting a fixed
16 set of values (e.g. --encryption of borg_init). Experimental features
17 are marked with red stripes on the sides, like this paragraph.
18 Experimental features are not stable, which means that they may be
20 changed in incompatible ways or even removed entirely without prior no‐
21 tice in following releases.
22 Positional Arguments and Options: Order matters
24 Borg only supports taking options (-s and --progress in the example) to
25 the left or right of all positional arguments (repo::archive and path
26 in the example), but not in between them:
27 borg create -s --progress repo::archive path # good and preferred
29 borg create repo::archive path -s --progress # also works
30 borg create -s repo::archive path --progress # works, but ugly
31 borg create repo::archive -s --progress path # BAD
32 This is due to a problem in the argparse module:
34 https://bugs.python.org/issue15112
35 Repository URLs
37 Local filesystem (or locally mounted network filesystem):
38 /path/to/repo - filesystem path to repo directory, absolute path
40 path/to/repo - filesystem path to repo directory, relative path
42 Also, stuff like ~/path/to/repo or ~other/path/to/repo works (this is
44 expanded by your shell).
45 Note: you may also prepend a file:// to a filesystem path to get URL
47 style.
48 Remote repositories accessed via ssh user@host:
50 user@host:/path/to/repo - remote repo, absolute path
52 ssh://user@host:port/path/to/repo - same, alternative syntax, port can
54 be given
55 Remote repositories with relative paths can be given using this syntax:
57 user@host:path/to/repo - path relative to current directory
59 user@host:~/path/to/repo - path relative to user's home directory
61 user@host:~other/path/to/repo - path relative to other's home directory
63 Note: giving user@host:/./path/to/repo or user@host:/~/path/to/repo or
65 user@host:/~other/path/to/repo is also supported, but not required
66 here.
67 Remote repositories with relative paths, alternative syntax with port:
69 ssh://user@host:port/./path/to/repo - path relative to current direc‐
71 tory
72 ssh://user@host:port/~/path/to/repo - path relative to user's home di‐
74 rectory
75 ssh://user@host:port/~other/path/to/repo - path relative to other's
77 home directory
78 If you frequently need the same repo URL, it is a good idea to set the
80 BORG_REPO environment variable to set a default for the repo URL:
81 export BORG_REPO='ssh://user@host:port/path/to/repo'
83 Then just leave away the repo URL if only a repo URL is needed and you
85 want to use the default - it will be read from BORG_REPO then.
86 Use :: syntax to give the repo URL when syntax requires giving a posi‐
88 tional argument for the repo (e.g. borg mount :: /mnt).
89 Repository / Archive Locations
91 Many commands want either a repository (just give the repo URL, see
92 above) or an archive location, which is a repo URL followed by ::ar‐
93 chive_name.
94 Archive names must not contain the / (slash) character. For simplicity,
96 maybe also avoid blanks or other characters that have special meaning
97 on the shell or in a filesystem (borg mount will use the archive name
98 as directory name).
99 If you have set BORG_REPO (see above) and an archive location is
101 needed, use ::archive_name - the repo URL part is then read from
102 BORG_REPO.
103 Logging
105 Borg writes all log output to stderr by default. But please note that
106 something showing up on stderr does not indicate an error condition
107 just because it is on stderr. Please check the log levels of the mes‐
108 sages and the return code of borg for determining error, warning or
109 success conditions.
110 If you want to capture the log output to a file, just redirect it:
112 borg create repo::archive myfiles 2>> logfile
114 Custom logging configurations can be implemented via BORG_LOGGING_CONF.
116 The log level of the builtin logging configuration defaults to WARNING.
118 This is because we want Borg to be mostly silent and only output warn‐
119 ings, errors and critical messages, unless output has been requested by
120 supplying an option that implies output (e.g. --list or --progress).
121 Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
123 Use --debug to set DEBUG log level - to get debug, info, warning, error
125 and critical level output.
126 Use --info (or -v or --verbose) to set INFO log level - to get info,
128 warning, error and critical level output.
129 Use --warning (default) to set WARNING log level - to get warning, er‐
131 ror and critical level output.
132 Use --error to set ERROR log level - to get error and critical level
134 output.
135 Use --critical to set CRITICAL log level - to get critical level out‐
137 put.
138 While you can set misc. log levels, do not expect that every command
140 will give different output on different log levels - it's just a possi‐
141 bility.
142 WARNING:
144 Options --critical and --error are provided for completeness, their
145 usage is not recommended as you might miss important information.
146 Return codes
148 Borg can exit with the following return codes (rc):
149 ┌────────────┬────────────────────────────┐
151 │Return code │ Meaning │
152 ├────────────┼────────────────────────────┤
153 │0 │ success (logged as INFO) │
154 ├────────────┼────────────────────────────┤
155 │1 │ warning (operation reached │
156 │ │ its normal end, but there │
157 │ │ were warnings -- you │
158 │ │ should check the log, │
159 │ │ logged as WARNING) │
160 ├────────────┼────────────────────────────┤
161 │2 │ error (like a fatal error, │
162 │ │ a local or remote excep‐ │
163 │ │ tion, the operation did │
164 │ │ not reach its normal end, │
165 │ │ logged as ERROR) │
166 ├────────────┼────────────────────────────┤
167 │128+N │ killed by signal N (e.g. │
168 │ │ 137 == kill -9) │
169 └────────────┴────────────────────────────┘
170 If you use --show-rc, the return code is also logged at the indicated
172 level as the last log entry.
173 Environment Variables
175 Borg uses some environment variables for automation:
176 General:
178 BORG_REPO
180 When set, use the value to give the default repository
181 location. If a command needs an archive parameter, you
182 can abbreviate as ::archive. If a command needs a reposi‐
183 tory parameter, you can either leave it away or abbrevi‐
184 ate as ::, if a positional parameter is required.
185 BORG_PASSPHRASE
187 When set, use the value to answer the passphrase question
188 for encrypted repositories. It is used when a passphrase
189 is needed to access an encrypted repo as well as when a
190 new passphrase should be initially set when initializing
191 an encrypted repo. See also BORG_NEW_PASSPHRASE.
192 BORG_PASSCOMMAND
194 When set, use the standard output of the command (trail‐
195 ing newlines are stripped) to answer the passphrase ques‐
196 tion for encrypted repositories. It is used when a
197 passphrase is needed to access an encrypted repo as well
198 as when a new passphrase should be initially set when
199 initializing an encrypted repo. Note that the command is
200 executed without a shell. So variables, like $HOME will
201 work, but ~ won't. If BORG_PASSPHRASE is also set, it
202 takes precedence. See also BORG_NEW_PASSPHRASE.
203 BORG_PASSPHRASE_FD
205 When set, specifies a file descriptor to read a
206 passphrase from. Programs starting borg may choose to
207 open an anonymous pipe and use it to pass a passphrase.
208 This is safer than passing via BORG_PASSPHRASE, because
209 on some systems (e.g. Linux) environment can be examined
210 by other processes. If BORG_PASSPHRASE or BORG_PASSCOM‐
211 MAND are also set, they take precedence.
212 BORG_NEW_PASSPHRASE
214 When set, use the value to answer the passphrase question
215 when a new passphrase is asked for. This variable is
216 checked first. If it is not set, BORG_PASSPHRASE and
217 BORG_PASSCOMMAND will also be checked. Main usecase for
218 this is to fully automate borg change-passphrase.
219 BORG_DISPLAY_PASSPHRASE
221 When set, use the value to answer the "display the
222 passphrase for verification" question when defining a new
223 passphrase for encrypted repositories.
224 BORG_HOST_ID
226 Borg usually computes a host id from the FQDN plus the
227 results of uuid.getnode() (which usually returns a unique
228 id based on the MAC address of the network interface. Ex‐
229 cept if that MAC happens to be all-zero - in that case it
230 returns a random value, which is not what we want (be‐
231 cause it kills automatic stale lock removal). So, if you
232 have a all-zero MAC address or other reasons to better
233 externally control the host id, just set this environment
234 variable to a unique value. If all your FQDNs are unique,
235 you can just use the FQDN. If not, use fqdn@uniqueid.
236 BORG_LOGGING_CONF
238 When set, use the given filename as INI-style logging
239 configuration. A basic example conf can be found at
240 docs/misc/logging.conf.
241 BORG_RSH
243 When set, use this command instead of ssh. This can be
244 used to specify ssh options, such as a custom identity
245 file ssh -i /path/to/private/key. See man ssh for other
246 options. Using the --rsh CMD commandline option overrides
247 the environment variable.
248 BORG_REMOTE_PATH
250 When set, use the given path as borg executable on the
251 remote (defaults to "borg" if unset). Using --re‐
252 mote-path PATH commandline option overrides the environ‐
253 ment variable.
254 BORG_FILES_CACHE_SUFFIX
256 When set to a value at least one character long, in‐
257 structs borg to use a specifically named (based on the
258 suffix) alternative files cache. This can be used to
259 avoid loading and saving cache entries for backup sources
260 other than the current sources.
261 BORG_FILES_CACHE_TTL
263 When set to a numeric value, this determines the maximum
264 "time to live" for the files cache entries (default: 20).
265 The files cache is used to quickly determine whether a
266 file is unchanged. The FAQ explains this more detailed
267 in: always_chunking
268 BORG_SHOW_SYSINFO
270 When set to no (default: yes), system information (like
271 OS, Python version, ...) in exceptions is not shown.
272 Please only use for good reasons as it makes issues
273 harder to analyze.
274 BORG_FUSE_IMPL
276 Choose the lowlevel FUSE implementation borg shall use
277 for borg mount. This is a comma-separated list of imple‐
278 mentation names, they are tried in the given order, e.g.:
279 • pyfuse3,llfuse: default, first try to load pyfuse3,
281 then try to load llfuse.
282 • llfuse,pyfuse3: first try to load llfuse, then try to
284 load pyfuse3.
285 • pyfuse3: only try to load pyfuse3
287 • llfuse: only try to load llfuse
289 • none: do not try to load an implementation
291 BORG_SELFTEST
293 This can be used to influence borg's builtin self-tests.
294 The default is to execute the tests at the beginning of
295 each borg command invocation.
296 BORG_SELFTEST=disabled can be used to switch off the
298 tests and rather save some time. Disabling is not recom‐
299 mended for normal borg users, but large scale borg stor‐
300 age providers can use this to optimize production servers
301 after at least doing a one-time test borg (with selftests
302 not disabled) when installing or upgrading machines / OS
303 / borg.
304 BORG_WORKAROUNDS
306 A list of comma separated strings that trigger work‐
307 arounds in borg, e.g. to work around bugs in other soft‐
308 ware.
309 Currently known strings are:
311 basesyncfile
313 Use the more simple BaseSyncFile code to avoid is‐
314 sues with sync_file_range. You might need this to
315 run borg on WSL (Windows Subsystem for Linux) or
316 in systemd.nspawn containers on some architectures
317 (e.g. ARM). Using this does not affect data
318 safety, but might result in a more bursty write to
319 disk behaviour (not continuously streaming to
320 disk).
321 retry_erofs
323 Retry opening a file without O_NOATIME if opening
324 a file with O_NOATIME caused EROFS. You will need
325 this to make archives from volume shadow copies in
326 WSL1 (Windows Subsystem for Linux 1).
327 Some automatic answerers (if set, they automatically answer confirma‐
329 tion questions):
330 BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
332 For "Warning: Attempting to access a previously unknown
333 unencrypted repository"
334 BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
336 For "Warning: The repository at location ... was previ‐
337 ously located at ..."
338 BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
340 For "This is a potentially dangerous function..." (check
341 --repair)
342 BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
344 For "You requested to completely DELETE the repository
345 including all archives it contains:"
346 Note: answers are case sensitive. setting an invalid answer
348 value might either give the default answer or ask you interac‐
349 tively, depending on whether retries are allowed (they by de‐
350 fault are allowed). So please test your scripts interactively
351 before making them a non-interactive script.
352 Directories and files:
354 BORG_BASE_DIR
356 Defaults to $HOME or ~$USER or ~ (in that order). If you
357 want to move all borg-specific folders to a custom path
358 at once, all you need to do is to modify BORG_BASE_DIR:
359 the other paths for cache, config etc. will adapt accord‐
360 ingly (assuming you didn't set them to a different custom
361 value).
362 BORG_CACHE_DIR
364 Defaults to $BORG_BASE_DIR/.cache/borg. If BORG_BASE_DIR
365 is not explicitly set while XDG env var XDG_CACHE_HOME is
366 set, then $XDG_CACHE_HOME/borg is being used instead.
367 This directory contains the local cache and might need a
368 lot of space for dealing with big repositories. Make sure
369 you're aware of the associated security aspects of the
370 cache location: cache_security
371 BORG_CONFIG_DIR
373 Defaults to $BORG_BASE_DIR/.config/borg. If BORG_BASE_DIR
374 is not explicitly set while XDG env var XDG_CONFIG_HOME
375 is set, then $XDG_CONFIG_HOME/borg is being used instead.
376 This directory contains all borg configuration directo‐
377 ries, see the FAQ for a security advisory about the data
378 in this directory: home_config_borg
379 BORG_SECURITY_DIR
381 Defaults to $BORG_CONFIG_DIR/security. This directory
382 contains information borg uses to track its usage of
383 NONCES ("numbers used once" - usually in encryption con‐
384 text) and other security relevant data.
385 BORG_KEYS_DIR
387 Defaults to $BORG_CONFIG_DIR/keys. This directory con‐
388 tains keys for encrypted repositories.
389 BORG_KEY_FILE
391 When set, use the given filename as repository key file.
392 TMPDIR This is where temporary files are stored (might need a
394 lot of temporary space for some operations), see tempfile
395 for details.
396 Building:
398 BORG_OPENSSL_PREFIX
400 Adds given OpenSSL header file directory to the default
401 locations (setup.py).
402 BORG_LIBLZ4_PREFIX
404 Adds given prefix directory to the default locations. If
405 a 'include/lz4.h' is found Borg will be linked against
406 the system liblz4 instead of a bundled implementation.
407 (setup.py)
408 BORG_LIBB2_PREFIX
410 Adds given prefix directory to the default locations. If
411 a 'include/blake2.h' is found Borg will be linked against
412 the system libb2 instead of a bundled implementation.
413 (setup.py)
414 BORG_LIBZSTD_PREFIX
416 Adds given prefix directory to the default locations. If
417 a 'include/zstd.h' is found Borg will be linked against
418 the system libzstd instead of a bundled implementation.
419 (setup.py)
420 Please note:
422 • Be very careful when using the "yes" sayers, the warnings with prompt
424 exist for your / your data's security/safety.
425 • Also be very careful when putting your passphrase into a script, make
427 sure it has appropriate file permissions (e.g. mode 600, root:root).
428 File systems
430 We strongly recommend against using Borg (or any other database-like
431 software) on non-journaling file systems like FAT, since it is not pos‐
432 sible to assume any consistency in case of power failures (or a sudden
433 disconnect of an external drive or similar failures).
434 While Borg uses a data store that is resilient against these failures
436 when used on journaling file systems, it is not possible to guarantee
437 this with some hardware -- independent of the software used. We don't
438 know a list of affected hardware.
439 If you are suspicious whether your Borg repository is still consistent
441 and readable after one of the failures mentioned above occurred, run
442 borg check --verify-data to make sure it is consistent.
443 Requirements for Borg repository file systems
445 • Long file names
447 • At least three directory levels with short names
449 • Typically, file sizes up to a few hundred MB. Large repositories may
451 require large files (>2 GB).
452 • Up to 1000 files per directory (10000 for repositories initialized
454 with Borg 1.0)
455 • rename(2) / MoveFile(Ex) should work as specified, i.e. on the same
457 file system it should be a move (not a copy) operation, and in case
458 of a directory it should fail if the destination exists and is not an
459 empty directory, since this is used for locking.
460 • Hardlinks are needed for borg_upgrade (if --inplace option is not
462 used). Also hardlinks are used for more safe and secure file updat‐
463 ing (e.g. of the repo config file), but the code tries to work also
464 if hardlinks are not supported.
465 Units
467 To display quantities, Borg takes care of respecting the usual conven‐
468 tions of scale. Disk sizes are displayed in decimal, using powers of
469 ten (so kB means 1000 bytes). For memory usage, binary prefixes are
470 used, and are indicated using the IEC binary prefixes, using powers of
471 two (so KiB means 1024 bytes).
472 Date and Time
474 We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and
475 HH:MM:SS (24h clock).
476 For more information about that, see: https://xkcd.com/1179/
478 Unless otherwise noted, we display local date and time. Internally, we
480 store and process date and time as UTC.
481 Resource Usage
483 Borg might use a lot of resources depending on the size of the data set
484 it is dealing with.
485 If one uses Borg in a client/server way (with a ssh: repository), the
487 resource usage occurs in part on the client and in another part on the
488 server.
489 If one uses Borg as a single process (with a filesystem repo), all the
491 resource usage occurs in that one process, so just add up client +
492 server to get the approximate resource usage.
493 CPU client:
495 • borg create: does chunking, hashing, compression, crypto (high
497 CPU usage)
498 • chunks cache sync: quite heavy on CPU, doing lots of hashtable
500 operations.
501 • borg extract: crypto, decompression (medium to high CPU usage)
503 • borg check: similar to extract, but depends on options given.
505 • borg prune / borg delete archive: low to medium CPU usage
507 • borg delete repo: done on the server
509 It won't go beyond 100% of 1 core as the code is currently sin‐
511 gle-threaded. Especially higher zlib and lzma compression lev‐
512 els use significant amounts of CPU cycles. Crypto might be cheap
513 on the CPU (if hardware accelerated) or expensive (if not).
514 CPU server:
516 It usually doesn't need much CPU, it just deals with the
517 key/value store (repository) and uses the repository index for
518 that.
519 borg check: the repository check computes the checksums of all
521 chunks (medium CPU usage) borg delete repo: low CPU usage
522 CPU (only for client/server operation):
524 When using borg in a client/server way with a ssh:-type repo,
525 the ssh processes used for the transport layer will need some
526 CPU on the client and on the server due to the crypto they are
527 doing - esp. if you are pumping big amounts of data.
528 Memory (RAM) client:
530 The chunks index and the files index are read into memory for
531 performance reasons. Might need big amounts of memory (see be‐
532 low). Compression, esp. lzma compression with high levels might
533 need substantial amounts of memory.
534 Memory (RAM) server:
536 The server process will load the repository index into memory.
537 Might need considerable amounts of memory, but less than on the
538 client (see below).
539 Chunks index (client only):
541 Proportional to the amount of data chunks in your repo. Lots of
542 chunks in your repo imply a big chunks index. It is possible to
543 tweak the chunker params (see create options).
544 Files index (client only):
546 Proportional to the amount of files in your last backups. Can be
547 switched off (see create options), but next backup might be much
548 slower if you do. The speed benefit of using the files cache is
549 proportional to file size.
550 Repository index (server only):
552 Proportional to the amount of data chunks in your repo. Lots of
553 chunks in your repo imply a big repository index. It is possi‐
554 ble to tweak the chunker params (see create options) to influ‐
555 ence the amount of chunks being created.
556 Temporary files (client):
558 Reading data and metadata from a FUSE mounted repository will
559 consume up to the size of all deduplicated, small chunks in the
560 repository. Big chunks won't be locally cached.
561 Temporary files (server):
563 A non-trivial amount of data will be stored on the remote temp
564 directory for each client that connects to it. For some remotes,
565 this can fill the default temporary directory at /tmp. This can
566 be remediated by ensuring the $TMPDIR, $TEMP, or $TMP environ‐
567 ment variable is properly set for the sshd process. For some
568 OSes, this can be done just by setting the correct value in the
569 .bashrc (or equivalent login config file for other shells), how‐
570 ever in other cases it may be necessary to first enable Permi‐
571 tUserEnvironment yes in your sshd_config file, then add environ‐
572 ment="TMPDIR=/my/big/tmpdir" at the start of the public key to
573 be used in the authorized_hosts file.
574 Cache files (client only):
576 Contains the chunks index and files index (plus a collection of
577 single- archive chunk indexes which might need huge amounts of
578 disk space, depending on archive count and size - see FAQ about
579 how to reduce).
580 Network (only for client/server operation):
582 If your repository is remote, all deduplicated (and optionally
583 compressed/ encrypted) data of course has to go over the connec‐
584 tion (ssh:// repo url). If you use a locally mounted network
585 filesystem, additionally some copy operations used for transac‐
586 tion support also go over the connection. If you backup multiple
587 sources to one target repository, additional traffic happens for
588 cache resynchronization.
589 Support for file metadata
591 Besides regular file and directory structures, Borg can preserve
592 • symlinks (stored as symlink, the symlink is not followed)
594 • special files:
596 • character and block device files (restored via mknod)
598 • FIFOs ("named pipes")
600 • special file contents can be backed up in --read-special mode. By
602 default the metadata to create them with mknod(2), mkfifo(2) etc.
603 is stored.
604 • hardlinked regular files, devices, FIFOs (considering all items in
606 the same archive)
607 • timestamps in nanosecond precision: mtime, atime, ctime
609 • other timestamps: birthtime (on platforms supporting it)
611 • permissions:
613 • IDs of owning user and owning group
615 • names of owning user and owning group (if the IDs can be resolved)
617 • Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky)
619 On some platforms additional features are supported:
621 ┌─────────────────┬──────────┬───────────┬───────────┐
623 │Platform │ ACLs [5] │ xattr [6] │ Flags [7] │
624 ├─────────────────┼──────────┼───────────┼───────────┤
625 │Linux │ Yes │ Yes │ Yes [1] │
626 ├─────────────────┼──────────┼───────────┼───────────┤
627 │Mac OS X │ Yes │ Yes │ Yes (all) │
628 ├─────────────────┼──────────┼───────────┼───────────┤
629 │FreeBSD │ Yes │ Yes │ Yes (all) │
630 ├─────────────────┼──────────┼───────────┼───────────┤
631 │OpenBSD │ n/a │ n/a │ Yes (all) │
632 ├─────────────────┼──────────┼───────────┼───────────┤
633 │NetBSD │ n/a │ No [2] │ Yes (all) │
634 ├─────────────────┼──────────┼───────────┼───────────┤
635 │Solaris and de‐ │ No [3] │ No [3] │ n/a │
636 │rivatives │ │ │ │
637 ├─────────────────┼──────────┼───────────┼───────────┤
638 │Windows (cygwin) │ No [4] │ No │ No │
639 └─────────────────┴──────────┴───────────┴───────────┘
640 Other Unix-like operating systems may work as well, but have not been
642 tested at all.
643 Note that most of the platform-dependent features also depend on the
645 file system. For example, ntfs-3g on Linux isn't able to convey NTFS
646 ACLs.
647 [1] Only "nodump", "immutable", "compressed" and "append" are sup‐
649 ported. Feature request #618 for more flags.
650 [2] Feature request #1332
652 [3] Feature request #1337
654 [4] Cygwin tries to map NTFS ACLs to permissions with varying degrees
656 of success.
657 [5] The native access control list mechanism of the OS. This normally
659 limits access to non-native ACLs. For example, NTFS ACLs aren't
660 completely accessible on Linux with ntfs-3g.
661 [6] extended attributes; key-value pairs attached to a file, mainly
663 used by the OS. This includes resource forks on Mac OS X.
664 [7] aka BSD flags. The Linux set of flags [1] is portable across plat‐
666 forms. The BSDs define additional flags.
667 In case you are interested in more details (like formulas), please
669 see internals. For details on the available JSON output, refer to
670 json_output.
671 Common options
673 All Borg commands share these options:
674 -h, --help
676 show this help message and exit
677 --critical
679 work on log level CRITICAL
680 --error
682 work on log level ERROR
683 --warning
685 work on log level WARNING (default)
686 --info, -v, --verbose
688 work on log level INFO
689 --debug
691 enable debug output, work on log level DEBUG
692 --debug-topic TOPIC
694 enable TOPIC debugging (can be specified multiple times). The
695 logger path is borg.debug.<TOPIC> if TOPIC is not fully quali‐
696 fied.
697 -p, --progress
699 show progress information
700 --iec format using IEC units (1KiB = 1024B)
702 --log-json
704 Output one JSON object per log line instead of formatted text.
705 --lock-wait SECONDS
707 wait at most SECONDS for acquiring a repository/cache lock (de‐
708 fault: 1).
709 --bypass-lock
711 Bypass locking mechanism
712 --show-version
714 show/log the borg version
715 --show-rc
717 show/log the return code (rc)
718 --umask M
720 set umask to M (local only, default: 0077)
721 --remote-path PATH
723 use PATH as borg executable on the remote (default: "borg")
724 --remote-ratelimit RATE
726 deprecated, use --upload-ratelimit instead
727 --upload-ratelimit RATE
729 set network upload rate limit in kiByte/s (default: 0=unlimited)
730 --remote-buffer UPLOAD_BUFFER
732 deprecated, use --upload-buffer instead
733 --upload-buffer UPLOAD_BUFFER
735 set network upload buffer size in MiB. (default: 0=no buffer)
736 --consider-part-files
738 treat part files like normal files (e.g. to list/extract them)
739 --debug-profile FILE
741 Write execution profile in Borg format into FILE. For local use
742 a Python-compatible file can be generated by suffixing FILE with
743 ".pyprof".
744 --rsh RSH
746 Use this command to connect to the 'borg serve' process (de‐
747 fault: 'ssh')
748 Option --bypass-lock allows you to access the repository while bypass‐
750 ing borg's locking mechanism. This is necessary if your repository is
751 on a read-only storage where you don't have write permissions or capa‐
752 bilities and therefore cannot create a lock. Examples are repositories
753 stored on a Bluray disc or a read-only network storage. Avoid this op‐
754 tion if you are able to use locks as that is the safer way; see the
755 warning below.
756 WARNING:
758 If you do use --bypass-lock, you are responsible to ensure that no
759 other borg instances have write access to the repository. Otherwise,
760 you might experience errors and read broken data if changes to that
761 repository are being made at the same time.
762 Examples
764 # Create an archive and log: borg version, files list, return code
765 $ borg create --show-version --list --show-rc /path/to/repo::my-files files
766
768 borg [common options] init [options] [REPOSITORY]
769 Description
771 This command initializes an empty repository. A repository is a
772 filesystem directory containing the deduplicated data from zero or more
773 archives.
774 Encryption mode TLDR
776 The encryption mode can only be configured when creating a new reposi‐
777 tory - you can neither configure it on a per-archive basis nor change
778 the encryption mode of an existing repository.
779 Use repokey:
781 borg init --encryption repokey /path/to/repo
783 Or repokey-blake2 depending on which is faster on your client machines
785 (see below):
786 borg init --encryption repokey-blake2 /path/to/repo
788 Borg will:
790 1. Ask you to come up with a passphrase.
792 2. Create a borg key (which contains 3 random secrets. See key_files).
794 3. Encrypt the key with your passphrase.
796 4. Store the encrypted borg key inside the repository directory (in the
798 repo config). This is why it is essential to use a secure
799 passphrase.
800 5. Encrypt and sign your backups to prevent anyone from reading or
802 forging them unless they have the key and know the passphrase. Make
803 sure to keep a backup of your key outside the repository - do not
804 lock yourself out by "leaving your keys inside your car" (see
805 borg_key_export). For remote backups the encryption is done locally
806 - the remote machine never sees your passphrase, your unencrypted
807 key or your unencrypted files. Chunking and id generation are also
808 based on your key to improve your privacy.
809 6. Use the key when extracting files to decrypt them and to verify that
811 the contents of the backups have not been accidentally or mali‐
812 ciously altered.
813 Picking a passphrase
815 Make sure you use a good passphrase. Not too short, not too simple. The
816 real encryption / decryption key is encrypted with / locked by your
817 passphrase. If an attacker gets your key, he can't unlock and use it
818 without knowing the passphrase.
819 Be careful with special or non-ascii characters in your passphrase:
821 • Borg processes the passphrase as unicode (and encodes it as utf-8),
823 so it does not have problems dealing with even the strangest charac‐
824 ters.
825 • BUT: that does not necessarily apply to your OS / VM / keyboard con‐
827 figuration.
828 So better use a long passphrase made from simple ascii chars than one
830 that includes non-ascii stuff or characters that are hard/impossible to
831 enter on a different keyboard layout.
832 You can change your passphrase for existing repos at any time, it won't
834 affect the encryption/decryption key or other secrets.
835 More encryption modes
837 Only use --encryption none if you are OK with anyone who has access to
838 your repository being able to read your backups and tamper with their
839 contents without you noticing.
840 If you want "passphrase and having-the-key" security, use --encryption
842 keyfile. The key will be stored in your home directory (in ~/.con‐
843 fig/borg/keys).
844 If you do not want to encrypt the contents of your backups, but still
846 want to detect malicious tampering use --encryption authenticated.
847 If BLAKE2b is faster than SHA-256 on your hardware, use --encryption
849 authenticated-blake2, --encryption repokey-blake2 or --encryption key‐
850 file-blake2. Note: for remote backups the hashing is done on your local
851 machine.
852 ┌─────────┬──────────────────┬──────────────────┬──────────────────┐
854 │Hash/MAC │ Not encrypted no │ Not encrypted, │ Encrypted (AEAD │
855 │ │ auth │ but authenti‐ │ w/ AES) and au‐ │
856 │ │ │ cated │ thenticated │
857 ├─────────┼──────────────────┼──────────────────┼──────────────────┤
858 │SHA-256 │ none │ authenticated │ repokey keyfile │
859 └─────────┴──────────────────┴──────────────────┴──────────────────┘
860 │BLAKE2b │ n/a │ authenti‐ │ repokey-blake2 │
863 │ │ │ cated-blake2 │ keyfile-blake2 │
864 └─────────┴──────────────────┴──────────────────┴──────────────────┘
865 Modes marked like this in the above table are new in Borg 1.1 and are
867 not backwards-compatible with Borg 1.0.x.
868 On modern Intel/AMD CPUs (except very cheap ones), AES is usually hard‐
870 ware-accelerated. BLAKE2b is faster than SHA256 on Intel/AMD 64-bit
871 CPUs (except AMD Ryzen and future CPUs with SHA extensions), which
872 makes authenticated-blake2 faster than none and authenticated.
873 On modern ARM CPUs, NEON provides hardware acceleration for SHA256 mak‐
875 ing it faster than BLAKE2b-256 there. NEON accelerates AES as well.
876 Hardware acceleration is always used automatically when available.
878 repokey and keyfile use AES-CTR-256 for encryption and HMAC-SHA256 for
880 authentication in an encrypt-then-MAC (EtM) construction. The chunk ID
881 hash is HMAC-SHA256 as well (with a separate key). These modes are
882 compatible with Borg 1.0.x.
883 repokey-blake2 and keyfile-blake2 are also authenticated encryption
885 modes, but use BLAKE2b-256 instead of HMAC-SHA256 for authentication.
886 The chunk ID hash is a keyed BLAKE2b-256 hash. These modes are new and
887 not compatible with Borg 1.0.x.
888 authenticated mode uses no encryption, but authenticates repository
890 contents through the same HMAC-SHA256 hash as the repokey and keyfile
891 modes (it uses it as the chunk ID hash). The key is stored like re‐
892 pokey. This mode is new and not compatible with Borg 1.0.x.
893 authenticated-blake2 is like authenticated, but uses the keyed
895 BLAKE2b-256 hash from the other blake2 modes. This mode is new and not
896 compatible with Borg 1.0.x.
897 none mode uses no encryption and no authentication. It uses SHA256 as
899 chunk ID hash. This mode is not recommended, you should rather consider
900 using an authenticated or authenticated/encrypted mode. This mode has
901 possible denial-of-service issues when running borg create on contents
902 controlled by an attacker. Use it only for new repositories where no
903 encryption is wanted and when compatibility with 1.0.x is important. If
904 compatibility with 1.0.x is not important, use authenticated-blake2 or
905 authenticated instead. This mode is compatible with Borg 1.0.x.
906 Examples
908 # Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
909 $ borg init --encryption=repokey-blake2 /path/to/repo
910 # Local repository (no encryption)
912 $ borg init --encryption=none /path/to/repo
913 # Remote repository (accesses a remote borg via ssh)
915 # repokey: stores the (encrypted) key into <REPO_DIR>/config
916 $ borg init --encryption=repokey-blake2 user@hostname:backup
917 # Remote repository (accesses a remote borg via ssh)
919 # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
920 $ borg init --encryption=keyfile user@hostname:backup
921
923 borg [common options] create [options] ARCHIVE [PATH...]
924 Description
926 This command creates a backup archive containing all files found while
927 recursively traversing all paths specified. Paths are added to the ar‐
928 chive as they are given, that means if relative paths are desired, the
929 command has to be run from the correct directory.
930 When giving '-' as path, borg will read data from standard input and
932 create a file 'stdin' in the created archive from that data. In some
933 cases it's more appropriate to use --content-from-command, however. See
934 section Reading from stdin below for details.
935 The archive will consume almost no disk space for files or parts of
937 files that have already been stored in other archives.
938 The archive name needs to be unique. It must not end in '.checkpoint'
940 or '.checkpoint.N' (with N being a number), because these names are
941 used for checkpoints and treated in special ways.
942 In the archive name, you may use the following placeholders: {now},
944 {utcnow}, {fqdn}, {hostname}, {user} and some others.
945 Backup speed is increased by not reprocessing files that are already
947 part of existing archives and weren't modified. The detection of unmod‐
948 ified files is done by comparing multiple file metadata values with
949 previous values kept in the files cache.
950 This comparison can operate in different modes as given by
952 --files-cache:
953 • ctime,size,inode (default)
955 • mtime,size,inode (default behaviour of borg versions older than
957 1.1.0rc4)
958 • ctime,size (ignore the inode number)
960 • mtime,size (ignore the inode number)
962 • rechunk,ctime (all files are considered modified - rechunk, cache
964 ctime)
965 • rechunk,mtime (all files are considered modified - rechunk, cache
967 mtime)
968 • disabled (disable the files cache, all files considered modified -
970 rechunk)
971 inode number: better safety, but often unstable on network filesystems
973 Normally, detecting file modifications will take inode information into
975 consideration to improve the reliability of file change detection.
976 This is problematic for files located on sshfs and similar network file
977 systems which do not provide stable inode numbers, such files will al‐
978 ways be considered modified. You can use modes without inode in this
979 case to improve performance, but reliability of change detection might
980 be reduced.
981 ctime vs. mtime: safety vs. speed
983 • ctime is a rather safe way to detect changes to a file (metadata and
985 contents) as it can not be set from userspace. But, a metadata-only
986 change will already update the ctime, so there might be some unneces‐
987 sary chunking/hashing even without content changes. Some filesystems
988 do not support ctime (change time). E.g. doing a chown or chmod to a
989 file will change its ctime.
990 • mtime usually works and only updates if file contents were changed.
992 But mtime can be arbitrarily set from userspace, e.g. to set mtime
993 back to the same value it had before a content change happened. This
994 can be used maliciously as well as well-meant, but in both cases
995 mtime based cache modes can be problematic.
996 The mount points of filesystems or filesystem snapshots should be the
998 same for every creation of a new archive to ensure fast operation. This
999 is because the file cache that is used to determine changed files
1000 quickly uses absolute filenames. If this is not possible, consider
1001 creating a bind mount to a stable location.
1002 The --progress option shows (from left to right) Original, Compressed
1004 and Deduplicated (O, C and D, respectively), then the Number of files
1005 (N) processed so far, followed by the currently processed path.
1006 When using --stats, you will get some statistics about how much data
1008 was added - the "This Archive" deduplicated size there is most inter‐
1009 esting as that is how much your repository will grow. Please note that
1010 the "All archives" stats refer to the state after creation. Also, the
1011 --stats and --dry-run options are mutually exclusive because the data
1012 is not actually compressed and deduplicated during a dry run.
1013 For more help on include/exclude patterns, see the borg_patterns com‐
1015 mand output.
1016 For more help on placeholders, see the borg_placeholders command out‐
1018 put.
1019 The --exclude patterns are not like tar. In tar --exclude .bundler/gems
1021 will exclude foo/.bundler/gems. In borg it will not, you need to use
1022 --exclude '*/.bundler/gems' to get the same effect.
1023 In addition to using --exclude patterns, it is possible to use --ex‐
1025 clude-if-present to specify the name of a filesystem object (e.g. a
1026 file or folder name) which, when contained within another folder, will
1027 prevent the containing folder from being backed up. By default, the
1028 containing folder and all of its contents will be omitted from the
1029 backup. If, however, you wish to only include the objects specified by
1030 --exclude-if-present in your backup, and not include any other contents
1031 of the containing folder, this can be enabled through using the
1032 --keep-exclude-tags option.
1033 The -x or --one-file-system option excludes directories, that are
1035 mountpoints (and everything in them). It detects mountpoints by com‐
1036 paring the device number from the output of stat() of the directory and
1037 its parent directory. Specifically, it excludes directories for which
1038 stat() reports a device number different from the device number of
1039 their parent. Be aware that in Linux (and possibly elsewhere) there are
1040 directories with device number different from their parent, which the
1041 kernel does not consider a mountpoint and also the other way around.
1042 Examples are bind mounts (possibly same device number, but always a
1043 mountpoint) and ALL subvolumes of a btrfs (different device number from
1044 parent but not necessarily a mountpoint). Therefore when using
1045 --one-file-system, one should make doubly sure that the backup works as
1046 intended especially when using btrfs. This is even more important, if
1047 the btrfs layout was created by someone else, e.g. a distribution in‐
1048 staller.
1049 Item flags
1051 --list outputs a list of all files, directories and other file system
1052 items it considered (no matter whether they had content changes or
1053 not). For each item, it prefixes a single-letter flag that indicates
1054 type and/or status of the item.
1055 If you are interested only in a subset of that output, you can give
1057 e.g. --filter=AME and it will only show regular files with A, M or E
1058 status (see below).
1059 A uppercase character represents the status of a regular file relative
1061 to the "files" cache (not relative to the repo -- this is an issue if
1062 the files cache is not used). Metadata is stored in any case and for
1063 'A' and 'M' also new data chunks are stored. For 'U' all data chunks
1064 refer to already existing chunks.
1065 • 'A' = regular file, added (see also a_status_oddity in the FAQ)
1067 • 'M' = regular file, modified
1069 • 'U' = regular file, unchanged
1071 • 'C' = regular file, it changed while we backed it up
1073 • 'E' = regular file, an error happened while accessing/reading this
1075 file
1076 A lowercase character means a file type other than a regular file, borg
1078 usually just stores their metadata:
1079 • 'd' = directory
1081 • 'b' = block device
1083 • 'c' = char device
1085 • 'h' = regular file, hardlink (to already seen inodes)
1087 • 's' = symlink
1089 • 'f' = fifo
1091 Other flags used include:
1093 • 'i' = backup data was read from standard input (stdin)
1095 • '-' = dry run, item was not backed up
1097 • 'x' = excluded, item was not backed up
1099 • '?' = missing status code (if you see this, please file a bug re‐
1101 port!)
1102 Reading from stdin
1104 There are two methods to read from stdin. Either specify - as path and
1105 pipe directly to borg:
1106 backup-vm --id myvm --stdout | borg create REPO::ARCHIVE -
1108 Or use --content-from-command to have Borg manage the execution of the
1110 command and piping. If you do so, the first PATH argument is inter‐
1111 preted as command to execute and any further arguments are treated as
1112 arguments to the command:
1113 borg create --content-from-command REPO::ARCHIVE -- backup-vm --id myvm --stdout
1115 -- is used to ensure --id and --stdout are not considered arguments to
1117 borg but rather backup-vm.
1118 The difference between the two approaches is that piping to borg cre‐
1120 ates an archive even if the command piping to borg exits with a fail‐
1121 ure. In this case, one can end up with truncated output being backed
1122 up. Using --content-from-command, in contrast, borg is guaranteed to
1123 fail without creating an archive should the command fail. The command
1124 is considered failed when it returned a non-zero exit code.
1125 Reading from stdin yields just a stream of data without file metadata
1127 associated with it, and the files cache is not needed at all. So it is
1128 safe to disable it via --files-cache disabled and speed up backup cre‐
1129 ation a bit.
1130 By default, the content read from stdin is stored in a file called
1132 'stdin'. Use --stdin-name to change the name.
1133 Examples
1135 # Backup ~/Documents into an archive named "my-documents"
1136 $ borg create /path/to/repo::my-documents ~/Documents
1137 # same, but list all files as we process them
1139 $ borg create --list /path/to/repo::my-documents ~/Documents
1140 # Backup ~/Documents and ~/src but exclude pyc files
1142 $ borg create /path/to/repo::my-files \
1143 ~/Documents \
1144 ~/src \
1145 --exclude '*.pyc'
1146 # Backup home directories excluding image thumbnails (i.e. only
1148 # /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
1149 $ borg create /path/to/repo::my-files /home \
1150 --exclude 'sh:home/*/.thumbnails'
1151 # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
1153 # use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio)
1154 $ borg create -C zlib,6 --one-file-system /path/to/repo::root-{now:%Y-%m-%d} /
1155 # Backup onto a remote host ("push" style) via ssh to port 2222,
1157 # logging in as user "borg" and storing into /path/to/repo
1158 $ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}-root-{now} /
1159 # Backup a remote host locally ("pull" style) using sshfs
1161 $ mkdir sshfs-mount
1162 $ sshfs root@example.com:/ sshfs-mount
1163 $ cd sshfs-mount
1164 $ borg create /path/to/repo::example.com-root-{now:%Y-%m-%d} .
1165 $ cd ..
1166 $ fusermount -u sshfs-mount
1167 # Make a big effort in fine granular deduplication (big chunk management
1169 # overhead, needs a lot of RAM and disk space, see formula in internals
1170 # docs - same parameters as borg < 1.0 or attic):
1171 $ borg create --chunker-params buzhash,10,23,16,4095 /path/to/repo::small /smallstuff
1172 # Backup a raw device (must not be active/in use/mounted at that time)
1174 $ borg create --read-special --chunker-params fixed,4194304 /path/to/repo::my-sdx /dev/sdX
1175 # Backup a sparse disk image (must not be active/in use/mounted at that time)
1177 $ borg create --sparse --chunker-params fixed,4194304 /path/to/repo::my-disk my-disk.raw
1178 # No compression (none)
1180 $ borg create --compression none /path/to/repo::arch ~
1181 # Super fast, low compression (lz4, default)
1183 $ borg create /path/to/repo::arch ~
1184 # Less fast, higher compression (zlib, N = 0..9)
1186 $ borg create --compression zlib,N /path/to/repo::arch ~
1187 # Even slower, even higher compression (lzma, N = 0..9)
1189 $ borg create --compression lzma,N /path/to/repo::arch ~
1190 # Only compress compressible data with lzma,N (N = 0..9)
1192 $ borg create --compression auto,lzma,N /path/to/repo::arch ~
1193 # Use short hostname, user name and current time in archive name
1195 $ borg create /path/to/repo::{hostname}-{user}-{now} ~
1196 # Similar, use the same datetime format that is default as of borg 1.1
1197 $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S} ~
1198 # As above, but add nanoseconds
1199 $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S.%f} ~
1200 # Backing up relative paths by moving into the correct directory first
1202 $ cd /home/user/Documents
1203 # The root directory of the archive will be "projectA"
1204 $ borg create /path/to/repo::daily-projectA-{now:%Y-%m-%d} projectA
1205 # Use external command to determine files to archive
1207 # Use --paths-from-stdin with find to only backup files less than 1MB in size
1208 $ find ~ -size -1000k | borg create --paths-from-stdin /path/to/repo::small-files-only
1209 # Use --paths-from-command with find to only backup files from a given user
1210 $ borg create --paths-from-command /path/to/repo::joes-files -- find /srv/samba/shared -user joe
1211 # Use --paths-from-stdin with --paths-delimiter (for example, for filenames with newlines in them)
1212 $ find ~ -size -1000k -print0 | borg create \
1213 --paths-from-stdin \
1214 --paths-delimiter "\0" \
1215 /path/to/repo::smallfiles-handle-newline
1216
1218 borg [common options] extract [options] ARCHIVE [PATH...]
1219 Description
1221 This command extracts the contents of an archive. By default the entire
1222 archive is extracted but a subset of files and directories can be se‐
1223 lected by passing a list of PATHs as arguments. The file selection can
1224 further be restricted by using the --exclude option.
1225 For more help on include/exclude patterns, see the borg_patterns com‐
1227 mand output.
1228 By using --dry-run, you can do all extraction steps except actually
1230 writing the output data: reading metadata and data chunks from the
1231 repo, checking the hash/hmac, decrypting, decompressing.
1232 --progress can be slower than no progress display, since it makes one
1234 additional pass over the archive metadata.
1235 NOTE:
1237 Currently, extract always writes into the current working directory
1238 ("."), so make sure you cd to the right place before calling borg
1239 extract.
1240 When parent directories are not extracted (because of using file/di‐
1242 rectory selection or any other reason), borg can not restore parent
1243 directories' metadata, e.g. owner, group, permission, etc.
1244 Examples
1246 # Extract entire archive
1247 $ borg extract /path/to/repo::my-files
1248 # Extract entire archive and list files while processing
1250 $ borg extract --list /path/to/repo::my-files
1251 # Verify whether an archive could be successfully extracted, but do not write files to disk
1253 $ borg extract --dry-run /path/to/repo::my-files
1254 # Extract the "src" directory
1256 $ borg extract /path/to/repo::my-files home/USERNAME/src
1257 # Extract the "src" directory but exclude object files
1259 $ borg extract /path/to/repo::my-files home/USERNAME/src --exclude '*.o'
1260 # Restore a raw device (must not be active/in use/mounted at that time)
1262 $ borg extract --stdout /path/to/repo::my-sdx | dd of=/dev/sdx bs=10M
1263
1265 borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
1266 Description
1268 The check command verifies the consistency of a repository and the cor‐
1269 responding archives.
1270 check --repair is a potentially dangerous function and might lead to
1272 data loss (for kinds of corruption it is not capable of dealing with).
1273 BE VERY CAREFUL!
1274 Pursuant to the previous warning it is also highly recommended to test
1276 the reliability of the hardware running this software with stress test‐
1277 ing software such as memory testers. Unreliable hardware can also lead
1278 to data loss especially when this command is run in repair mode.
1279 First, the underlying repository data files are checked:
1281 • For all segments, the segment magic header is checked.
1283 • For all objects stored in the segments, all metadata (e.g. CRC and
1285 size) and all data is read. The read data is checked by size and CRC.
1286 Bit rot and other types of accidental damage can be detected this
1287 way.
1288 • In repair mode, if an integrity error is detected in a segment, try
1290 to recover as many objects from the segment as possible.
1291 • In repair mode, make sure that the index is consistent with the data
1293 stored in the segments.
1294 • If checking a remote repo via ssh:, the repo check is executed on the
1296 server without causing significant network traffic.
1297 • The repository check can be skipped using the --archives-only option.
1299 • A repository check can be time consuming. Partial checks are possible
1301 with the --max-duration option.
1302 Second, the consistency and correctness of the archive metadata is ver‐
1304 ified:
1305 • Is the repo manifest present? If not, it is rebuilt from archive
1307 metadata chunks (this requires reading and decrypting of all metadata
1308 and data).
1309 • Check if archive metadata chunk is present; if not, remove archive
1311 from manifest.
1312 • For all files (items) in the archive, for all chunks referenced by
1314 these files, check if chunk is present. In repair mode, if a chunk is
1315 not present, replace it with a same-size replacement chunk of zeroes.
1316 If a previously lost chunk reappears (e.g. via a later backup), in
1317 repair mode the all-zero replacement chunk will be replaced by the
1318 correct chunk. This requires reading of archive and file metadata,
1319 but not data.
1320 • In repair mode, when all the archives were checked, orphaned chunks
1322 are deleted from the repo. One cause of orphaned chunks are input
1323 file related errors (like read errors) in the archive creation
1324 process.
1325 • In verify-data mode, a complete cryptographic verification of the ar‐
1327 chive data integrity is performed. This conflicts with --reposi‐
1328 tory-only as this mode only makes sense if the archive checks are en‐
1329 abled. The full details of this mode are documented below.
1330 • If checking a remote repo via ssh:, the archive check is executed on
1332 the client machine because it requires decryption, and this is always
1333 done client-side as key access is needed.
1334 • The archive checks can be time consuming; they can be skipped using
1336 the --repository-only option.
1337 The --max-duration option can be used to split a long-running reposi‐
1339 tory check into multiple partial checks. After the given number of sec‐
1340 onds the check is interrupted. The next partial check will continue
1341 where the previous one stopped, until the complete repository has been
1342 checked. Example: Assuming a complete check took 7 hours, then running
1343 a daily check with --max-duration=3600 (1 hour) resulted in one com‐
1344 pleted check per week.
1345 Attention: A partial --repository-only check can only do way less
1347 checking than a full --repository-only check: only the non-crypto‐
1348 graphic checksum checks on segment file entries are done, while a full
1349 --repository-only check would also do a repo index check. A partial
1350 check cannot be combined with the --repair option. Partial checks may
1351 therefore be useful only with very large repositories where a full
1352 check would take too long. Doing a full repository check aborts a par‐
1353 tial check; the next partial check will restart from the beginning.
1354 The --verify-data option will perform a full integrity verification (as
1356 opposed to checking the CRC32 of the segment) of data, which means
1357 reading the data from the repository, decrypting and decompressing it.
1358 This is a cryptographic verification, which will detect (accidental)
1359 corruption. For encrypted repositories it is tamper-resistant as well,
1360 unless the attacker has access to the keys. It is also very slow.
1361
1363 borg [common options] rename [options] ARCHIVE NEWNAME
1364 Description
1366 This command renames an archive in the repository.
1367 This results in a different archive ID.
1369 Examples
1371 $ borg create /path/to/repo::archivename ~
1372 $ borg list /path/to/repo
1373 archivename Mon, 2016-02-15 19:50:19
1374 $ borg rename /path/to/repo::archivename newname
1376 $ borg list /path/to/repo
1377 newname Mon, 2016-02-15 19:50:19
1378
1380 borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
1381 Description
1383 This command lists the contents of a repository or an archive.
1384 For more help on include/exclude patterns, see the borg_patterns com‐
1386 mand output.
1387 The FORMAT specifier syntax
1389 The --format option uses python's format string syntax.
1390 Examples:
1392 $ borg list --format '{archive}{NL}' /path/to/repo
1394 ArchiveFoo
1395 ArchiveBar
1396 ...
1397 # {VAR:NUMBER} - pad to NUMBER columns.
1399 # Strings are left-aligned, numbers are right-aligned.
1400 # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded.
1401 $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo
1402 ArchiveFoo Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
1403 $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
1404 -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo
1405 ...
1406 # {VAR:<NUMBER} - pad to NUMBER columns left-aligned.
1408 # {VAR:>NUMBER} - pad to NUMBER columns right-aligned.
1409 $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
1410 -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo
1411 ...
1412 The following keys are always available:
1414 • NEWLINE: OS dependent line separator
1416 • NL: alias of NEWLINE
1418 • NUL: NUL character for creating print0 / xargs -0 like output, see
1420 barchive and bpath keys below
1421 • SPACE
1423 • TAB
1425 • CR
1427 • LF
1429 Keys available only when listing archives in a repository:
1431 • archive: archive name interpreted as text (might be missing non-text
1433 characters, see barchive)
1434 • name: alias of "archive"
1436 • barchive: verbatim archive name, can contain any character except NUL
1438 • comment: archive comment interpreted as text (might be missing
1440 non-text characters, see bcomment)
1441 • bcomment: verbatim archive comment, can contain any character except
1443 NUL
1444 • id: internal ID of the archive
1446 • start: time (start) of creation of the archive
1448 • time: alias of "start"
1450 • end: time (end) of creation of the archive
1452 • command_line: command line which was used to create the archive
1454 • hostname: hostname of host on which this archive was created
1456 • username: username of user who created this archive
1458 Keys available only when listing files in an archive:
1460 • type
1462 • mode
1464 • uid
1466 • gid
1468 • user
1470 • group
1472 • path: path interpreted as text (might be missing non-text characters,
1474 see bpath)
1475 • bpath: verbatim POSIX path, can contain any character except NUL
1477 • source: link target for links (identical to linktarget)
1479 • linktarget
1481 • flags
1483 • size
1485 • csize: compressed size
1487 • dsize: deduplicated size
1489 • dcsize: deduplicated compressed size
1491 • num_chunks: number of chunks in this file
1493 • unique_chunks: number of unique chunks in this file
1495 • mtime
1497 • ctime
1499 • atime
1501 • isomtime
1503 • isoctime
1505 • isoatime
1507 • blake2b
1509 • blake2s
1511 • md5
1513 • sha1
1515 • sha224
1517 • sha256
1519 • sha384
1521 • sha3_224
1523 • sha3_256
1525 • sha3_384
1527 • sha3_512
1529 • sha512
1531 • xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic
1533 hash!)
1534 • archiveid
1536 • archivename
1538 • extra: prepends {source} with " -> " for soft links and " link to "
1540 for hard links
1541 • health: either "healthy" (file ok) or "broken" (if file has all-zero
1543 replacement chunks)
1544 Examples
1546 $ borg list /path/to/repo
1547 Monday Mon, 2016-02-15 19:15:11
1548 repo Mon, 2016-02-15 19:26:54
1549 root-2016-02-15 Mon, 2016-02-15 19:36:29
1550 newname Mon, 2016-02-15 19:50:19
1551 ...
1552 $ borg list /path/to/repo::root-2016-02-15
1554 drwxr-xr-x root root 0 Mon, 2016-02-15 17:44:27 .
1555 drwxrwxr-x root root 0 Mon, 2016-02-15 19:04:49 bin
1556 -rwxr-xr-x root root 1029624 Thu, 2014-11-13 00:08:51 bin/bash
1557 lrwxrwxrwx root root 0 Fri, 2015-03-27 20:24:26 bin/bzcmp -> bzdiff
1558 -rwxr-xr-x root root 2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
1559 ...
1560 $ borg list /path/to/repo::root-2016-02-15 --pattern "- bin/ba*"
1562 drwxr-xr-x root root 0 Mon, 2016-02-15 17:44:27 .
1563 drwxrwxr-x root root 0 Mon, 2016-02-15 19:04:49 bin
1564 lrwxrwxrwx root root 0 Fri, 2015-03-27 20:24:26 bin/bzcmp -> bzdiff
1565 -rwxr-xr-x root root 2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
1566 ...
1567 $ borg list /path/to/repo::archiveA --format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
1569 drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 .
1570 drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 code
1571 drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 code/myproject
1572 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
1573 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.text
1574 ...
1575 $ borg list /path/to/repo/::archiveA --pattern 're:\.ext$'
1577 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
1578 ...
1579 $ borg list /path/to/repo/::archiveA --pattern 're:.ext$'
1581 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
1582 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.text
1583 ...
1584
1586 borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
1587 Description
1589 This command finds differences (file contents, user/group/mode) between
1590 archives.
1591 A repository location and an archive name must be specified for
1593 REPO::ARCHIVE1. ARCHIVE2 is just another archive name in same reposi‐
1594 tory (no repository location allowed).
1595 For archives created with Borg 1.1 or newer diff automatically detects
1597 whether the archives are created with the same chunker params. If so,
1598 only chunk IDs are compared, which is very fast.
1599 For archives prior to Borg 1.1 chunk contents are compared by default.
1601 If you did not create the archives with different chunker params, pass
1602 --same-chunker-params. Note that the chunker params changed from Borg
1603 0.xx to 1.0.
1604 For more help on include/exclude patterns, see the borg_patterns com‐
1606 mand output.
1607 Examples
1609 $ borg init -e=none testrepo
1610 $ mkdir testdir
1611 $ cd testdir
1612 $ echo asdf > file1
1613 $ dd if=/dev/urandom bs=1M count=4 > file2
1614 $ touch file3
1615 $ borg create ../testrepo::archive1 .
1616 $ chmod a+x file1
1618 $ echo "something" >> file2
1619 $ borg create ../testrepo::archive2 .
1620 $ echo "testing 123" >> file1
1622 $ rm file3
1623 $ touch file4
1624 $ borg create ../testrepo::archive3 .
1625 $ cd ..
1627 $ borg diff testrepo::archive1 archive2
1628 [-rw-r--r-- -> -rwxr-xr-x] file1
1629 +135 B -252 B file2
1630 $ borg diff testrepo::archive2 archive3
1632 +17 B -5 B file1
1633 added 0 B file4
1634 removed 0 B file3
1635 $ borg diff testrepo::archive1 archive3
1637 +17 B -5 B [-rw-r--r-- -> -rwxr-xr-x] file1
1638 +135 B -252 B file2
1639 added 0 B file4
1640 removed 0 B file3
1641 $ borg diff --json-lines testrepo::archive1 archive3
1643 {"path": "file1", "changes": [{"type": "modified", "added": 17, "removed": 5}, {"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"}]}
1644 {"path": "file2", "changes": [{"type": "modified", "added": 135, "removed": 252}]}
1645 {"path": "file4", "changes": [{"type": "added", "size": 0}]}
1646 {"path": "file3", "changes": [{"type": "removed", "size": 0}]}
1647
1649 borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...]
1650 Description
1652 This command deletes an archive from the repository or the complete
1653 repository.
1654 Important: When deleting archives, repository disk space is not freed
1656 until you run borg compact.
1657 When you delete a complete repository, the security info and local
1659 cache for it (if any) are also deleted. Alternatively, you can delete
1660 just the local cache with the --cache-only option, or keep the security
1661 info with the --keep-security-info option.
1662 When in doubt, use --dry-run --list to see what would be deleted.
1664 When using --stats, you will get some statistics about how much data
1666 was deleted - the "Deleted data" deduplicated size there is most inter‐
1667 esting as that is how much your repository will shrink. Please note
1668 that the "All archives" stats refer to the state after deletion.
1669 You can delete multiple archives by specifying their common prefix, if
1671 they have one, using the --prefix PREFIX option. You can also specify a
1672 shell pattern to match multiple archives using the --glob-archives GLOB
1673 option (for more info on these patterns, see borg_patterns). Note that
1674 these two options are mutually exclusive.
1675 To avoid accidentally deleting archives, especially when using glob
1677 patterns, it might be helpful to use the --dry-run to test out the com‐
1678 mand without actually making any changes to the repository.
1679 Examples
1681 # delete a single backup archive:
1682 $ borg delete /path/to/repo::Monday
1683 # actually free disk space:
1684 $ borg compact /path/to/repo
1685 # delete all archives whose names begin with the machine's hostname followed by "-"
1687 $ borg delete --prefix '{hostname}-' /path/to/repo
1688 # delete all archives whose names contain "-2012-"
1690 $ borg delete --glob-archives '*-2012-*' /path/to/repo
1691 # see what would be deleted if delete was run without --dry-run
1693 $ borg delete --list --dry-run -a '*-May-*' /path/to/repo
1694 # delete the whole repository and the related local cache:
1696 $ borg delete /path/to/repo
1697 You requested to completely DELETE the repository *including* all archives it contains:
1698 repo Mon, 2016-02-15 19:26:54
1699 root-2016-02-15 Mon, 2016-02-15 19:36:29
1700 newname Mon, 2016-02-15 19:50:19
1701 Type 'YES' if you understand this and want to continue: YES
1702
1704 borg [common options] prune [options] [REPOSITORY]
1705 Description
1707 The prune command prunes a repository by deleting all archives not
1708 matching any of the specified retention options.
1709 Important: Repository disk space is not freed until you run borg com‐
1711 pact.
1712 This command is normally used by automated backup scripts wanting to
1714 keep a certain number of historic backups. This retention policy is
1715 commonly referred to as GFS (Grandfather-father-son) backup rotation
1716 scheme.
1717 Also, prune automatically removes checkpoint archives (incomplete ar‐
1719 chives left behind by interrupted backup runs) except if the checkpoint
1720 is the latest archive (and thus still needed). Checkpoint archives are
1721 not considered when comparing archive counts against the retention lim‐
1722 its (--keep-X).
1723 If a prefix is set with -P, then only archives that start with the pre‐
1725 fix are considered for deletion and only those archives count towards
1726 the totals specified by the rules. Otherwise, all archives in the
1727 repository are candidates for deletion! There is no automatic distinc‐
1728 tion between archives representing different contents. These need to be
1729 distinguished by specifying matching prefixes.
1730 If you have multiple sequences of archives with different data sets
1732 (e.g. from different machines) in one shared repository, use one prune
1733 call per data set that matches only the respective archives using the
1734 -P option.
1735 The --keep-within option takes an argument of the form "<int><char>",
1737 where char is "H", "d", "w", "m", "y". For example, --keep-within 2d
1738 means to keep all archives that were created within the past 48 hours.
1739 "1m" is taken to mean "31d". The archives kept with this option do not
1740 count towards the totals specified by any other options.
1741 A good procedure is to thin out more and more the older your backups
1743 get. As an example, --keep-daily 7 means to keep the latest backup on
1744 each day, up to 7 most recent days with backups (days without backups
1745 do not count). The rules are applied from secondly to yearly, and
1746 backups selected by previous rules do not count towards those of later
1747 rules. The time that each backup starts is used for pruning purposes.
1748 Dates and times are interpreted in the local timezone, and weeks go
1749 from Monday to Sunday. Specifying a negative number of archives to keep
1750 means that there is no limit. As of borg 1.2.0, borg will retain the
1751 oldest archive if any of the secondly, minutely, hourly, daily, weekly,
1752 monthly, or yearly rules was not otherwise able to meet its retention
1753 target. This enables the first chronological archive to continue aging
1754 until it is replaced by a newer archive that meets the retention crite‐
1755 ria.
1756 The --keep-last N option is doing the same as --keep-secondly N (and it
1758 will keep the last N archives under the assumption that you do not cre‐
1759 ate more than one backup archive in the same second).
1760 When using --stats, you will get some statistics about how much data
1762 was deleted - the "Deleted data" deduplicated size there is most inter‐
1763 esting as that is how much your repository will shrink. Please note
1764 that the "All archives" stats refer to the state after pruning.
1765 Examples
1767 Be careful, prune is a potentially dangerous command, it will remove
1768 backup archives.
1769 The default of prune is to apply to all archives in the repository un‐
1771 less you restrict its operation to a subset of the archives using
1772 --prefix. When using --prefix, be careful to choose a good prefix -
1773 e.g. do not use a prefix "foo" if you do not also want to match "foo‐
1774 bar".
1775 It is strongly recommended to always run prune -v --list --dry-run ...
1777 first so you will see what it would do without it actually doing any‐
1778 thing.
1779 # Keep 7 end of day and 4 additional end of week archives.
1781 # Do a dry-run without actually deleting anything.
1782 $ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
1783 # Same as above but only apply to archive names starting with the hostname
1785 # of the machine followed by a "-" character:
1786 $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --prefix='{hostname}-' /path/to/repo
1787 # actually free disk space:
1788 $ borg compact /path/to/repo
1789 # Keep 7 end of day, 4 additional end of week archives,
1791 # and an end of month archive for every month:
1792 $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /path/to/repo
1793 # Keep all backups in the last 10 days, 4 additional end of week archives,
1795 # and an end of month archive for every month:
1796 $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/repo
1797 There is also a visualized prune example in docs/misc/prune-exam‐
1799 ple.txt:
1800 borg prune visualized
1802 =====================
1803 Assume it is 2016-01-01, today's backup has not yet been made, you have
1805 created at least one backup on each day in 2015 except on 2015-12-19 (no
1806 backup made on that day), and you started backing up with borg on
1807 2015-01-01.
1808 This is what borg prune --keep-daily 14 --keep-monthly 6 --keep-yearly 1
1810 would keep.
1811 Backups kept by the --keep-daily rule are marked by a "d" to the right,
1813 backups kept by the --keep-monthly rule are marked by a "m" to the right,
1814 and backups kept by the --keep-yearly rule are marked by a "y" to the
1815 right.
1816 Calendar view
1818 -------------
1819 2015
1821 January February March
1822 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1823 1y 2 3 4 1 1
1824 5 6 7 8 9 10 11 2 3 4 5 6 7 8 2 3 4 5 6 7 8
1825 12 13 14 15 16 17 18 9 10 11 12 13 14 15 9 10 11 12 13 14 15
1826 19 20 21 22 23 24 25 16 17 18 19 20 21 22 16 17 18 19 20 21 22
1827 26 27 28 29 30 31 23 24 25 26 27 28 23 24 25 26 27 28 29
1828 30 31
1829 April May June
1831 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1832 1 2 3 4 5 1 2 3 1 2 3 4 5 6 7
1833 6 7 8 9 10 11 12 4 5 6 7 8 9 10 8 9 10 11 12 13 14
1834 13 14 15 16 17 18 19 11 12 13 14 15 16 17 15 16 17 18 19 20 21
1835 20 21 22 23 24 25 26 18 19 20 21 22 23 24 22 23 24 25 26 27 28
1836 27 28 29 30 25 26 27 28 29 30 31 29 30m
1837 July August September
1840 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1841 1 2 3 4 5 1 2 1 2 3 4 5 6
1842 6 7 8 9 10 11 12 3 4 5 6 7 8 9 7 8 9 10 11 12 13
1843 13 14 15 16 17 18 19 10 11 12 13 14 15 16 14 15 16 17 18 19 20
1844 20 21 22 23 24 25 26 17 18 19 20 21 22 23 21 22 23 24 25 26 27
1845 27 28 29 30 31m 24 25 26 27 28 29 30 28 29 30m
1846 31m
1847 October November December
1849 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1850 1 2 3 4 1 1 2 3 4 5 6
1851 5 6 7 8 9 10 11 2 3 4 5 6 7 8 7 8 9 10 11 12 13
1852 12 13 14 15 16 17 18 9 10 11 12 13 14 15 14 15 16 17d18d19 20d
1853 19 20 21 22 23 24 25 16 17 18 19 20 21 22 21d22d23d24d25d26d27d
1854 26 27 28 29 30 31m 23 24 25 26 27 28 29 28d29d30d31d
1855 30m
1856 List view
1858 ---------
1859 --keep-daily 14 --keep-monthly 6 --keep-yearly 1
1861 ----------------------------------------------------------------
1862 1. 2015-12-31 (2015-12-31 kept (2015-12-31 kept
1863 2. 2015-12-30 by daily rule) by daily rule)
1864 3. 2015-12-29 1. 2015-11-30 1. 2015-01-01 (oldest)
1865 4. 2015-12-28 2. 2015-10-31
1866 5. 2015-12-27 3. 2015-09-30
1867 6. 2015-12-26 4. 2015-08-31
1868 7. 2015-12-25 5. 2015-07-31
1869 8. 2015-12-24 6. 2015-06-30
1870 9. 2015-12-23
1871 10. 2015-12-22
1872 11. 2015-12-21
1873 12. 2015-12-20
1874 (no backup made on 2015-12-19)
1875 13. 2015-12-18
1876 14. 2015-12-17
1877 Notes
1880 -----
1881 2015-12-31 is kept due to the --keep-daily 14 rule (because it is applied
1883 first), not due to the --keep-monthly or --keep-yearly rule.
1884 The --keep-yearly 1 rule does not consider the December 31st backup because it
1886 has already been kept due to the daily rule. There are no backups available
1887 from previous years, so the --keep-yearly target of 1 backup is not satisfied.
1888 Because of this, the 2015-01-01 archive (the oldest archive available) is kept.
1889 The --keep-monthly 6 rule keeps Nov, Oct, Sep, Aug, Jul and Jun. December is
1891 not considered for this rule, because that backup was already kept because of
1892 the daily rule.
1893 2015-12-17 is kept to satisfy the --keep-daily 14 rule - because no backup was
1895 made on 2015-12-19. If a backup had been made on that day, it would not keep
1896 the one from 2015-12-17.
1897 We did not include weekly, hourly, minutely or secondly rules to keep this
1899 example simple. They all work in basically the same way.
1900 The weekly rule is easy to understand roughly, but hard to understand in all
1902 details. If interested, read "ISO 8601:2000 standard week-based year".
1903
1906 borg [common options] compact [options] [REPOSITORY]
1907 Description
1909 This command frees repository space by compacting segments.
1910 Use this regularly to avoid running out of space - you do not need to
1912 use this after each borg command though. It is especially useful after
1913 deleting archives, because only compaction will really free repository
1914 space.
1915 borg compact does not need a key, so it is possible to invoke it from
1917 the client or also from the server.
1918 Depending on the amount of segments that need compaction, it may take a
1920 while, so consider using the --progress option.
1921 A segment is compacted if the amount of saved space is above the per‐
1923 centage value given by the --threshold option. If omitted, a threshold
1924 of 10% is used. When using --verbose, borg will output an estimate of
1925 the freed space.
1926 After upgrading borg (server) to 1.2+, you can use borg compact
1928 --cleanup-commits to clean up the numerous 17byte commit-only segments
1929 that borg 1.1 did not clean up due to a bug. It is enough to do that
1930 once per repository. After cleaning up the commits, borg will also do a
1931 normal compaction.
1932 See separate_compaction in Additional Notes for more details.
1934 Examples
1936 # compact segments and free repo disk space
1937 $ borg compact /path/to/repo
1938 # same as above plus clean up 17byte commit-only segments
1940 $ borg compact --cleanup-commits /path/to/repo
1941
1943 borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
1944 Description
1946 This command displays detailed information about the specified archive
1947 or repository.
1948 Please note that the deduplicated sizes of the individual archives do
1950 not add up to the deduplicated size of the repository ("all archives"),
1951 because the two are meaning different things:
1952 This archive / deduplicated size = amount of data stored ONLY for this
1954 archive = unique chunks of this archive. All archives / deduplicated
1955 size = amount of data stored in the repo = all chunks in the reposi‐
1956 tory.
1957 Borg archives can only contain a limited amount of file metadata. The
1959 size of an archive relative to this limit depends on a number of fac‐
1960 tors, mainly the number of files, the lengths of paths and other meta‐
1961 data stored for files. This is shown as utilization of maximum sup‐
1962 ported archive size.
1963 Examples
1965 $ borg info /path/to/repo::2017-06-29T11:00-srv
1966 Archive name: 2017-06-29T11:00-srv
1967 Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
1968 Comment:
1969 Hostname: myhostname
1970 Username: root
1971 Time (start): Thu, 2017-06-29 11:03:07
1972 Time (end): Thu, 2017-06-29 11:03:13
1973 Duration: 5.66 seconds
1974 Number of files: 17037
1975 Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
1976 Utilization of max. archive size: 0%
1977 ------------------------------------------------------------------------------
1978 Original size Compressed size Deduplicated size
1979 This archive: 12.53 GB 12.49 GB 1.62 kB
1980 All archives: 121.82 TB 112.41 TB 215.42 GB
1981 Unique chunks Total chunks
1983 Chunk index: 1015213 626934122
1984 $ borg info /path/to/repo --last 1
1986 Archive name: 2017-06-29T11:00-srv
1987 Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
1988 Comment:
1989 Hostname: myhostname
1990 Username: root
1991 Time (start): Thu, 2017-06-29 11:03:07
1992 Time (end): Thu, 2017-06-29 11:03:13
1993 Duration: 5.66 seconds
1994 Number of files: 17037
1995 Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
1996 Utilization of max. archive size: 0%
1997 ------------------------------------------------------------------------------
1998 Original size Compressed size Deduplicated size
1999 This archive: 12.53 GB 12.49 GB 1.62 kB
2000 All archives: 121.82 TB 112.41 TB 215.42 GB
2001 Unique chunks Total chunks
2003 Chunk index: 1015213 626934122
2004 $ borg info /path/to/repo
2006 Repository ID: d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
2007 Location: /path/to/repo
2008 Encrypted: Yes (repokey)
2009 Cache: /root/.cache/borg/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
2010 Security dir: /root/.config/borg/security/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
2011 ------------------------------------------------------------------------------
2012 Original size Compressed size Deduplicated size
2013 All archives: 121.82 TB 112.41 TB 215.42 GB
2014 Unique chunks Total chunks
2016 Chunk index: 1015213 626934122
2017
2019 borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
2020 Description
2022 This command mounts an archive as a FUSE filesystem. This can be useful
2023 for browsing an archive or restoring individual files. Unless the
2024 --foreground option is given the command will run in the background un‐
2025 til the filesystem is umounted.
2026 The command borgfs provides a wrapper for borg mount. This can also be
2028 used in fstab entries: /path/to/repo /mnt/point fuse.borgfs de‐
2029 faults,noauto 0 0
2030 To allow a regular user to use fstab entries, add the user option:
2032 /path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0
2033 For FUSE configuration and mount options, see the mount.fuse(8) manual
2035 page.
2036 Borg's default behavior is to use the archived user and group names of
2038 each file and map them to the system's respective user and group ids.
2039 Alternatively, using numeric-ids will instead use the archived user and
2040 group ids without any mapping.
2041 The uid and gid mount options (implemented by Borg) can be used to
2043 override the user and group ids of all files (i.e., borg mount -o
2044 uid=1000,gid=1000).
2045 The man page references user_id and group_id mount options (implemented
2047 by fuse) which specify the user and group id of the mount owner (aka,
2048 the user who does the mounting). It is set automatically by libfuse (or
2049 the filesystem if libfuse is not used). However, you should not specify
2050 these manually. Unlike the uid and gid mount options which affect all
2051 files, user_id and group_id affect the user and group id of the mounted
2052 (base) directory.
2053 Additional mount options supported by borg:
2055 • versions: when used with a repository mount, this gives a merged,
2057 versioned view of the files in the archives. EXPERIMENTAL, layout may
2058 change in future.
2059 • allow_damaged_files: by default damaged files (where missing chunks
2061 were replaced with runs of zeros by borg check --repair) are not
2062 readable and return EIO (I/O error). Set this option to read such
2063 files.
2064 • ignore_permissions: for security reasons the "default_permissions"
2066 mount option is internally enforced by borg. "ignore_permissions" can
2067 be given to not enforce "default_permissions".
2068 The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for ad‐
2070 vanced users to tweak the performance. It sets the number of cached
2071 data chunks; additional memory usage can be up to ~8 MiB times this
2072 number. The default is the number of CPU cores.
2073 When the daemonized process receives a signal or crashes, it does not
2075 unmount. Unmounting in these cases could cause an active rsync or sim‐
2076 ilar process to unintentionally delete data.
2077 When running in the foreground ^C/SIGINT unmounts cleanly, but other
2079 signals or crashes do not.
2080
2082 borg [common options] umount [options] MOUNTPOINT
2083 Description
2085 This command un-mounts a FUSE filesystem that was mounted with borg
2086 mount.
2087 This is a convenience wrapper that just calls the platform-specific
2089 shell command - usually this is either umount or fusermount -u.
2090 Examples
2092 # Mounting the repository shows all archives.
2093 # Archives are loaded lazily, expect some delay when navigating to an archive
2094 # for the first time.
2095 $ borg mount /path/to/repo /tmp/mymountpoint
2096 $ ls /tmp/mymountpoint
2097 root-2016-02-14 root-2016-02-15
2098 $ borg umount /tmp/mymountpoint
2099 # Mounting a specific archive is possible as well.
2101 $ borg mount /path/to/repo::root-2016-02-15 /tmp/mymountpoint
2102 $ ls /tmp/mymountpoint
2103 bin boot etc home lib lib64 lost+found media mnt opt
2104 root sbin srv tmp usr var
2105 $ borg umount /tmp/mymountpoint
2106 # The "versions view" merges all archives in the repository
2108 # and provides a versioned view on files.
2109 $ borg mount -o versions /path/to/repo /tmp/mymountpoint
2110 $ ls -l /tmp/mymountpoint/home/user/doc.txt/
2111 total 24
2112 -rw-rw-r-- 1 user group 12357 Aug 26 21:19 doc.cda00bc9.txt
2113 -rw-rw-r-- 1 user group 12204 Aug 26 21:04 doc.fa760f28.txt
2114 $ borg umount /tmp/mymountpoint
2115 # Archive filters are supported.
2117 # These are especially handy for the "versions view",
2118 # which does not support lazy processing of archives.
2119 $ borg mount -o versions --glob-archives '*-my-home' --last 10 /path/to/repo /tmp/mymountpoint
2120 # Exclusion options are supported.
2122 # These can speed up mounting and lower memory needs significantly.
2123 $ borg mount /path/to/repo /tmp/mymountpoint only/that/path
2124 $ borg mount --exclude '...' /path/to/repo /tmp/mymountpoint
2125 borgfs
2127 $ echo '/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
2128 $ echo '/mnt/backup::root-2016-02-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
2129 $ mount /tmp/myrepo
2130 $ mount /tmp/myarchive
2131 $ ls /tmp/myrepo
2132 root-2016-02-01 root-2016-02-2015
2133 $ ls /tmp/myarchive
2134 bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
2135 NOTE:
2137 borgfs will be automatically provided if you used a distribution
2138 package, pip or setup.py to install Borg. Users of the standalone
2139 binary will have to manually create a symlink (see pyinstaller-bi‐
2140 nary).
2141
2143 borg [common options] key change-passphrase [options] [REPOSITORY]
2144 Description
2146 The key files used for repository encryption are optionally passphrase
2147 protected. This command can be used to change this passphrase.
2148 Please note that this command only changes the passphrase, but not any
2150 secret protected by it (like e.g. encryption/MAC keys or chunker seed).
2151 Thus, changing the passphrase after passphrase and borg key got compro‐
2152 mised does not protect future (nor past) backups to the same reposi‐
2153 tory.
2154 Examples
2156 # Create a key file protected repository
2157 $ borg init --encryption=keyfile -v /path/to/repo
2158 Initializing repository at "/path/to/repo"
2159 Enter new passphrase:
2160 Enter same passphrase again:
2161 Remember your passphrase. Your data will be inaccessible without it.
2162 Key in "/root/.config/borg/keys/mnt_backup" created.
2163 Keep this key safe. Your data will be inaccessible without it.
2164 Synchronizing chunks cache...
2165 Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
2166 Done.
2167 # Change key file passphrase
2169 $ borg key change-passphrase -v /path/to/repo
2170 Enter passphrase for key /root/.config/borg/keys/mnt_backup:
2171 Enter new passphrase:
2172 Enter same passphrase again:
2173 Remember your passphrase. Your data will be inaccessible without it.
2174 Key updated
2175 # Import a previously-exported key into the specified
2177 # key file (creating or overwriting the output key)
2178 # (keyfile repositories only)
2179 $ BORG_KEY_FILE=/path/to/output-key borg key import /path/to/repo /path/to/exported
2180 Fully automated using environment variables:
2182 $ BORG_NEW_PASSPHRASE=old borg init -e=repokey repo
2184 # now "old" is the current passphrase.
2185 $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase repo
2186 # now "new" is the current passphrase.
2187
2189 borg [common options] key export [options] [REPOSITORY] [PATH]
2190 Description
2192 If repository encryption is used, the repository is inaccessible with‐
2193 out the key. This command allows one to backup this essential key.
2194 Note that the backup produced does not include the passphrase itself
2195 (i.e. the exported key stays encrypted). In order to regain access to a
2196 repository, one needs both the exported key and the original
2197 passphrase.
2198 There are three backup formats. The normal backup format is suitable
2200 for digital storage as a file. The --paper backup format is optimized
2201 for printing and typing in while importing, with per line checks to re‐
2202 duce problems with manual input. The --qr-html creates a printable HTML
2203 template with a QR code and a copy of the --paper-formatted key.
2204 For repositories using keyfile encryption the key is saved locally on
2206 the system that is capable of doing backups. To guard against loss of
2207 this key, the key needs to be backed up independently of the main data
2208 backup.
2209 For repositories using the repokey encryption the key is saved in the
2211 repository in the config file. A backup is thus not strictly needed,
2212 but guards against the repository becoming inaccessible if the file is
2213 damaged for some reason.
2214 Examples:
2216 borg key export /path/to/repo > encrypted-key-backup
2218 borg key export --paper /path/to/repo > encrypted-key-backup.txt
2219 borg key export --qr-html /path/to/repo > encrypted-key-backup.html
2220 # Or pass the output file as an argument instead of redirecting stdout:
2221 borg key export /path/to/repo encrypted-key-backup
2222 borg key export --paper /path/to/repo encrypted-key-backup.txt
2223 borg key export --qr-html /path/to/repo encrypted-key-backup.html
2224
2226 borg [common options] key import [options] [REPOSITORY] [PATH]
2227 Description
2229 This command restores a key previously backed up with the export com‐
2230 mand.
2231 If the --paper option is given, the import will be an interactive
2233 process in which each line is checked for plausibility before proceed‐
2234 ing to the next line. For this format PATH must not be given.
2235 For repositories using keyfile encryption, the key file which borg key
2237 import writes to depends on several factors. If the BORG_KEY_FILE envi‐
2238 ronment variable is set and non-empty, borg key import creates or over‐
2239 writes that file named by $BORG_KEY_FILE. Otherwise, borg key import
2240 searches in the $BORG_KEYS_DIR directory for a key file associated with
2241 the repository. If a key file is found in $BORG_KEYS_DIR, borg key im‐
2242 port overwrites it; otherwise, borg key import creates a new key file
2243 in $BORG_KEYS_DIR.
2244
2246 borg [common options] upgrade [options] [REPOSITORY]
2247 Description
2249 Upgrade an existing, local Borg repository.
2250 When you do not need borg upgrade
2252 Not every change requires that you run borg upgrade.
2253 You do not need to run it when:
2255 • moving your repository to a different place
2257 • upgrading to another point release (like 1.0.x to 1.0.y), except when
2259 noted otherwise in the changelog
2260 • upgrading from 1.0.x to 1.1.x, except when noted otherwise in the
2262 changelog
2263 Borg 1.x.y upgrades
2265 Use borg upgrade --tam REPO to require manifest authentication intro‐
2266 duced with Borg 1.0.9 to address security issues. This means that modi‐
2267 fying the repository after doing this with a version prior to 1.0.9
2268 will raise a validation error, so only perform this upgrade after up‐
2269 dating all clients using the repository to 1.0.9 or newer.
2270 This upgrade should be done on each client for safety reasons.
2272 If a repository is accidentally modified with a pre-1.0.9 client after
2274 this upgrade, use borg upgrade --tam --force REPO to remedy it.
2275 If you routinely do this you might not want to enable this upgrade
2277 (which will leave you exposed to the security issue). You can reverse
2278 the upgrade by issuing borg upgrade --disable-tam REPO.
2279 See
2281 https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability
2282 for details.
2283 Attic and Borg 0.xx to Borg 1.x
2285 This currently supports converting an Attic repository to Borg and also
2286 helps with converting Borg 0.xx to 1.0.
2287 Currently, only LOCAL repositories can be upgraded (issue #465).
2289 Please note that borg create (since 1.0.0) uses bigger chunks by de‐
2291 fault than old borg or attic did, so the new chunks won't deduplicate
2292 with the old chunks in the upgraded repository. See --chunker-params
2293 option of borg create and borg recreate.
2294 borg upgrade will change the magic strings in the repository's segments
2296 to match the new Borg magic strings. The keyfiles found in $AT‐
2297 TIC_KEYS_DIR or ~/.attic/keys/ will also be converted and copied to
2298 $BORG_KEYS_DIR or ~/.config/borg/keys.
2299 The cache files are converted, from $ATTIC_CACHE_DIR or ~/.cache/attic
2301 to $BORG_CACHE_DIR or ~/.cache/borg, but the cache layout between Borg
2302 and Attic changed, so it is possible the first backup after the conver‐
2303 sion takes longer than expected due to the cache resync.
2304 Upgrade should be able to resume if interrupted, although it will still
2306 iterate over all segments. If you want to start from scratch, use borg
2307 delete over the copied repository to make sure the cache files are also
2308 removed:
2309 borg delete borg
2311 Unless --inplace is specified, the upgrade process first creates a
2313 backup copy of the repository, in REPOSITORY.before-upgrade-DATETIME,
2314 using hardlinks. This requires that the repository and its parent di‐
2315 rectory reside on same filesystem so the hardlink copy can work. This
2316 takes longer than in place upgrades, but is much safer and gives
2317 progress information (as opposed to cp -al). Once you are satisfied
2318 with the conversion, you can safely destroy the backup copy.
2319 WARNING: Running the upgrade in place will make the current copy unus‐
2321 able with older version, with no way of going back to previous ver‐
2322 sions. This can PERMANENTLY DAMAGE YOUR REPOSITORY! Attic CAN NOT READ
2323 BORG REPOSITORIES, as the magic strings have changed. You have been
2324 warned.
2325 Examples
2327 # Upgrade the borg repository to the most recent version.
2328 $ borg upgrade -v /path/to/repo
2329 making a hardlink copy in /path/to/repo.before-upgrade-2016-02-15-20:51:55
2330 opening attic repository with borg and converting
2331 no key file found for repository
2332 converting repo index /path/to/repo/index.0
2333 converting 1 segments...
2334 converting borg 0.xx to borg current
2335 no key file found for repository
2336 Upgrading a passphrase encrypted attic repo
2338 attic offered a "passphrase" encryption mode, but this was removed in
2339 borg 1.0 and replaced by the "repokey" mode (which stores the
2340 passphrase-protected encryption key into the repository config).
2341 Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2
2343 steps are needed, in this order:
2344 • borg upgrade repo
2346 • borg key migrate-to-repokey repo
2348
2350 borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
2351 Description
2353 Recreate the contents of existing archives.
2354 recreate is a potentially dangerous function and might lead to data
2356 loss (if used wrongly). BE VERY CAREFUL!
2357 Important: Repository disk space is not freed until you run borg com‐
2359 pact.
2360 --exclude, --exclude-from, --exclude-if-present, --keep-exclude-tags
2362 and PATH have the exact same semantics as in "borg create", but they
2363 only check for files in the archives and not in the local file system.
2364 If PATHs are specified, the resulting archives will only contain files
2365 from these PATHs.
2366 Note that all paths in an archive are relative, therefore absolute pat‐
2368 terns/paths will not match (--exclude, --exclude-from, PATHs).
2369 --recompress allows one to change the compression of existing data in
2371 archives. Due to how Borg stores compressed size information this
2372 might display incorrect information for archives that were not recre‐
2373 ated at the same time. There is no risk of data loss by this.
2374 --chunker-params will re-chunk all files in the archive, this can be
2376 used to have upgraded Borg 0.xx or Attic archives deduplicate with Borg
2377 1.x archives.
2378 USE WITH CAUTION. Depending on the PATHs and patterns given, recreate
2380 can be used to permanently delete files from archives. When in doubt,
2381 use --dry-run --verbose --list to see how patterns/PATHS are inter‐
2382 preted. See list_item_flags in borg create for details.
2383 The archive being recreated is only removed after the operation com‐
2385 pletes. The archive that is built during the operation exists at the
2386 same time at "<ARCHIVE>.recreate". The new archive will have a differ‐
2387 ent archive ID.
2388 With --target the original archive is not replaced, instead a new ar‐
2390 chive is created.
2391 When rechunking (or recompressing), space usage can be substantial -
2393 expect at least the entire deduplicated size of the archives using the
2394 previous chunker (or compression) params.
2395 If you recently ran borg check --repair and it had to fix lost chunks
2397 with all-zero replacement chunks, please first run another backup for
2398 the same data and re-run borg check --repair afterwards to heal any ar‐
2399 chives that had lost chunks which are still generated from the input
2400 data.
2401 Important: running borg recreate to re-chunk will remove the
2403 chunks_healthy metadata of all items with replacement chunks, so heal‐
2404 ing will not be possible any more after re-chunking (it is also un‐
2405 likely it would ever work: due to the change of chunking parameters,
2406 the missing chunk likely will never be seen again even if you still
2407 have the data that produced it).
2408 Examples
2410 # Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
2411 # Archives created with Borg 1.1+ and the default chunker params are skipped
2412 # (archive ID stays the same).
2413 $ borg recreate /mnt/backup --chunker-params default --progress
2414 # Create a backup with little but fast compression
2416 $ borg create /mnt/backup::archive /some/files --compression lz4
2417 # Then compress it - this might take longer, but the backup has already completed,
2418 # so no inconsistencies from a long-running backup job.
2419 $ borg recreate /mnt/backup::archive --recompress --compression zlib,9
2420 # Remove unwanted files from all archives in a repository.
2422 # Note the relative path for the --exclude option - archives only contain relative paths.
2423 $ borg recreate /mnt/backup --exclude home/icke/Pictures/drunk_photos
2424 # Change archive comment
2426 $ borg create --comment "This is a comment" /mnt/backup::archivename ~
2427 $ borg info /mnt/backup::archivename
2428 Name: archivename
2429 Fingerprint: ...
2430 Comment: This is a comment
2431 ...
2432 $ borg recreate --comment "This is a better comment" /mnt/backup::archivename
2433 $ borg info /mnt/backup::archivename
2434 Name: archivename
2435 Fingerprint: ...
2436 Comment: This is a better comment
2437 ...
2438
2440 borg [common options] import-tar [options] ARCHIVE TARFILE
2441 Description
2443 This command creates a backup archive from a tarball.
2444 When giving '-' as path, Borg will read a tar stream from standard in‐
2446 put.
2447 By default (--tar-filter=auto) Borg will detect whether the file is
2449 compressed based on its file extension and pipe the file through an ap‐
2450 propriate filter:
2451 • .tar.gz or .tgz: gzip -d
2453 • .tar.bz2 or .tbz: bzip2 -d
2455 • .tar.xz or .txz: xz -d
2457 • .tar.zstd: zstd -d
2459 • .tar.lz4: lz4 -d
2461 Alternatively, a --tar-filter program may be explicitly specified. It
2463 should read compressed data from stdin and output an uncompressed tar
2464 stream on stdout.
2465 Most documentation of borg create applies. Note that this command does
2467 not support excluding files.
2468 import-tar is a lossy conversion: BSD flags, ACLs, extended attributes
2470 (xattrs), atime and ctime are not exported. Timestamp resolution is
2471 limited to whole seconds, not the nanosecond resolution otherwise sup‐
2472 ported by Borg.
2473 A --sparse option (as found in borg create) is not supported.
2475 import-tar reads POSIX.1-1988 (ustar), POSIX.1-2001 (pax), GNU tar,
2477 UNIX V7 tar and SunOS tar with extended attributes.
2478
2480 borg [common options] export-tar [options] ARCHIVE FILE [PATH...]
2481 Description
2483 This command creates a tarball from an archive.
2484 When giving '-' as the output FILE, Borg will write a tar stream to
2486 standard output.
2487 By default (--tar-filter=auto) Borg will detect whether the FILE should
2489 be compressed based on its file extension and pipe the tarball through
2490 an appropriate filter before writing it to FILE:
2491 • .tar.gz or .tgz: gzip
2493 • .tar.bz2 or .tbz: bzip2
2495 • .tar.xz or .txz: xz
2497 • .tar.zstd: zstd
2499 • .tar.lz4: lz4
2501 Alternatively, a --tar-filter program may be explicitly specified. It
2503 should read the uncompressed tar stream from stdin and write a com‐
2504 pressed/filtered tar stream to stdout.
2505 The generated tarball uses the GNU tar format.
2507 export-tar is a lossy conversion: BSD flags, ACLs, extended attributes
2509 (xattrs), atime and ctime are not exported. Timestamp resolution is
2510 limited to whole seconds, not the nanosecond resolution otherwise sup‐
2511 ported by Borg.
2512 A --sparse option (as found in borg extract) is not supported.
2514 By default the entire archive is extracted but a subset of files and
2516 directories can be selected by passing a list of PATHs as arguments.
2517 The file selection can further be restricted by using the --exclude op‐
2518 tion.
2519 For more help on include/exclude patterns, see the borg_patterns com‐
2521 mand output.
2522 --progress can be slower than no progress display, since it makes one
2524 additional pass over the archive metadata.
2525 Examples
2527 # export as uncompressed tar
2528 $ borg export-tar /path/to/repo::Monday Monday.tar
2529 # exclude some types, compress using gzip
2531 $ borg export-tar /path/to/repo::Monday Monday.tar.gz --exclude '*.so'
2532 # use higher compression level with gzip
2534 $ borg export-tar --tar-filter="gzip -9" testrepo::linux Monday.tar.gz
2535 # export a tar, but instead of storing it on disk,
2537 # upload it to a remote site using curl.
2538 $ borg export-tar /path/to/repo::Monday - | curl --data-binary @- https://somewhere/to/POST
2539 # remote extraction via "tarpipe"
2541 $ borg export-tar /path/to/repo::Monday - | ssh somewhere "cd extracted; tar x"
2542
2544 borg [common options] serve [options]
2545 Description
2547 This command starts a repository server process. This command is usu‐
2548 ally not used manually.
2549 Examples
2551 borg serve has special support for ssh forced commands (see autho‐
2552 rized_keys example below): if the environment variable SSH_ORIGI‐
2553 NAL_COMMAND is set it will ignore some options given on the command
2554 line and use the values from the variable instead. This only applies to
2555 a carefully controlled allowlist of safe options. This list currently
2556 contains:
2557 • Options that control the log level and debug topics printed such as
2559 --verbose, --info, --debug, --debug-topic, etc.
2560 • --lock-wait to allow the client to control how long to wait before
2562 giving up and aborting the operation when another process is holding
2563 a lock.
2564 Environment variables (such as BORG_XXX) contained in the original com‐
2566 mand sent by the client are not interpreted, but ignored. If BORG_XXX
2567 environment variables should be set on the borg serve side, then these
2568 must be set in system-specific locations like /etc/environment or in
2569 the forced command itself (example below).
2570 # Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
2572 # Use key options to disable unneeded and potentially dangerous SSH functionality.
2573 # This will help to secure an automated remote backup system.
2574 $ cat ~/.ssh/authorized_keys
2575 command="borg serve --restrict-to-path /path/to/repo",restrict ssh-rsa AAAAB3[...]
2576 # Set a BORG_XXX environment variable on the "borg serve" side
2578 $ cat ~/.ssh/authorized_keys
2579 command="export BORG_XXX=value; borg serve [...]",restrict ssh-rsa [...]
2580 NOTE:
2582 The examples above use the restrict directive. This does automati‐
2583 cally block potential dangerous ssh features, even when they are
2584 added in a future update. Thus, this option should be preferred.
2585 If you're using openssh-server < 7.2, however, you have to explic‐
2587 itly specify the ssh features to restrict and cannot simply use the
2588 restrict option as it has been introduced in v7.2. We recommend to
2589 use no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forward‐
2590 ing,no-user-rc in this case.
2591 Details about sshd usage: sshd(8)
2593 SSH Configuration
2595 borg serve's pipes (stdin/stdout/stderr) are connected to the sshd
2596 process on the server side. In the event that the SSH connection be‐
2597 tween borg serve and the client is disconnected or stuck abnormally
2598 (for example, due to a network outage), it can take a long time for
2599 sshd to notice the client is disconnected. In the meantime, sshd con‐
2600 tinues running, and as a result so does the borg serve process holding
2601 the lock on the repository. This can cause subsequent borg operations
2602 on the remote repository to fail with the error: Failed to create/ac‐
2603 quire the lock.
2604 In order to avoid this, it is recommended to perform the following ad‐
2606 ditional SSH configuration:
2607 Either in the client side's ~/.ssh/config file, or in the client's
2609 /etc/ssh/ssh_config file:
2610 Host backupserver
2612 ServerAliveInterval 10
2613 ServerAliveCountMax 30
2614 Replacing backupserver with the hostname, FQDN or IP address of the
2616 borg server.
2617 This will cause the client to send a keepalive to the server every 10
2619 seconds. If 30 consecutive keepalives are sent without a response (a
2620 time of 300 seconds), the ssh client process will be terminated, caus‐
2621 ing the borg process to terminate gracefully.
2622 On the server side's sshd configuration file (typically
2624 /etc/ssh/sshd_config):
2625 ClientAliveInterval 10
2627 ClientAliveCountMax 30
2628 This will cause the server to send a keep alive to the client every 10
2630 seconds. If 30 consecutive keepalives are sent without a response (a
2631 time of 300 seconds), the server's sshd process will be terminated,
2632 causing the borg serve process to terminate gracefully and release the
2633 lock on the repository.
2634 If you then run borg commands with --lock-wait 600, this gives suffi‐
2636 cient time for the borg serve processes to terminate after the SSH con‐
2637 nection is torn down after the 300 second wait for the keepalives to
2638 fail.
2639 You may, of course, modify the timeout values demonstrated above to
2641 values that suit your environment and use case.
2642
2644 borg [common options] config [options] [REPOSITORY] [NAME] [VALUE]
2645 Description
2647 This command gets and sets options in a local repository or cache con‐
2648 fig file. For security reasons, this command only works on local
2649 repositories.
2650 To delete a config value entirely, use --delete. To list the values of
2652 the configuration file or the default values, use --list. To get and
2653 existing key, pass only the key name. To set a key, pass both the key
2654 name and the new value. Keys can be specified in the format "sec‐
2655 tion.name" or simply "name"; the section will default to "repository"
2656 and "cache" for the repo and cache configs, respectively.
2657 By default, borg config manipulates the repository config file. Using
2659 --cache edits the repository cache's config file instead.
2660 NOTE:
2662 The repository & cache config files are some of the only directly
2663 manipulable parts of a repository that aren't versioned or backed
2664 up, so be careful when making changes!
2665 Examples
2667 # find cache directory
2668 $ cd ~/.cache/borg/$(borg config /path/to/repo id)
2669 # reserve some space
2671 $ borg config /path/to/repo additional_free_space 2G
2672 # make a repo append-only
2674 $ borg config /path/to/repo append_only 1
2675
2677 borg [common options] with-lock [options] REPOSITORY COMMAND [ARGS...]
2678 Description
2680 This command runs a user-specified command while the repository lock is
2681 held.
2682 It will first try to acquire the lock (make sure that no other opera‐
2684 tion is running in the repo), then execute the given command as a sub‐
2685 process and wait for its termination, release the lock and return the
2686 user command's return code as borg's return code.
2687 NOTE:
2689 If you copy a repository with the lock held, the lock will be
2690 present in the copy. Thus, before using borg on the copy from a dif‐
2691 ferent host, you need to use "borg break-lock" on the copied reposi‐
2692 tory, because Borg is cautious and does not automatically remove
2693 stale locks made by a different host.
2694
2696 borg [common options] break-lock [options] [REPOSITORY]
2697 Description
2699 This command breaks the repository and cache locks. Please use care‐
2700 fully and only while no borg process (on any machine) is trying to ac‐
2701 cess the Cache or the Repository.
2702
2704 borg [common options] benchmark crud [options] REPOSITORY PATH
2705 Description
2707 This command benchmarks borg CRUD (create, read, update, delete) opera‐
2708 tions.
2709 It creates input data below the given PATH and backups this data into
2711 the given REPO. The REPO must already exist (it could be a fresh empty
2712 repo or an existing repo, the command will create / read / update /
2713 delete some archives named borg-benchmark-crud* there.
2714 Make sure you have free space there, you'll need about 1GB each (+
2716 overhead).
2717 If your repository is encrypted and borg needs a passphrase to unlock
2719 the key, use:
2720 BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
2722 Measurements are done with different input file sizes and counts. The
2724 file contents are very artificial (either all zero or all random), thus
2725 the measurement results do not necessarily reflect performance with
2726 real data. Also, due to the kind of content used, no compression is
2727 used in these benchmarks.
2728 C- == borg create (1st archive creation, no compression, do not use
2730 files cache)
2731 C-Z- == all-zero files. full dedup, this is primarily measuring
2732 reader/chunker/hasher. C-R- == random files. no dedup, measur‐
2733 ing throughput through all processing stages.
2734 R- == borg extract (extract archive, dry-run, do everything, but do not
2736 write files to disk)
2737 R-Z- == all zero files. Measuring heavily duplicated files.
2738 R-R- == random files. No duplication here, measuring throughput
2739 through all processing stages, except writing to disk.
2740 U- == borg create (2nd archive creation of unchanged input files, mea‐
2742 sure files cache speed)
2743 The throughput value is kind of virtual here, it does not actu‐
2744 ally read the file. U-Z- == needs to check the 2 all-zero
2745 chunks' existence in the repo. U-R- == needs to check existence
2746 of a lot of different chunks in the repo.
2747 D- == borg delete archive (delete last remaining archive, measure dele‐
2749 tion + compaction)
2750 D-Z- == few chunks to delete / few segments to compact/remove.
2751 D-R- == many chunks to delete / many segments to compact/remove.
2752 Please note that there might be quite some variance in these measure‐
2754 ments. Try multiple measurements and having a otherwise idle machine
2755 (and network, if you use it).
2756
2758 borg help patterns
2759 The path/filenames used as input for the pattern matching start from
2760 the currently active recursion root. You usually give the recursion
2761 root(s) when invoking borg and these can be either relative or absolute
2762 paths.
2763 If you give /absolute/ as root, the paths going into the matcher will
2765 look relative like absolute/.../file.ext, because file paths in Borg
2766 archives are always stored normalized and relative. This means that
2767 e.g. borg create /path/to/repo ../some/path will store all files as
2768 some/path/.../file.ext and borg create /path/to/repo /home/user will
2769 store all files as home/user/.../file.ext.
2770 A directory exclusion pattern can end either with or without a slash
2772 ('/'). If it ends with a slash, such as some/path/, the directory will
2773 be included but not its content. If it does not end with a slash, such
2774 as some/path, both the directory and content will be excluded.
2775 File patterns support these styles: fnmatch, shell, regular expres‐
2777 sions, path prefixes and path full-matches. By default, fnmatch is used
2778 for --exclude patterns and shell-style is used for the --pattern op‐
2779 tion. For commands that support patterns in their PATH argument like
2780 (borg list), the default pattern is path prefix.
2781 Starting with Borg 1.2, discovered fs paths are normalised, have lead‐
2783 ing slashes removed and then are matched against your patterns. Note:
2784 You need to review your include / exclude patterns and make sure they
2785 do not expect leading slashes. Borg can only deal with this for some
2786 very simple patterns by removing leading slashes there also.
2787 If followed by a colon (':') the first two characters of a pattern are
2789 used as a style selector. Explicit style selection is necessary when a
2790 non-default style is desired or when the desired pattern starts with
2791 two alphanumeric characters followed by a colon (i.e. aa:something/*).
2792 Fnmatch, selector fm:
2794 This is the default style for --exclude and --exclude-from.
2795 These patterns use a variant of shell pattern syntax, with '*'
2796 matching any number of characters, '?' matching any single char‐
2797 acter, '[...]' matching any single character specified, includ‐
2798 ing ranges, and '[!...]' matching any character not specified.
2799 For the purpose of these patterns, the path separator (backslash
2800 for Windows and '/' on other systems) is not treated specially.
2801 Wrap meta-characters in brackets for a literal match (i.e. [?]
2802 to match the literal character ?). For a path to match a pat‐
2803 tern, the full path must match, or it must match from the start
2804 of the full path to just before a path separator. Except for the
2805 root path, paths will never end in the path separator when
2806 matching is attempted. Thus, if a given pattern ends in a path
2807 separator, a '*' is appended before matching is attempted. A
2808 leading path separator is always removed.
2809 Shell-style patterns, selector sh:
2811 This is the default style for --pattern and --patterns-from.
2812 Like fnmatch patterns these are similar to shell patterns. The
2813 difference is that the pattern may include **/ for matching zero
2814 or more directory levels, * for matching zero or more arbitrary
2815 characters with the exception of any path separator. A leading
2816 path separator is always removed.
2817 Regular expressions, selector re:
2819 Regular expressions similar to those found in Perl are sup‐
2820 ported. Unlike shell patterns regular expressions are not re‐
2821 quired to match the full path and any substring match is suffi‐
2822 cient. It is strongly recommended to anchor patterns to the
2823 start ('^'), to the end ('$') or both. Path separators (back‐
2824 slash for Windows and '/' on other systems) in paths are always
2825 normalized to a forward slash ('/') before applying a pattern.
2826 The regular expression syntax is described in the Python docu‐
2827 mentation for the re module.
2828 Path prefix, selector pp:
2830 This pattern style is useful to match whole sub-directories. The
2831 pattern pp:root/somedir matches root/somedir and everything
2832 therein. A leading path separator is always removed.
2833 Path full-match, selector pf:
2835 This pattern style is (only) useful to match full paths. This
2836 is kind of a pseudo pattern as it can not have any variable or
2837 unspecified parts - the full path must be given.
2838 pf:root/file.ext matches root/file.ext only. A leading path sep‐
2839 arator is always removed.
2840 Implementation note: this is implemented via very time-efficient
2842 O(1) hashtable lookups (this means you can have huge amounts of
2843 such patterns without impacting performance much). Due to that,
2844 this kind of pattern does not respect any context or order. If
2845 you use such a pattern to include a file, it will always be in‐
2846 cluded (if the directory recursion encounters it). Other in‐
2847 clude/exclude patterns that would normally match will be ig‐
2848 nored. Same logic applies for exclude.
2849 NOTE:
2851 re:, sh: and fm: patterns are all implemented on top of the Python
2852 SRE engine. It is very easy to formulate patterns for each of these
2853 types which requires an inordinate amount of time to match paths. If
2854 untrusted users are able to supply patterns, ensure they cannot sup‐
2855 ply re: patterns. Further, ensure that sh: and fm: patterns only
2856 contain a handful of wildcards at most.
2857 Exclusions can be passed via the command line option --exclude. When
2859 used from within a shell, the patterns should be quoted to protect them
2860 from expansion.
2861 The --exclude-from option permits loading exclusion patterns from a
2863 text file with one pattern per line. Lines empty or starting with the
2864 number sign ('#') after removing whitespace on both ends are ignored.
2865 The optional style selector prefix is also supported for patterns
2866 loaded from a file. Due to whitespace removal, paths with whitespace at
2867 the beginning or end can only be excluded using regular expressions.
2868 To test your exclusion patterns without performing an actual backup you
2870 can run borg create --list --dry-run ....
2871 Examples:
2873 # Exclude '/home/user/file.o' but not '/home/user/file.odt':
2875 $ borg create -e '*.o' backup /
2876 # Exclude '/home/user/junk' and '/home/user/subdir/junk' but
2878 # not '/home/user/importantjunk' or '/etc/junk':
2879 $ borg create -e 'home/*/junk' backup /
2880 # Exclude the contents of '/home/user/cache' but not the directory itself:
2882 $ borg create -e home/user/cache/ backup /
2883 # The file '/home/user/cache/important' is *not* backed up:
2885 $ borg create -e home/user/cache/ backup / /home/user/cache/important
2886 # The contents of directories in '/home' are not backed up when their name
2888 # ends in '.tmp'
2889 $ borg create --exclude 're:^home/[^/]+\.tmp/' backup /
2890 # Load exclusions from file
2892 $ cat >exclude.txt <<EOF
2893 # Comment line
2894 home/*/junk
2895 *.tmp
2896 fm:aa:something/*
2897 re:^home/[^/]+\.tmp/
2898 sh:home/*/.thumbnails
2899 # Example with spaces, no need to escape as it is processed by borg
2900 some file with spaces.txt
2901 EOF
2902 $ borg create --exclude-from exclude.txt backup /
2903 A more general and easier to use way to define filename matching pat‐
2905 terns exists with the --pattern and --patterns-from options. Using
2906 these, you may specify the backup roots (starting points) and patterns
2907 for inclusion/exclusion. A root path starts with the prefix R, fol‐
2908 lowed by a path (a plain path, not a file pattern). An include rule
2909 starts with the prefix +, an exclude rule starts with the prefix -, an
2910 exclude-norecurse rule starts with !, all followed by a pattern.
2911 NOTE:
2913 Via --pattern or --patterns-from you can define BOTH inclusion and
2914 exclusion of files using pattern prefixes + and -. With --exclude
2915 and --exclude-from ONLY excludes are defined.
2916 Inclusion patterns are useful to include paths that are contained in an
2918 excluded path. The first matching pattern is used so if an include pat‐
2919 tern matches before an exclude pattern, the file is backed up. If an
2920 exclude-norecurse pattern matches a directory, it won't recurse into it
2921 and won't discover any potential matches for include rules below that
2922 directory.
2923 NOTE:
2925 It's possible that a sub-directory/file is matched while parent di‐
2926 rectories are not. In that case, parent directories are not backed
2927 up thus their user, group, permission, etc. can not be restored.
2928 Note that the default pattern style for --pattern and --patterns-from
2930 is shell style (sh:), so those patterns behave similar to rsync in‐
2931 clude/exclude patterns. The pattern style can be set via the P prefix.
2932 Patterns (--pattern) and excludes (--exclude) from the command line are
2934 considered first (in the order of appearance). Then patterns from
2935 --patterns-from are added. Exclusion patterns from --exclude-from files
2936 are appended last.
2937 Examples:
2939 # backup pics, but not the ones from 2018, except the good ones:
2941 # note: using = is essential to avoid cmdline argument parsing issues.
2942 borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
2943 # use a file with patterns:
2945 borg create --patterns-from patterns.lst repo::arch
2946 The patterns.lst file could look like that:
2948 # "sh:" pattern style is the default, so the following line is not needed:
2950 P sh
2951 R /
2952 # can be rebuild
2953 - home/*/.cache
2954 # they're downloads for a reason
2955 - home/*/Downloads
2956 # susan is a nice person
2957 # include susans home
2958 + home/susan
2959 # also back up this exact file
2960 + pf:home/bobby/specialfile.txt
2961 # don't backup the other home directories
2962 - home/*
2963 # don't even look in /proc
2964 ! proc
2965 You can specify recursion roots either on the command line or in a pat‐
2967 ternfile:
2968 # these two commands do the same thing
2970 borg create --exclude home/bobby/junk repo::arch /home/bobby /home/susan
2971 borg create --patterns-from patternfile.lst repo::arch
2972 The patternfile:
2974 # note that excludes use fm: by default and patternfiles use sh: by default.
2976 # therefore, we need to specify fm: to have the same exact behavior.
2977 P fm
2978 R /home/bobby
2979 R /home/susan
2980 - home/bobby/junk
2982 This allows you to share the same patterns between multiple reposito‐
2984 ries without needing to specify them on the command line.
2985 borg help placeholders
2987 Repository (or Archive) URLs, --prefix, --glob-archives, --comment and
2988 --remote-path values support these placeholders:
2989 {hostname}
2991 The (short) hostname of the machine.
2992 {fqdn} The full name of the machine.
2994 {reverse-fqdn}
2996 The full name of the machine in reverse domain name notation.
2997 {now} The current local date and time, by default in ISO-8601 format.
2999 You can also supply your own format string, e.g.
3000 {now:%Y-%m-%d_%H:%M:%S}
3001 {utcnow}
3003 The current UTC date and time, by default in ISO-8601 format.
3004 You can also supply your own format string, e.g. {utc‐
3005 now:%Y-%m-%d_%H:%M:%S}
3006 {user} The user name (or UID, if no name is available) of the user run‐
3008 ning borg.
3009 {pid} The current process ID.
3011 {borgversion}
3013 The version of borg, e.g.: 1.0.8rc1
3014 {borgmajor}
3016 The version of borg, only the major version, e.g.: 1
3017 {borgminor}
3019 The version of borg, only major and minor version, e.g.: 1.0
3020 {borgpatch}
3022 The version of borg, only major, minor and patch version, e.g.:
3023 1.0.8
3024 If literal curly braces need to be used, double them for escaping:
3026 borg create /path/to/repo::{{literal_text}}
3028 Examples:
3030 borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
3032 borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
3033 borg prune --prefix '{hostname}-' ...
3034 NOTE:
3036 systemd uses a difficult, non-standard syntax for command lines in
3037 unit files (refer to the systemd.unit(5) manual page).
3038 When invoking borg from unit files, pay particular attention to es‐
3040 caping, especially when using the now/utcnow placeholders, since
3041 systemd performs its own %-based variable replacement even in quoted
3042 text. To avoid interference from systemd, double all percent signs
3043 ({hostname}-{now:%Y-%m-%d_%H:%M:%S} becomes {host‐
3044 name}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}).
3045 borg help compression
3047 It is no problem to mix different compression methods in one repo,
3048 deduplication is done on the source data chunks (not on the compressed
3049 or encrypted data).
3050 If some specific chunk was once compressed and stored into the repo,
3052 creating another backup that also uses this chunk will not change the
3053 stored chunk. So if you use different compression specs for the back‐
3054 ups, whichever stores a chunk first determines its compression. See
3055 also borg recreate.
3056 Compression is lz4 by default. If you want something else, you have to
3058 specify what you want.
3059 Valid compression specifiers are:
3061 none Do not compress.
3063 lz4 Use lz4 compression. Very high speed, very low compression. (de‐
3065 fault)
3066 zstd[,L]
3068 Use zstd ("zstandard") compression, a modern wide-range algo‐
3069 rithm. If you do not explicitly give the compression level L
3070 (ranging from 1 to 22), it will use level 3. Archives com‐
3071 pressed with zstd are not compatible with borg < 1.1.4.
3072 zlib[,L]
3074 Use zlib ("gz") compression. Medium speed, medium compression.
3075 If you do not explicitly give the compression level L (ranging
3076 from 0 to 9), it will use level 6. Giving level 0 (means "no
3077 compression", but still has zlib protocol overhead) is usually
3078 pointless, you better use "none" compression.
3079 lzma[,L]
3081 Use lzma ("xz") compression. Low speed, high compression. If
3082 you do not explicitly give the compression level L (ranging from
3083 0 to 9), it will use level 6. Giving levels above 6 is point‐
3084 less and counterproductive because it does not compress better
3085 due to the buffer size used by borg - but it wastes lots of CPU
3086 cycles and RAM.
3087 auto,C[,L]
3089 Use a built-in heuristic to decide per chunk whether to compress
3090 or not. The heuristic tries with lz4 whether the data is com‐
3091 pressible. For incompressible data, it will not use compression
3092 (uses "none"). For compressible data, it uses the given C[,L]
3093 compression - with C[,L] being any valid compression specifier.
3094 obfuscate,SPEC,C[,L]
3096 Use compressed-size obfuscation to make fingerprinting attacks
3097 based on the observable stored chunk size more difficult. Note:
3098 - you must combine this with encryption or it won't make any
3099 sense. - your repo size will be bigger, of course.
3100 The SPEC value will determine how the size obfuscation will
3102 work:
3103 Relative random reciprocal size variation: Size will increase by
3105 a factor, relative to the compressed data size. Smaller factors
3106 are often used, larger factors rarely. 1: factor 0.01 .. 100.0
3107 2: factor 0.1 .. 1000.0 3: factor 1.0 .. 10000.0 4: factor 10.0
3108 .. 100000.0 5: factor 100.0 .. 1000000.0 6: factor 1000.0 ..
3109 10000000.0
3110 Add a randomly sized padding up to the given size: 110: 1kiB ...
3112 120: 1MiB ... 123: 8MiB (max.)
3113 Examples:
3115 borg create --compression lz4 REPO::ARCHIVE data
3117 borg create --compression zstd REPO::ARCHIVE data
3118 borg create --compression zstd,10 REPO::ARCHIVE data
3119 borg create --compression zlib REPO::ARCHIVE data
3120 borg create --compression zlib,1 REPO::ARCHIVE data
3121 borg create --compression auto,lzma,6 REPO::ARCHIVE data
3122 borg create --compression auto,lzma ...
3123 borg create --compression obfuscate,3,none ...
3124 borg create --compression obfuscate,3,auto,zstd,10 ...
3125 borg create --compression obfuscate,2,zstd,6 ...
3126
3128 There is a borg debug command that has some subcommands which are all
3129 not intended for normal use and potentially very dangerous if used in‐
3130 correctly.
3131 For example, borg debug put-obj and borg debug delete-obj will only do
3133 what their name suggests: put objects into repo / delete objects from
3134 repo.
3135 Please note:
3137 • they will not update the chunks cache (chunks index) about the object
3139 • they will not update the manifest (so no automatic chunks index
3141 resync is triggered)
3142 • they will not check whether the object is in use (e.g. before
3144 delete-obj)
3145 • they will not update any metadata which may point to the object
3147 They exist to improve debugging capabilities without direct system ac‐
3149 cess, e.g. in case you ever run into some severe malfunction. Use them
3150 only if you know what you are doing or if a trusted Borg developer
3151 tells you what to do.
3152 Borg has a --debug-topic TOPIC option to enable specific debugging mes‐
3154 sages. Topics are generally not documented.
3155 A --debug-profile FILE option exists which writes a profile of the main
3157 program's execution to a file. The format of these files is not di‐
3158 rectly compatible with the Python profiling tools, since these use the
3159 "marshal" format, which is not intended to be secure (quoting the
3160 Python docs: "Never unmarshal data received from an untrusted or unau‐
3161 thenticated source.").
3162 The borg debug profile-convert command can be used to take a Borg pro‐
3164 file and convert it to a profile file that is compatible with the
3165 Python tools.
3166 Additionally, if the filename specified for --debug-profile ends with
3168 ".pyprof" a Python compatible profile is generated. This is only in‐
3169 tended for local use by developers.
3170
3172 Here are misc. notes about topics that are maybe not covered in enough
3173 detail in the usage section.
3174 --chunker-params
3176 The chunker params influence how input files are cut into pieces
3177 (chunks) which are then considered for deduplication. They also have a
3178 big impact on resource usage (RAM and disk space) as the amount of re‐
3179 sources needed is (also) determined by the total amount of chunks in
3180 the repository (see cache-memory-usage for details).
3181 --chunker-params=buzhash,10,23,16,4095 results in a fine-grained dedu‐
3183 plication| and creates a big amount of chunks and thus uses a lot of
3184 resources to manage them. This is good for relatively small data vol‐
3185 umes and if the machine has a good amount of free RAM and disk space.
3186 --chunker-params=buzhash,19,23,21,4095 (default) results in a
3188 coarse-grained deduplication and creates a much smaller amount of
3189 chunks and thus uses less resources. This is good for relatively big
3190 data volumes and if the machine has a relatively low amount of free RAM
3191 and disk space.
3192 --chunker-params=fixed,4194304 results in fixed 4MiB sized block dedu‐
3194 plication and is more efficient than the previous example when used for
3195 for block devices (like disks, partitions, LVM LVs) or raw disk image
3196 files.
3197 --chunker-params=fixed,4096,512 results in fixed 4kiB sized blocks, but
3199 the first header block will only be 512B long. This might be useful to
3200 dedup files with 1 header + N fixed size data blocks. Be careful to not
3201 produce a too big amount of chunks (like using small block size for
3202 huge files).
3203 If you already have made some archives in a repository and you then
3205 change chunker params, this of course impacts deduplication as the
3206 chunks will be cut differently.
3207 In the worst case (all files are big and were touched in between back‐
3209 ups), this will store all content into the repository again.
3210 Usually, it is not that bad though:
3212 • usually most files are not touched, so it will just re-use the old
3214 chunks it already has in the repo
3215 • files smaller than the (both old and new) minimum chunksize result in
3217 only one chunk anyway, so the resulting chunks are same and dedupli‐
3218 cation will apply
3219 If you switch chunker params to save resources for an existing repo
3221 that already has some backup archives, you will see an increasing ef‐
3222 fect over time, when more and more files have been touched and stored
3223 again using the bigger chunksize and all references to the smaller
3224 older chunks have been removed (by deleting / pruning archives).
3225 If you want to see an immediate big effect on resource usage, you bet‐
3227 ter start a new repository when changing chunker params.
3228 For more details, see chunker_details.
3230 --noatime / --noctime
3232 You can use these borg create options to not store the respective time‐
3233 stamp into the archive, in case you do not really need it.
3234 Besides saving a little space for the not archived timestamp, it might
3236 also affect metadata stream deduplication: if only this timestamp
3237 changes between backups and is stored into the metadata stream, the
3238 metadata stream chunks won't deduplicate just because of that.
3239 --nobsdflags / --noflags
3241 You can use this to not query and store (or not extract and set) flags
3242 - in case you don't need them or if they are broken somehow for your
3243 fs.
3244 On Linux, dealing with the flags needs some additional syscalls. Espe‐
3246 cially when dealing with lots of small files, this causes a noticeable
3247 overhead, so you can use this option also for speeding up operations.
3248 --umask
3250 borg uses a safe default umask of 077 (that means the files borg cre‐
3251 ates have only permissions for owner, but no permissions for group and
3252 others) - so there should rarely be a need to change the default behav‐
3253 iour.
3254 This option only affects the process to which it is given. Thus, when
3256 you run borg in client/server mode and you want to change the behaviour
3257 on the server side, you need to use borg serve --umask=XXX ... as a ssh
3258 forced command in authorized_keys. The --umask value given on the
3259 client side is not transferred to the server side.
3260 Also, if you choose to use the --umask option, always be consistent and
3262 use the same umask value so you do not create a mixup of permissions in
3263 a borg repository or with other files borg creates.
3264 --read-special
3266 The --read-special option is special - you do not want to use it for
3267 normal full-filesystem backups, but rather after carefully picking some
3268 targets for it.
3269 The option --read-special triggers special treatment for block and char
3271 device files as well as FIFOs. Instead of storing them as such a device
3272 (or FIFO), they will get opened, their content will be read and in the
3273 backup archive they will show up like a regular file.
3274 Symlinks will also get special treatment if (and only if) they point to
3276 such a special file: instead of storing them as a symlink, the target
3277 special file will get processed as described above.
3278 One intended use case of this is backing up the contents of one or mul‐
3280 tiple block devices, like e.g. LVM snapshots or inactive LVs or disk
3281 partitions.
3282 You need to be careful about what you include when using --read-spe‐
3284 cial, e.g. if you include /dev/zero, your backup will never terminate.
3285 Restoring such files' content is currently only supported one at a time
3287 via --stdout option (and you have to redirect stdout to where ever it
3288 shall go, maybe directly into an existing device file of your choice or
3289 indirectly via dd).
3290 To some extent, mounting a backup archive with the backups of special
3292 files via borg mount and then loop-mounting the image files from inside
3293 the mount point will work. If you plan to access a lot of data in
3294 there, it likely will scale and perform better if you do not work via
3295 the FUSE mount.
3296 Example
3298 Imagine you have made some snapshots of logical volumes (LVs) you want
3299 to backup.
3300 NOTE:
3302 For some scenarios, this is a good method to get "crash-like" con‐
3303 sistency (I call it crash-like because it is the same as you would
3304 get if you just hit the reset button or your machine would abruptly
3305 and completely crash). This is better than no consistency at all
3306 and a good method for some use cases, but likely not good enough if
3307 you have databases running.
3308 Then you create a backup archive of all these snapshots. The backup
3310 process will see a "frozen" state of the logical volumes, while the
3311 processes working in the original volumes continue changing the data
3312 stored there.
3313 You also add the output of lvdisplay to your backup, so you can see the
3315 LV sizes in case you ever need to recreate and restore them.
3316 After the backup has completed, you remove the snapshots again.
3318 $ # create snapshots here
3320 $ lvdisplay > lvdisplay.txt
3321 $ borg create --read-special /path/to/repo::arch lvdisplay.txt /dev/vg0/*-snapshot
3322 $ # remove snapshots here
3323 Now, let's see how to restore some LVs from such a backup.
3325 $ borg extract /path/to/repo::arch lvdisplay.txt
3327 $ # create empty LVs with correct sizes here (look into lvdisplay.txt).
3328 $ # we assume that you created an empty root and home LV and overwrite it now:
3329 $ borg extract --stdout /path/to/repo::arch dev/vg0/root-snapshot > /dev/vg0/root
3330 $ borg extract --stdout /path/to/repo::arch dev/vg0/home-snapshot > /dev/vg0/home
3331 Separate compaction
3333 Borg does not auto-compact the segment files in the repository at com‐
3334 mit time (at the end of each repository-writing command) any more.
3335 This is new since borg 1.2.0 and requires borg >= 1.2.0 on client and
3337 server.
3338 This causes a similar behaviour of the repository as if it was in ap‐
3340 pend-only mode (see below) most of the time (until borg compact is in‐
3341 voked or an old client triggers auto-compaction).
3342 This has some notable consequences:
3344 • repository space is not freed immediately when deleting / pruning ar‐
3346 chives
3347 • commands finish quicker
3349 • repository is more robust and might be easier to recover after dam‐
3351 ages (as it contains data in a more sequential manner, historic mani‐
3352 fests, multiple commits - until you run borg compact)
3353 • user can choose when to run compaction (it should be done regularly,
3355 but not necessarily after each single borg command)
3356 • user can choose from where to invoke borg compact to do the com‐
3358 paction (from client or from server, it does not need a key)
3359 • less repo sync data traffic in case you create a copy of your reposi‐
3361 tory by using a sync tool (like rsync, rclone, ...)
3362 You can manually run compaction by invoking the borg compact command.
3364 Append-only mode (forbid compaction)
3366 A repository can be made "append-only", which means that Borg will
3367 never overwrite or delete committed data (append-only refers to the
3368 segment files, but borg will also reject to delete the repository com‐
3369 pletely).
3370 If borg compact command is used on a repo in append-only mode, there
3372 will be no warning or error, but no compaction will happen.
3373 append-only is useful for scenarios where a backup client machine back‐
3375 ups remotely to a backup server using borg serve, since a hacked client
3376 machine cannot delete backups on the server permanently.
3377 To activate append-only mode, set append_only to 1 in the repository
3379 config:
3380 borg config /path/to/repo append_only 1
3382 Note that you can go back-and-forth between normal and append-only op‐
3384 eration with borg config; it's not a "one way trip."
3385 In append-only mode Borg will create a transaction log in the transac‐
3387 tions file, where each line is a transaction and a UTC timestamp.
3388 In addition, borg serve can act as if a repository is in append-only
3390 mode with its option --append-only. This can be very useful for
3391 fine-tuning access control in .ssh/authorized_keys:
3392 command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustable backup clients>
3394 command="borg serve ..." ssh-rsa <key used for backup management>
3395 Running borg init via a borg serve --append-only server will not create
3397 an append-only repository. Running borg init --append-only creates an
3398 append-only repository regardless of server settings.
3399 Example
3401 Suppose an attacker remotely deleted all backups, but your repository
3402 was in append-only mode. A transaction log in this situation might look
3403 like this:
3404 transaction 1, UTC time 2016-03-31T15:53:27.383532
3406 transaction 5, UTC time 2016-03-31T15:53:52.588922
3407 transaction 11, UTC time 2016-03-31T15:54:23.887256
3408 transaction 12, UTC time 2016-03-31T15:55:54.022540
3409 transaction 13, UTC time 2016-03-31T15:55:55.472564
3410 From your security logs you conclude the attacker gained access at
3412 15:54:00 and all the backups where deleted or replaced by compromised
3413 backups. From the log you know that transactions 11 and later are com‐
3414 promised. Note that the transaction ID is the name of the last file in
3415 the transaction. For example, transaction 11 spans files 6 to 11.
3416 In a real attack you'll likely want to keep the compromised repository
3418 intact to analyze what the attacker tried to achieve. It's also a good
3419 idea to make this copy just in case something goes wrong during the re‐
3420 covery. Since recovery is done by deleting some files, a hard link copy
3421 (cp -al) is sufficient.
3422 The first step to reset the repository to transaction 5, the last un‐
3424 compromised transaction, is to remove the hints.N, index.N and integ‐
3425 rity.N files in the repository (these files are always expendable). In
3426 this example N is 13.
3427 Then remove or move all segment files from the segment directories in
3429 data/ starting with file 6:
3430 rm data/**/{6..13}
3432 That's all to do in the repository.
3434 If you want to access this rollbacked repository from a client that al‐
3436 ready has a cache for this repository, the cache will reflect a newer
3437 repository state than what you actually have in the repository now, af‐
3438 ter the rollback.
3439 Thus, you need to clear the cache:
3441 borg delete --cache-only repo
3443 The cache will get rebuilt automatically. Depending on repo size and
3445 archive count, it may take a while.
3446 You also will need to remove ~/.config/borg/security/REPOID/mani‐
3448 fest-timestamp.
3449 Drawbacks
3451 As data is only appended, and nothing removed, commands like prune or
3452 delete won't free disk space, they merely tag data as deleted in a new
3453 transaction.
3454 Be aware that as soon as you write to the repo in non-append-only mode
3456 (e.g. prune, delete or create archives from an admin machine), it will
3457 remove the deleted objects permanently (including the ones that were
3458 already marked as deleted, but not removed, in append-only mode). Auto‐
3459 mated edits to the repository (such as a cron job running borg prune)
3460 will render append-only mode moot if data is deleted.
3461 Even if an archive appears to be available, it is possible an attacker
3463 could delete just a few chunks from an archive and silently corrupt its
3464 data. While in append-only mode, this is reversible, but borg check
3465 should be run before a writing/pruning operation on an append-only
3466 repository to catch accidental or malicious corruption:
3467 # run without append-only mode
3469 borg check --verify-data repo && borg compact repo
3470 Aside from checking repository & archive integrity you may want to also
3472 manually check backups to ensure their content seems correct.
3473 Further considerations
3475 Append-only mode is not respected by tools other than Borg. rm still
3476 works on the repository. Make sure that backup client machines only get
3477 to access the repository via borg serve.
3478 Ensure that no remote access is possible if the repository is temporar‐
3480 ily set to normal mode for e.g. regular pruning.
3481 Further protections can be implemented, but are outside of Borg's
3483 scope. For example, file system snapshots or wrapping borg serve to set
3484 special permissions or ACLs on new data files.
3485 SSH batch mode
3487 When running Borg using an automated script, ssh might still ask for a
3488 password, even if there is an SSH key for the target server. Use this
3489 to make scripts more robust:
3490 export BORG_RSH='ssh -oBatchMode=yes'
3492
3494 The Borg Collective (see AUTHORS file)
3495
3497 2010-2022 Jonas Borgström, 2015-2022 The Borg Collective (see AUTHORS
3498 file)
34991.2.1 2022-06-06 BORG(1)