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: It always chunks all my files, even unchanged ones!
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 authenticated_no_key
329 Work around a lost passphrase or key for an au‐
330 thenticated mode repository (these are only au‐
331 thenticated, but not encrypted). If the key is
332 missing in the repository config, add key = any‐
333 thing there.
334 This workaround is only for emergencies and only
336 to extract data from an affected repository
337 (read-only access):
338 BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
340 After you have extracted all data you need, you
342 MUST delete the repository:
343 BORG_WORKAROUNDS=authenticated_no_key borg delete repo
345 Now you can init a fresh repo. Make sure you do
347 not use the workaround any more.
348 ignore_invalid_archive_tam
350 Work around invalid archive TAMs created by borg <
351 1.2.5, see #7791.
352 This workaround likely needs to get used only once
354 when following the upgrade instructions for
355 CVE-2023-36811, see Pre-1.2.5 archives spoofing
356 vulnerability (CVE-2023-36811).
357 In normal production operations, this workaround
359 should never be used.
360 Some automatic "answerers" (if set, they automatically answer confirma‐
362 tion questions):
363 BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
365 For "Warning: Attempting to access a previously unknown
366 unencrypted repository"
367 BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
369 For "Warning: The repository at location ... was previ‐
370 ously located at ..."
371 BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
373 For "This is a potentially dangerous function..." (check
374 --repair)
375 BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
377 For "You requested to completely DELETE the repository
378 including all archives it contains:"
379 Note: answers are case sensitive. setting an invalid answer
381 value might either give the default answer or ask you interac‐
382 tively, depending on whether retries are allowed (they by de‐
383 fault are allowed). So please test your scripts interactively
384 before making them a non-interactive script.
385 Directories and files:
387 BORG_BASE_DIR
389 Defaults to $HOME or ~$USER or ~ (in that order). If you
390 want to move all borg-specific folders to a custom path
391 at once, all you need to do is to modify BORG_BASE_DIR:
392 the other paths for cache, config etc. will adapt accord‐
393 ingly (assuming you didn't set them to a different custom
394 value).
395 BORG_CACHE_DIR
397 Defaults to $BORG_BASE_DIR/.cache/borg. If BORG_BASE_DIR
398 is not explicitly set while XDG env var XDG_CACHE_HOME is
399 set, then $XDG_CACHE_HOME/borg is being used instead.
400 This directory contains the local cache and might need a
401 lot of space for dealing with big repositories. Make sure
402 you're aware of the associated security aspects of the
403 cache location: Do I need to take security precautions
404 regarding the cache?
405 BORG_CONFIG_DIR
407 Defaults to $BORG_BASE_DIR/.config/borg. If BORG_BASE_DIR
408 is not explicitly set while XDG env var XDG_CONFIG_HOME
409 is set, then $XDG_CONFIG_HOME/borg is being used instead.
410 This directory contains all borg configuration directo‐
411 ries, see the FAQ for a security advisory about the data
412 in this directory: How important is the $HOME/.con‐
413 fig/borg directory?
414 BORG_SECURITY_DIR
416 Defaults to $BORG_CONFIG_DIR/security. This directory
417 contains information borg uses to track its usage of
418 NONCES ("numbers used once" - usually in encryption con‐
419 text) and other security relevant data.
420 BORG_KEYS_DIR
422 Defaults to $BORG_CONFIG_DIR/keys. This directory con‐
423 tains keys for encrypted repositories.
424 BORG_KEY_FILE
426 When set, use the given path as repository key file.
427 Please note that this is only for rather special applica‐
428 tions that externally fully manage the key files:
429 • this setting only applies to the keyfile modes (not to
431 the repokey modes).
432 • using a full, absolute path to the key file is recom‐
434 mended.
435 • all directories in the given path must exist.
437 • this setting forces borg to use the key file at the
439 given location.
440 • the key file must either exist (for most commands) or
442 will be created (borg init).
443 • you need to give a different path for different reposi‐
445 tories.
446 • you need to point to the correct key file matching the
448 repository the command will operate on.
449 TMPDIR This is where temporary files are stored (might need a
451 lot of temporary space for some operations), see tempfile
452 for details.
453 Building:
455 BORG_OPENSSL_PREFIX
457 Adds given OpenSSL header file directory to the default
458 locations (setup.py).
459 BORG_LIBLZ4_PREFIX
461 Adds given prefix directory to the default locations. If
462 a 'include/lz4.h' is found Borg will be linked against
463 the system liblz4 instead of a bundled implementation.
464 (setup.py)
465 BORG_LIBZSTD_PREFIX
467 Adds given prefix directory to the default locations. If
468 a 'include/zstd.h' is found Borg will be linked against
469 the system libzstd instead of a bundled implementation.
470 (setup.py)
471 Please note:
473 • Be very careful when using the "yes" sayers, the warnings with prompt
475 exist for your / your data's security/safety.
476 • Also be very careful when putting your passphrase into a script, make
478 sure it has appropriate file permissions (e.g. mode 600, root:root).
479 File systems
481 We strongly recommend against using Borg (or any other database-like
482 software) on non-journaling file systems like FAT, since it is not pos‐
483 sible to assume any consistency in case of power failures (or a sudden
484 disconnect of an external drive or similar failures).
485 While Borg uses a data store that is resilient against these failures
487 when used on journaling file systems, it is not possible to guarantee
488 this with some hardware -- independent of the software used. We don't
489 know a list of affected hardware.
490 If you are suspicious whether your Borg repository is still consistent
492 and readable after one of the failures mentioned above occurred, run
493 borg check --verify-data to make sure it is consistent.
494 Requirements for Borg repository file systems
496 • Long file names
498 • At least three directory levels with short names
500 • Typically, file sizes up to a few hundred MB. Large repositories may
502 require large files (>2 GB).
503 • Up to 1000 files per directory (10000 for repositories initialized
505 with Borg 1.0)
506 • rename(2) / MoveFile(Ex) should work as specified, i.e. on the same
508 file system it should be a move (not a copy) operation, and in case
509 of a directory it should fail if the destination exists and is not an
510 empty directory, since this is used for locking.
511 • Hardlinks are needed for borg upgrade (if --inplace option is not
513 used). Also hardlinks are used for more safe and secure file updat‐
514 ing (e.g. of the repo config file), but the code tries to work also
515 if hardlinks are not supported.
516 Units
518 To display quantities, Borg takes care of respecting the usual conven‐
519 tions of scale. Disk sizes are displayed in decimal, using powers of
520 ten (so kB means 1000 bytes). For memory usage, binary prefixes are
521 used, and are indicated using the IEC binary prefixes, using powers of
522 two (so KiB means 1024 bytes).
523 Date and Time
525 We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and
526 HH:MM:SS (24h clock).
527 For more information about that, see: https://xkcd.com/1179/
529 Unless otherwise noted, we display local date and time. Internally, we
531 store and process date and time as UTC.
532 Resource Usage
534 Borg might use a lot of resources depending on the size of the data set
535 it is dealing with.
536 If one uses Borg in a client/server way (with a ssh: repository), the
538 resource usage occurs in part on the client and in another part on the
539 server.
540 If one uses Borg as a single process (with a filesystem repo), all the
542 resource usage occurs in that one process, so just add up client +
543 server to get the approximate resource usage.
544 CPU client:
546 • borg create: does chunking, hashing, compression, crypto (high
548 CPU usage)
549 • chunks cache sync: quite heavy on CPU, doing lots of hashtable
551 operations.
552 • borg extract: crypto, decompression (medium to high CPU usage)
554 • borg check: similar to extract, but depends on options given.
556 • borg prune / borg delete archive: low to medium CPU usage
558 • borg delete repo: done on the server
560 It won't go beyond 100% of 1 core as the code is currently sin‐
562 gle-threaded. Especially higher zlib and lzma compression lev‐
563 els use significant amounts of CPU cycles. Crypto might be cheap
564 on the CPU (if hardware accelerated) or expensive (if not).
565 CPU server:
567 It usually doesn't need much CPU, it just deals with the
568 key/value store (repository) and uses the repository index for
569 that.
570 borg check: the repository check computes the checksums of all
572 chunks (medium CPU usage) borg delete repo: low CPU usage
573 CPU (only for client/server operation):
575 When using borg in a client/server way with a ssh:-type repo,
576 the ssh processes used for the transport layer will need some
577 CPU on the client and on the server due to the crypto they are
578 doing - esp. if you are pumping big amounts of data.
579 Memory (RAM) client:
581 The chunks index and the files index are read into memory for
582 performance reasons. Might need big amounts of memory (see be‐
583 low). Compression, esp. lzma compression with high levels might
584 need substantial amounts of memory.
585 Memory (RAM) server:
587 The server process will load the repository index into memory.
588 Might need considerable amounts of memory, but less than on the
589 client (see below).
590 Chunks index (client only):
592 Proportional to the amount of data chunks in your repo. Lots of
593 chunks in your repo imply a big chunks index. It is possible to
594 tweak the chunker params (see create options).
595 Files index (client only):
597 Proportional to the amount of files in your last backups. Can be
598 switched off (see create options), but next backup might be much
599 slower if you do. The speed benefit of using the files cache is
600 proportional to file size.
601 Repository index (server only):
603 Proportional to the amount of data chunks in your repo. Lots of
604 chunks in your repo imply a big repository index. It is possi‐
605 ble to tweak the chunker params (see create options) to influ‐
606 ence the amount of chunks being created.
607 Temporary files (client):
609 Reading data and metadata from a FUSE mounted repository will
610 consume up to the size of all deduplicated, small chunks in the
611 repository. Big chunks won't be locally cached.
612 Temporary files (server):
614 A non-trivial amount of data will be stored on the remote temp
615 directory for each client that connects to it. For some remotes,
616 this can fill the default temporary directory at /tmp. This can
617 be remediated by ensuring the $TMPDIR, $TEMP, or $TMP environ‐
618 ment variable is properly set for the sshd process. For some
619 OSes, this can be done just by setting the correct value in the
620 .bashrc (or equivalent login config file for other shells), how‐
621 ever in other cases it may be necessary to first enable Permi‐
622 tUserEnvironment yes in your sshd_config file, then add environ‐
623 ment="TMPDIR=/my/big/tmpdir" at the start of the public key to
624 be used in the authorized_hosts file.
625 Cache files (client only):
627 Contains the chunks index and files index (plus a collection of
628 single- archive chunk indexes which might need huge amounts of
629 disk space, depending on archive count and size - see FAQ about
630 how to reduce).
631 Network (only for client/server operation):
633 If your repository is remote, all deduplicated (and optionally
634 compressed/ encrypted) data of course has to go over the connec‐
635 tion (ssh:// repo url). If you use a locally mounted network
636 filesystem, additionally some copy operations used for transac‐
637 tion support also go over the connection. If you backup multiple
638 sources to one target repository, additional traffic happens for
639 cache resynchronization.
640 Support for file metadata
642 Besides regular file and directory structures, Borg can preserve
643 • symlinks (stored as symlink, the symlink is not followed)
645 • special files:
647 • character and block device files (restored via mknod)
649 • FIFOs ("named pipes")
651 • special file contents can be backed up in --read-special mode. By
653 default the metadata to create them with mknod(2), mkfifo(2) etc.
654 is stored.
655 • hardlinked regular files, devices, FIFOs (considering all items in
657 the same archive)
658 • timestamps in nanosecond precision: mtime, atime, ctime
660 • other timestamps: birthtime (on platforms supporting it)
662 • permissions:
664 • IDs of owning user and owning group
666 • names of owning user and owning group (if the IDs can be resolved)
668 • Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky)
670 On some platforms additional features are supported:
672 ┌─────────────────┬──────────┬───────────┬───────────┐
674 │Platform │ ACLs [5] │ xattr [6] │ Flags [7] │
675 ├─────────────────┼──────────┼───────────┼───────────┤
676 │Linux │ Yes │ Yes │ Yes [1] │
677 ├─────────────────┼──────────┼───────────┼───────────┤
678 │Mac OS X │ Yes │ Yes │ Yes (all) │
679 ├─────────────────┼──────────┼───────────┼───────────┤
680 │FreeBSD │ Yes │ Yes │ Yes (all) │
681 └─────────────────┴──────────┴───────────┴───────────┘
682 │OpenBSD │ n/a │ n/a │ Yes (all) │
684 ├─────────────────┼──────────┼───────────┼───────────┤
685 │NetBSD │ n/a │ No [2] │ Yes (all) │
686 ├─────────────────┼──────────┼───────────┼───────────┤
687 │Solaris and de‐ │ No [3] │ No [3] │ n/a │
688 │rivatives │ │ │ │
689 ├─────────────────┼──────────┼───────────┼───────────┤
690 │Windows (cygwin) │ No [4] │ No │ No │
691 └─────────────────┴──────────┴───────────┴───────────┘
692 Other Unix-like operating systems may work as well, but have not been
694 tested at all.
695 Note that most of the platform-dependent features also depend on the
697 file system. For example, ntfs-3g on Linux isn't able to convey NTFS
698 ACLs.
699 [1] Only "nodump", "immutable", "compressed" and "append" are sup‐
701 ported. Feature request #618 for more flags.
702 [2] Feature request #1332
704 [3] Feature request #1337
706 [4] Cygwin tries to map NTFS ACLs to permissions with varying degrees
708 of success.
709 [5] The native access control list mechanism of the OS. This normally
711 limits access to non-native ACLs. For example, NTFS ACLs aren't
712 completely accessible on Linux with ntfs-3g.
713 [6] extended attributes; key-value pairs attached to a file, mainly
715 used by the OS. This includes resource forks on Mac OS X.
716 [7] aka BSD flags. The Linux set of flags [1] is portable across plat‐
718 forms. The BSDs define additional flags.
719 In case you are interested in more details (like formulas), please
721 see Internals. For details on the available JSON output, refer to
722 All about JSON: How to develop frontends.
723 Common options
725 All Borg commands share these options:
726 -h, --help
728 show this help message and exit
729 --critical
731 work on log level CRITICAL
732 --error
734 work on log level ERROR
735 --warning
737 work on log level WARNING (default)
738 --info, -v, --verbose
740 work on log level INFO
741 --debug
743 enable debug output, work on log level DEBUG
744 --debug-topic TOPIC
746 enable TOPIC debugging (can be specified multiple times). The
747 logger path is borg.debug.<TOPIC> if TOPIC is not fully quali‐
748 fied.
749 -p, --progress
751 show progress information
752 --iec format using IEC units (1KiB = 1024B)
754 --log-json
756 Output one JSON object per log line instead of formatted text.
757 --lock-wait SECONDS
759 wait at most SECONDS for acquiring a repository/cache lock (de‐
760 fault: 1).
761 --bypass-lock
763 Bypass locking mechanism
764 --show-version
766 show/log the borg version
767 --show-rc
769 show/log the return code (rc)
770 --umask M
772 set umask to M (local only, default: 0077)
773 --remote-path PATH
775 use PATH as borg executable on the remote (default: "borg")
776 --remote-ratelimit RATE
778 deprecated, use --upload-ratelimit instead
779 --upload-ratelimit RATE
781 set network upload rate limit in kiByte/s (default: 0=unlimited)
782 --remote-buffer UPLOAD_BUFFER
784 deprecated, use --upload-buffer instead
785 --upload-buffer UPLOAD_BUFFER
787 set network upload buffer size in MiB. (default: 0=no buffer)
788 --consider-part-files
790 treat part files like normal files (e.g. to list/extract them)
791 --debug-profile FILE
793 Write execution profile in Borg format into FILE. For local use
794 a Python-compatible file can be generated by suffixing FILE with
795 ".pyprof".
796 --rsh RSH
798 Use this command to connect to the 'borg serve' process (de‐
799 fault: 'ssh')
800 Option --bypass-lock allows you to access the repository while bypass‐
802 ing borg's locking mechanism. This is necessary if your repository is
803 on a read-only storage where you don't have write permissions or capa‐
804 bilities and therefore cannot create a lock. Examples are repositories
805 stored on a Bluray disc or a read-only network storage. Avoid this op‐
806 tion if you are able to use locks as that is the safer way; see the
807 warning below.
808 WARNING:
810 If you do use --bypass-lock, you are responsible to ensure that no
811 other borg instances have write access to the repository. Otherwise,
812 you might experience errors and read broken data if changes to that
813 repository are being made at the same time.
814 Examples
816 # Create an archive and log: borg version, files list, return code
817 $ borg create --show-version --list --show-rc /path/to/repo::my-files files
818
820 borg [common options] init [options] [REPOSITORY]
821 Description
823 This command initializes an empty repository. A repository is a
824 filesystem directory containing the deduplicated data from zero or more
825 archives.
826 Encryption mode TLDR
828 The encryption mode can only be configured when creating a new reposi‐
829 tory - you can neither configure it on a per-archive basis nor change
830 the encryption mode of an existing repository.
831 Use repokey:
833 borg init --encryption repokey /path/to/repo
835 Or repokey-blake2 depending on which is faster on your client machines
837 (see below):
838 borg init --encryption repokey-blake2 /path/to/repo
840 Borg will:
842 1. Ask you to come up with a passphrase.
844 2. Create a borg key (which contains 3 random secrets. See Key files).
846 3. Encrypt the key with your passphrase.
848 4. Store the encrypted borg key inside the repository directory (in the
850 repo config). This is why it is essential to use a secure
851 passphrase.
852 5. Encrypt and sign your backups to prevent anyone from reading or
854 forging them unless they have the key and know the passphrase. Make
855 sure to keep a backup of your key outside the repository - do not
856 lock yourself out by "leaving your keys inside your car" (see borg
857 key export). For remote backups the encryption is done locally -
858 the remote machine never sees your passphrase, your unencrypted key
859 or your unencrypted files. Chunking and id generation are also
860 based on your key to improve your privacy.
861 6. Use the key when extracting files to decrypt them and to verify that
863 the contents of the backups have not been accidentally or mali‐
864 ciously altered.
865 Picking a passphrase
867 Make sure you use a good passphrase. Not too short, not too simple. The
868 real encryption / decryption key is encrypted with / locked by your
869 passphrase. If an attacker gets your key, he can't unlock and use it
870 without knowing the passphrase.
871 Be careful with special or non-ascii characters in your passphrase:
873 • Borg processes the passphrase as unicode (and encodes it as utf-8),
875 so it does not have problems dealing with even the strangest charac‐
876 ters.
877 • BUT: that does not necessarily apply to your OS / VM / keyboard con‐
879 figuration.
880 So better use a long passphrase made from simple ascii chars than one
882 that includes non-ascii stuff or characters that are hard/impossible to
883 enter on a different keyboard layout.
884 You can change your passphrase for existing repos at any time, it won't
886 affect the encryption/decryption key or other secrets.
887 More encryption modes
889 Only use --encryption none if you are OK with anyone who has access to
890 your repository being able to read your backups and tamper with their
891 contents without you noticing.
892 If you want "passphrase and having-the-key" security, use --encryption
894 keyfile. The key will be stored in your home directory (in ~/.con‐
895 fig/borg/keys).
896 If you do not want to encrypt the contents of your backups, but still
898 want to detect malicious tampering use --encryption authenticated. To
899 normally work with authenticated repos, you will need the passphrase,
900 but there is an emergency workaround, see BORG_WORKAROUNDS=authenti‐
901 cated_no_key docs.
902 If BLAKE2b is faster than SHA-256 on your hardware, use --encryption
904 authenticated-blake2, --encryption repokey-blake2 or --encryption key‐
905 file-blake2. Note: for remote backups the hashing is done on your local
906 machine.
907 ┌─────────┬──────────────────┬──────────────────┬──────────────────┐
909 │Hash/MAC │ Not encrypted no │ Not encrypted, │ Encrypted (AEAD │
910 │ │ auth │ but authenti‐ │ w/ AES) and au‐ │
911 │ │ │ cated │ thenticated │
912 ├─────────┼──────────────────┼──────────────────┼──────────────────┤
913 │SHA-256 │ none │ authenticated │ repokey keyfile │
914 ├─────────┼──────────────────┼──────────────────┼──────────────────┤
915 │BLAKE2b │ n/a │ authenti‐ │ repokey-blake2 │
916 │ │ │ cated-blake2 │ keyfile-blake2 │
917 └─────────┴──────────────────┴──────────────────┴──────────────────┘
918 Modes marked like this in the above table are new in Borg 1.1 and are
920 not backwards-compatible with Borg 1.0.x.
921 On modern Intel/AMD CPUs (except very cheap ones), AES is usually hard‐
923 ware-accelerated. BLAKE2b is faster than SHA256 on Intel/AMD 64-bit
924 CPUs (except AMD Ryzen and future CPUs with SHA extensions), which
925 makes authenticated-blake2 faster than none and authenticated.
926 On modern ARM CPUs, NEON provides hardware acceleration for SHA256 mak‐
928 ing it faster than BLAKE2b-256 there. NEON accelerates AES as well.
929 Hardware acceleration is always used automatically when available.
931 repokey and keyfile use AES-CTR-256 for encryption and HMAC-SHA256 for
933 authentication in an encrypt-then-MAC (EtM) construction. The chunk ID
934 hash is HMAC-SHA256 as well (with a separate key). These modes are
935 compatible with Borg 1.0.x.
936 repokey-blake2 and keyfile-blake2 are also authenticated encryption
938 modes, but use BLAKE2b-256 instead of HMAC-SHA256 for authentication.
939 The chunk ID hash is a keyed BLAKE2b-256 hash. These modes are new and
940 not compatible with Borg 1.0.x.
941 authenticated mode uses no encryption, but authenticates repository
943 contents through the same HMAC-SHA256 hash as the repokey and keyfile
944 modes (it uses it as the chunk ID hash). The key is stored like re‐
945 pokey. This mode is new and not compatible with Borg 1.0.x.
946 authenticated-blake2 is like authenticated, but uses the keyed
948 BLAKE2b-256 hash from the other blake2 modes. This mode is new and not
949 compatible with Borg 1.0.x.
950 none mode uses no encryption and no authentication. It uses SHA256 as
952 chunk ID hash. This mode is not recommended, you should rather consider
953 using an authenticated or authenticated/encrypted mode. This mode has
954 possible denial-of-service issues when running borg create on contents
955 controlled by an attacker. Use it only for new repositories where no
956 encryption is wanted and when compatibility with 1.0.x is important. If
957 compatibility with 1.0.x is not important, use authenticated-blake2 or
958 authenticated instead. This mode is compatible with Borg 1.0.x.
959 Examples
961 # Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
962 $ borg init --encryption=repokey-blake2 /path/to/repo
963 # Local repository (no encryption)
965 $ borg init --encryption=none /path/to/repo
966 # Remote repository (accesses a remote borg via ssh)
968 # repokey: stores the (encrypted) key into <REPO_DIR>/config
969 $ borg init --encryption=repokey-blake2 user@hostname:backup
970 # Remote repository (accesses a remote borg via ssh)
972 # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
973 $ borg init --encryption=keyfile user@hostname:backup
974
976 borg [common options] create [options] ARCHIVE [PATH...]
977 Description
979 This command creates a backup archive containing all files found while
980 recursively traversing all paths specified. Paths are added to the ar‐
981 chive as they are given, that means if relative paths are desired, the
982 command has to be run from the correct directory.
983 When giving '-' as path, borg will read data from standard input and
985 create a file 'stdin' in the created archive from that data. In some
986 cases it's more appropriate to use --content-from-command, however. See
987 section Reading from stdin below for details.
988 The archive will consume almost no disk space for files or parts of
990 files that have already been stored in other archives.
991 The archive name needs to be unique. It must not end in '.checkpoint'
993 or '.checkpoint.N' (with N being a number), because these names are
994 used for checkpoints and treated in special ways.
995 In the archive name, you may use the following placeholders: {now},
997 {utcnow}, {fqdn}, {hostname}, {user} and some others.
998 Backup speed is increased by not reprocessing files that are already
1000 part of existing archives and weren't modified. The detection of unmod‐
1001 ified files is done by comparing multiple file metadata values with
1002 previous values kept in the files cache.
1003 This comparison can operate in different modes as given by
1005 --files-cache:
1006 • ctime,size,inode (default)
1008 • mtime,size,inode (default behaviour of borg versions older than
1010 1.1.0rc4)
1011 • ctime,size (ignore the inode number)
1013 • mtime,size (ignore the inode number)
1015 • rechunk,ctime (all files are considered modified - rechunk, cache
1017 ctime)
1018 • rechunk,mtime (all files are considered modified - rechunk, cache
1020 mtime)
1021 • disabled (disable the files cache, all files considered modified -
1023 rechunk)
1024 inode number: better safety, but often unstable on network filesystems
1026 Normally, detecting file modifications will take inode information into
1028 consideration to improve the reliability of file change detection.
1029 This is problematic for files located on sshfs and similar network file
1030 systems which do not provide stable inode numbers, such files will al‐
1031 ways be considered modified. You can use modes without inode in this
1032 case to improve performance, but reliability of change detection might
1033 be reduced.
1034 ctime vs. mtime: safety vs. speed
1036 • ctime is a rather safe way to detect changes to a file (metadata and
1038 contents) as it can not be set from userspace. But, a metadata-only
1039 change will already update the ctime, so there might be some unneces‐
1040 sary chunking/hashing even without content changes. Some filesystems
1041 do not support ctime (change time). E.g. doing a chown or chmod to a
1042 file will change its ctime.
1043 • mtime usually works and only updates if file contents were changed.
1045 But mtime can be arbitrarily set from userspace, e.g. to set mtime
1046 back to the same value it had before a content change happened. This
1047 can be used maliciously as well as well-meant, but in both cases
1048 mtime based cache modes can be problematic.
1049 The mount points of filesystems or filesystem snapshots should be the
1051 same for every creation of a new archive to ensure fast operation. This
1052 is because the file cache that is used to determine changed files
1053 quickly uses absolute filenames. If this is not possible, consider
1054 creating a bind mount to a stable location.
1055 The --progress option shows (from left to right) Original, Compressed
1057 and Deduplicated (O, C and D, respectively), then the Number of files
1058 (N) processed so far, followed by the currently processed path.
1059 When using --stats, you will get some statistics about how much data
1061 was added - the "This Archive" deduplicated size there is most inter‐
1062 esting as that is how much your repository will grow. Please note that
1063 the "All archives" stats refer to the state after creation. Also, the
1064 --stats and --dry-run options are mutually exclusive because the data
1065 is not actually compressed and deduplicated during a dry run.
1066 For more help on include/exclude patterns, see the borg help patterns
1068 command output.
1069 For more help on placeholders, see the borg help placeholders command
1071 output.
1072 The --exclude patterns are not like tar. In tar --exclude .bundler/gems
1074 will exclude foo/.bundler/gems. In borg it will not, you need to use
1075 --exclude '*/.bundler/gems' to get the same effect.
1076 In addition to using --exclude patterns, it is possible to use --ex‐
1078 clude-if-present to specify the name of a filesystem object (e.g. a
1079 file or folder name) which, when contained within another folder, will
1080 prevent the containing folder from being backed up. By default, the
1081 containing folder and all of its contents will be omitted from the
1082 backup. If, however, you wish to only include the objects specified by
1083 --exclude-if-present in your backup, and not include any other contents
1084 of the containing folder, this can be enabled through using the
1085 --keep-exclude-tags option.
1086 The -x or --one-file-system option excludes directories, that are
1088 mountpoints (and everything in them). It detects mountpoints by com‐
1089 paring the device number from the output of stat() of the directory and
1090 its parent directory. Specifically, it excludes directories for which
1091 stat() reports a device number different from the device number of
1092 their parent. In general: be aware that there are directories with de‐
1093 vice number different from their parent, which the kernel does not con‐
1094 sider a mountpoint and also the other way around. Linux examples for
1095 this are bind mounts (possibly same device number, but always a mount‐
1096 point) and ALL subvolumes of a btrfs (different device number from par‐
1097 ent but not necessarily a mountpoint). macOS examples are the apfs
1098 mounts of a typical macOS installation. Therefore, when using
1099 --one-file-system, you should double-check that the backup works as in‐
1100 tended.
1101 Item flags
1103 --list outputs a list of all files, directories and other file system
1104 items it considered (no matter whether they had content changes or
1105 not). For each item, it prefixes a single-letter flag that indicates
1106 type and/or status of the item.
1107 If you are interested only in a subset of that output, you can give
1109 e.g. --filter=AME and it will only show regular files with A, M or E
1110 status (see below).
1111 A uppercase character represents the status of a regular file relative
1113 to the "files" cache (not relative to the repo -- this is an issue if
1114 the files cache is not used). Metadata is stored in any case and for
1115 'A' and 'M' also new data chunks are stored. For 'U' all data chunks
1116 refer to already existing chunks.
1117 • 'A' = regular file, added (see also I am seeing 'A' (added) status
1119 for an unchanged file!? in the FAQ)
1120 • 'M' = regular file, modified
1122 • 'U' = regular file, unchanged
1124 • 'C' = regular file, it changed while we backed it up
1126 • 'E' = regular file, an error happened while accessing/reading this
1128 file
1129 A lowercase character means a file type other than a regular file, borg
1131 usually just stores their metadata:
1132 • 'd' = directory
1134 • 'b' = block device
1136 • 'c' = char device
1138 • 'h' = regular file, hardlink (to already seen inodes)
1140 • 's' = symlink
1142 • 'f' = fifo
1144 Other flags used include:
1146 • 'i' = backup data was read from standard input (stdin)
1148 • '-' = dry run, item was not backed up
1150 • 'x' = excluded, item was not backed up
1152 • '?' = missing status code (if you see this, please file a bug re‐
1154 port!)
1155 Reading from stdin
1157 There are two methods to read from stdin. Either specify - as path and
1158 pipe directly to borg:
1159 backup-vm --id myvm --stdout | borg create REPO::ARCHIVE -
1161 Or use --content-from-command to have Borg manage the execution of the
1163 command and piping. If you do so, the first PATH argument is inter‐
1164 preted as command to execute and any further arguments are treated as
1165 arguments to the command:
1166 borg create --content-from-command REPO::ARCHIVE -- backup-vm --id myvm --stdout
1168 -- is used to ensure --id and --stdout are not considered arguments to
1170 borg but rather backup-vm.
1171 The difference between the two approaches is that piping to borg cre‐
1173 ates an archive even if the command piping to borg exits with a fail‐
1174 ure. In this case, one can end up with truncated output being backed
1175 up. Using --content-from-command, in contrast, borg is guaranteed to
1176 fail without creating an archive should the command fail. The command
1177 is considered failed when it returned a non-zero exit code.
1178 Reading from stdin yields just a stream of data without file metadata
1180 associated with it, and the files cache is not needed at all. So it is
1181 safe to disable it via --files-cache disabled and speed up backup cre‐
1182 ation a bit.
1183 By default, the content read from stdin is stored in a file called
1185 'stdin'. Use --stdin-name to change the name.
1186 Examples
1188 # Backup ~/Documents into an archive named "my-documents"
1189 $ borg create /path/to/repo::my-documents ~/Documents
1190 # same, but list all files as we process them
1192 $ borg create --list /path/to/repo::my-documents ~/Documents
1193 # Backup ~/Documents and ~/src but exclude pyc files
1195 $ borg create /path/to/repo::my-files \
1196 ~/Documents \
1197 ~/src \
1198 --exclude '*.pyc'
1199 # Backup home directories excluding image thumbnails (i.e. only
1201 # /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
1202 $ borg create /path/to/repo::my-files /home \
1203 --exclude 'sh:home/*/.thumbnails'
1204 # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
1206 # use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio)
1207 $ borg create -C zlib,6 --one-file-system /path/to/repo::root-{now:%Y-%m-%d} /
1208 # Backup onto a remote host ("push" style) via ssh to port 2222,
1210 # logging in as user "borg" and storing into /path/to/repo
1211 $ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}-root-{now} /
1212 # Backup a remote host locally ("pull" style) using sshfs
1214 $ mkdir sshfs-mount
1215 $ sshfs root@example.com:/ sshfs-mount
1216 $ cd sshfs-mount
1217 $ borg create /path/to/repo::example.com-root-{now:%Y-%m-%d} .
1218 $ cd ..
1219 $ fusermount -u sshfs-mount
1220 # Make a big effort in fine granular deduplication (big chunk management
1222 # overhead, needs a lot of RAM and disk space, see formula in internals
1223 # docs - same parameters as borg < 1.0 or attic):
1224 $ borg create --chunker-params buzhash,10,23,16,4095 /path/to/repo::small /smallstuff
1225 # Backup a raw device (must not be active/in use/mounted at that time)
1227 $ borg create --read-special --chunker-params fixed,4194304 /path/to/repo::my-sdx /dev/sdX
1228 # Backup a sparse disk image (must not be active/in use/mounted at that time)
1230 $ borg create --sparse --chunker-params fixed,4194304 /path/to/repo::my-disk my-disk.raw
1231 # No compression (none)
1233 $ borg create --compression none /path/to/repo::arch ~
1234 # Super fast, low compression (lz4, default)
1236 $ borg create /path/to/repo::arch ~
1237 # Less fast, higher compression (zlib, N = 0..9)
1239 $ borg create --compression zlib,N /path/to/repo::arch ~
1240 # Even slower, even higher compression (lzma, N = 0..9)
1242 $ borg create --compression lzma,N /path/to/repo::arch ~
1243 # Only compress compressible data with lzma,N (N = 0..9)
1245 $ borg create --compression auto,lzma,N /path/to/repo::arch ~
1246 # Use short hostname, user name and current time in archive name
1248 $ borg create /path/to/repo::{hostname}-{user}-{now} ~
1249 # Similar, use the same datetime format that is default as of borg 1.1
1250 $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S} ~
1251 # As above, but add nanoseconds
1252 $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S.%f} ~
1253 # Backing up relative paths by moving into the correct directory first
1255 $ cd /home/user/Documents
1256 # The root directory of the archive will be "projectA"
1257 $ borg create /path/to/repo::daily-projectA-{now:%Y-%m-%d} projectA
1258 # Use external command to determine files to archive
1260 # Use --paths-from-stdin with find to only backup files less than 1MB in size
1261 $ find ~ -size -1000k | borg create --paths-from-stdin /path/to/repo::small-files-only
1262 # Use --paths-from-command with find to only backup files from a given user
1263 $ borg create --paths-from-command /path/to/repo::joes-files -- find /srv/samba/shared -user joe
1264 # Use --paths-from-stdin with --paths-delimiter (for example, for filenames with newlines in them)
1265 $ find ~ -size -1000k -print0 | borg create \
1266 --paths-from-stdin \
1267 --paths-delimiter "\0" \
1268 /path/to/repo::smallfiles-handle-newline
1269
1271 borg [common options] extract [options] ARCHIVE [PATH...]
1272 Description
1274 This command extracts the contents of an archive. By default the entire
1275 archive is extracted but a subset of files and directories can be se‐
1276 lected by passing a list of PATHs as arguments. The file selection can
1277 further be restricted by using the --exclude option.
1278 For more help on include/exclude patterns, see the borg help patterns
1280 command output.
1281 By using --dry-run, you can do all extraction steps except actually
1283 writing the output data: reading metadata and data chunks from the
1284 repo, checking the hash/hmac, decrypting, decompressing.
1285 --progress can be slower than no progress display, since it makes one
1287 additional pass over the archive metadata.
1288 NOTE:
1290 Currently, extract always writes into the current working directory
1291 ("."), so make sure you cd to the right place before calling borg
1292 extract.
1293 When parent directories are not extracted (because of using file/di‐
1295 rectory selection or any other reason), borg can not restore parent
1296 directories' metadata, e.g. owner, group, permission, etc.
1297 Examples
1299 # Extract entire archive
1300 $ borg extract /path/to/repo::my-files
1301 # Extract entire archive and list files while processing
1303 $ borg extract --list /path/to/repo::my-files
1304 # Verify whether an archive could be successfully extracted, but do not write files to disk
1306 $ borg extract --dry-run /path/to/repo::my-files
1307 # Extract the "src" directory
1309 $ borg extract /path/to/repo::my-files home/USERNAME/src
1310 # Extract the "src" directory but exclude object files
1312 $ borg extract /path/to/repo::my-files home/USERNAME/src --exclude '*.o'
1313 # Restore a raw device (must not be active/in use/mounted at that time)
1315 $ borg extract --stdout /path/to/repo::my-sdx | dd of=/dev/sdx bs=10M
1316
1318 borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
1319 Description
1321 The check command verifies the consistency of a repository and its ar‐
1322 chives. It consists of two major steps:
1323 1. Checking the consistency of the repository itself. This includes
1325 checking the segment magic headers, and both the metadata and data
1326 of all objects in the segments. The read data is checked by size and
1327 CRC. Bit rot and other types of accidental damage can be detected
1328 this way. Running the repository check can be split into multiple
1329 partial checks using --max-duration. When checking a remote reposi‐
1330 tory, please note that the checks run on the server and do not cause
1331 significant network traffic.
1332 2. Checking consistency and correctness of the archive metadata and op‐
1334 tionally archive data (requires --verify-data). This includes ensur‐
1335 ing that the repository manifest exists, the archive metadata chunk
1336 is present, and that all chunks referencing files (items) in the ar‐
1337 chive exist. This requires reading archive and file metadata, but
1338 not data. To cryptographically verify the file (content) data integ‐
1339 rity pass --verify-data, but keep in mind that this requires reading
1340 all data and is hence very time consuming. When checking archives of
1341 a remote repository, archive checks run on the client machine be‐
1342 cause they require decrypting data and therefore the encryption key.
1343 Both steps can also be run independently. Pass --repository-only to run
1345 the repository checks only, or pass --archives-only to run the archive
1346 checks only.
1347 The --max-duration option can be used to split a long-running reposi‐
1349 tory check into multiple partial checks. After the given number of sec‐
1350 onds the check is interrupted. The next partial check will continue
1351 where the previous one stopped, until the full repository has been
1352 checked. Assuming a complete check would take 7 hours, then running a
1353 daily check with --max-duration=3600 (1 hour) would result in one full
1354 repository check per week. Doing a full repository check aborts any
1355 previous partial check; the next partial check will restart from the
1356 beginning. With partial repository checks you can run neither archive
1357 checks, nor enable repair mode. Consequently, if you want to use
1358 --max-duration you must also pass --repository-only, and must not pass
1359 --archives-only, nor --repair.
1360 Warning: Please note that partial repository checks (i.e. running it
1362 with --max-duration) can only perform non-cryptographic checksum checks
1363 on the segment files. A full repository check (i.e. without --max-dura‐
1364 tion) can also do a repository index check. Enabling partial repository
1365 checks excepts archive checks for the same reason. Therefore partial
1366 checks may be useful with very large repositories only where a full
1367 check would take too long.
1368 The --verify-data option will perform a full integrity verification (as
1370 opposed to checking the CRC32 of the segment) of data, which means
1371 reading the data from the repository, decrypting and decompressing it.
1372 It is a complete cryptographic verification and hence very time consum‐
1373 ing, but will detect any accidental and malicious corruption. Tam‐
1374 per-resistance is only guaranteed for encrypted repositories against
1375 attackers without access to the keys. You can not use --verify-data
1376 with --repository-only.
1377 About repair mode
1379 The check command is a readonly task by default. If any corruption is
1380 found, Borg will report the issue and proceed with checking. To actu‐
1381 ally repair the issues found, pass --repair.
1382 NOTE:
1384 --repair is a POTENTIALLY DANGEROUS FEATURE and might lead to data
1385 loss! This does not just include data that was previously lost any‐
1386 way, but might include more data for kinds of corruption it is not
1387 capable of dealing with. BE VERY CAREFUL!
1388 Pursuant to the previous warning it is also highly recommended to test
1390 the reliability of the hardware running Borg with stress testing soft‐
1391 ware. This especially includes storage and memory testers. Unreliable
1392 hardware might lead to additional data loss.
1393 It is highly recommended to create a backup of your repository before
1395 running in repair mode (i.e. running it with --repair).
1396 Repair mode will attempt to fix any corruptions found. Fixing corrup‐
1398 tions does not mean recovering lost data: Borg can not magically re‐
1399 store data lost due to e.g. a hardware failure. Repairing a repository
1400 means sacrificing some data for the sake of the repository as a whole
1401 and the remaining data. Hence it is, by definition, a potentially lossy
1402 task.
1403 In practice, repair mode hooks into both the repository and archive
1405 checks:
1406 1. When checking the repository's consistency, repair mode will try to
1408 recover as many objects from segments with integrity errors as pos‐
1409 sible, and ensure that the index is consistent with the data stored
1410 in the segments.
1411 2. When checking the consistency and correctness of archives, repair
1413 mode might remove whole archives from the manifest if their archive
1414 metadata chunk is corrupt or lost. On a chunk level (i.e. the con‐
1415 tents of files), repair mode will replace corrupt or lost chunks
1416 with a same-size replacement chunk of zeroes. If a previously zeroed
1417 chunk reappears, repair mode will restore this lost chunk using the
1418 new chunk. Lastly, repair mode will also delete orphaned chunks
1419 (e.g. caused by read errors while creating the archive).
1420 Most steps taken by repair mode have a one-time effect on the reposi‐
1422 tory, like removing a lost archive from the repository. However, re‐
1423 placing a corrupt or lost chunk with an all-zero replacement will have
1424 an ongoing effect on the repository: When attempting to extract a file
1425 referencing an all-zero chunk, the extract command will distinctly warn
1426 about it. The FUSE filesystem created by the mount command will reject
1427 reading such a "zero-patched" file unless a special mount option is
1428 given.
1429 As mentioned earlier, Borg might be able to "heal" a "zero-patched"
1431 file in repair mode, if all its previously lost chunks reappear (e.g.
1432 via a later backup). This is achieved by Borg not only keeping track of
1433 the all-zero replacement chunks, but also by keeping metadata about the
1434 lost chunks. In repair mode Borg will check whether a previously lost
1435 chunk reappeared and will replace the all-zero replacement chunk by the
1436 reappeared chunk. If all lost chunks of a "zero-patched" file reappear,
1437 this effectively "heals" the file. Consequently, if lost chunks were
1438 repaired earlier, it is advised to run --repair a second time after
1439 creating some new backups.
1440
1442 borg [common options] rename [options] ARCHIVE NEWNAME
1443 Description
1445 This command renames an archive in the repository.
1446 This results in a different archive ID.
1448 Examples
1450 $ borg create /path/to/repo::archivename ~
1451 $ borg list /path/to/repo
1452 archivename Mon, 2016-02-15 19:50:19
1453 $ borg rename /path/to/repo::archivename newname
1455 $ borg list /path/to/repo
1456 newname Mon, 2016-02-15 19:50:19
1457
1459 borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
1460 Description
1462 This command lists the contents of a repository or an archive.
1463 For more help on include/exclude patterns, see the borg help patterns
1465 command output.
1466 The FORMAT specifier syntax
1468 The --format option uses python's format string syntax.
1469 Examples:
1471 $ borg list --format '{archive}{NL}' /path/to/repo
1473 ArchiveFoo
1474 ArchiveBar
1475 ...
1476 # {VAR:NUMBER} - pad to NUMBER columns.
1478 # Strings are left-aligned, numbers are right-aligned.
1479 # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded.
1480 $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo
1481 ArchiveFoo Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
1482 $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
1483 -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo
1484 ...
1485 # {VAR:<NUMBER} - pad to NUMBER columns left-aligned.
1487 # {VAR:>NUMBER} - pad to NUMBER columns right-aligned.
1488 $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
1489 -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo
1490 ...
1491 The following keys are always available:
1493 • NEWLINE: OS dependent line separator
1495 • NL: alias of NEWLINE
1497 • NUL: NUL character for creating print0 / xargs -0 like output, see
1499 barchive and bpath keys below
1500 • SPACE
1502 • TAB
1504 • CR
1506 • LF
1508 Keys available only when listing archives in a repository:
1510 • archive: archive name interpreted as text (might be missing non-text
1512 characters, see barchive)
1513 • name: alias of "archive"
1515 • barchive: verbatim archive name, can contain any character except NUL
1517 • comment: archive comment interpreted as text (might be missing
1519 non-text characters, see bcomment)
1520 • bcomment: verbatim archive comment, can contain any character except
1522 NUL
1523 • id: internal ID of the archive
1525 • tam: TAM authentication state of this archive
1527 • start: time (start) of creation of the archive
1529 • time: alias of "start"
1531 • end: time (end) of creation of the archive
1533 • command_line: command line which was used to create the archive
1535 • hostname: hostname of host on which this archive was created
1537 • username: username of user who created this archive
1539 Keys available only when listing files in an archive:
1541 • type
1543 • mode
1545 • uid
1547 • gid
1549 • user
1551 • group
1553 • path: path interpreted as text (might be missing non-text characters,
1555 see bpath)
1556 • bpath: verbatim POSIX path, can contain any character except NUL
1558 • source: link target for links (identical to linktarget)
1560 • linktarget
1562 • flags
1564 • size
1566 • csize: compressed size
1568 • dsize: deduplicated size
1570 • dcsize: deduplicated compressed size
1572 • num_chunks: number of chunks in this file
1574 • unique_chunks: number of unique chunks in this file
1576 • mtime
1578 • ctime
1580 • atime
1582 • isomtime
1584 • isoctime
1586 • isoatime
1588 • blake2b
1590 • blake2s
1592 • md5
1594 • sha1
1596 • sha224
1598 • sha256
1600 • sha384
1602 • sha3_224
1604 • sha3_256
1606 • sha3_384
1608 • sha3_512
1610 • sha512
1612 • xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic
1614 hash!)
1615 • archiveid
1617 • archivename
1619 • extra: prepends {source} with " -> " for soft links and " link to "
1621 for hard links
1622 • health: either "healthy" (file ok) or "broken" (if file has all-zero
1624 replacement chunks)
1625 Examples
1627 $ borg list /path/to/repo
1628 Monday Mon, 2016-02-15 19:15:11
1629 repo Mon, 2016-02-15 19:26:54
1630 root-2016-02-15 Mon, 2016-02-15 19:36:29
1631 newname Mon, 2016-02-15 19:50:19
1632 ...
1633 $ borg list /path/to/repo::root-2016-02-15
1635 drwxr-xr-x root root 0 Mon, 2016-02-15 17:44:27 .
1636 drwxrwxr-x root root 0 Mon, 2016-02-15 19:04:49 bin
1637 -rwxr-xr-x root root 1029624 Thu, 2014-11-13 00:08:51 bin/bash
1638 lrwxrwxrwx root root 0 Fri, 2015-03-27 20:24:26 bin/bzcmp -> bzdiff
1639 -rwxr-xr-x root root 2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
1640 ...
1641 $ borg list /path/to/repo::root-2016-02-15 --pattern "- bin/ba*"
1643 drwxr-xr-x root root 0 Mon, 2016-02-15 17:44:27 .
1644 drwxrwxr-x root root 0 Mon, 2016-02-15 19:04:49 bin
1645 lrwxrwxrwx root root 0 Fri, 2015-03-27 20:24:26 bin/bzcmp -> bzdiff
1646 -rwxr-xr-x root root 2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
1647 ...
1648 $ borg list /path/to/repo::archiveA --format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
1650 drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 .
1651 drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 code
1652 drwxrwxr-x user user 0 Sun, 2015-02-01 11:00:00 code/myproject
1653 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
1654 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.text
1655 ...
1656 $ borg list /path/to/repo/::archiveA --pattern '+ re:\.ext$' --pattern '- re:^.*$'
1658 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
1659 ...
1660 $ borg list /path/to/repo/::archiveA --pattern '+ re:.ext$' --pattern '- re:^.*$'
1662 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
1663 -rw-rw-r-- user user 1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.text
1664 ...
1665
1667 borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
1668 Description
1670 This command finds differences (file contents, user/group/mode) between
1671 archives.
1672 A repository location and an archive name must be specified for
1674 REPO::ARCHIVE1. ARCHIVE2 is just another archive name in same reposi‐
1675 tory (no repository location allowed).
1676 For archives created with Borg 1.1 or newer diff automatically detects
1678 whether the archives are created with the same chunker params. If so,
1679 only chunk IDs are compared, which is very fast.
1680 For archives prior to Borg 1.1 chunk contents are compared by default.
1682 If you did not create the archives with different chunker params, pass
1683 --same-chunker-params. Note that the chunker params changed from Borg
1684 0.xx to 1.0.
1685 For more help on include/exclude patterns, see the borg help patterns
1687 command output.
1688 Examples
1690 $ borg init -e=none testrepo
1691 $ mkdir testdir
1692 $ cd testdir
1693 $ echo asdf > file1
1694 $ dd if=/dev/urandom bs=1M count=4 > file2
1695 $ touch file3
1696 $ borg create ../testrepo::archive1 .
1697 $ chmod a+x file1
1699 $ echo "something" >> file2
1700 $ borg create ../testrepo::archive2 .
1701 $ echo "testing 123" >> file1
1703 $ rm file3
1704 $ touch file4
1705 $ borg create ../testrepo::archive3 .
1706 $ cd ..
1708 $ borg diff testrepo::archive1 archive2
1709 [-rw-r--r-- -> -rwxr-xr-x] file1
1710 +135 B -252 B file2
1711 $ borg diff testrepo::archive2 archive3
1713 +17 B -5 B file1
1714 added 0 B file4
1715 removed 0 B file3
1716 $ borg diff testrepo::archive1 archive3
1718 +17 B -5 B [-rw-r--r-- -> -rwxr-xr-x] file1
1719 +135 B -252 B file2
1720 added 0 B file4
1721 removed 0 B file3
1722 $ borg diff --json-lines testrepo::archive1 archive3
1724 {"path": "file1", "changes": [{"type": "modified", "added": 17, "removed": 5}, {"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"}]}
1725 {"path": "file2", "changes": [{"type": "modified", "added": 135, "removed": 252}]}
1726 {"path": "file4", "changes": [{"type": "added", "size": 0}]}
1727 {"path": "file3", "changes": [{"type": "removed", "size": 0}]}
1728
1730 borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...]
1731 Description
1733 This command deletes an archive from the repository or the complete
1734 repository.
1735 Important: When deleting archives, repository disk space is not freed
1737 until you run borg compact.
1738 When you delete a complete repository, the security info and local
1740 cache for it (if any) are also deleted. Alternatively, you can delete
1741 just the local cache with the --cache-only option, or keep the security
1742 info with the --keep-security-info option.
1743 When in doubt, use --dry-run --list to see what would be deleted.
1745 When using --stats, you will get some statistics about how much data
1747 was deleted - the "Deleted data" deduplicated size there is most inter‐
1748 esting as that is how much your repository will shrink. Please note
1749 that the "All archives" stats refer to the state after deletion.
1750 You can delete multiple archives by specifying a shell pattern to match
1752 multiple archives using the --glob-archives GLOB option (for more info
1753 on these patterns, see borg help patterns).
1754 To avoid accidentally deleting archives, especially when using glob
1756 patterns, it might be helpful to use the --dry-run to test out the com‐
1757 mand without actually making any changes to the repository.
1758 Examples
1760 # delete a single backup archive:
1761 $ borg delete /path/to/repo::Monday
1762 # actually free disk space:
1763 $ borg compact /path/to/repo
1764 # delete all archives whose names begin with the machine's hostname followed by "-"
1766 $ borg delete --glob-archives '{hostname}-*' /path/to/repo
1767 # delete all archives whose names contain "-2012-"
1769 $ borg delete --glob-archives '*-2012-*' /path/to/repo
1770 # see what would be deleted if delete was run without --dry-run
1772 $ borg delete --list --dry-run -a '*-May-*' /path/to/repo
1773 # delete the whole repository and the related local cache:
1775 $ borg delete /path/to/repo
1776 You requested to completely DELETE the repository *including* all archives it contains:
1777 repo Mon, 2016-02-15 19:26:54
1778 root-2016-02-15 Mon, 2016-02-15 19:36:29
1779 newname Mon, 2016-02-15 19:50:19
1780 Type 'YES' if you understand this and want to continue: YES
1781
1783 borg [common options] prune [options] [REPOSITORY]
1784 Description
1786 The prune command prunes a repository by deleting all archives not
1787 matching any of the specified retention options.
1788 Important: Repository disk space is not freed until you run borg com‐
1790 pact.
1791 This command is normally used by automated backup scripts wanting to
1793 keep a certain number of historic backups. This retention policy is
1794 commonly referred to as GFS (Grandfather-father-son) backup rotation
1795 scheme.
1796 Also, prune automatically removes checkpoint archives (incomplete ar‐
1798 chives left behind by interrupted backup runs) except if the checkpoint
1799 is the latest archive (and thus still needed). Checkpoint archives are
1800 not considered when comparing archive counts against the retention lim‐
1801 its (--keep-X).
1802 If a prefix is set with -P, then only archives that start with the pre‐
1804 fix are considered for deletion and only those archives count towards
1805 the totals specified by the rules. Otherwise, all archives in the
1806 repository are candidates for deletion! There is no automatic distinc‐
1807 tion between archives representing different contents. These need to be
1808 distinguished by specifying matching prefixes.
1809 If you have multiple sequences of archives with different data sets
1811 (e.g. from different machines) in one shared repository, use one prune
1812 call per data set that matches only the respective archives using the
1813 -P option.
1814 The --keep-within option takes an argument of the form "<int><char>",
1816 where char is "H", "d", "w", "m", "y". For example, --keep-within 2d
1817 means to keep all archives that were created within the past 48 hours.
1818 "1m" is taken to mean "31d". The archives kept with this option do not
1819 count towards the totals specified by any other options.
1820 A good procedure is to thin out more and more the older your backups
1822 get. As an example, --keep-daily 7 means to keep the latest backup on
1823 each day, up to 7 most recent days with backups (days without backups
1824 do not count). The rules are applied from secondly to yearly, and
1825 backups selected by previous rules do not count towards those of later
1826 rules. The time that each backup starts is used for pruning purposes.
1827 Dates and times are interpreted in the local timezone, and weeks go
1828 from Monday to Sunday. Specifying a negative number of archives to keep
1829 means that there is no limit. As of borg 1.2.0, borg will retain the
1830 oldest archive if any of the secondly, minutely, hourly, daily, weekly,
1831 monthly, or yearly rules was not otherwise able to meet its retention
1832 target. This enables the first chronological archive to continue aging
1833 until it is replaced by a newer archive that meets the retention crite‐
1834 ria.
1835 The --keep-last N option is doing the same as --keep-secondly N (and it
1837 will keep the last N archives under the assumption that you do not cre‐
1838 ate more than one backup archive in the same second).
1839 When using --stats, you will get some statistics about how much data
1841 was deleted - the "Deleted data" deduplicated size there is most inter‐
1842 esting as that is how much your repository will shrink. Please note
1843 that the "All archives" stats refer to the state after pruning.
1844 Examples
1846 Be careful, prune is a potentially dangerous command, it will remove
1847 backup archives.
1848 The default of prune is to apply to all archives in the repository un‐
1850 less you restrict its operation to a subset of the archives using
1851 --glob-archives. When using --glob-archives, be careful to choose a
1852 good matching pattern - e.g. do not use "foo*" if you do not also want
1853 to match "foobar".
1854 It is strongly recommended to always run prune -v --list --dry-run ...
1856 first so you will see what it would do without it actually doing any‐
1857 thing.
1858 # Keep 7 end of day and 4 additional end of week archives.
1860 # Do a dry-run without actually deleting anything.
1861 $ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
1862 # Same as above but only apply to archive names starting with the hostname
1864 # of the machine followed by a "-" character:
1865 $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --glob-archives='{hostname}-*' /path/to/repo
1866 # actually free disk space:
1867 $ borg compact /path/to/repo
1868 # Keep 7 end of day, 4 additional end of week archives,
1870 # and an end of month archive for every month:
1871 $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /path/to/repo
1872 # Keep all backups in the last 10 days, 4 additional end of week archives,
1874 # and an end of month archive for every month:
1875 $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/repo
1876 There is also a visualized prune example in docs/misc/prune-exam‐
1878 ple.txt:
1879 borg prune visualized
1881 =====================
1882 Assume it is 2016-01-01, today's backup has not yet been made, you have
1884 created at least one backup on each day in 2015 except on 2015-12-19 (no
1885 backup made on that day), and you started backing up with borg on
1886 2015-01-01.
1887 This is what borg prune --keep-daily 14 --keep-monthly 6 --keep-yearly 1
1889 would keep.
1890 Backups kept by the --keep-daily rule are marked by a "d" to the right,
1892 backups kept by the --keep-monthly rule are marked by a "m" to the right,
1893 and backups kept by the --keep-yearly rule are marked by a "y" to the
1894 right.
1895 Calendar view
1897 -------------
1898 2015
1900 January February March
1901 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1902 1y 2 3 4 1 1
1903 5 6 7 8 9 10 11 2 3 4 5 6 7 8 2 3 4 5 6 7 8
1904 12 13 14 15 16 17 18 9 10 11 12 13 14 15 9 10 11 12 13 14 15
1905 19 20 21 22 23 24 25 16 17 18 19 20 21 22 16 17 18 19 20 21 22
1906 26 27 28 29 30 31 23 24 25 26 27 28 23 24 25 26 27 28 29
1907 30 31
1908 April May June
1910 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1911 1 2 3 4 5 1 2 3 1 2 3 4 5 6 7
1912 6 7 8 9 10 11 12 4 5 6 7 8 9 10 8 9 10 11 12 13 14
1913 13 14 15 16 17 18 19 11 12 13 14 15 16 17 15 16 17 18 19 20 21
1914 20 21 22 23 24 25 26 18 19 20 21 22 23 24 22 23 24 25 26 27 28
1915 27 28 29 30 25 26 27 28 29 30 31 29 30m
1916 July August September
1919 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1920 1 2 3 4 5 1 2 1 2 3 4 5 6
1921 6 7 8 9 10 11 12 3 4 5 6 7 8 9 7 8 9 10 11 12 13
1922 13 14 15 16 17 18 19 10 11 12 13 14 15 16 14 15 16 17 18 19 20
1923 20 21 22 23 24 25 26 17 18 19 20 21 22 23 21 22 23 24 25 26 27
1924 27 28 29 30 31m 24 25 26 27 28 29 30 28 29 30m
1925 31m
1926 October November December
1928 Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1929 1 2 3 4 1 1 2 3 4 5 6
1930 5 6 7 8 9 10 11 2 3 4 5 6 7 8 7 8 9 10 11 12 13
1931 12 13 14 15 16 17 18 9 10 11 12 13 14 15 14 15 16 17d18d19 20d
1932 19 20 21 22 23 24 25 16 17 18 19 20 21 22 21d22d23d24d25d26d27d
1933 26 27 28 29 30 31m 23 24 25 26 27 28 29 28d29d30d31d
1934 30m
1935 List view
1937 ---------
1938 --keep-daily 14 --keep-monthly 6 --keep-yearly 1
1940 ----------------------------------------------------------------
1941 1. 2015-12-31 (2015-12-31 kept (2015-12-31 kept
1942 2. 2015-12-30 by daily rule) by daily rule)
1943 3. 2015-12-29 1. 2015-11-30 1. 2015-01-01 (oldest)
1944 4. 2015-12-28 2. 2015-10-31
1945 5. 2015-12-27 3. 2015-09-30
1946 6. 2015-12-26 4. 2015-08-31
1947 7. 2015-12-25 5. 2015-07-31
1948 8. 2015-12-24 6. 2015-06-30
1949 9. 2015-12-23
1950 10. 2015-12-22
1951 11. 2015-12-21
1952 12. 2015-12-20
1953 (no backup made on 2015-12-19)
1954 13. 2015-12-18
1955 14. 2015-12-17
1956 Notes
1959 -----
1960 2015-12-31 is kept due to the --keep-daily 14 rule (because it is applied
1962 first), not due to the --keep-monthly or --keep-yearly rule.
1963 The --keep-yearly 1 rule does not consider the December 31st backup because it
1965 has already been kept due to the daily rule. There are no backups available
1966 from previous years, so the --keep-yearly target of 1 backup is not satisfied.
1967 Because of this, the 2015-01-01 archive (the oldest archive available) is kept.
1968 The --keep-monthly 6 rule keeps Nov, Oct, Sep, Aug, Jul and Jun. December is
1970 not considered for this rule, because that backup was already kept because of
1971 the daily rule.
1972 2015-12-17 is kept to satisfy the --keep-daily 14 rule - because no backup was
1974 made on 2015-12-19. If a backup had been made on that day, it would not keep
1975 the one from 2015-12-17.
1976 We did not include weekly, hourly, minutely or secondly rules to keep this
1978 example simple. They all work in basically the same way.
1979 The weekly rule is easy to understand roughly, but hard to understand in all
1981 details. If interested, read "ISO 8601:2000 standard week-based year".
1982
1985 borg [common options] compact [options] [REPOSITORY]
1986 Description
1988 This command frees repository space by compacting segments.
1989 Use this regularly to avoid running out of space - you do not need to
1991 use this after each borg command though. It is especially useful after
1992 deleting archives, because only compaction will really free repository
1993 space.
1994 borg compact does not need a key, so it is possible to invoke it from
1996 the client or also from the server.
1997 Depending on the amount of segments that need compaction, it may take a
1999 while, so consider using the --progress option.
2000 A segment is compacted if the amount of saved space is above the per‐
2002 centage value given by the --threshold option. If omitted, a threshold
2003 of 10% is used. When using --verbose, borg will output an estimate of
2004 the freed space.
2005 After upgrading borg (server) to 1.2+, you can use borg compact
2007 --cleanup-commits to clean up the numerous 17byte commit-only segments
2008 that borg 1.1 did not clean up due to a bug. It is enough to do that
2009 once per repository. After cleaning up the commits, borg will also do a
2010 normal compaction.
2011 See Separate compaction in Additional Notes for more details.
2013 Examples
2015 # compact segments and free repo disk space
2016 $ borg compact /path/to/repo
2017 # same as above plus clean up 17byte commit-only segments
2019 $ borg compact --cleanup-commits /path/to/repo
2020
2022 borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
2023 Description
2025 This command displays detailed information about the specified archive
2026 or repository.
2027 Please note that the deduplicated sizes of the individual archives do
2029 not add up to the deduplicated size of the repository ("all archives"),
2030 because the two are meaning different things:
2031 This archive / deduplicated size = amount of data stored ONLY for this
2033 archive = unique chunks of this archive. All archives / deduplicated
2034 size = amount of data stored in the repo = all chunks in the reposi‐
2035 tory.
2036 Borg archives can only contain a limited amount of file metadata. The
2038 size of an archive relative to this limit depends on a number of fac‐
2039 tors, mainly the number of files, the lengths of paths and other meta‐
2040 data stored for files. This is shown as utilization of maximum sup‐
2041 ported archive size.
2042 Examples
2044 $ borg info /path/to/repo::2017-06-29T11:00-srv
2045 Archive name: 2017-06-29T11:00-srv
2046 Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
2047 Comment:
2048 Hostname: myhostname
2049 Username: root
2050 Time (start): Thu, 2017-06-29 11:03:07
2051 Time (end): Thu, 2017-06-29 11:03:13
2052 Duration: 5.66 seconds
2053 Number of files: 17037
2054 Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
2055 Utilization of max. archive size: 0%
2056 ------------------------------------------------------------------------------
2057 Original size Compressed size Deduplicated size
2058 This archive: 12.53 GB 12.49 GB 1.62 kB
2059 All archives: 121.82 TB 112.41 TB 215.42 GB
2060 Unique chunks Total chunks
2062 Chunk index: 1015213 626934122
2063 $ borg info /path/to/repo --last 1
2065 Archive name: 2017-06-29T11:00-srv
2066 Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
2067 Comment:
2068 Hostname: myhostname
2069 Username: root
2070 Time (start): Thu, 2017-06-29 11:03:07
2071 Time (end): Thu, 2017-06-29 11:03:13
2072 Duration: 5.66 seconds
2073 Number of files: 17037
2074 Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
2075 Utilization of max. archive size: 0%
2076 ------------------------------------------------------------------------------
2077 Original size Compressed size Deduplicated size
2078 This archive: 12.53 GB 12.49 GB 1.62 kB
2079 All archives: 121.82 TB 112.41 TB 215.42 GB
2080 Unique chunks Total chunks
2082 Chunk index: 1015213 626934122
2083 $ borg info /path/to/repo
2085 Repository ID: d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
2086 Location: /path/to/repo
2087 Encrypted: Yes (repokey)
2088 Cache: /root/.cache/borg/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
2089 Security dir: /root/.config/borg/security/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
2090 ------------------------------------------------------------------------------
2091 Original size Compressed size Deduplicated size
2092 All archives: 121.82 TB 112.41 TB 215.42 GB
2093 Unique chunks Total chunks
2095 Chunk index: 1015213 626934122
2096
2098 borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
2099 Description
2101 This command mounts an archive as a FUSE filesystem. This can be useful
2102 for browsing an archive or restoring individual files. Unless the
2103 --foreground option is given the command will run in the background un‐
2104 til the filesystem is umounted.
2105 The command borgfs provides a wrapper for borg mount. This can also be
2107 used in fstab entries: /path/to/repo /mnt/point fuse.borgfs de‐
2108 faults,noauto 0 0
2109 To allow a regular user to use fstab entries, add the user option:
2111 /path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0
2112 For FUSE configuration and mount options, see the mount.fuse(8) manual
2114 page.
2115 Borg's default behavior is to use the archived user and group names of
2117 each file and map them to the system's respective user and group ids.
2118 Alternatively, using numeric-ids will instead use the archived user and
2119 group ids without any mapping.
2120 The uid and gid mount options (implemented by Borg) can be used to
2122 override the user and group ids of all files (i.e., borg mount -o
2123 uid=1000,gid=1000).
2124 The man page references user_id and group_id mount options (implemented
2126 by fuse) which specify the user and group id of the mount owner (aka,
2127 the user who does the mounting). It is set automatically by libfuse (or
2128 the filesystem if libfuse is not used). However, you should not specify
2129 these manually. Unlike the uid and gid mount options which affect all
2130 files, user_id and group_id affect the user and group id of the mounted
2131 (base) directory.
2132 Additional mount options supported by borg:
2134 • versions: when used with a repository mount, this gives a merged,
2136 versioned view of the files in the archives. EXPERIMENTAL, layout may
2137 change in future.
2138 • allow_damaged_files: by default damaged files (where missing chunks
2140 were replaced with runs of zeros by borg check --repair) are not
2141 readable and return EIO (I/O error). Set this option to read such
2142 files.
2143 • ignore_permissions: for security reasons the default_permissions
2145 mount option is internally enforced by borg. ignore_permissions can
2146 be given to not enforce default_permissions.
2147 The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for ad‐
2149 vanced users to tweak the performance. It sets the number of cached
2150 data chunks; additional memory usage can be up to ~8 MiB times this
2151 number. The default is the number of CPU cores.
2152 When the daemonized process receives a signal or crashes, it does not
2154 unmount. Unmounting in these cases could cause an active rsync or sim‐
2155 ilar process to unintentionally delete data.
2156 When running in the foreground ^C/SIGINT unmounts cleanly, but other
2158 signals or crashes do not.
2159
2161 borg [common options] umount [options] MOUNTPOINT
2162 Description
2164 This command un-mounts a FUSE filesystem that was mounted with borg
2165 mount.
2166 This is a convenience wrapper that just calls the platform-specific
2168 shell command - usually this is either umount or fusermount -u.
2169 Examples
2171 # Mounting the repository shows all archives.
2172 # Archives are loaded lazily, expect some delay when navigating to an archive
2173 # for the first time.
2174 $ borg mount /path/to/repo /tmp/mymountpoint
2175 $ ls /tmp/mymountpoint
2176 root-2016-02-14 root-2016-02-15
2177 $ borg umount /tmp/mymountpoint
2178 # Mounting a specific archive is possible as well.
2180 $ borg mount /path/to/repo::root-2016-02-15 /tmp/mymountpoint
2181 $ ls /tmp/mymountpoint
2182 bin boot etc home lib lib64 lost+found media mnt opt
2183 root sbin srv tmp usr var
2184 $ borg umount /tmp/mymountpoint
2185 # The "versions view" merges all archives in the repository
2187 # and provides a versioned view on files.
2188 $ borg mount -o versions /path/to/repo /tmp/mymountpoint
2189 $ ls -l /tmp/mymountpoint/home/user/doc.txt/
2190 total 24
2191 -rw-rw-r-- 1 user group 12357 Aug 26 21:19 doc.cda00bc9.txt
2192 -rw-rw-r-- 1 user group 12204 Aug 26 21:04 doc.fa760f28.txt
2193 $ borg umount /tmp/mymountpoint
2194 # Archive filters are supported.
2196 # These are especially handy for the "versions view",
2197 # which does not support lazy processing of archives.
2198 $ borg mount -o versions --glob-archives '*-my-home' --last 10 /path/to/repo /tmp/mymountpoint
2199 # Exclusion options are supported.
2201 # These can speed up mounting and lower memory needs significantly.
2202 $ borg mount /path/to/repo /tmp/mymountpoint only/that/path
2203 $ borg mount --exclude '...' /path/to/repo /tmp/mymountpoint
2204 borgfs
2206 $ echo '/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
2207 $ echo '/mnt/backup::root-2016-02-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
2208 $ mount /tmp/myrepo
2209 $ mount /tmp/myarchive
2210 $ ls /tmp/myrepo
2211 root-2016-02-01 root-2016-02-2015
2212 $ ls /tmp/myarchive
2213 bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
2214 NOTE:
2216 borgfs will be automatically provided if you used a distribution
2217 package, pip or setup.py to install Borg. Users of the standalone
2218 binary will have to manually create a symlink (see Standalone Bi‐
2219 nary).
2220
2222 borg [common options] key change-passphrase [options] [REPOSITORY]
2223 Description
2225 The key files used for repository encryption are optionally passphrase
2226 protected. This command can be used to change this passphrase.
2227 Please note that this command only changes the passphrase, but not any
2229 secret protected by it (like e.g. encryption/MAC keys or chunker seed).
2230 Thus, changing the passphrase after passphrase and borg key got compro‐
2231 mised does not protect future (nor past) backups to the same reposi‐
2232 tory.
2233 Examples
2235 # Create a key file protected repository
2236 $ borg init --encryption=keyfile -v /path/to/repo
2237 Initializing repository at "/path/to/repo"
2238 Enter new passphrase:
2239 Enter same passphrase again:
2240 Remember your passphrase. Your data will be inaccessible without it.
2241 Key in "/root/.config/borg/keys/mnt_backup" created.
2242 Keep this key safe. Your data will be inaccessible without it.
2243 Synchronizing chunks cache...
2244 Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
2245 Done.
2246 # Change key file passphrase
2248 $ borg key change-passphrase -v /path/to/repo
2249 Enter passphrase for key /root/.config/borg/keys/mnt_backup:
2250 Enter new passphrase:
2251 Enter same passphrase again:
2252 Remember your passphrase. Your data will be inaccessible without it.
2253 Key updated
2254 # Import a previously-exported key into the specified
2256 # key file (creating or overwriting the output key)
2257 # (keyfile repositories only)
2258 $ BORG_KEY_FILE=/path/to/output-key borg key import /path/to/repo /path/to/exported
2259 Fully automated using environment variables:
2261 $ BORG_NEW_PASSPHRASE=old borg init -e=repokey repo
2263 # now "old" is the current passphrase.
2264 $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase repo
2265 # now "new" is the current passphrase.
2266
2268 borg [common options] key export [options] [REPOSITORY] [PATH]
2269 Description
2271 If repository encryption is used, the repository is inaccessible with‐
2272 out the key. This command allows one to backup this essential key.
2273 Note that the backup produced does not include the passphrase itself
2274 (i.e. the exported key stays encrypted). In order to regain access to a
2275 repository, one needs both the exported key and the original
2276 passphrase.
2277 There are three backup formats. The normal backup format is suitable
2279 for digital storage as a file. The --paper backup format is optimized
2280 for printing and typing in while importing, with per line checks to re‐
2281 duce problems with manual input. The --qr-html creates a printable HTML
2282 template with a QR code and a copy of the --paper-formatted key.
2283 For repositories using keyfile encryption the key is saved locally on
2285 the system that is capable of doing backups. To guard against loss of
2286 this key, the key needs to be backed up independently of the main data
2287 backup.
2288 For repositories using the repokey encryption the key is saved in the
2290 repository in the config file. A backup is thus not strictly needed,
2291 but guards against the repository becoming inaccessible if the file is
2292 damaged for some reason.
2293 Examples:
2295 borg key export /path/to/repo > encrypted-key-backup
2297 borg key export --paper /path/to/repo > encrypted-key-backup.txt
2298 borg key export --qr-html /path/to/repo > encrypted-key-backup.html
2299 # Or pass the output file as an argument instead of redirecting stdout:
2300 borg key export /path/to/repo encrypted-key-backup
2301 borg key export --paper /path/to/repo encrypted-key-backup.txt
2302 borg key export --qr-html /path/to/repo encrypted-key-backup.html
2303
2305 borg [common options] key import [options] [REPOSITORY] [PATH]
2306 Description
2308 This command restores a key previously backed up with the export com‐
2309 mand.
2310 If the --paper option is given, the import will be an interactive
2312 process in which each line is checked for plausibility before proceed‐
2313 ing to the next line. For this format PATH must not be given.
2314 For repositories using keyfile encryption, the key file which borg key
2316 import writes to depends on several factors. If the BORG_KEY_FILE envi‐
2317 ronment variable is set and non-empty, borg key import creates or over‐
2318 writes that file named by $BORG_KEY_FILE. Otherwise, borg key import
2319 searches in the $BORG_KEYS_DIR directory for a key file associated with
2320 the repository. If a key file is found in $BORG_KEYS_DIR, borg key im‐
2321 port overwrites it; otherwise, borg key import creates a new key file
2322 in $BORG_KEYS_DIR.
2323
2325 borg [common options] upgrade [options] [REPOSITORY]
2326 Description
2328 Upgrade an existing, local Borg repository.
2329 When you do not need borg upgrade
2331 Not every change requires that you run borg upgrade.
2332 You do not need to run it when:
2334 • moving your repository to a different place
2336 • upgrading to another point release (like 1.0.x to 1.0.y), except when
2338 noted otherwise in the changelog
2339 • upgrading from 1.0.x to 1.1.x, except when noted otherwise in the
2341 changelog
2342 Borg 1.x.y upgrades
2344 Archive TAM authentication:
2345 Use borg upgrade --archives-tam REPO to add archive TAMs to all ar‐
2347 chives that are not TAM authenticated yet. This is a convenient method
2348 to just trust all archives present - if an archive does not have TAM
2349 authentication yet, a TAM will be added. Archives created by old borg
2350 versions < 1.0.9 do not have TAMs. Archives created by newer borg ver‐
2351 sion should have TAMs already. If you have a high risk environment,
2352 you should not just run this, but first verify that the archives are
2353 authentic and not malicious (== have good content, have a good time‐
2354 stamp). Borg 1.2.5+ needs all archives to be TAM authenticated for
2355 safety reasons.
2356 This upgrade needs to be done once per repository.
2358 Manifest TAM authentication:
2360 Use borg upgrade --tam REPO to require manifest authentication intro‐
2362 duced with Borg 1.0.9 to address security issues. This means that modi‐
2363 fying the repository after doing this with a version prior to 1.0.9
2364 will raise a validation error, so only perform this upgrade after up‐
2365 dating all clients using the repository to 1.0.9 or newer.
2366 This upgrade should be done on each client for safety reasons.
2368 If a repository is accidentally modified with a pre-1.0.9 client after
2370 this upgrade, use borg upgrade --tam --force REPO to remedy it.
2371 If you routinely do this you might not want to enable this upgrade
2373 (which will leave you exposed to the security issue). You can reverse
2374 the upgrade by issuing borg upgrade --disable-tam REPO.
2375 See
2377 https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability
2378 for details.
2379 Attic and Borg 0.xx to Borg 1.x
2381 This currently supports converting an Attic repository to Borg and also
2382 helps with converting Borg 0.xx to 1.0.
2383 Currently, only LOCAL repositories can be upgraded (issue #465).
2385 Please note that borg create (since 1.0.0) uses bigger chunks by de‐
2387 fault than old borg or attic did, so the new chunks won't deduplicate
2388 with the old chunks in the upgraded repository. See --chunker-params
2389 option of borg create and borg recreate.
2390 borg upgrade will change the magic strings in the repository's segments
2392 to match the new Borg magic strings. The keyfiles found in $AT‐
2393 TIC_KEYS_DIR or ~/.attic/keys/ will also be converted and copied to
2394 $BORG_KEYS_DIR or ~/.config/borg/keys.
2395 The cache files are converted, from $ATTIC_CACHE_DIR or ~/.cache/attic
2397 to $BORG_CACHE_DIR or ~/.cache/borg, but the cache layout between Borg
2398 and Attic changed, so it is possible the first backup after the conver‐
2399 sion takes longer than expected due to the cache resync.
2400 Upgrade should be able to resume if interrupted, although it will still
2402 iterate over all segments. If you want to start from scratch, use borg
2403 delete over the copied repository to make sure the cache files are also
2404 removed:
2405 borg delete borg
2407 Unless --inplace is specified, the upgrade process first creates a
2409 backup copy of the repository, in REPOSITORY.before-upgrade-DATETIME,
2410 using hardlinks. This requires that the repository and its parent di‐
2411 rectory reside on same filesystem so the hardlink copy can work. This
2412 takes longer than in place upgrades, but is much safer and gives
2413 progress information (as opposed to cp -al). Once you are satisfied
2414 with the conversion, you can safely destroy the backup copy.
2415 WARNING: Running the upgrade in place will make the current copy unus‐
2417 able with older version, with no way of going back to previous ver‐
2418 sions. This can PERMANENTLY DAMAGE YOUR REPOSITORY! Attic CAN NOT READ
2419 BORG REPOSITORIES, as the magic strings have changed. You have been
2420 warned.
2421 Examples
2423 # Upgrade the borg repository to the most recent version.
2424 $ borg upgrade -v /path/to/repo
2425 making a hardlink copy in /path/to/repo.before-upgrade-2016-02-15-20:51:55
2426 opening attic repository with borg and converting
2427 no key file found for repository
2428 converting repo index /path/to/repo/index.0
2429 converting 1 segments...
2430 converting borg 0.xx to borg current
2431 no key file found for repository
2432 Upgrading a passphrase encrypted attic repo
2434 attic offered a "passphrase" encryption mode, but this was removed in
2435 borg 1.0 and replaced by the "repokey" mode (which stores the
2436 passphrase-protected encryption key into the repository config).
2437 Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2
2439 steps are needed, in this order:
2440 • borg upgrade repo
2442 • borg key migrate-to-repokey repo
2444
2446 borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
2447 Description
2449 Recreate the contents of existing archives.
2450 recreate is a potentially dangerous function and might lead to data
2452 loss (if used wrongly). BE VERY CAREFUL!
2453 Important: Repository disk space is not freed until you run borg com‐
2455 pact.
2456 --exclude, --exclude-from, --exclude-if-present, --keep-exclude-tags
2458 and PATH have the exact same semantics as in "borg create", but they
2459 only check for files in the archives and not in the local file system.
2460 If PATHs are specified, the resulting archives will only contain files
2461 from these PATHs.
2462 Note that all paths in an archive are relative, therefore absolute pat‐
2464 terns/paths will not match (--exclude, --exclude-from, PATHs).
2465 --recompress allows one to change the compression of existing data in
2467 archives. Due to how Borg stores compressed size information this
2468 might display incorrect information for archives that were not recre‐
2469 ated at the same time. There is no risk of data loss by this.
2470 --chunker-params will re-chunk all files in the archive, this can be
2472 used to have upgraded Borg 0.xx or Attic archives deduplicate with Borg
2473 1.x archives.
2474 USE WITH CAUTION. Depending on the PATHs and patterns given, recreate
2476 can be used to permanently delete files from archives. When in doubt,
2477 use --dry-run --verbose --list to see how patterns/PATHS are inter‐
2478 preted. See Item flags in borg create for details.
2479 The archive being recreated is only removed after the operation com‐
2481 pletes. The archive that is built during the operation exists at the
2482 same time at "<ARCHIVE>.recreate". The new archive will have a differ‐
2483 ent archive ID.
2484 With --target the original archive is not replaced, instead a new ar‐
2486 chive is created.
2487 When rechunking (or recompressing), space usage can be substantial -
2489 expect at least the entire deduplicated size of the archives using the
2490 previous chunker (or compression) params.
2491 If you recently ran borg check --repair and it had to fix lost chunks
2493 with all-zero replacement chunks, please first run another backup for
2494 the same data and re-run borg check --repair afterwards to heal any ar‐
2495 chives that had lost chunks which are still generated from the input
2496 data.
2497 Important: running borg recreate to re-chunk will remove the
2499 chunks_healthy metadata of all items with replacement chunks, so heal‐
2500 ing will not be possible any more after re-chunking (it is also un‐
2501 likely it would ever work: due to the change of chunking parameters,
2502 the missing chunk likely will never be seen again even if you still
2503 have the data that produced it).
2504 Examples
2506 # Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
2507 # Archives created with Borg 1.1+ and the default chunker params are skipped
2508 # (archive ID stays the same).
2509 $ borg recreate /mnt/backup --chunker-params default --progress
2510 # Create a backup with little but fast compression
2512 $ borg create /mnt/backup::archive /some/files --compression lz4
2513 # Then compress it - this might take longer, but the backup has already completed,
2514 # so no inconsistencies from a long-running backup job.
2515 $ borg recreate /mnt/backup::archive --recompress --compression zlib,9
2516 # Remove unwanted files from all archives in a repository.
2518 # Note the relative path for the --exclude option - archives only contain relative paths.
2519 $ borg recreate /mnt/backup --exclude home/icke/Pictures/drunk_photos
2520 # Change archive comment
2522 $ borg create --comment "This is a comment" /mnt/backup::archivename ~
2523 $ borg info /mnt/backup::archivename
2524 Name: archivename
2525 Fingerprint: ...
2526 Comment: This is a comment
2527 ...
2528 $ borg recreate --comment "This is a better comment" /mnt/backup::archivename
2529 $ borg info /mnt/backup::archivename
2530 Name: archivename
2531 Fingerprint: ...
2532 Comment: This is a better comment
2533 ...
2534
2536 borg [common options] import-tar [options] ARCHIVE TARFILE
2537 Description
2539 This command creates a backup archive from a tarball.
2540 When giving '-' as path, Borg will read a tar stream from standard in‐
2542 put.
2543 By default (--tar-filter=auto) Borg will detect whether the file is
2545 compressed based on its file extension and pipe the file through an ap‐
2546 propriate filter:
2547 • .tar.gz or .tgz: gzip -d
2549 • .tar.bz2 or .tbz: bzip2 -d
2551 • .tar.xz or .txz: xz -d
2553 • .tar.zstd or .tar.zst: zstd -d
2555 • .tar.lz4: lz4 -d
2557 Alternatively, a --tar-filter program may be explicitly specified. It
2559 should read compressed data from stdin and output an uncompressed tar
2560 stream on stdout.
2561 Most documentation of borg create applies. Note that this command does
2563 not support excluding files.
2564 import-tar is a lossy conversion: BSD flags, ACLs, extended attributes
2566 (xattrs), atime and ctime are not exported. Timestamp resolution is
2567 limited to whole seconds, not the nanosecond resolution otherwise sup‐
2568 ported by Borg.
2569 A --sparse option (as found in borg create) is not supported.
2571 import-tar reads POSIX.1-1988 (ustar), POSIX.1-2001 (pax), GNU tar,
2573 UNIX V7 tar and SunOS tar with extended attributes.
2574 To import multiple tarballs into a single archive, they can be simply
2576 concatenated (e.g. using "cat") into a single file, and imported with
2577 an --ignore-zeros option to skip through the stop markers between them.
2578
2580 borg [common options] export-tar [options] ARCHIVE FILE [PATH...]
2581 Description
2583 This command creates a tarball from an archive.
2584 When giving '-' as the output FILE, Borg will write a tar stream to
2586 standard output.
2587 By default (--tar-filter=auto) Borg will detect whether the FILE should
2589 be compressed based on its file extension and pipe the tarball through
2590 an appropriate filter before writing it to FILE:
2591 • .tar.gz or .tgz: gzip
2593 • .tar.bz2 or .tbz: bzip2
2595 • .tar.xz or .txz: xz
2597 • .tar.zstd or .tar.zst: zstd
2599 • .tar.lz4: lz4
2601 Alternatively, a --tar-filter program may be explicitly specified. It
2603 should read the uncompressed tar stream from stdin and write a com‐
2604 pressed/filtered tar stream to stdout.
2605 The generated tarball uses the GNU tar format.
2607 export-tar is a lossy conversion: BSD flags, ACLs, extended attributes
2609 (xattrs), atime and ctime are not exported. Timestamp resolution is
2610 limited to whole seconds, not the nanosecond resolution otherwise sup‐
2611 ported by Borg.
2612 A --sparse option (as found in borg extract) is not supported.
2614 By default the entire archive is extracted but a subset of files and
2616 directories can be selected by passing a list of PATHs as arguments.
2617 The file selection can further be restricted by using the --exclude op‐
2618 tion.
2619 For more help on include/exclude patterns, see the borg help patterns
2621 command output.
2622 --progress can be slower than no progress display, since it makes one
2624 additional pass over the archive metadata.
2625 Examples
2627 # export as uncompressed tar
2628 $ borg export-tar /path/to/repo::Monday Monday.tar
2629 # exclude some types, compress using gzip
2631 $ borg export-tar /path/to/repo::Monday Monday.tar.gz --exclude '*.so'
2632 # use higher compression level with gzip
2634 $ borg export-tar --tar-filter="gzip -9" testrepo::linux Monday.tar.gz
2635 # export a tar, but instead of storing it on disk,
2637 # upload it to a remote site using curl.
2638 $ borg export-tar /path/to/repo::Monday - | curl --data-binary @- https://somewhere/to/POST
2639 # remote extraction via "tarpipe"
2641 $ borg export-tar /path/to/repo::Monday - | ssh somewhere "cd extracted; tar x"
2642
2644 borg [common options] serve [options]
2645 Description
2647 This command starts a repository server process. This command is usu‐
2648 ally not used manually.
2649 Examples
2651 borg serve has special support for ssh forced commands (see autho‐
2652 rized_keys example below): if the environment variable SSH_ORIGI‐
2653 NAL_COMMAND is set it will ignore some options given on the command
2654 line and use the values from the variable instead. This only applies to
2655 a carefully controlled allowlist of safe options. This list currently
2656 contains:
2657 • Options that control the log level and debug topics printed such as
2659 --verbose, --info, --debug, --debug-topic, etc.
2660 • --lock-wait to allow the client to control how long to wait before
2662 giving up and aborting the operation when another process is holding
2663 a lock.
2664 Environment variables (such as BORG_XXX) contained in the original com‐
2666 mand sent by the client are not interpreted, but ignored. If BORG_XXX
2667 environment variables should be set on the borg serve side, then these
2668 must be set in system-specific locations like /etc/environment or in
2669 the forced command itself (example below).
2670 # Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
2672 # Use key options to disable unneeded and potentially dangerous SSH functionality.
2673 # This will help to secure an automated remote backup system.
2674 $ cat ~/.ssh/authorized_keys
2675 command="borg serve --restrict-to-path /path/to/repo",restrict ssh-rsa AAAAB3[...]
2676 # Set a BORG_XXX environment variable on the "borg serve" side
2678 $ cat ~/.ssh/authorized_keys
2679 command="export BORG_XXX=value; borg serve [...]",restrict ssh-rsa [...]
2680 NOTE:
2682 The examples above use the restrict directive. This does automati‐
2683 cally block potential dangerous ssh features, even when they are
2684 added in a future update. Thus, this option should be preferred.
2685 If you're using openssh-server < 7.2, however, you have to explic‐
2687 itly specify the ssh features to restrict and cannot simply use the
2688 restrict option as it has been introduced in v7.2. We recommend to
2689 use no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forward‐
2690 ing,no-user-rc in this case.
2691 Details about sshd usage: sshd(8)
2693 SSH Configuration
2695 borg serve's pipes (stdin/stdout/stderr) are connected to the sshd
2696 process on the server side. In the event that the SSH connection be‐
2697 tween borg serve and the client is disconnected or stuck abnormally
2698 (for example, due to a network outage), it can take a long time for
2699 sshd to notice the client is disconnected. In the meantime, sshd con‐
2700 tinues running, and as a result so does the borg serve process holding
2701 the lock on the repository. This can cause subsequent borg operations
2702 on the remote repository to fail with the error: Failed to create/ac‐
2703 quire the lock.
2704 In order to avoid this, it is recommended to perform the following ad‐
2706 ditional SSH configuration:
2707 Either in the client side's ~/.ssh/config file, or in the client's
2709 /etc/ssh/ssh_config file:
2710 Host backupserver
2712 ServerAliveInterval 10
2713 ServerAliveCountMax 30
2714 Replacing backupserver with the hostname, FQDN or IP address of the
2716 borg server.
2717 This will cause the client to send a keepalive to the server every 10
2719 seconds. If 30 consecutive keepalives are sent without a response (a
2720 time of 300 seconds), the ssh client process will be terminated, caus‐
2721 ing the borg process to terminate gracefully.
2722 On the server side's sshd configuration file (typically
2724 /etc/ssh/sshd_config):
2725 ClientAliveInterval 10
2727 ClientAliveCountMax 30
2728 This will cause the server to send a keep alive to the client every 10
2730 seconds. If 30 consecutive keepalives are sent without a response (a
2731 time of 300 seconds), the server's sshd process will be terminated,
2732 causing the borg serve process to terminate gracefully and release the
2733 lock on the repository.
2734 If you then run borg commands with --lock-wait 600, this gives suffi‐
2736 cient time for the borg serve processes to terminate after the SSH con‐
2737 nection is torn down after the 300 second wait for the keepalives to
2738 fail.
2739 You may, of course, modify the timeout values demonstrated above to
2741 values that suit your environment and use case.
2742
2744 borg [common options] config [options] [REPOSITORY] [NAME] [VALUE]
2745 Description
2747 This command gets and sets options in a local repository or cache con‐
2748 fig file. For security reasons, this command only works on local
2749 repositories.
2750 To delete a config value entirely, use --delete. To list the values of
2752 the configuration file or the default values, use --list. To get and
2753 existing key, pass only the key name. To set a key, pass both the key
2754 name and the new value. Keys can be specified in the format "sec‐
2755 tion.name" or simply "name"; the section will default to "repository"
2756 and "cache" for the repo and cache configs, respectively.
2757 By default, borg config manipulates the repository config file. Using
2759 --cache edits the repository cache's config file instead.
2760 NOTE:
2762 The repository & cache config files are some of the only directly
2763 manipulable parts of a repository that aren't versioned or backed
2764 up, so be careful when making changes!
2765 Examples
2767 # find cache directory
2768 $ cd ~/.cache/borg/$(borg config /path/to/repo id)
2769 # reserve some space
2771 $ borg config /path/to/repo additional_free_space 2G
2772 # make a repo append-only
2774 $ borg config /path/to/repo append_only 1
2775
2777 borg [common options] with-lock [options] REPOSITORY COMMAND [ARGS...]
2778 Description
2780 This command runs a user-specified command while the repository lock is
2781 held.
2782 It will first try to acquire the lock (make sure that no other opera‐
2784 tion is running in the repo), then execute the given command as a sub‐
2785 process and wait for its termination, release the lock and return the
2786 user command's return code as borg's return code.
2787 NOTE:
2789 If you copy a repository with the lock held, the lock will be
2790 present in the copy. Thus, before using borg on the copy from a dif‐
2791 ferent host, you need to use "borg break-lock" on the copied reposi‐
2792 tory, because Borg is cautious and does not automatically remove
2793 stale locks made by a different host.
2794
2796 borg [common options] break-lock [options] [REPOSITORY]
2797 Description
2799 This command breaks the repository and cache locks. Please use care‐
2800 fully and only while no borg process (on any machine) is trying to ac‐
2801 cess the Cache or the Repository.
2802
2804 borg [common options] benchmark crud [options] REPOSITORY PATH
2805 Description
2807 This command benchmarks borg CRUD (create, read, update, delete) opera‐
2808 tions.
2809 It creates input data below the given PATH and backups this data into
2811 the given REPO. The REPO must already exist (it could be a fresh empty
2812 repo or an existing repo, the command will create / read / update /
2813 delete some archives named borg-benchmark-crud* there.
2814 Make sure you have free space there, you'll need about 1GB each (+
2816 overhead).
2817 If your repository is encrypted and borg needs a passphrase to unlock
2819 the key, use:
2820 BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
2822 Measurements are done with different input file sizes and counts. The
2824 file contents are very artificial (either all zero or all random), thus
2825 the measurement results do not necessarily reflect performance with
2826 real data. Also, due to the kind of content used, no compression is
2827 used in these benchmarks.
2828 C- == borg create (1st archive creation, no compression, do not use
2830 files cache)
2831 C-Z- == all-zero files. full dedup, this is primarily measuring
2832 reader/chunker/hasher. C-R- == random files. no dedup, measur‐
2833 ing throughput through all processing stages.
2834 R- == borg extract (extract archive, dry-run, do everything, but do not
2836 write files to disk)
2837 R-Z- == all zero files. Measuring heavily duplicated files.
2838 R-R- == random files. No duplication here, measuring throughput
2839 through all processing stages, except writing to disk.
2840 U- == borg create (2nd archive creation of unchanged input files, mea‐
2842 sure files cache speed)
2843 The throughput value is kind of virtual here, it does not actu‐
2844 ally read the file. U-Z- == needs to check the 2 all-zero
2845 chunks' existence in the repo. U-R- == needs to check existence
2846 of a lot of different chunks in the repo.
2847 D- == borg delete archive (delete last remaining archive, measure dele‐
2849 tion + compaction)
2850 D-Z- == few chunks to delete / few segments to compact/remove.
2851 D-R- == many chunks to delete / many segments to compact/remove.
2852 Please note that there might be quite some variance in these measure‐
2854 ments. Try multiple measurements and having a otherwise idle machine
2855 (and network, if you use it).
2856
2858 borg help patterns
2859 The path/filenames used as input for the pattern matching start from
2860 the currently active recursion root. You usually give the recursion
2861 root(s) when invoking borg and these can be either relative or absolute
2862 paths.
2863 Starting with Borg 1.2, paths that are matched against patterns always
2865 appear relative. If you give /absolute/ as root, the paths going into
2866 the matcher will start with absolute/. If you give ../../relative as
2867 root, the paths will be normalized as relative/.
2868 A directory exclusion pattern can end either with or without a slash
2870 ('/'). If it ends with a slash, such as some/path/, the directory will
2871 be included but not its content. If it does not end with a slash, such
2872 as some/path, both the directory and content will be excluded.
2873 Borg supports different pattern styles. To define a non-default style
2875 for a specific pattern, prefix it with two characters followed by a
2876 colon ':' (i.e. fm:path/*, sh:path/**).
2877 Fnmatch, selector fm:
2879 This is the default style for --exclude and --exclude-from.
2880 These patterns use a variant of shell pattern syntax, with '*'
2881 matching any number of characters, '?' matching any single char‐
2882 acter, '[...]' matching any single character specified, includ‐
2883 ing ranges, and '[!...]' matching any character not specified.
2884 For the purpose of these patterns, the path separator (backslash
2885 for Windows and '/' on other systems) is not treated specially.
2886 Wrap meta-characters in brackets for a literal match (i.e. [?]
2887 to match the literal character ?). For a path to match a pat‐
2888 tern, the full path must match, or it must match from the start
2889 of the full path to just before a path separator. Except for the
2890 root path, paths will never end in the path separator when
2891 matching is attempted. Thus, if a given pattern ends in a path
2892 separator, a '*' is appended before matching is attempted. A
2893 leading path separator is always removed.
2894 Shell-style patterns, selector sh:
2896 This is the default style for --pattern and --patterns-from.
2897 Like fnmatch patterns these are similar to shell patterns. The
2898 difference is that the pattern may include **/ for matching zero
2899 or more directory levels, * for matching zero or more arbitrary
2900 characters with the exception of any path separator. A leading
2901 path separator is always removed.
2902 Regular expressions, selector re:
2904 Regular expressions similar to those found in Perl are sup‐
2905 ported. Unlike shell patterns regular expressions are not re‐
2906 quired to match the full path and any substring match is suffi‐
2907 cient. It is strongly recommended to anchor patterns to the
2908 start ('^'), to the end ('$') or both. Path separators (back‐
2909 slash for Windows and '/' on other systems) in paths are always
2910 normalized to a forward slash ('/') before applying a pattern.
2911 The regular expression syntax is described in the Python docu‐
2912 mentation for the re module.
2913 Path prefix, selector pp:
2915 This pattern style is useful to match whole sub-directories. The
2916 pattern pp:root/somedir matches root/somedir and everything
2917 therein. A leading path separator is always removed.
2918 Path full-match, selector pf:
2920 This pattern style is (only) useful to match full paths. This
2921 is kind of a pseudo pattern as it can not have any variable or
2922 unspecified parts - the full path must be given.
2923 pf:root/file.ext matches root/file.ext only. A leading path sep‐
2924 arator is always removed.
2925 Implementation note: this is implemented via very time-efficient
2927 O(1) hashtable lookups (this means you can have huge amounts of
2928 such patterns without impacting performance much). Due to that,
2929 this kind of pattern does not respect any context or order. If
2930 you use such a pattern to include a file, it will always be in‐
2931 cluded (if the directory recursion encounters it). Other in‐
2932 clude/exclude patterns that would normally match will be ig‐
2933 nored. Same logic applies for exclude.
2934 NOTE:
2936 re:, sh: and fm: patterns are all implemented on top of the Python
2937 SRE engine. It is very easy to formulate patterns for each of these
2938 types which requires an inordinate amount of time to match paths. If
2939 untrusted users are able to supply patterns, ensure they cannot sup‐
2940 ply re: patterns. Further, ensure that sh: and fm: patterns only
2941 contain a handful of wildcards at most.
2942 Exclusions can be passed via the command line option --exclude. When
2944 used from within a shell, the patterns should be quoted to protect them
2945 from expansion.
2946 The --exclude-from option permits loading exclusion patterns from a
2948 text file with one pattern per line. Lines empty or starting with the
2949 number sign ('#') after removing whitespace on both ends are ignored.
2950 The optional style selector prefix is also supported for patterns
2951 loaded from a file. Due to whitespace removal, paths with whitespace at
2952 the beginning or end can only be excluded using regular expressions.
2953 To test your exclusion patterns without performing an actual backup you
2955 can run borg create --list --dry-run ....
2956 Examples:
2958 # Exclude '/home/user/file.o' but not '/home/user/file.odt':
2960 $ borg create -e '*.o' backup /
2961 # Exclude '/home/user/junk' and '/home/user/subdir/junk' but
2963 # not '/home/user/importantjunk' or '/etc/junk':
2964 $ borg create -e 'home/*/junk' backup /
2965 # Exclude the contents of '/home/user/cache' but not the directory itself:
2967 $ borg create -e home/user/cache/ backup /
2968 # The file '/home/user/cache/important' is *not* backed up:
2970 $ borg create -e home/user/cache/ backup / /home/user/cache/important
2971 # The contents of directories in '/home' are not backed up when their name
2973 # ends in '.tmp'
2974 $ borg create --exclude 're:^home/[^/]+\.tmp/' backup /
2975 # Load exclusions from file
2977 $ cat >exclude.txt <<EOF
2978 # Comment line
2979 home/*/junk
2980 *.tmp
2981 fm:aa:something/*
2982 re:^home/[^/]+\.tmp/
2983 sh:home/*/.thumbnails
2984 # Example with spaces, no need to escape as it is processed by borg
2985 some file with spaces.txt
2986 EOF
2987 $ borg create --exclude-from exclude.txt backup /
2988 A more general and easier to use way to define filename matching pat‐
2990 terns exists with the --pattern and --patterns-from options. Using
2991 these, you may specify the backup roots, default pattern styles and
2992 patterns for inclusion and exclusion.
2993 Root path prefix R
2995 A recursion root path starts with the prefix R, followed by a
2996 path (a plain path, not a file pattern). Use this prefix to have
2997 the root paths in the patterns file rather than as command line
2998 arguments.
2999 Pattern style prefix P
3001 To change the default pattern style, use the P prefix, followed
3002 by the pattern style abbreviation (fm, pf, pp, re, sh). All
3003 patterns following this line will use this style until another
3004 style is specified.
3005 Exclude pattern prefix -
3007 Use the prefix -, followed by a pattern, to define an exclusion.
3008 This has the same effect as the --exclude option.
3009 Exclude no-recurse pattern prefix !
3011 Use the prefix !, followed by a pattern, to define an exclusion
3012 that does not recurse into subdirectories. This saves time, but
3013 prevents include patterns to match any files in subdirectories.
3014 Include pattern prefix +
3016 Use the prefix +, followed by a pattern, to define inclusions.
3017 This is useful to include paths that are covered in an exclude
3018 pattern and would otherwise not be backed up.
3019 NOTE:
3021 Via --pattern or --patterns-from you can define BOTH inclusion and
3022 exclusion of files using pattern prefixes + and -. With --exclude
3023 and --exclude-from ONLY excludes are defined.
3024 The first matching pattern is used, so if an include pattern matches
3026 before an exclude pattern, the file is backed up. Note that a no-re‐
3027 curse exclude stops examination of subdirectories so that potential in‐
3028 cludes will not match - use normal excludes for such use cases.
3029 Example:
3031 # Define the recursion root
3033 R /
3034 # Exclude all iso files in any directory
3035 - **/*.iso
3036 # Explicitly include all inside etc and root
3037 + etc/**
3038 + root/**
3039 # Exclude a specific directory under each user's home directories
3040 - home/*/.cache
3041 # Explicitly include everything in /home
3042 + home/**
3043 # Explicitly exclude some directories without recursing into them
3044 ! re:^(dev|proc|run|sys|tmp)
3045 # Exclude all other files and directories
3046 # that are not specifically included earlier.
3047 - **
3048 NOTE:
3050 It's possible that a sub-directory/file is matched while parent di‐
3051 rectories are not. In that case, parent directories are not backed
3052 up thus their user, group, permission, etc. can not be restored.
3053 Note that the default pattern style for --pattern and --patterns-from
3055 is shell style (sh:), so those patterns behave similar to rsync in‐
3056 clude/exclude patterns. The pattern style can be set via the P prefix.
3057 Patterns (--pattern) and excludes (--exclude) from the command line are
3059 considered first (in the order of appearance). Then patterns from
3060 --patterns-from are added. Exclusion patterns from --exclude-from files
3061 are appended last.
3062 Examples:
3064 # backup pics, but not the ones from 2018, except the good ones:
3066 # note: using = is essential to avoid cmdline argument parsing issues.
3067 borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
3068 # use a file with patterns:
3070 borg create --patterns-from patterns.lst repo::arch
3071 The patterns.lst file could look like that:
3073 # "sh:" pattern style is the default, so the following line is not needed:
3075 P sh
3076 R /
3077 # can be rebuild
3078 - home/*/.cache
3079 # they're downloads for a reason
3080 - home/*/Downloads
3081 # susan is a nice person
3082 # include susans home
3083 + home/susan
3084 # also back up this exact file
3085 + pf:home/bobby/specialfile.txt
3086 # don't backup the other home directories
3087 - home/*
3088 # don't even look in /proc
3089 ! proc
3090 You can specify recursion roots either on the command line or in a pat‐
3092 ternfile:
3093 # these two commands do the same thing
3095 borg create --exclude home/bobby/junk repo::arch /home/bobby /home/susan
3096 borg create --patterns-from patternfile.lst repo::arch
3097 The patternfile:
3099 # note that excludes use fm: by default and patternfiles use sh: by default.
3101 # therefore, we need to specify fm: to have the same exact behavior.
3102 P fm
3103 R /home/bobby
3104 R /home/susan
3105 - home/bobby/junk
3107 This allows you to share the same patterns between multiple reposito‐
3109 ries without needing to specify them on the command line.
3110 borg help placeholders
3112 Repository (or Archive) URLs, --prefix, --glob-archives, --comment and
3113 --remote-path values support these placeholders:
3114 {hostname}
3116 The (short) hostname of the machine.
3117 {fqdn} The full name of the machine.
3119 {reverse-fqdn}
3121 The full name of the machine in reverse domain name notation.
3122 {now} The current local date and time, by default in ISO-8601 format.
3124 You can also supply your own format string, e.g.
3125 {now:%Y-%m-%d_%H:%M:%S}
3126 {utcnow}
3128 The current UTC date and time, by default in ISO-8601 format.
3129 You can also supply your own format string, e.g. {utc‐
3130 now:%Y-%m-%d_%H:%M:%S}
3131 {user} The user name (or UID, if no name is available) of the user run‐
3133 ning borg.
3134 {pid} The current process ID.
3136 {borgversion}
3138 The version of borg, e.g.: 1.0.8rc1
3139 {borgmajor}
3141 The version of borg, only the major version, e.g.: 1
3142 {borgminor}
3144 The version of borg, only major and minor version, e.g.: 1.0
3145 {borgpatch}
3147 The version of borg, only major, minor and patch version, e.g.:
3148 1.0.8
3149 If literal curly braces need to be used, double them for escaping:
3151 borg create /path/to/repo::{{literal_text}}
3153 Examples:
3155 borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
3157 borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
3158 borg prune --glob-archives '{hostname}-*' ...
3159 NOTE:
3161 systemd uses a difficult, non-standard syntax for command lines in
3162 unit files (refer to the systemd.unit(5) manual page).
3163 When invoking borg from unit files, pay particular attention to es‐
3165 caping, especially when using the now/utcnow placeholders, since
3166 systemd performs its own %-based variable replacement even in quoted
3167 text. To avoid interference from systemd, double all percent signs
3168 ({hostname}-{now:%Y-%m-%d_%H:%M:%S} becomes {host‐
3169 name}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}).
3170 borg help compression
3172 It is no problem to mix different compression methods in one repo,
3173 deduplication is done on the source data chunks (not on the compressed
3174 or encrypted data).
3175 If some specific chunk was once compressed and stored into the repo,
3177 creating another backup that also uses this chunk will not change the
3178 stored chunk. So if you use different compression specs for the back‐
3179 ups, whichever stores a chunk first determines its compression. See
3180 also borg recreate.
3181 Compression is lz4 by default. If you want something else, you have to
3183 specify what you want.
3184 Valid compression specifiers are:
3186 none Do not compress.
3188 lz4 Use lz4 compression. Very high speed, very low compression. (de‐
3190 fault)
3191 zstd[,L]
3193 Use zstd ("zstandard") compression, a modern wide-range algo‐
3194 rithm. If you do not explicitly give the compression level L
3195 (ranging from 1 to 22), it will use level 3. Archives com‐
3196 pressed with zstd are not compatible with borg < 1.1.4.
3197 zlib[,L]
3199 Use zlib ("gz") compression. Medium speed, medium compression.
3200 If you do not explicitly give the compression level L (ranging
3201 from 0 to 9), it will use level 6. Giving level 0 (means "no
3202 compression", but still has zlib protocol overhead) is usually
3203 pointless, you better use "none" compression.
3204 lzma[,L]
3206 Use lzma ("xz") compression. Low speed, high compression. If
3207 you do not explicitly give the compression level L (ranging from
3208 0 to 9), it will use level 6. Giving levels above 6 is point‐
3209 less and counterproductive because it does not compress better
3210 due to the buffer size used by borg - but it wastes lots of CPU
3211 cycles and RAM.
3212 auto,C[,L]
3214 Use a built-in heuristic to decide per chunk whether to compress
3215 or not. The heuristic tries with lz4 whether the data is com‐
3216 pressible. For incompressible data, it will not use compression
3217 (uses "none"). For compressible data, it uses the given C[,L]
3218 compression - with C[,L] being any valid compression specifier.
3219 obfuscate,SPEC,C[,L]
3221 Use compressed-size obfuscation to make fingerprinting attacks
3222 based on the observable stored chunk size more difficult. Note:
3223 • You must combine this with encryption, or it won't make any
3225 sense.
3226 • Your repo size will be bigger, of course.
3228 • A chunk is limited by the constant MAX_DATA_SIZE (cur.
3230 ~20MiB).
3231 The SPEC value determines how the size obfuscation works:
3233 Relative random reciprocal size variation (multiplicative)
3235 Size will increase by a factor, relative to the compressed data
3237 size. Smaller factors are used often, larger factors rarely.
3238 Available factors:
3240 1: 0.01 .. 100
3242 2: 0.1 .. 1,000
3243 3: 1 .. 10,000
3244 4: 10 .. 100,000
3245 5: 100 .. 1,000,000
3246 6: 1,000 .. 10,000,000
3247 Example probabilities for SPEC 1:
3249 90 % 0.01 .. 0.1
3251 9 % 0.1 .. 1
3252 0.9 % 1 .. 10
3253 0.09% 10 .. 100
3254 Randomly sized padding up to the given size (additive)
3256 110: 1kiB (2 ^ (SPEC - 100))
3258 ...
3259 120: 1MiB
3260 ...
3261 123: 8MiB (max.)
3262 Examples:
3264 borg create --compression lz4 REPO::ARCHIVE data
3266 borg create --compression zstd REPO::ARCHIVE data
3267 borg create --compression zstd,10 REPO::ARCHIVE data
3268 borg create --compression zlib REPO::ARCHIVE data
3269 borg create --compression zlib,1 REPO::ARCHIVE data
3270 borg create --compression auto,lzma,6 REPO::ARCHIVE data
3271 borg create --compression auto,lzma ...
3272 borg create --compression obfuscate,110,none ...
3273 borg create --compression obfuscate,3,auto,zstd,10 ...
3274 borg create --compression obfuscate,2,zstd,6 ...
3275
3277 There is a borg debug command that has some subcommands which are all
3278 not intended for normal use and potentially very dangerous if used in‐
3279 correctly.
3280 For example, borg debug put-obj and borg debug delete-obj will only do
3282 what their name suggests: put objects into repo / delete objects from
3283 repo.
3284 Please note:
3286 • they will not update the chunks cache (chunks index) about the object
3288 • they will not update the manifest (so no automatic chunks index
3290 resync is triggered)
3291 • they will not check whether the object is in use (e.g. before
3293 delete-obj)
3294 • they will not update any metadata which may point to the object
3296 They exist to improve debugging capabilities without direct system ac‐
3298 cess, e.g. in case you ever run into some severe malfunction. Use them
3299 only if you know what you are doing or if a trusted Borg developer
3300 tells you what to do.
3301 Borg has a --debug-topic TOPIC option to enable specific debugging mes‐
3303 sages. Topics are generally not documented.
3304 A --debug-profile FILE option exists which writes a profile of the main
3306 program's execution to a file. The format of these files is not di‐
3307 rectly compatible with the Python profiling tools, since these use the
3308 "marshal" format, which is not intended to be secure (quoting the
3309 Python docs: "Never unmarshal data received from an untrusted or unau‐
3310 thenticated source.").
3311 The borg debug profile-convert command can be used to take a Borg pro‐
3313 file and convert it to a profile file that is compatible with the
3314 Python tools.
3315 Additionally, if the filename specified for --debug-profile ends with
3317 ".pyprof" a Python compatible profile is generated. This is only in‐
3318 tended for local use by developers.
3319
3321 Here are misc. notes about topics that are maybe not covered in enough
3322 detail in the usage section.
3323 --chunker-params
3325 The chunker params influence how input files are cut into pieces
3326 (chunks) which are then considered for deduplication. They also have a
3327 big impact on resource usage (RAM and disk space) as the amount of re‐
3328 sources needed is (also) determined by the total amount of chunks in
3329 the repository (see Indexes / Caches memory usage for details).
3330 --chunker-params=buzhash,10,23,16,4095 results in a fine-grained dedu‐
3332 plication| and creates a big amount of chunks and thus uses a lot of
3333 resources to manage them. This is good for relatively small data vol‐
3334 umes and if the machine has a good amount of free RAM and disk space.
3335 --chunker-params=buzhash,19,23,21,4095 (default) results in a
3337 coarse-grained deduplication and creates a much smaller amount of
3338 chunks and thus uses less resources. This is good for relatively big
3339 data volumes and if the machine has a relatively low amount of free RAM
3340 and disk space.
3341 --chunker-params=fixed,4194304 results in fixed 4MiB sized block dedu‐
3343 plication and is more efficient than the previous example when used for
3344 for block devices (like disks, partitions, LVM LVs) or raw disk image
3345 files.
3346 --chunker-params=fixed,4096,512 results in fixed 4kiB sized blocks, but
3348 the first header block will only be 512B long. This might be useful to
3349 dedup files with 1 header + N fixed size data blocks. Be careful to not
3350 produce a too big amount of chunks (like using small block size for
3351 huge files).
3352 If you already have made some archives in a repository and you then
3354 change chunker params, this of course impacts deduplication as the
3355 chunks will be cut differently.
3356 In the worst case (all files are big and were touched in between back‐
3358 ups), this will store all content into the repository again.
3359 Usually, it is not that bad though:
3361 • usually most files are not touched, so it will just re-use the old
3363 chunks it already has in the repo
3364 • files smaller than the (both old and new) minimum chunksize result in
3366 only one chunk anyway, so the resulting chunks are same and dedupli‐
3367 cation will apply
3368 If you switch chunker params to save resources for an existing repo
3370 that already has some backup archives, you will see an increasing ef‐
3371 fect over time, when more and more files have been touched and stored
3372 again using the bigger chunksize and all references to the smaller
3373 older chunks have been removed (by deleting / pruning archives).
3374 If you want to see an immediate big effect on resource usage, you bet‐
3376 ter start a new repository when changing chunker params.
3377 For more details, see Chunks.
3379 --noatime / --noctime
3381 You can use these borg create options to not store the respective time‐
3382 stamp into the archive, in case you do not really need it.
3383 Besides saving a little space for the not archived timestamp, it might
3385 also affect metadata stream deduplication: if only this timestamp
3386 changes between backups and is stored into the metadata stream, the
3387 metadata stream chunks won't deduplicate just because of that.
3388 --nobsdflags / --noflags
3390 You can use this to not query and store (or not extract and set) flags
3391 - in case you don't need them or if they are broken somehow for your
3392 fs.
3393 On Linux, dealing with the flags needs some additional syscalls. Espe‐
3395 cially when dealing with lots of small files, this causes a noticeable
3396 overhead, so you can use this option also for speeding up operations.
3397 --umask
3399 borg uses a safe default umask of 077 (that means the files borg cre‐
3400 ates have only permissions for owner, but no permissions for group and
3401 others) - so there should rarely be a need to change the default behav‐
3402 iour.
3403 This option only affects the process to which it is given. Thus, when
3405 you run borg in client/server mode and you want to change the behaviour
3406 on the server side, you need to use borg serve --umask=XXX ... as a ssh
3407 forced command in authorized_keys. The --umask value given on the
3408 client side is not transferred to the server side.
3409 Also, if you choose to use the --umask option, always be consistent and
3411 use the same umask value so you do not create a mixup of permissions in
3412 a borg repository or with other files borg creates.
3413 --read-special
3415 The --read-special option is special - you do not want to use it for
3416 normal full-filesystem backups, but rather after carefully picking some
3417 targets for it.
3418 The option --read-special triggers special treatment for block and char
3420 device files as well as FIFOs. Instead of storing them as such a device
3421 (or FIFO), they will get opened, their content will be read and in the
3422 backup archive they will show up like a regular file.
3423 Symlinks will also get special treatment if (and only if) they point to
3425 such a special file: instead of storing them as a symlink, the target
3426 special file will get processed as described above.
3427 One intended use case of this is backing up the contents of one or mul‐
3429 tiple block devices, like e.g. LVM snapshots or inactive LVs or disk
3430 partitions.
3431 You need to be careful about what you include when using --read-spe‐
3433 cial, e.g. if you include /dev/zero, your backup will never terminate.
3434 Restoring such files' content is currently only supported one at a time
3436 via --stdout option (and you have to redirect stdout to where ever it
3437 shall go, maybe directly into an existing device file of your choice or
3438 indirectly via dd).
3439 To some extent, mounting a backup archive with the backups of special
3441 files via borg mount and then loop-mounting the image files from inside
3442 the mount point will work. If you plan to access a lot of data in
3443 there, it likely will scale and perform better if you do not work via
3444 the FUSE mount.
3445 Example
3447 Imagine you have made some snapshots of logical volumes (LVs) you want
3448 to backup.
3449 NOTE:
3451 For some scenarios, this is a good method to get "crash-like" con‐
3452 sistency (I call it crash-like because it is the same as you would
3453 get if you just hit the reset button or your machine would abruptly
3454 and completely crash). This is better than no consistency at all
3455 and a good method for some use cases, but likely not good enough if
3456 you have databases running.
3457 Then you create a backup archive of all these snapshots. The backup
3459 process will see a "frozen" state of the logical volumes, while the
3460 processes working in the original volumes continue changing the data
3461 stored there.
3462 You also add the output of lvdisplay to your backup, so you can see the
3464 LV sizes in case you ever need to recreate and restore them.
3465 After the backup has completed, you remove the snapshots again.
3467 $ # create snapshots here
3469 $ lvdisplay > lvdisplay.txt
3470 $ borg create --read-special /path/to/repo::arch lvdisplay.txt /dev/vg0/*-snapshot
3471 $ # remove snapshots here
3472 Now, let's see how to restore some LVs from such a backup.
3474 $ borg extract /path/to/repo::arch lvdisplay.txt
3476 $ # create empty LVs with correct sizes here (look into lvdisplay.txt).
3477 $ # we assume that you created an empty root and home LV and overwrite it now:
3478 $ borg extract --stdout /path/to/repo::arch dev/vg0/root-snapshot > /dev/vg0/root
3479 $ borg extract --stdout /path/to/repo::arch dev/vg0/home-snapshot > /dev/vg0/home
3480 Separate compaction
3482 Borg does not auto-compact the segment files in the repository at com‐
3483 mit time (at the end of each repository-writing command) any more.
3484 This is new since borg 1.2.0 and requires borg >= 1.2.0 on client and
3486 server.
3487 This causes a similar behaviour of the repository as if it was in ap‐
3489 pend-only mode (see below) most of the time (until borg compact is in‐
3490 voked or an old client triggers auto-compaction).
3491 This has some notable consequences:
3493 • repository space is not freed immediately when deleting / pruning ar‐
3495 chives
3496 • commands finish quicker
3498 • repository is more robust and might be easier to recover after dam‐
3500 ages (as it contains data in a more sequential manner, historic mani‐
3501 fests, multiple commits - until you run borg compact)
3502 • user can choose when to run compaction (it should be done regularly,
3504 but not necessarily after each single borg command)
3505 • user can choose from where to invoke borg compact to do the com‐
3507 paction (from client or from server, it does not need a key)
3508 • less repo sync data traffic in case you create a copy of your reposi‐
3510 tory by using a sync tool (like rsync, rclone, ...)
3511 You can manually run compaction by invoking the borg compact command.
3513 Append-only mode (forbid compaction)
3515 A repository can be made "append-only", which means that Borg will
3516 never overwrite or delete committed data (append-only refers to the
3517 segment files, but borg will also reject to delete the repository com‐
3518 pletely).
3519 If borg compact command is used on a repo in append-only mode, there
3521 will be no warning or error, but no compaction will happen.
3522 append-only is useful for scenarios where a backup client machine back‐
3524 ups remotely to a backup server using borg serve, since a hacked client
3525 machine cannot delete backups on the server permanently.
3526 To activate append-only mode, set append_only to 1 in the repository
3528 config:
3529 borg config /path/to/repo append_only 1
3531 Note that you can go back-and-forth between normal and append-only op‐
3533 eration with borg config; it's not a "one way trip."
3534 In append-only mode Borg will create a transaction log in the transac‐
3536 tions file, where each line is a transaction and a UTC timestamp.
3537 In addition, borg serve can act as if a repository is in append-only
3539 mode with its option --append-only. This can be very useful for
3540 fine-tuning access control in .ssh/authorized_keys:
3541 command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustable backup clients>
3543 command="borg serve ..." ssh-rsa <key used for backup management>
3544 Running borg init via a borg serve --append-only server will not create
3546 an append-only repository. Running borg init --append-only creates an
3547 append-only repository regardless of server settings.
3548 Example
3550 Suppose an attacker remotely deleted all backups, but your repository
3551 was in append-only mode. A transaction log in this situation might look
3552 like this:
3553 transaction 1, UTC time 2016-03-31T15:53:27.383532
3555 transaction 5, UTC time 2016-03-31T15:53:52.588922
3556 transaction 11, UTC time 2016-03-31T15:54:23.887256
3557 transaction 12, UTC time 2016-03-31T15:55:54.022540
3558 transaction 13, UTC time 2016-03-31T15:55:55.472564
3559 From your security logs you conclude the attacker gained access at
3561 15:54:00 and all the backups where deleted or replaced by compromised
3562 backups. From the log you know that transactions 11 and later are com‐
3563 promised. Note that the transaction ID is the name of the last file in
3564 the transaction. For example, transaction 11 spans files 6 to 11.
3565 In a real attack you'll likely want to keep the compromised repository
3567 intact to analyze what the attacker tried to achieve. It's also a good
3568 idea to make this copy just in case something goes wrong during the re‐
3569 covery. Since recovery is done by deleting some files, a hard link copy
3570 (cp -al) is sufficient.
3571 The first step to reset the repository to transaction 5, the last un‐
3573 compromised transaction, is to remove the hints.N, index.N and integ‐
3574 rity.N files in the repository (these files are always expendable). In
3575 this example N is 13.
3576 Then remove or move all segment files from the segment directories in
3578 data/ starting with file 6:
3579 rm data/**/{6..13}
3581 That's all to do in the repository.
3583 If you want to access this rollbacked repository from a client that al‐
3585 ready has a cache for this repository, the cache will reflect a newer
3586 repository state than what you actually have in the repository now, af‐
3587 ter the rollback.
3588 Thus, you need to clear the cache:
3590 borg delete --cache-only repo
3592 The cache will get rebuilt automatically. Depending on repo size and
3594 archive count, it may take a while.
3595 You also will need to remove ~/.config/borg/security/REPOID/mani‐
3597 fest-timestamp.
3598 Drawbacks
3600 As data is only appended, and nothing removed, commands like prune or
3601 delete won't free disk space, they merely tag data as deleted in a new
3602 transaction.
3603 Be aware that as soon as you write to the repo in non-append-only mode
3605 (e.g. prune, delete or create archives from an admin machine), it will
3606 remove the deleted objects permanently (including the ones that were
3607 already marked as deleted, but not removed, in append-only mode). Auto‐
3608 mated edits to the repository (such as a cron job running borg prune)
3609 will render append-only mode moot if data is deleted.
3610 Even if an archive appears to be available, it is possible an attacker
3612 could delete just a few chunks from an archive and silently corrupt its
3613 data. While in append-only mode, this is reversible, but borg check
3614 should be run before a writing/pruning operation on an append-only
3615 repository to catch accidental or malicious corruption:
3616 # run without append-only mode
3618 borg check --verify-data repo && borg compact repo
3619 Aside from checking repository & archive integrity you may want to also
3621 manually check backups to ensure their content seems correct.
3622 Further considerations
3624 Append-only mode is not respected by tools other than Borg. rm still
3625 works on the repository. Make sure that backup client machines only get
3626 to access the repository via borg serve.
3627 Ensure that no remote access is possible if the repository is temporar‐
3629 ily set to normal mode for e.g. regular pruning.
3630 Further protections can be implemented, but are outside of Borg's
3632 scope. For example, file system snapshots or wrapping borg serve to set
3633 special permissions or ACLs on new data files.
3634 SSH batch mode
3636 When running Borg using an automated script, ssh might still ask for a
3637 password, even if there is an SSH key for the target server. Use this
3638 to make scripts more robust:
3639 export BORG_RSH='ssh -oBatchMode=yes'
3641
3643 The Borg Collective (see AUTHORS file)
3644
3646 2010-2023 Jonas Borgström, 2015-2023 The Borg Collective (see AUTHORS
3647 file)
36481.2.6 2023-09-05 BORG(1)