1BORG(1)                  Borg - Deduplicating Archiver                 BORG(1)
2
3
4

NAME

6       borg  - BorgBackup is a deduplicating backup program with optional com‐
7       pression and authenticated encryption.
8

GENERAL

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
14       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
19       Experimental  features  are  not  stable,  which means that they may be
20       changed in incompatible ways or even  removed  entirely  without  prior
21       notice in following releases.
22
23   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
28          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
33       This    is    due    to    a    problem   in   the   argparse   module:
34       https://bugs.python.org/issue15112
35
36   Repository URLs
37       Local filesystem (or locally mounted network filesystem):
38
39       /path/to/repo - filesystem path to repo directory, absolute path
40
41       path/to/repo - filesystem path to repo directory, relative path
42
43       Also, stuff like ~/path/to/repo or ~other/path/to/repo works  (this  is
44       expanded by your shell).
45
46       Note:  you  may  also prepend a file:// to a filesystem path to get URL
47       style.
48
49       Remote repositories accessed via ssh user@host:
50
51       user@host:/path/to/repo - remote repo, absolute path
52
53       ssh://user@host:port/path/to/repo - same, alternative syntax, port  can
54       be given
55
56       Remote repositories with relative paths can be given using this syntax:
57
58       user@host:path/to/repo - path relative to current directory
59
60       user@host:~/path/to/repo - path relative to user's home directory
61
62       user@host:~other/path/to/repo - path relative to other's home directory
63
64       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
68       Remote repositories with relative paths, alternative syntax with port:
69
70       ssh://user@host:port/./path/to/repo  -  path relative to current direc‐
71       tory
72
73       ssh://user@host:port/~/path/to/repo -  path  relative  to  user's  home
74       directory
75
76       ssh://user@host:port/~other/path/to/repo  -  path  relative  to other's
77       home directory
78
79       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
82          export BORG_REPO='ssh://user@host:port/path/to/repo'
83
84       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
87       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
90   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
95       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
100       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
104   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
111       If you want to capture the log output to a file, just redirect it:
112
113          borg create repo::archive myfiles 2>> logfile
114
115       Custom logging configurations can be implemented via BORG_LOGGING_CONF.
116
117       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
122       Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
123
124       Use --debug to set DEBUG log level - to get debug, info, warning, error
125       and critical level output.
126
127       Use --info (or -v or --verbose) to set INFO log level -  to  get  info,
128       warning, error and critical level output.
129
130       Use  --warning  (default)  to  set  WARNING log level - to get warning,
131       error and critical level output.
132
133       Use --error to set ERROR log level - to get error  and  critical  level
134       output.
135
136       Use  --critical  to set CRITICAL log level - to get critical level out‐
137       put.
138
139       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
143       WARNING:
144          Options --critical and --error are provided for completeness,  their
145          usage is not recommended as you might miss important information.
146
147   Return codes
148       Borg can exit with the following return codes (rc):
149
150                     ┌────────────┬────────────────────────────┐
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
171       If you use --show-rc, the return code is also logged at  the  indicated
172       level as the last log entry.
173
174   Environment Variables
175       Borg uses some environment variables for automation:
176
177       General:
178
179              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
186              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
193              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
204              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
213              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
220              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
225              BORG_HOSTNAME_IS_UNIQUE=no
226                     Borg assumes that it can derive a unique hostname / iden‐
227                     tity (see borg debug info).  If this is not the  case  or
228                     you do not want Borg to automatically remove stale locks,
229                     set this to no.
230
231              BORG_HOST_ID
232                     Borg usually computes a host id from the  FQDN  plus  the
233                     results of uuid.getnode() (which usually returns a unique
234                     id based on the MAC address  of  the  network  interface.
235                     Except  if that MAC happens to be all-zero - in that case
236                     it returns a random value, which  is  not  what  we  want
237                     (because  it kills automatic stale lock removal).  So, if
238                     you have a all-zero MAC address or other reasons to  bet‐
239                     ter  externally  control the host id, just set this envi‐
240                     ronment variable to a unique value. If all your FQDNs are
241                     unique,   you   can  just  use  the  FQDN.  If  not,  use
242                     fqdn@uniqueid.
243
244              BORG_LOGGING_CONF
245                     When set, use the given  filename  as  INI-style  logging
246                     configuration.   A  basic  example  conf  can be found at
247                     docs/misc/logging.conf.
248
249              BORG_RSH
250                     When set, use this command instead of ssh.  This  can  be
251                     used  to  specify  ssh options, such as a custom identity
252                     file ssh -i /path/to/private/key. See man ssh  for  other
253                     options. Using the --rsh CMD commandline option overrides
254                     the environment variable.
255
256              BORG_REMOTE_PATH
257                     When set, use the given path as borg  executable  on  the
258                     remote    (defaults   to   "borg"   if   unset).    Using
259                     --remote-path PATH commandline option overrides the envi‐
260                     ronment variable.
261
262              BORG_FILES_CACHE_SUFFIX
263                     When  set  to  a  value  at  least  one  character  long,
264                     instructs borg to use a specifically named (based on  the
265                     suffix)  alternative  files  cache.  This  can be used to
266                     avoid loading and saving cache entries for backup sources
267                     other than the current sources.
268
269              BORG_FILES_CACHE_TTL
270                     When  set to a numeric value, this determines the maximum
271                     "time to live" for the files cache entries (default: 20).
272                     The  files  cache  is used to quickly determine whether a
273                     file is unchanged.  The FAQ explains this  more  detailed
274                     in: always_chunking
275
276              BORG_SHOW_SYSINFO
277                     When  set  to no (default: yes), system information (like
278                     OS, Python version, ...)  in  exceptions  is  not  shown.
279                     Please  only  use  for  good  reasons  as it makes issues
280                     harder to analyze.
281
282              BORG_WORKAROUNDS
283                     A list of comma  separated  strings  that  trigger  work‐
284                     arounds  in borg, e.g. to work around bugs in other soft‐
285                     ware.
286
287                     Currently known strings are:
288
289                     basesyncfile
290                            Use the more simple  BaseSyncFile  code  to  avoid
291                            issues  with sync_file_range.  You might need this
292                            to run borg on WSL (Windows Subsystem  for  Linux)
293                            or  in systemd.nspawn containers on some architec‐
294                            tures (e.g. ARM).  Using this does not affect data
295                            safety, but might result in a more bursty write to
296                            disk  behaviour  (not  continuously  streaming  to
297                            disk).
298
299       Some  automatic  answerers (if set, they automatically answer confirma‐
300       tion questions):
301
302              BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
303                     For "Warning: Attempting to access a  previously  unknown
304                     unencrypted repository"
305
306              BORG_RELOCATED_REPO_ACCESS_IS_OK=no (or =yes)
307                     For  "Warning:  The repository at location ... was previ‐
308                     ously located at ..."
309
310              BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
311                     For "This is a potentially dangerous function..."  (check
312                     --repair)
313
314              BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
315                     For  "You  requested  to completely DELETE the repository
316                     including all archives it contains:"
317
318              Note: answers are case  sensitive.  setting  an  invalid  answer
319              value  might  either give the default answer or ask you interac‐
320              tively, depending  on  whether  retries  are  allowed  (they  by
321              default  are allowed). So please test your scripts interactively
322              before making them a non-interactive script.
323
324       Directories and files:
325
326              BORG_BASE_DIR
327                     Defaults to $HOME or ~$USER or ~ (in that order).  If you
328                     want  to  move all borg-specific folders to a custom path
329                     at once, all you need to do is to  modify  BORG_BASE_DIR:
330                     the other paths for cache, config etc. will adapt accord‐
331                     ingly (assuming you didn't set them to a different custom
332                     value).
333
334              BORG_CACHE_DIR
335                     Defaults  to $BORG_BASE_DIR/.cache/borg. If BORG_BASE_DIR
336                     is not explicitly set while XDG env var XDG_CACHE_HOME is
337                     set,  then  $XDG_CACHE_HOME/borg  is  being used instead.
338                     This directory contains the local cache and might need  a
339                     lot of space for dealing with big repositories. Make sure
340                     you're aware of the associated security  aspects  of  the
341                     cache location: cache_security
342
343              BORG_CONFIG_DIR
344                     Defaults to $BORG_BASE_DIR/.config/borg. If BORG_BASE_DIR
345                     is not explicitly set while XDG env  var  XDG_CONFIG_HOME
346                     is set, then $XDG_CONFIG_HOME/borg is being used instead.
347                     This directory contains all borg  configuration  directo‐
348                     ries,  see the FAQ for a security advisory about the data
349                     in this directory: home_config_borg
350
351              BORG_SECURITY_DIR
352                     Defaults to  $BORG_CONFIG_DIR/security.   This  directory
353                     contains  information  borg  uses  to  track its usage of
354                     NONCES ("numbers used once" - usually in encryption  con‐
355                     text) and other security relevant data.
356
357              BORG_KEYS_DIR
358                     Defaults  to  $BORG_CONFIG_DIR/keys.  This directory con‐
359                     tains keys for encrypted repositories.
360
361              BORG_KEY_FILE
362                     When set, use the given filename as repository key file.
363
364              TMPDIR This is where temporary files are stored  (might  need  a
365                     lot of temporary space for some operations), see tempfile
366                     for details.
367
368       Building:
369
370              BORG_OPENSSL_PREFIX
371                     Adds given OpenSSL header file directory to  the  default
372                     locations (setup.py).
373
374              BORG_LIBLZ4_PREFIX
375                     Adds  given prefix directory to the default locations. If
376                     a 'include/lz4.h' is found Borg will  be  linked  against
377                     the  system  liblz4  instead of a bundled implementation.
378                     (setup.py)
379
380              BORG_LIBB2_PREFIX
381                     Adds given prefix directory to the default locations.  If
382                     a 'include/blake2.h' is found Borg will be linked against
383                     the system libb2 instead  of  a  bundled  implementation.
384                     (setup.py)
385
386              BORG_LIBZSTD_PREFIX
387                     Adds  given prefix directory to the default locations. If
388                     a 'include/zstd.h' is found Borg will be  linked  against
389                     the  system  libzstd instead of a bundled implementation.
390                     (setup.py)
391
392       Please note:
393
394       · Be very careful when using the "yes" sayers, the warnings with prompt
395         exist for your / your data's security/safety.
396
397       · Also be very careful when putting your passphrase into a script, make
398         sure it has appropriate file permissions (e.g.  mode 600, root:root).
399
400   File systems
401       We strongly recommend against using Borg (or  any  other  database-like
402       software) on non-journaling file systems like FAT, since it is not pos‐
403       sible to assume any consistency in case of power failures (or a  sudden
404       disconnect of an external drive or similar failures).
405
406       While  Borg  uses a data store that is resilient against these failures
407       when used on journaling file systems, it is not possible  to  guarantee
408       this  with  some hardware -- independent of the software used. We don't
409       know a list of affected hardware.
410
411       If you are suspicious whether your Borg repository is still  consistent
412       and  readable  after  one of the failures mentioned above occurred, run
413       borg check --verify-data to make sure it is consistent.
414
415       Requirements for Borg repository file systems
416
417       · Long file names
418
419       · At least three directory levels with short names
420
421       · Typically, file sizes up to a few hundred MB.  Large repositories may
422         require large files (>2 GB).
423
424       · Up  to  1000  files per directory (10000 for repositories initialized
425         with Borg 1.0)
426
427       · mkdir(2) should be atomic, since it is used for locking
428
429       · Hardlinks are needed for borg_upgrade (if  --inplace  option  is  not
430         used).   Also hardlinks are used for more safe and secure file updat‐
431         ing (e.g. of the repo config file), but the code tries to  work  also
432         if hardlinks are not supported.
433
434   Units
435       To  display quantities, Borg takes care of respecting the usual conven‐
436       tions of scale. Disk sizes are displayed in decimal,  using  powers  of
437       ten  (so  kB  means  1000 bytes). For memory usage, binary prefixes are
438       used, and are indicated using the IEC binary prefixes, using powers  of
439       two (so KiB means 1024 bytes).
440
441   Date and Time
442       We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and
443       HH:MM:SS (24h clock).
444
445       For more information about that, see: https://xkcd.com/1179/
446
447       Unless otherwise noted, we display local date and time.  Internally, we
448       store and process date and time as UTC.
449
450   Resource Usage
451       Borg might use a lot of resources depending on the size of the data set
452       it is dealing with.
453
454       If one uses Borg in a client/server way (with a ssh:  repository),  the
455       resource  usage occurs in part on the client and in another part on the
456       server.
457
458       If one uses Borg as a single process (with a filesystem repo), all  the
459       resource  usage  occurs  in  that  one process, so just add up client +
460       server to get the approximate resource usage.
461
462       CPU client:
463
464              · borg create: does chunking, hashing, compression, crypto (high
465                CPU usage)
466
467              · chunks cache sync: quite heavy on CPU, doing lots of hashtable
468                operations.
469
470              · borg extract: crypto, decompression (medium to high CPU usage)
471
472              · borg check: similar to extract, but depends on options given.
473
474              · borg prune / borg delete archive: low to medium CPU usage
475
476              · borg delete repo: done on the server
477
478              It won't go beyond 100% of 1 core as the code is currently  sin‐
479              gle-threaded.   Especially higher zlib and lzma compression lev‐
480              els use significant amounts of CPU cycles. Crypto might be cheap
481              on the CPU (if hardware accelerated) or expensive (if not).
482
483       CPU server:
484              It  usually  doesn't  need  much  CPU,  it  just  deals with the
485              key/value store (repository) and uses the repository  index  for
486              that.
487
488              borg  check:  the repository check computes the checksums of all
489              chunks (medium CPU usage) borg delete repo: low CPU usage
490
491       CPU (only for client/server operation):
492              When using borg in a client/server way with  a  ssh:-type  repo,
493              the  ssh  processes  used for the transport layer will need some
494              CPU on the client and on the server due to the crypto  they  are
495              doing - esp. if you are pumping big amounts of data.
496
497       Memory (RAM) client:
498              The  chunks  index  and the files index are read into memory for
499              performance reasons. Might  need  big  amounts  of  memory  (see
500              below).   Compression,  esp.  lzma  compression with high levels
501              might need substantial amounts of memory.
502
503       Memory (RAM) server:
504              The server process will load the repository index  into  memory.
505              Might  need considerable amounts of memory, but less than on the
506              client (see below).
507
508       Chunks index (client only):
509              Proportional to the amount of data chunks in your repo. Lots  of
510              chunks in your repo imply a big chunks index.  It is possible to
511              tweak the chunker params (see create options).
512
513       Files index (client only):
514              Proportional to the amount of files in your last backups. Can be
515              switched off (see create options), but next backup might be much
516              slower if you do.  The speed benefit of using the files cache is
517              proportional to file size.
518
519       Repository index (server only):
520              Proportional  to the amount of data chunks in your repo. Lots of
521              chunks in your repo imply a big repository index.  It is  possi‐
522              ble  to  tweak the chunker params (see create options) to influ‐
523              ence the amount of chunks being created.
524
525       Temporary files (client):
526              Reading data and metadata from a FUSE  mounted  repository  will
527              consume  up to the size of all deduplicated, small chunks in the
528              repository. Big chunks won't be locally cached.
529
530       Temporary files (server):
531              A non-trivial amount of data will be stored on the  remote  temp
532              directory for each client that connects to it. For some remotes,
533              this can fill the default temporary directory at /tmp. This  can
534              be  remediated  by ensuring the $TMPDIR, $TEMP, or $TMP environ‐
535              ment variable is properly set for the sshd  process.   For  some
536              OSes,  this can be done just by setting the correct value in the
537              .bashrc (or equivalent login config file for other shells), how‐
538              ever  in  other cases it may be necessary to first enable Permi‐
539              tUserEnvironment yes in your sshd_config file, then add environ‐
540              ment="TMPDIR=/my/big/tmpdir"  at  the start of the public key to
541              be used in the authorized_hosts file.
542
543       Cache files (client only):
544              Contains the chunks index and files index (plus a collection  of
545              single-  archive  chunk indexes which might need huge amounts of
546              disk space, depending on archive count and size - see FAQ  about
547              how to reduce).
548
549       Network (only for client/server operation):
550              If  your  repository is remote, all deduplicated (and optionally
551              compressed/ encrypted) data of course has to go over the connec‐
552              tion  (ssh://  repo  url).  If you use a locally mounted network
553              filesystem, additionally some copy operations used for  transac‐
554              tion support also go over the connection. If you backup multiple
555              sources to one target repository, additional traffic happens for
556              cache resynchronization.
557
558   Support for file metadata
559       Besides regular file and directory structures, Borg can preserve
560
561       · symlinks (stored as symlink, the symlink is not followed)
562
563       · special files:
564
565         · character and block device files (restored via mknod)
566
567         · FIFOs ("named pipes")
568
569         · special  file contents can be backed up in --read-special mode.  By
570           default the metadata to create them with mknod(2),  mkfifo(2)  etc.
571           is stored.
572
573       · hardlinked  regular  files,  devices, FIFOs (considering all items in
574         the same archive)
575
576       · timestamps in nanosecond precision: mtime, atime, ctime
577
578       · other timestamps: birthtime (on platforms supporting it)
579
580       · permissions:
581
582         · IDs of owning user and owning group
583
584         · names of owning user and owning group (if the IDs can be resolved)
585
586         · Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky)
587
588       On some platforms additional features are supported:
589
590                ┌─────────────────┬──────────┬───────────┬───────────┐
591                │Platform         │ ACLs [5] │ xattr [6] │ Flags [7] │
592                ├─────────────────┼──────────┼───────────┼───────────┤
593                │Linux            │ Yes      │ Yes       │ Yes [1]   │
594                ├─────────────────┼──────────┼───────────┼───────────┤
595                │Mac OS X         │ Yes      │ Yes       │ Yes (all) │
596                ├─────────────────┼──────────┼───────────┼───────────┤
597                │FreeBSD          │ Yes      │ Yes       │ Yes (all) │
598                ├─────────────────┼──────────┼───────────┼───────────┤
599                │OpenBSD          │ n/a      │ n/a       │ Yes (all) │
600                ├─────────────────┼──────────┼───────────┼───────────┤
601                │NetBSD           │ n/a      │ No [2]    │ Yes (all) │
602                └─────────────────┴──────────┴───────────┴───────────┘
603
604                │Solaris and  de‐ │ No [3]   │ No [3]    │ n/a       │
605                │rivatives        │          │           │           │
606                ├─────────────────┼──────────┼───────────┼───────────┤
607                │Windows (cygwin) │ No [4]   │ No        │ No        │
608                └─────────────────┴──────────┴───────────┴───────────┘
609
610       Other  Unix-like  operating systems may work as well, but have not been
611       tested at all.
612
613       Note that most of the platform-dependent features also  depend  on  the
614       file  system.   For example, ntfs-3g on Linux isn't able to convey NTFS
615       ACLs.
616
617       [1]  Only "nodump", "immutable", "compressed"  and  "append"  are  sup‐
618            ported.  Feature request #618 for more flags.
619
620       [2]  Feature request #1332
621
622       [3]  Feature request #1337
623
624       [4]  Cygwin  tries to map NTFS ACLs to permissions with varying degrees
625            of success.
626
627       [5]  The native access control list mechanism of the OS. This  normally
628            limits  access  to  non-native ACLs. For example, NTFS ACLs aren't
629            completely accessible on Linux with ntfs-3g.
630
631       [6]  extended attributes; key-value pairs attached to  a  file,  mainly
632            used by the OS.  This includes resource forks on Mac OS X.
633
634       [7]  aka BSD flags. The Linux set of flags [1] is portable across plat‐
635            forms.  The BSDs define additional flags.
636
637            In case you are interested in more details (like formulas), please
638            see  internals. For details on the available JSON output, refer to
639            json_output.
640
641   Common options
642       All Borg commands share these options:
643
644       -h, --help
645              show this help message and exit
646
647       --critical
648              work on log level CRITICAL
649
650       --error
651              work on log level ERROR
652
653       --warning
654              work on log level WARNING (default)
655
656       --info, -v, --verbose
657              work on log level INFO
658
659       --debug
660              enable debug output, work on log level DEBUG
661
662       --debug-topic TOPIC
663              enable TOPIC debugging (can be specified  multiple  times).  The
664              logger  path  is borg.debug.<TOPIC> if TOPIC is not fully quali‐
665              fied.
666
667       -p, --progress
668              show progress information
669
670       --log-json
671              Output one JSON object per log line instead of formatted text.
672
673       --lock-wait SECONDS
674              wait at most  SECONDS  for  acquiring  a  repository/cache  lock
675              (default: 1).
676
677       --bypass-lock
678              Bypass locking mechanism
679
680       --show-version
681              show/log the borg version
682
683       --show-rc
684              show/log the return code (rc)
685
686       --umask M
687              set umask to M (local and remote, default: 0077)
688
689       --remote-path PATH
690              use PATH as borg executable on the remote (default: "borg")
691
692       --remote-ratelimit RATE
693              set  remote  network  upload  rate  limit  in kiByte/s (default:
694              0=unlimited)
695
696       --consider-part-files
697              treat part files like normal files (e.g. to list/extract them)
698
699       --debug-profile FILE
700              Write execution profile in Borg format into FILE. For local  use
701              a Python-compatible file can be generated by suffixing FILE with
702              ".pyprof".
703
704       --rsh RSH
705              Use  this  command  to  connect  to  the  'borg  serve'  process
706              (default: 'ssh')
707
708       Option  --bypass-lock allows you to access the repository while bypass‐
709       ing borg's locking mechanism. This is necessary if your  repository  is
710       on  a read-only storage where you don't have write permissions or capa‐
711       bilities and therefore cannot create a lock. Examples are  repositories
712       stored  on  a  Bluray  disc  or a read-only network storage. Avoid this
713       option if you are able to use locks as that is the safer way;  see  the
714       warning below.
715
716       WARNING:
717          If  you  do use --bypass-lock, you are responsible to ensure that no
718          other borg instances have write access to the repository. Otherwise,
719          you  might experience errors and read broken data if changes to that
720          repository are being made at the same time.
721
722   Examples
723          # Create an archive and log: borg version, files list, return code
724          $ borg create --show-version --list --show-rc /path/to/repo::my-files files
725

BORG INIT

727          borg [common options] init [options] [REPOSITORY]
728
729   Description
730       This command  initializes  an  empty  repository.  A  repository  is  a
731       filesystem directory containing the deduplicated data from zero or more
732       archives.
733
734       Encryption can be enabled at repository init time. It cannot be changed
735       later.
736
737       It is not recommended to work without encryption. Repository encryption
738       protects you e.g. against the case that an attacker has access to  your
739       backup repository.
740
741       Borg relies on randomly generated key material and uses that for chunk‐
742       ing, id generation, encryption and authentication. The key material  is
743       encrypted using the passphrase you give before it is stored on-disk.
744
745       You need to be careful with the key / the passphrase:
746
747       If  you  want "passphrase-only" security, use one of the repokey modes.
748       The key will be stored inside the repository (in its "config" file). In
749       above  mentioned  attack  scenario, the attacker will have the key (but
750       not the passphrase).
751
752       If you want "passphrase and having-the-key" security, use  one  of  the
753       keyfile  modes. The key will be stored in your home directory (in .con‐
754       fig/borg/keys).  In the attack scenario,  the  attacker  who  has  just
755       access to your repo won't have the key (and also not the passphrase).
756
757       Make  a  backup copy of the key file (keyfile mode) or repo config file
758       (repokey mode) and keep it at a safe place, so you still have  the  key
759       in  case  it gets corrupted or lost. Also keep the passphrase at a safe
760       place.  The backup that is encrypted with that key won't help you  with
761       that, of course.
762
763       Make sure you use a good passphrase. Not too short, not too simple. The
764       real encryption / decryption key is encrypted with  /  locked  by  your
765       passphrase.   If  an attacker gets your key, he can't unlock and use it
766       without knowing the passphrase.
767
768       Be careful with special or non-ascii characters in your passphrase:
769
770       · Borg processes the passphrase as unicode (and encodes it  as  utf-8),
771         so  it does not have problems dealing with even the strangest charac‐
772         ters.
773
774       · BUT: that does not necessarily apply to your OS / VM / keyboard  con‐
775         figuration.
776
777       So  better  use a long passphrase made from simple ascii chars than one
778       that includes non-ascii stuff or characters that are hard/impossible to
779       enter on a different keyboard layout.
780
781       You can change your passphrase for existing repos at any time, it won't
782       affect the encryption/decryption key or other secrets.
783
784   Encryption modes
785       You can choose from the encryption modes seen in the table below  on  a
786       per-repo  basis.  The  mode  determines  encryption algorithm, hash/MAC
787       algorithm and also the key storage location.
788
789       Example: borg init --encryption repokey ...
790
791         ┌─────────┬──────────────────┬──────────────────┬──────────────────┐
792         │Hash/MAC │ Not encrypted no │ Not   encrypted, │ Encrypted  (AEAD │
793         │         │ auth             │ but    authenti‐ │ w/   AES)    and │
794         │         │                  │ cated            │ authenticated    │
795         ├─────────┼──────────────────┼──────────────────┼──────────────────┤
796         │SHA-256  │ none             │ authenticated    │ repokey keyfile  │
797         ├─────────┼──────────────────┼──────────────────┼──────────────────┤
798         │BLAKE2b  │ n/a              │ authenti‐repokey-blake2
799         │         │                  │ cated-blake2keyfile-blake2
800         └─────────┴──────────────────┴──────────────────┴──────────────────┘
801
802       Modes  marked  like this in the above table are new in Borg 1.1 and are
803       not backwards-compatible with Borg 1.0.x.
804
805       On modern Intel/AMD CPUs (except very cheap ones), AES is usually hard‐
806       ware-accelerated.   BLAKE2b  is  faster than SHA256 on Intel/AMD 64-bit
807       CPUs (except AMD Ryzen and future  CPUs  with  SHA  extensions),  which
808       makes authenticated-blake2 faster than none and authenticated.
809
810       On modern ARM CPUs, NEON provides hardware acceleration for SHA256 mak‐
811       ing it faster than BLAKE2b-256 there. NEON accelerates AES as well.
812
813       Hardware acceleration is always used automatically when available.
814
815       repokey and keyfile use AES-CTR-256 for encryption and HMAC-SHA256  for
816       authentication  in an encrypt-then-MAC (EtM) construction. The chunk ID
817       hash is HMAC-SHA256 as well (with a separate  key).   These  modes  are
818       compatible with Borg 1.0.x.
819
820       repokey-blake2  and  keyfile-blake2  are  also authenticated encryption
821       modes, but use BLAKE2b-256 instead of HMAC-SHA256  for  authentication.
822       The chunk ID hash is a keyed BLAKE2b-256 hash.  These modes are new and
823       not compatible with Borg 1.0.x.
824
825       authenticated mode uses no  encryption,  but  authenticates  repository
826       contents  through  the same HMAC-SHA256 hash as the repokey and keyfile
827       modes (it uses it as the  chunk  ID  hash).  The  key  is  stored  like
828       repokey.  This mode is new and not compatible with Borg 1.0.x.
829
830       authenticated-blake2   is   like  authenticated,  but  uses  the  keyed
831       BLAKE2b-256 hash from the other blake2 modes.  This mode is new and not
832       compatible with Borg 1.0.x.
833
834       none  mode  uses no encryption and no authentication. It uses SHA256 as
835       chunk ID hash. This mode is not recommended, you should rather consider
836       using  an  authenticated or authenticated/encrypted mode. This mode has
837       possible denial-of-service issues when running borg create on  contents
838       controlled  by  an attacker.  Use it only for new repositories where no
839       encryption is wanted and when compatibility with 1.0.x is important. If
840       compatibility  with 1.0.x is not important, use authenticated-blake2 or
841       authenticated instead.  This mode is compatible with Borg 1.0.x.
842
843   Examples
844          # Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
845          $ borg init --encryption=repokey-blake2 /path/to/repo
846
847          # Local repository (no encryption)
848          $ borg init --encryption=none /path/to/repo
849
850          # Remote repository (accesses a remote borg via ssh)
851          # repokey: stores the (encrypted) key into <REPO_DIR>/config
852          $ borg init --encryption=repokey-blake2 user@hostname:backup
853
854          # Remote repository (accesses a remote borg via ssh)
855          # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
856          $ borg init --encryption=keyfile user@hostname:backup
857

BORG CREATE

859          borg [common options] create [options] ARCHIVE [PATH...]
860
861   Description
862       This command creates a backup archive containing all files found  while
863       recursively  traversing all paths specified. Paths are added to the ar‐
864       chive as they are given, that means if relative paths are desired,  the
865       command has to be run from the correct directory.
866
867       When  giving  '-'  as path, borg will read data from standard input and
868       create a file 'stdin' in the created archive from that data.  See  sec‐
869       tion Reading from stdin below for details.
870
871       The  archive  will  consume  almost no disk space for files or parts of
872       files that have already been stored in other archives.
873
874       The archive name needs to be unique. It must not end  in  '.checkpoint'
875       or  '.checkpoint.N'  (with  N  being a number), because these names are
876       used for checkpoints and treated in special ways.
877
878       In the archive name, you may use  the  following  placeholders:  {now},
879       {utcnow}, {fqdn}, {hostname}, {user} and some others.
880
881       Backup  speed  is  increased by not reprocessing files that are already
882       part of existing archives and weren't modified. The detection of unmod‐
883       ified  files  is  done  by comparing multiple file metadata values with
884       previous values kept in the files cache.
885
886       This  comparison  can  operate  in  different   modes   as   given   by
887       --files-cache:
888
889       · ctime,size,inode (default)
890
891       · mtime,size,inode  (default  behaviour  of  borg  versions  older than
892         1.1.0rc4)
893
894       · ctime,size (ignore the inode number)
895
896       · mtime,size (ignore the inode number)
897
898       · rechunk,ctime (all files are considered  modified  -  rechunk,  cache
899         ctime)
900
901       · rechunk,mtime  (all  files  are  considered modified - rechunk, cache
902         mtime)
903
904       · disabled (disable the files cache, all files  considered  modified  -
905         rechunk)
906
907       inode number: better safety, but often unstable on network filesystems
908
909       Normally, detecting file modifications will take inode information into
910       consideration to improve the  reliability  of  file  change  detection.
911       This is problematic for files located on sshfs and similar network file
912       systems which do not provide stable  inode  numbers,  such  files  will
913       always  be considered modified. You can use modes without inode in this
914       case to improve performance, but reliability of change detection  might
915       be reduced.
916
917       ctime vs. mtime: safety vs. speed
918
919       · ctime  is a rather safe way to detect changes to a file (metadata and
920         contents) as it can not be set from userspace. But,  a  metadata-only
921         change will already update the ctime, so there might be some unneces‐
922         sary chunking/hashing even without content changes. Some  filesystems
923         do not support ctime (change time).  E.g. doing a chown or chmod to a
924         file will change its ctime.
925
926       · mtime usually works and only updates if file contents  were  changed.
927         But  mtime  can  be arbitrarily set from userspace, e.g. to set mtime
928         back to the same value it had before a content change happened.  This
929         can  be  used  maliciously  as  well as well-meant, but in both cases
930         mtime based cache modes can be problematic.
931
932       The mount points of filesystems or filesystem snapshots should  be  the
933       same for every creation of a new archive to ensure fast operation. This
934       is because the file cache that  is  used  to  determine  changed  files
935       quickly  uses  absolute  filenames.   If this is not possible, consider
936       creating a bind mount to a stable location.
937
938       The --progress option shows (from left to right)  Original,  Compressed
939       and  Deduplicated  (O, C and D, respectively), then the Number of files
940       (N) processed so far, followed by the currently processed path.
941
942       When using --stats, you will get some statistics about  how  much  data
943       was  added  - the "This Archive" deduplicated size there is most inter‐
944       esting as that is how much your repository will grow. Please note  that
945       the  "All  archives" stats refer to the state after creation. Also, the
946       --stats and --dry-run options are mutually exclusive because  the  data
947       is not actually compressed and deduplicated during a dry run.
948
949       See  the  output  of  the "borg help patterns" command for more help on
950       exclude patterns.
951
952       See the output of the "borg help placeholders" command for more help on
953       placeholders.
954
955       The --exclude patterns are not like tar. In tar --exclude .bundler/gems
956       will exclude foo/.bundler/gems. In borg it will not, you  need  to  use
957       --exclude  '*/.bundler/gems' to get the same effect. See borg help pat‐
958       terns for more information.
959
960       In addition  to  using  --exclude  patterns,  it  is  possible  to  use
961       --exclude-if-present to specify the name of a filesystem object (e.g. a
962       file or folder name) which, when contained within another folder,  will
963       prevent  the  containing  folder from being backed up.  By default, the
964       containing folder and all of its contents  will  be  omitted  from  the
965       backup.  If, however, you wish to only include the objects specified by
966       --exclude-if-present in your backup, and not include any other contents
967       of  the  containing  folder,  this  can  be  enabled  through using the
968       --keep-exclude-tags option.
969
970       The -x or  --one-file-system  option  excludes  directories,  that  are
971       mountpoints  (and  everything in them).  It detects mountpoints by com‐
972       paring the device number from the output of stat() of the directory and
973       its  parent  directory. Specifically, it excludes directories for which
974       stat() reports a device number different  from  the  device  number  of
975       their parent. Be aware that in Linux (and possibly elsewhere) there are
976       directories with device number different from their parent,  which  the
977       kernel  does  not  consider a mountpoint and also the other way around.
978       Examples are bind mounts (possibly same device  number,  but  always  a
979       mountpoint) and ALL subvolumes of a btrfs (different device number from
980       parent  but  not  necessarily  a  mountpoint).  Therefore  when   using
981       --one-file-system, one should make doubly sure that the backup works as
982       intended especially when using btrfs. This is even more  important,  if
983       the  btrfs  layout was created by someone else, e.g. a distribution in‐
984       staller.
985
986   Item flags
987       --list outputs a list of all files, directories and other  file  system
988       items  it  considered  (no  matter  whether they had content changes or
989       not). For each item, it prefixes a single-letter  flag  that  indicates
990       type and/or status of the item.
991
992       If  you  are  interested  only in a subset of that output, you can give
993       e.g.  --filter=AME and it will only show regular files with A, M  or  E
994       status (see below).
995
996       A  uppercase character represents the status of a regular file relative
997       to the "files" cache (not relative to the repo -- this is an  issue  if
998       the  files  cache  is not used). Metadata is stored in any case and for
999       'A' and 'M' also new data chunks are stored. For 'U'  all  data  chunks
1000       refer to already existing chunks.
1001
1002       · 'A' = regular file, added (see also a_status_oddity in the FAQ)
1003
1004       · 'M' = regular file, modified
1005
1006       · 'U' = regular file, unchanged
1007
1008       · 'E'  =  regular  file, an error happened while accessing/reading this
1009         file
1010
1011       A lowercase character means a file type other than a regular file, borg
1012       usually just stores their metadata:
1013
1014       · 'd' = directory
1015
1016       · 'b' = block device
1017
1018       · 'c' = char device
1019
1020       · 'h' = regular file, hardlink (to already seen inodes)
1021
1022       · 's' = symlink
1023
1024       · 'f' = fifo
1025
1026       Other flags used include:
1027
1028       · 'i' = backup data was read from standard input (stdin)
1029
1030       · '-' = dry run, item was not backed up
1031
1032       · 'x' = excluded, item was not backed up
1033
1034       · '?'  =  missing  status  code  (if  you  see  this, please file a bug
1035         report!)
1036
1037   Reading from stdin
1038       To read from stdin, specify - as path and pipe directly to borg:
1039
1040          backup-vm --id myvm --stdout | borg create REPO::ARCHIVE -
1041
1042       Note that piping to borg creates an archive even if the command  piping
1043       to  borg  exits with a failure. In this case, one can end up with trun‐
1044       cated output being backed up.
1045
1046       Reading from stdin yields just a stream of data without  file  metadata
1047       associated  with it, and the files cache is not needed at all. So it is
1048       safe to disable it via --no-files-cache and speed up backup creation  a
1049       bit.
1050
1051       By  default,  the  content  read  from stdin is stored in a file called
1052       'stdin'.  Use --stdin-name to change the name.
1053
1054   Examples
1055          # Backup ~/Documents into an archive named "my-documents"
1056          $ borg create /path/to/repo::my-documents ~/Documents
1057
1058          # same, but list all files as we process them
1059          $ borg create --list /path/to/repo::my-documents ~/Documents
1060
1061          # Backup ~/Documents and ~/src but exclude pyc files
1062          $ borg create /path/to/repo::my-files \
1063              ~/Documents                       \
1064              ~/src                             \
1065              --exclude '*.pyc'
1066
1067          # Backup home directories excluding image thumbnails (i.e. only
1068          # /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
1069          $ borg create /path/to/repo::my-files /home \
1070              --exclude 'sh:/home/*/.thumbnails'
1071
1072          # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
1073          # use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio)
1074          $ borg create -C zlib,6 --one-file-system /path/to/repo::root-{now:%Y-%m-%d} /
1075
1076          # Backup a remote host locally ("pull" style) using sshfs
1077          $ mkdir sshfs-mount
1078          $ sshfs root@example.com:/ sshfs-mount
1079          $ cd sshfs-mount
1080          $ borg create /path/to/repo::example.com-root-{now:%Y-%m-%d} .
1081          $ cd ..
1082          $ fusermount -u sshfs-mount
1083
1084          # Make a big effort in fine granular deduplication (big chunk management
1085          # overhead, needs a lot of RAM and disk space, see formula in internals
1086          # docs - same parameters as borg < 1.0 or attic):
1087          $ borg create --chunker-params 10,23,16,4095 /path/to/repo::small /smallstuff
1088
1089          # Backup a raw device (must not be active/in use/mounted at that time)
1090          $ dd if=/dev/sdx bs=10M | borg create /path/to/repo::my-sdx -
1091
1092          # No compression (none)
1093          $ borg create --compression none /path/to/repo::arch ~
1094
1095          # Super fast, low compression (lz4, default)
1096          $ borg create /path/to/repo::arch ~
1097
1098          # Less fast, higher compression (zlib, N = 0..9)
1099          $ borg create --compression zlib,N /path/to/repo::arch ~
1100
1101          # Even slower, even higher compression (lzma, N = 0..9)
1102          $ borg create --compression lzma,N /path/to/repo::arch ~
1103
1104          # Only compress compressible data with lzma,N (N = 0..9)
1105          $ borg create --compression auto,lzma,N /path/to/repo::arch ~
1106
1107          # Use short hostname, user name and current time in archive name
1108          $ borg create /path/to/repo::{hostname}-{user}-{now} ~
1109          # Similar, use the same datetime format that is default as of borg 1.1
1110          $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S} ~
1111          # As above, but add nanoseconds
1112          $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S.%f} ~
1113
1114          # Backing up relative paths by moving into the correct directory first
1115          $ cd /home/user/Documents
1116          # The root directory of the archive will be "projectA"
1117          $ borg create /path/to/repo::daily-projectA-{now:%Y-%m-%d} projectA
1118

BORG EXTRACT

1120          borg [common options] extract [options] ARCHIVE [PATH...]
1121
1122   Description
1123       This command extracts the contents of an archive. By default the entire
1124       archive  is  extracted  but  a  subset  of files and directories can be
1125       selected by passing a list of PATHs as arguments.  The  file  selection
1126       can further be restricted by using the --exclude option.
1127
1128       See  the  output  of  the "borg help patterns" command for more help on
1129       exclude patterns.
1130
1131       By using --dry-run, you can do all  extraction  steps  except  actually
1132       writing  the  output  data:  reading  metadata and data chunks from the
1133       repo, checking the hash/hmac, decrypting, decompressing.
1134
1135       --progress can be slower than no progress display, since it  makes  one
1136       additional pass over the archive metadata.
1137
1138       NOTE:
1139          Currently,  extract always writes into the current working directory
1140          ("."), so make sure you cd to the right place  before  calling  borg
1141          extract.
1142
1143   Examples
1144          # Extract entire archive
1145          $ borg extract /path/to/repo::my-files
1146
1147          # Extract entire archive and list files while processing
1148          $ borg extract --list /path/to/repo::my-files
1149
1150          # Verify whether an archive could be successfully extracted, but do not write files to disk
1151          $ borg extract --dry-run /path/to/repo::my-files
1152
1153          # Extract the "src" directory
1154          $ borg extract /path/to/repo::my-files home/USERNAME/src
1155
1156          # Extract the "src" directory but exclude object files
1157          $ borg extract /path/to/repo::my-files home/USERNAME/src --exclude '*.o'
1158
1159          # Restore a raw device (must not be active/in use/mounted at that time)
1160          $ borg extract --stdout /path/to/repo::my-sdx | dd of=/dev/sdx bs=10M
1161

BORG CHECK

1163          borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
1164
1165   Description
1166       The check command verifies the consistency of a repository and the cor‐
1167       responding archives.
1168
1169       check --repair is a potentially dangerous function and  might  lead  to
1170       data  loss (for kinds of corruption it is not capable of dealing with).
1171       BE VERY CAREFUL!
1172
1173       First, the underlying repository data files are checked:
1174
1175       · For all segments, the segment magic header is checked.
1176
1177       · For all objects stored in the segments, all metadata  (e.g.  CRC  and
1178         size) and all data is read. The read data is checked by size and CRC.
1179         Bit rot and other types of accidental damage  can  be  detected  this
1180         way.
1181
1182       · In  repair  mode, if an integrity error is detected in a segment, try
1183         to recover as many objects from the segment as possible.
1184
1185       · In repair mode, make sure that the index is consistent with the  data
1186         stored in the segments.
1187
1188       · If checking a remote repo via ssh:, the repo check is executed on the
1189         server without causing significant network traffic.
1190
1191       · The repository check can be skipped using the --archives-only option.
1192
1193       Second, the consistency and correctness of the archive metadata is ver‐
1194       ified:
1195
1196       · Is  the  repo  manifest  present?  If not, it is rebuilt from archive
1197         metadata chunks (this requires reading and decrypting of all metadata
1198         and data).
1199
1200       · Check  if  archive  metadata chunk is present; if not, remove archive
1201         from manifest.
1202
1203       · For all files (items) in the archive, for all  chunks  referenced  by
1204         these files, check if chunk is present. In repair mode, if a chunk is
1205         not present, replace it with a same-size replacement chunk of zeroes.
1206         If  a  previously  lost chunk reappears (e.g. via a later backup), in
1207         repair mode the all-zero replacement chunk will be  replaced  by  the
1208         correct  chunk.  This  requires reading of archive and file metadata,
1209         but not data.
1210
1211       · In repair mode, when all the archives were checked,  orphaned  chunks
1212         are  deleted  from  the  repo. One cause of orphaned chunks are input
1213         file related errors  (like  read  errors)  in  the  archive  creation
1214         process.
1215
1216       · If  checking a remote repo via ssh:, the archive check is executed on
1217         the client machine because it requires decryption, and this is always
1218         done client-side as key access is needed.
1219
1220       · The  archive  checks can be time consuming; they can be skipped using
1221         the --repository-only option.
1222
1223       The --verify-data option will perform a full integrity verification (as
1224       opposed  to  checking  the  CRC32  of the segment) of data, which means
1225       reading the data from the repository, decrypting and decompressing  it.
1226       This  is  a  cryptographic verification, which will detect (accidental)
1227       corruption. For encrypted repositories it is tamper-resistant as  well,
1228       unless the attacker has access to the keys. It is also very slow.
1229

BORG RENAME

1231          borg [common options] rename [options] ARCHIVE NEWNAME
1232
1233   Description
1234       This command renames an archive in the repository.
1235
1236       This results in a different archive ID.
1237
1238   Examples
1239          $ borg create /path/to/repo::archivename ~
1240          $ borg list /path/to/repo
1241          archivename                          Mon, 2016-02-15 19:50:19
1242
1243          $ borg rename /path/to/repo::archivename newname
1244          $ borg list /path/to/repo
1245          newname                              Mon, 2016-02-15 19:50:19
1246

BORG LIST

1248          borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
1249
1250   Description
1251       This command lists the contents of a repository or an archive.
1252
1253       See the "borg help patterns" command for more help on exclude patterns.
1254
1255       The following keys are available for --format:
1256
1257       · NEWLINE: OS dependent line separator
1258
1259       · NL: alias of NEWLINE
1260
1261       · NUL:  NUL  character  for creating print0 / xargs -0 like output, see
1262         barchive/bpath
1263
1264       · SPACE
1265
1266       · TAB
1267
1268       · CR
1269
1270       · LF
1271
1272       Keys for listing repository archives:
1273
1274       · archive: archive name interpreted as text (might be missing  non-text
1275         characters, see barchive)
1276
1277       · name: alias of "archive"
1278
1279       · barchive: verbatim archive name, can contain any character except NUL
1280
1281       · comment:  archive  comment  interpreted  as  text  (might  be missing
1282         non-text characters, see bcomment)
1283
1284       · bcomment: verbatim archive comment, can contain any character  except
1285         NUL
1286
1287       · id: internal ID of the archive
1288
1289       · start: time (start) of creation of the archive
1290
1291       · time: alias of "start"
1292
1293       · end: time (end) of creation of the archive
1294
1295       · hostname: hostname of host on which this archive was created
1296
1297       · username: username of user who created this archive
1298
1299       Keys for listing archive files:
1300
1301       · type
1302
1303       · mode
1304
1305       · uid
1306
1307       · gid
1308
1309       · user
1310
1311       · group
1312
1313       · path: path interpreted as text (might be missing non-text characters,
1314         see bpath)
1315
1316       · bpath: verbatim POSIX path, can contain any character except NUL
1317
1318       · source: link target for links (identical to linktarget)
1319
1320       · linktarget
1321
1322       · flags
1323
1324       · size
1325
1326       · csize: compressed size
1327
1328       · dsize: deduplicated size
1329
1330       · dcsize: deduplicated compressed size
1331
1332       · num_chunks: number of chunks in this file
1333
1334       · unique_chunks: number of unique chunks in this file
1335
1336       · mtime
1337
1338       · ctime
1339
1340       · atime
1341
1342       · isomtime
1343
1344       · isoctime
1345
1346       · isoatime
1347
1348       · blake2b
1349
1350       · blake2s
1351
1352       · md5
1353
1354       · sha1
1355
1356       · sha224
1357
1358       · sha256
1359
1360       · sha384
1361
1362       · sha3_224
1363
1364       · sha3_256
1365
1366       · sha3_384
1367
1368       · sha3_512
1369
1370       · sha512
1371
1372       · shake_128
1373
1374       · shake_256
1375
1376       · archiveid
1377
1378       · archivename
1379
1380       · extra: prepends {source} with " -> " for soft links and " link  to  "
1381         for hard links
1382
1383       · health:  either "healthy" (file ok) or "broken" (if file has all-zero
1384         replacement chunks)
1385
1386   Examples
1387          $ borg list /path/to/repo
1388          Monday                               Mon, 2016-02-15 19:15:11
1389          repo                                 Mon, 2016-02-15 19:26:54
1390          root-2016-02-15                      Mon, 2016-02-15 19:36:29
1391          newname                              Mon, 2016-02-15 19:50:19
1392          ...
1393
1394          $ borg list /path/to/repo::root-2016-02-15
1395          drwxr-xr-x root   root          0 Mon, 2016-02-15 17:44:27 .
1396          drwxrwxr-x root   root          0 Mon, 2016-02-15 19:04:49 bin
1397          -rwxr-xr-x root   root    1029624 Thu, 2014-11-13 00:08:51 bin/bash
1398          lrwxrwxrwx root   root          0 Fri, 2015-03-27 20:24:26 bin/bzcmp -> bzdiff
1399          -rwxr-xr-x root   root       2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
1400          ...
1401
1402          $ borg list /path/to/repo::root-2016-02-15 --pattern "- bin/ba*"
1403          drwxr-xr-x root   root          0 Mon, 2016-02-15 17:44:27 .
1404          drwxrwxr-x root   root          0 Mon, 2016-02-15 19:04:49 bin
1405          lrwxrwxrwx root   root          0 Fri, 2015-03-27 20:24:26 bin/bzcmp -> bzdiff
1406          -rwxr-xr-x root   root       2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
1407          ...
1408
1409          $ borg list /path/to/repo::archiveA --format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
1410          drwxrwxr-x user   user          0 Sun, 2015-02-01 11:00:00 .
1411          drwxrwxr-x user   user          0 Sun, 2015-02-01 11:00:00 code
1412          drwxrwxr-x user   user          0 Sun, 2015-02-01 11:00:00 code/myproject
1413          -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
1414          ...
1415

BORG DIFF

1417          borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
1418
1419   Description
1420       This command finds differences (file contents, user/group/mode) between
1421       archives.
1422
1423       A  repository  location  and  an  archive  name  must  be specified for
1424       REPO::ARCHIVE1.  ARCHIVE2 is just another archive name in same  reposi‐
1425       tory (no repository location allowed).
1426
1427       For  archives created with Borg 1.1 or newer diff automatically detects
1428       whether the archives are created with the same chunker params.  If  so,
1429       only chunk IDs are compared, which is very fast.
1430
1431       For  archives prior to Borg 1.1 chunk contents are compared by default.
1432       If you did not create the archives with different chunker params,  pass
1433       --same-chunker-params.   Note that the chunker params changed from Borg
1434       0.xx to 1.0.
1435
1436       See the output of the "borg help patterns" command  for  more  help  on
1437       exclude patterns.
1438
1439   Examples
1440          $ borg init -e=none testrepo
1441          $ mkdir testdir
1442          $ cd testdir
1443          $ echo asdf > file1
1444          $ dd if=/dev/urandom bs=1M count=4 > file2
1445          $ touch file3
1446          $ borg create ../testrepo::archive1 .
1447
1448          $ chmod a+x file1
1449          $ echo "something" >> file2
1450          $ borg create ../testrepo::archive2 .
1451
1452          $ echo "testing 123" >> file1
1453          $ rm file3
1454          $ touch file4
1455          $ borg create ../testrepo::archive3 .
1456
1457          $ cd ..
1458          $ borg diff testrepo::archive1 archive2
1459          [-rw-r--r-- -> -rwxr-xr-x] file1
1460             +135 B    -252 B file2
1461
1462          $ borg diff testrepo::archive2 archive3
1463              +17 B      -5 B file1
1464          added           0 B file4
1465          removed         0 B file3
1466
1467          $ borg diff testrepo::archive1 archive3
1468              +17 B      -5 B [-rw-r--r-- -> -rwxr-xr-x] file1
1469             +135 B    -252 B file2
1470          added           0 B file4
1471          removed         0 B file3
1472
1473          $ borg diff --json-lines testrepo::archive1 archive3
1474          {"path": "file1", "changes": [{"type": "modified", "added": 17, "removed": 5}, {"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"}]}
1475          {"path": "file2", "changes": [{"type": "modified", "added": 135, "removed": 252}]}
1476          {"path": "file4", "changes": [{"type": "added", "size": 0}]}
1477          {"path": "file3", "changes": [{"type": "removed", "size": 0}]}
1478

BORG DELETE

1480          borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...]
1481
1482   Description
1483       This  command  deletes  an  archive from the repository or the complete
1484       repository.  Disk space is reclaimed accordingly.  If  you  delete  the
1485       complete repository, the local cache for it (if any) is also deleted.
1486
1487       When  using  --stats,  you will get some statistics about how much data
1488       was deleted - the "Deleted data" deduplicated size there is most inter‐
1489       esting  as  that  is how much your repository will shrink.  Please note
1490       that the "All archives" stats refer to the state after deletion.
1491
1492   Examples
1493          # delete a single backup archive:
1494          $ borg delete /path/to/repo::Monday
1495
1496          # delete the whole repository and the related local cache:
1497          $ borg delete /path/to/repo
1498          You requested to completely DELETE the repository *including* all archives it contains:
1499          repo                                 Mon, 2016-02-15 19:26:54
1500          root-2016-02-15                      Mon, 2016-02-15 19:36:29
1501          newname                              Mon, 2016-02-15 19:50:19
1502          Type 'YES' if you understand this and want to continue: YES
1503

BORG PRUNE

1505          borg [common options] prune [options] [REPOSITORY]
1506
1507   Description
1508       The prune command prunes a repository  by  deleting  all  archives  not
1509       matching  any  of the specified retention options. This command is nor‐
1510       mally used by automated backup scripts wanting to keep a certain number
1511       of historic backups.
1512
1513       Also,  prune  automatically removes checkpoint archives (incomplete ar‐
1514       chives left behind by interrupted backup runs) except if the checkpoint
1515       is  the latest archive (and thus still needed). Checkpoint archives are
1516       not considered when comparing archive counts against the retention lim‐
1517       its (--keep-X).
1518
1519       If a prefix is set with -P, then only archives that start with the pre‐
1520       fix are considered for deletion and only those archives  count  towards
1521       the  totals  specified  by  the  rules.  Otherwise, all archives in the
1522       repository are candidates for deletion!  There is no automatic distinc‐
1523       tion between archives representing different contents. These need to be
1524       distinguished by specifying matching prefixes.
1525
1526       If you have multiple sequences of archives  with  different  data  sets
1527       (e.g.  from different machines) in one shared repository, use one prune
1528       call per data set that matches only the respective archives  using  the
1529       -P option.
1530
1531       The  --keep-within  option takes an argument of the form "<int><char>",
1532       where char is "H", "d", "w", "m", "y". For  example,  --keep-within  2d
1533       means  to keep all archives that were created within the past 48 hours.
1534       "1m" is taken to mean "31d". The archives kept with this option do  not
1535       count towards the totals specified by any other options.
1536
1537       A  good  procedure  is to thin out more and more the older your backups
1538       get.  As an example, --keep-daily 7 means to keep the latest backup  on
1539       each  day,  up to 7 most recent days with backups (days without backups
1540       do not count).  The rules are applied  from  secondly  to  yearly,  and
1541       backups  selected by previous rules do not count towards those of later
1542       rules. The time that each backup starts is used for  pruning  purposes.
1543       Dates  and  times  are  interpreted in the local timezone, and weeks go
1544       from Monday to Sunday. Specifying a negative number of archives to keep
1545       means that there is no limit.
1546
1547       The --keep-last N option is doing the same as --keep-secondly N (and it
1548       will keep the last N archives under the assumption that you do not cre‐
1549       ate more than one backup archive in the same second).
1550
1551       When  using  --stats,  you will get some statistics about how much data
1552       was deleted - the "Deleted data" deduplicated size there is most inter‐
1553       esting  as  that  is how much your repository will shrink.  Please note
1554       that the "All archives" stats refer to the state after pruning.
1555
1556   Examples
1557       Be careful, prune is a potentially dangerous command,  it  will  remove
1558       backup archives.
1559
1560       The  default  of  prune  is  to apply to all archives in the repository
1561       unless you restrict its operation to a subset  of  the  archives  using
1562       --prefix.   When  using  --prefix, be careful to choose a good prefix -
1563       e.g. do not use a prefix "foo" if you do not also want to  match  "foo‐
1564       bar".
1565
1566       It  is strongly recommended to always run prune -v --list --dry-run ...
1567       first so you will see what it would do without it actually  doing  any‐
1568       thing.
1569
1570          # Keep 7 end of day and 4 additional end of week archives.
1571          # Do a dry-run without actually deleting anything.
1572          $ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
1573
1574          # Same as above but only apply to archive names starting with the hostname
1575          # of the machine followed by a "-" character:
1576          $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --prefix='{hostname}-' /path/to/repo
1577
1578          # Keep 7 end of day, 4 additional end of week archives,
1579          # and an end of month archive for every month:
1580          $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /path/to/repo
1581
1582          # Keep all backups in the last 10 days, 4 additional end of week archives,
1583          # and an end of month archive for every month:
1584          $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/repo
1585
1586       There  is  also  a  visualized  prune  example in docs/misc/prune-exam‐
1587       ple.txt:
1588
1589          borg prune visualized
1590          =====================
1591
1592          Assume it is 2016-01-01, today's backup has not yet been made and you have
1593          created at least one backup on each day in 2015 except on 2015-12-19 (no
1594          backup made on that day).
1595
1596          This is what borg prune --keep-daily 14 --keep-monthly 6 would keep.
1597
1598          Backups kept by the --keep-daily rule are marked by a "d" to the right,
1599          backups kept by the --keep-monthly rule are marked by a "m" to the right.
1600
1601          Calendar view
1602          -------------
1603
1604                                      2015
1605                January               February               March
1606          Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su
1607                    1  2  3  4                     1                     1
1608           5  6  7  8  9 10 11   2  3  4  5  6  7  8   2  3  4  5  6  7  8
1609          12 13 14 15 16 17 18   9 10 11 12 13 14 15   9 10 11 12 13 14 15
1610          19 20 21 22 23 24 25  16 17 18 19 20 21 22  16 17 18 19 20 21 22
1611          26 27 28 29 30 31     23 24 25 26 27 28     23 24 25 26 27 28 29
1612                                                      30 31
1613
1614                 April                  May                   June
1615          Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su
1616                 1  2  3  4  5               1  2  3   1  2  3  4  5  6  7
1617           6  7  8  9 10 11 12   4  5  6  7  8  9 10   8  9 10 11 12 13 14
1618          13 14 15 16 17 18 19  11 12 13 14 15 16 17  15 16 17 18 19 20 21
1619          20 21 22 23 24 25 26  18 19 20 21 22 23 24  22 23 24 25 26 27 28
1620          27 28 29 30           25 26 27 28 29 30 31  29 30m
1621
1622
1623                  July                 August              September
1624          Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su
1625                 1  2  3  4  5                  1  2      1  2  3  4  5  6
1626           6  7  8  9 10 11 12   3  4  5  6  7  8  9   7  8  9 10 11 12 13
1627          13 14 15 16 17 18 19  10 11 12 13 14 15 16  14 15 16 17 18 19 20
1628          20 21 22 23 24 25 26  17 18 19 20 21 22 23  21 22 23 24 25 26 27
1629          27 28 29 30 31m       24 25 26 27 28 29 30  28 29 30m
1630                                31m
1631
1632                October               November              December
1633          Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su  Mo Tu We Th Fr Sa Su
1634                    1  2  3  4                     1      1  2  3  4  5  6
1635           5  6  7  8  9 10 11   2  3  4  5  6  7  8   7  8  9 10 11 12 13
1636          12 13 14 15 16 17 18   9 10 11 12 13 14 15  14 15 16 17d18d19 20d
1637          19 20 21 22 23 24 25  16 17 18 19 20 21 22  21d22d23d24d25d26d27d
1638          26 27 28 29 30 31m    23 24 25 26 27 28 29  28d29d30d31d
1639                                30m
1640
1641          List view
1642          ---------
1643
1644          --keep-daily 14     --keep-monthly 6
1645          -------------------------------------------------
1646           1. 2015-12-31          (2015-12-31 kept by daily rule)
1647           2. 2015-12-30       1. 2015-11-30
1648           3. 2015-12-29       2. 2015-10-31
1649           4. 2015-12-28       3. 2015-09-30
1650           5. 2015-12-27       4. 2015-08-31
1651           6. 2015-12-26       5. 2015-07-31
1652           7. 2015-12-25       6. 2015-06-30
1653           8. 2015-12-24
1654           9. 2015-12-23
1655          10. 2015-12-22
1656          11. 2015-12-21
1657          12. 2015-12-20
1658              (no backup made on 2015-12-19)
1659          13. 2015-12-18
1660          14. 2015-12-17
1661
1662
1663          Notes
1664          -----
1665
1666          2015-12-31 is kept due to the --keep-daily 14 rule (because it is applied
1667          first), not due to the --keep-monthly rule.
1668
1669          Because of that, the --keep-monthly 6 rule keeps Nov, Oct, Sep, Aug, Jul and
1670          Jun. December is not considered for this rule, because that backup was already
1671          kept because of the daily rule.
1672
1673          2015-12-17 is kept to satisfy the --keep-daily 14 rule - because no backup was
1674          made on 2015-12-19. If a backup had been made on that day, it would not keep
1675          the one from 2015-12-17.
1676
1677          We did not include yearly, weekly, hourly, minutely or secondly rules to keep
1678          this example simple. They all work in basically the same way.
1679
1680          The weekly rule is easy to understand roughly, but hard to understand in all
1681          details. If interested, read "ISO 8601:2000 standard week-based year".
1682
1683

BORG INFO

1685          borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
1686
1687   Description
1688       This command displays detailed information about the specified  archive
1689       or repository.
1690
1691       Please  note  that the deduplicated sizes of the individual archives do
1692       not add up to the deduplicated size of the repository ("all archives"),
1693       because the two are meaning different things:
1694
1695       This  archive / deduplicated size = amount of data stored ONLY for this
1696       archive = unique chunks of this archive.  All archives  /  deduplicated
1697       size  =  amount  of data stored in the repo = all chunks in the reposi‐
1698       tory.
1699
1700       Borg archives can only contain a limited amount of file metadata.   The
1701       size  of  an archive relative to this limit depends on a number of fac‐
1702       tors, mainly the number of files, the lengths of paths and other  meta‐
1703       data  stored  for  files.  This is shown as utilization of maximum sup‐
1704       ported archive size.
1705
1706   Examples
1707          $ borg info /path/to/repo::2017-06-29T11:00-srv
1708          Archive name: 2017-06-29T11:00-srv
1709          Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
1710          Comment:
1711          Hostname: myhostname
1712          Username: root
1713          Time (start): Thu, 2017-06-29 11:03:07
1714          Time (end): Thu, 2017-06-29 11:03:13
1715          Duration: 5.66 seconds
1716          Number of files: 17037
1717          Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
1718          Utilization of max. archive size: 0%
1719          ------------------------------------------------------------------------------
1720                                 Original size      Compressed size    Deduplicated size
1721          This archive:               12.53 GB             12.49 GB              1.62 kB
1722          All archives:              121.82 TB            112.41 TB            215.42 GB
1723
1724                                 Unique chunks         Total chunks
1725          Chunk index:                 1015213            626934122
1726
1727          $ borg info /path/to/repo --last 1
1728          Archive name: 2017-06-29T11:00-srv
1729          Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
1730          Comment:
1731          Hostname: myhostname
1732          Username: root
1733          Time (start): Thu, 2017-06-29 11:03:07
1734          Time (end): Thu, 2017-06-29 11:03:13
1735          Duration: 5.66 seconds
1736          Number of files: 17037
1737          Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
1738          Utilization of max. archive size: 0%
1739          ------------------------------------------------------------------------------
1740                                 Original size      Compressed size    Deduplicated size
1741          This archive:               12.53 GB             12.49 GB              1.62 kB
1742          All archives:              121.82 TB            112.41 TB            215.42 GB
1743
1744                                 Unique chunks         Total chunks
1745          Chunk index:                 1015213            626934122
1746
1747          $ borg info /path/to/repo
1748          Repository ID: d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
1749          Location: /path/to/repo
1750          Encrypted: Yes (repokey)
1751          Cache: /root/.cache/borg/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
1752          Security dir: /root/.config/borg/security/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
1753          ------------------------------------------------------------------------------
1754                                 Original size      Compressed size    Deduplicated size
1755          All archives:              121.82 TB            112.41 TB            215.42 GB
1756
1757                                 Unique chunks         Total chunks
1758          Chunk index:                 1015213            626934122
1759

BORG MOUNT

1761          borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
1762
1763   Description
1764       This command mounts an archive as a FUSE filesystem. This can be useful
1765       for  browsing  an  archive  or  restoring  individual files. Unless the
1766       --foreground option is given the command will  run  in  the  background
1767       until the filesystem is umounted.
1768
1769       The  command borgfs provides a wrapper for borg mount. This can also be
1770       used   in   fstab   entries:   /path/to/repo   /mnt/point   fuse.borgfs
1771       defaults,noauto 0 0
1772
1773       To  allow  a  regular  user  to use fstab entries, add the user option:
1774       /path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0
1775
1776       For FUSE configuration and mount options, see the mount.fuse(8)  manual
1777       page.
1778
1779       Additional mount options supported by borg:
1780
1781       · versions:  when  used  with  a repository mount, this gives a merged,
1782         versioned view of the files in the archives. EXPERIMENTAL, layout may
1783         change in future.
1784
1785       · allow_damaged_files:  by  default damaged files (where missing chunks
1786         were replaced with runs of zeros by  borg  check  --repair)  are  not
1787         readable  and  return  EIO  (I/O error). Set this option to read such
1788         files.
1789
1790       · ignore_permissions: for security  reasons  the  "default_permissions"
1791         mount option is internally enforced by borg. "ignore_permissions" can
1792         be given to not enforce "default_permissions".
1793
1794       The BORG_MOUNT_DATA_CACHE_ENTRIES environment  variable  is  meant  for
1795       advanced  users  to tweak the performance. It sets the number of cached
1796       data chunks; additional memory usage can be up to  ~8  MiB  times  this
1797       number. The default is the number of CPU cores.
1798
1799       When  the  daemonized process receives a signal or crashes, it does not
1800       unmount.  Unmounting in these cases could cause an active rsync or sim‐
1801       ilar process to unintentionally delete data.
1802
1803       When  running  in  the foreground ^C/SIGINT unmounts cleanly, but other
1804       signals or crashes do not.
1805

BORG UMOUNT

1807          borg [common options] umount [options] MOUNTPOINT
1808
1809   Description
1810       This command un-mounts a FUSE filesystem that  was  mounted  with  borg
1811       mount.
1812
1813       This  is  a  convenience  wrapper that just calls the platform-specific
1814       shell command - usually this is either umount or fusermount -u.
1815
1816   Examples
1817          # Mounting the repository shows all archives.
1818          # Archives are loaded lazily, expect some delay when navigating to an archive
1819          # for the first time.
1820          $ borg mount /path/to/repo /tmp/mymountpoint
1821          $ ls /tmp/mymountpoint
1822          root-2016-02-14 root-2016-02-15
1823          $ borg umount /tmp/mymountpoint
1824
1825          # Mounting a specific archive is possible as well.
1826          $ borg mount /path/to/repo::root-2016-02-15 /tmp/mymountpoint
1827          $ ls /tmp/mymountpoint
1828          bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt
1829          root  sbin  srv  tmp  usr  var
1830          $ borg umount /tmp/mymountpoint
1831
1832          # The experimental "versions view" merges all archives in the repository
1833          # and provides a versioned view on files.
1834          $ borg mount -o versions /path/to/repo /tmp/mymountpoint
1835          $ ls -l /tmp/mymountpoint/home/user/doc.txt/
1836          total 24
1837          -rw-rw-r-- 1 user group 12357 Aug 26 21:19 doc.cda00bc9.txt
1838          -rw-rw-r-- 1 user group 12204 Aug 26 21:04 doc.fa760f28.txt
1839          $ borg umount /tmp/mymountpoint
1840
1841          # Archive filters are supported.
1842          # These are especially handy for the "versions view",
1843          # which does not support lazy processing of archives.
1844          $ borg mount -o versions --glob-archives '*-my-home' --last 10 /path/to/repo /tmp/mymountpoint
1845
1846          # Exclusion options are supported.
1847          # These can speed up mounting and lower memory needs significantly.
1848          $ borg mount /path/to/repo /tmp/mymountpoint only/that/path
1849          $ borg mount --exclude '...' /path/to/repo /tmp/mymountpoint
1850
1851   borgfs
1852          $ echo '/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
1853          $ echo '/mnt/backup::root-2016-02-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
1854          $ mount /tmp/myrepo
1855          $ mount /tmp/myarchive
1856          $ ls /tmp/myrepo
1857          root-2016-02-01 root-2016-02-2015
1858          $ ls /tmp/myarchive
1859          bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
1860
1861       NOTE:
1862          borgfs will be automatically provided if  you  used  a  distribution
1863          package,  pip  or  setup.py to install Borg. Users of the standalone
1864          binary  will  have  to  manually  create  a   symlink   (see   pyin‐
1865          staller-binary).
1866

BORG KEY CHANGE-PASSPHRASE

1868          borg [common options] key change-passphrase [options] [REPOSITORY]
1869
1870   Description
1871       The  key files used for repository encryption are optionally passphrase
1872       protected. This command can be used to change this passphrase.
1873
1874       Please note that this command only changes the passphrase, but not  any
1875       secret protected by it (like e.g. encryption/MAC keys or chunker seed).
1876       Thus, changing the passphrase after passphrase and borg key got compro‐
1877       mised  does  not  protect future (nor past) backups to the same reposi‐
1878       tory.
1879
1880   Examples
1881          # Create a key file protected repository
1882          $ borg init --encryption=keyfile -v /path/to/repo
1883          Initializing repository at "/path/to/repo"
1884          Enter new passphrase:
1885          Enter same passphrase again:
1886          Remember your passphrase. Your data will be inaccessible without it.
1887          Key in "/root/.config/borg/keys/mnt_backup" created.
1888          Keep this key safe. Your data will be inaccessible without it.
1889          Synchronizing chunks cache...
1890          Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
1891          Done.
1892
1893          # Change key file passphrase
1894          $ borg key change-passphrase -v /path/to/repo
1895          Enter passphrase for key /root/.config/borg/keys/mnt_backup:
1896          Enter new passphrase:
1897          Enter same passphrase again:
1898          Remember your passphrase. Your data will be inaccessible without it.
1899          Key updated
1900
1901       Fully automated using environment variables:
1902
1903          $ BORG_NEW_PASSPHRASE=old borg init -e=repokey repo
1904          # now "old" is the current passphrase.
1905          $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase repo
1906          # now "new" is the current passphrase.
1907

BORG KEY EXPORT

1909          borg [common options] key export [options] [REPOSITORY] [PATH]
1910
1911   Description
1912       If repository encryption is used, the repository is inaccessible  with‐
1913       out  the  key.  This command allows to backup this essential key.  Note
1914       that the backup produced does not include the passphrase  itself  (i.e.
1915       the  exported  key  stays  encrypted).  In  order to regain access to a
1916       repository,  one  needs  both  the  exported  key  and   the   original
1917       passphrase.
1918
1919       There  are two backup formats. The normal backup format is suitable for
1920       digital storage as a file. The --paper backup format is  optimized  for
1921       printing  and typing in while importing, with per line checks to reduce
1922       problems with manual input.
1923
1924       For repositories using keyfile encryption the key is saved  locally  on
1925       the  system  that is capable of doing backups. To guard against loss of
1926       this key, the key needs to be backed up independently of the main  data
1927       backup.
1928
1929       For  repositories  using the repokey encryption the key is saved in the
1930       repository in the config file. A backup is thus  not  strictly  needed,
1931       but  guards against the repository becoming inaccessible if the file is
1932       damaged for some reason.
1933

BORG KEY IMPORT

1935          borg [common options] key import [options] [REPOSITORY] [PATH]
1936
1937   Description
1938       This command allows to restore a key  previously  backed  up  with  the
1939       export command.
1940
1941       If  the  --paper  option  is  given,  the import will be an interactive
1942       process in which each line is checked for plausibility before  proceed‐
1943       ing to the next line. For this format PATH must not be given.
1944

BORG UPGRADE

1946          borg [common options] upgrade [options] [REPOSITORY]
1947
1948   Description
1949       Upgrade an existing, local Borg repository.
1950
1951   When you do not need borg upgrade
1952       Not every change requires that you run borg upgrade.
1953
1954       You do not need to run it when:
1955
1956       · moving your repository to a different place
1957
1958       · upgrading to another point release (like 1.0.x to 1.0.y), except when
1959         noted otherwise in the changelog
1960
1961       · upgrading from 1.0.x to 1.1.x, except when  noted  otherwise  in  the
1962         changelog
1963
1964   Borg 1.x.y upgrades
1965       Use  borg  upgrade --tam REPO to require manifest authentication intro‐
1966       duced with Borg 1.0.9 to address security issues. This means that modi‐
1967       fying  the  repository  after  doing this with a version prior to 1.0.9
1968       will raise a validation error,  so  only  perform  this  upgrade  after
1969       updating all clients using the repository to 1.0.9 or newer.
1970
1971       This upgrade should be done on each client for safety reasons.
1972
1973       If  a repository is accidentally modified with a pre-1.0.9 client after
1974       this upgrade, use borg upgrade --tam --force REPO to remedy it.
1975
1976       If you routinely do this you might not  want  to  enable  this  upgrade
1977       (which  will  leave you exposed to the security issue). You can reverse
1978       the upgrade by issuing borg upgrade --disable-tam REPO.
1979
1980       See
1981       https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoofing-vulnerability
1982       for details.
1983
1984   Attic and Borg 0.xx to Borg 1.x
1985       This currently supports converting an Attic repository to Borg and also
1986       helps with converting Borg 0.xx to 1.0.
1987
1988       Currently, only LOCAL repositories can be upgraded (issue #465).
1989
1990       Please  note  that  borg  create  (since  1.0.0)  uses bigger chunks by
1991       default than old borg or attic did, so the new chunks won't deduplicate
1992       with  the  old chunks in the upgraded repository.  See --chunker-params
1993       option of borg create and borg recreate.
1994
1995       borg upgrade will change the magic strings in the repository's segments
1996       to   match   the   new  Borg  magic  strings.  The  keyfiles  found  in
1997       $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and copied  to
1998       $BORG_KEYS_DIR or ~/.config/borg/keys.
1999
2000       The  cache files are converted, from $ATTIC_CACHE_DIR or ~/.cache/attic
2001       to $BORG_CACHE_DIR or ~/.cache/borg, but the cache layout between  Borg
2002       and Attic changed, so it is possible the first backup after the conver‐
2003       sion takes longer than expected due to the cache resync.
2004
2005       Upgrade should be able to resume if interrupted, although it will still
2006       iterate  over all segments. If you want to start from scratch, use borg
2007       delete over the copied repository to make sure the cache files are also
2008       removed:
2009
2010          borg delete borg
2011
2012       Unless  --inplace  is  specified,  the  upgrade process first creates a
2013       backup copy of the repository,  in  REPOSITORY.before-upgrade-DATETIME,
2014       using  hardlinks.   This  requires  that  the repository and its parent
2015       directory reside on same filesystem so  the  hardlink  copy  can  work.
2016       This  takes  longer than in place upgrades, but is much safer and gives
2017       progress information (as opposed to cp -al).  Once  you  are  satisfied
2018       with the conversion, you can safely destroy the backup copy.
2019
2020       WARNING:  Running the upgrade in place will make the current copy unus‐
2021       able with older version, with no way of going  back  to  previous  ver‐
2022       sions. This can PERMANENTLY DAMAGE YOUR REPOSITORY!  Attic CAN NOT READ
2023       BORG REPOSITORIES, as the magic strings have  changed.  You  have  been
2024       warned.
2025
2026   Examples
2027          # Upgrade the borg repository to the most recent version.
2028          $ borg upgrade -v /path/to/repo
2029          making a hardlink copy in /path/to/repo.before-upgrade-2016-02-15-20:51:55
2030          opening attic repository with borg and converting
2031          no key file found for repository
2032          converting repo index /path/to/repo/index.0
2033          converting 1 segments...
2034          converting borg 0.xx to borg current
2035          no key file found for repository
2036
2037   Upgrading a passphrase encrypted attic repo
2038       attic  offered  a "passphrase" encryption mode, but this was removed in
2039       borg  1.0  and  replaced  by  the  "repokey"  mode  (which  stores  the
2040       passphrase-protected encryption key into the repository config).
2041
2042       Thus,  to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2
2043       steps are needed, in this order:
2044
2045       · borg upgrade repo
2046
2047       · borg key migrate-to-repokey repo
2048

BORG RECREATE

2050          borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
2051
2052   Description
2053       Recreate the contents of existing archives.
2054
2055       recreate is a potentially dangerous function and  might  lead  to  data
2056       loss (if used wrongly). BE VERY CAREFUL!
2057
2058       --exclude,  --exclude-from,  --exclude-if-present,  --keep-exclude-tags
2059       and PATH have the exact same semantics as in "borg  create",  but  they
2060       only  check for files in the archives and not in the local file system.
2061       If PATHs are specified, the resulting archives will only contain  files
2062       from these PATHs.
2063
2064       Note that all paths in an archive are relative, therefore absolute pat‐
2065       terns/paths will not match (--exclude, --exclude-from, PATHs).
2066
2067       --recompress allows to change the compression of existing data  in  ar‐
2068       chives.   Due to how Borg stores compressed size information this might
2069       display incorrect information for archives that were not  recreated  at
2070       the same time.  There is no risk of data loss by this.
2071
2072       --chunker-params  will  re-chunk  all files in the archive, this can be
2073       used to have upgraded Borg 0.xx or Attic archives deduplicate with Borg
2074       1.x archives.
2075
2076       USE  WITH CAUTION.  Depending on the PATHs and patterns given, recreate
2077       can be used to permanently delete files from archives.  When in  doubt,
2078       use  --dry-run  --verbose  --list  to see how patterns/PATHS are inter‐
2079       preted. See list_item_flags in borg create for details.
2080
2081       The archive being recreated is only removed after  the  operation  com‐
2082       pletes.  The  archive  that is built during the operation exists at the
2083       same time at "<ARCHIVE>.recreate". The new archive will have a  differ‐
2084       ent archive ID.
2085
2086       With  --target  the original archive is not replaced, instead a new ar‐
2087       chive is created.
2088
2089       When rechunking space usage can be substantial,  expect  at  least  the
2090       entire  deduplicated  size  of  the archives using the previous chunker
2091       params.   When  recompressing  expect  approx.  (throughput  /   check‐
2092       point-interval) in space usage, assuming all chunks are recompressed.
2093
2094       If  you  recently ran borg check --repair and it had to fix lost chunks
2095       with all-zero replacement chunks, please first run another  backup  for
2096       the same data and re-run borg check --repair afterwards to heal any ar‐
2097       chives that had lost chunks which are still generated  from  the  input
2098       data.
2099
2100       Important:   running   borg   recreate  to  re-chunk  will  remove  the
2101       chunks_healthy metadata of all items with replacement chunks, so  heal‐
2102       ing  will  not  be  possible  any  more  after  re-chunking (it is also
2103       unlikely it would ever work: due to the change of chunking  parameters,
2104       the  missing  chunk  likely  will never be seen again even if you still
2105       have the data that produced it).
2106
2107   Examples
2108          # Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
2109          # Archives created with Borg 1.1+ and the default chunker params are skipped
2110          # (archive ID stays the same).
2111          $ borg recreate /mnt/backup --chunker-params default --progress
2112
2113          # Create a backup with little but fast compression
2114          $ borg create /mnt/backup::archive /some/files --compression lz4
2115          # Then compress it - this might take longer, but the backup has already completed,
2116          # so no inconsistencies from a long-running backup job.
2117          $ borg recreate /mnt/backup::archive --recompress --compression zlib,9
2118
2119          # Remove unwanted files from all archives in a repository.
2120          # Note the relative path for the --exclude option - archives only contain relative paths.
2121          $ borg recreate /mnt/backup --exclude home/icke/Pictures/drunk_photos
2122
2123          # Change archive comment
2124          $ borg create --comment "This is a comment" /mnt/backup::archivename ~
2125          $ borg info /mnt/backup::archivename
2126          Name: archivename
2127          Fingerprint: ...
2128          Comment: This is a comment
2129          ...
2130          $ borg recreate --comment "This is a better comment" /mnt/backup::archivename
2131          $ borg info /mnt/backup::archivename
2132          Name: archivename
2133          Fingerprint: ...
2134          Comment: This is a better comment
2135          ...
2136

BORG EXPORT-TAR

2138          borg [common options] export-tar [options] ARCHIVE FILE [PATH...]
2139
2140   Description
2141       This command creates a tarball from an archive.
2142
2143       When giving '-' as the output FILE, Borg will write  a  tar  stream  to
2144       standard output.
2145
2146       By default (--tar-filter=auto) Borg will detect whether the FILE should
2147       be compressed based on its file extension and pipe the tarball  through
2148       an appropriate filter before writing it to FILE:
2149
2150       · .tar.gz: gzip
2151
2152       · .tar.bz2: bzip2
2153
2154       · .tar.xz: xz
2155
2156       Alternatively  a  --tar-filter  program may be explicitly specified. It
2157       should read the uncompressed tar stream from stdin  and  write  a  com‐
2158       pressed/filtered tar stream to stdout.
2159
2160       The generated tarball uses the GNU tar format.
2161
2162       export-tar  is a lossy conversion: BSD flags, ACLs, extended attributes
2163       (xattrs), atime and ctime are not exported.   Timestamp  resolution  is
2164       limited  to whole seconds, not the nanosecond resolution otherwise sup‐
2165       ported by Borg.
2166
2167       A --sparse option (as found in borg extract) is not supported.
2168
2169       By default the entire archive is extracted but a subset  of  files  and
2170       directories  can  be  selected by passing a list of PATHs as arguments.
2171       The file selection can further be restricted  by  using  the  --exclude
2172       option.
2173
2174       See  the  output  of  the "borg help patterns" command for more help on
2175       exclude patterns.
2176
2177       --progress can be slower than no progress display, since it  makes  one
2178       additional pass over the archive metadata.
2179
2180   Examples
2181          # export as uncompressed tar
2182          $ borg export-tar /path/to/repo::Monday Monday.tar
2183
2184          # exclude some types, compress using gzip
2185          $ borg export-tar /path/to/repo::Monday Monday.tar.gz --exclude '*.so'
2186
2187          # use higher compression level with gzip
2188          $ borg export-tar --tar-filter="gzip -9" testrepo::linux Monday.tar.gz
2189
2190          # export a tar, but instead of storing it on disk,
2191          # upload it to a remote site using curl.
2192          $ borg export-tar /path/to/repo::Monday - | curl --data-binary @- https://somewhere/to/POST
2193
2194          # remote extraction via "tarpipe"
2195          $ borg export-tar /path/to/repo::Monday - | ssh somewhere "cd extracted; tar x"
2196

BORG SERVE

2198          borg [common options] serve [options]
2199
2200   Description
2201       This  command  starts a repository server process. This command is usu‐
2202       ally not used manually.
2203
2204   Examples
2205       borg serve has special support for  ssh  forced  commands  (see  autho‐
2206       rized_keys  example  below):  it will detect that you use such a forced
2207       command and extract the value of the --restrict-to-path option(s).
2208
2209       It will then parse the original command  that  came  from  the  client,
2210       makes  sure  that it is also borg serve and enforce path restriction(s)
2211       as given by the forced command. That way, other options  given  by  the
2212       client (like --info or --umask) are preserved (and are not fixed by the
2213       forced command).
2214
2215       Environment variables (such as  BORG_HOSTNAME_IS_UNIQUE)  contained  in
2216       the  original  command  sent  by  the  client  are not interpreted, but
2217       ignored. If BORG_XXX environment variables should be set  on  the  borg
2218       serve  side,  then  these must be set in system-specific locations like
2219       /etc/environment or in the forced command itself (example below).
2220
2221          # Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
2222          # Use key options to disable unneeded and potentially dangerous SSH functionality.
2223          # This will help to secure an automated remote backup system.
2224          $ cat ~/.ssh/authorized_keys
2225          command="borg serve --restrict-to-path /path/to/repo",restrict ssh-rsa AAAAB3[...]
2226
2227          # Set a BORG_XXX environment variable on the "borg serve" side
2228          $ cat ~/.ssh/authorized_keys
2229          command="export BORG_XXX=value; borg serve [...]",restrict ssh-rsa [...]
2230
2231       NOTE:
2232          The examples above use the restrict directive. This  does  automati‐
2233          cally  block  potential  dangerous  ssh features, even when they are
2234          added in a future update. Thus, this option should be preferred.
2235
2236          If you're using openssh-server < 7.2, however, you have  to  explic‐
2237          itly  specify the ssh features to restrict and cannot simply use the
2238          restrict option as it has been introduced in v7.2. We  recommend  to
2239          use    no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forward‐
2240          ing,no-user-rc in this case.
2241
2242   SSH Configuration
2243       borg serve's pipes (stdin/stdout/stderr)  are  connected  to  the  sshd
2244       process  on  the  server  side.  In  the  event that the SSH connection
2245       between borg serve and the client is disconnected or  stuck  abnormally
2246       (for  example,  due  to  a network outage), it can take a long time for
2247       sshd to notice the client is disconnected. In the meantime,  sshd  con‐
2248       tinues  running, and as a result so does the borg serve process holding
2249       the lock on the repository. This can cause subsequent  borg  operations
2250       on  the  remote  repository  to  fail  with  the  error: Failed to cre‐
2251       ate/acquire the lock.
2252
2253       In order to avoid this, it is  recommended  to  perform  the  following
2254       additional SSH configuration:
2255
2256       Either  in  the  client  side's  ~/.ssh/config file, or in the client's
2257       /etc/ssh/ssh_config file:
2258
2259          Host backupserver
2260                  ServerAliveInterval 10
2261                  ServerAliveCountMax 30
2262
2263       Replacing backupserver with the hostname, FQDN or  IP  address  of  the
2264       borg server.
2265
2266       This  will  cause the client to send a keepalive to the server every 10
2267       seconds. If 30 consecutive keepalives are sent without  a  response  (a
2268       time  of 300 seconds), the ssh client process will be terminated, caus‐
2269       ing the borg process to terminate gracefully.
2270
2271       On   the   server   side's   sshd   configuration    file    (typically
2272       /etc/ssh/sshd_config):
2273
2274          ClientAliveInterval 10
2275          ClientAliveCountMax 30
2276
2277       This  will cause the server to send a keep alive to the client every 10
2278       seconds. If 30 consecutive keepalives are sent without  a  response  (a
2279       time  of  300  seconds),  the server's sshd process will be terminated,
2280       causing the borg serve process to terminate gracefully and release  the
2281       lock on the repository.
2282
2283       If  you  then run borg commands with --lock-wait 600, this gives suffi‐
2284       cient time for the borg serve processes to terminate after the SSH con‐
2285       nection  is  torn  down after the 300 second wait for the keepalives to
2286       fail.
2287
2288       You may, of course, modify the timeout  values  demonstrated  above  to
2289       values that suit your environment and use case.
2290

BORG CONFIG

2292          borg [common options] config [options] [REPOSITORY] [NAME] [VALUE]
2293
2294   Description
2295       This  command gets and sets options in a local repository or cache con‐
2296       fig file.  For security reasons,  this  command  only  works  on  local
2297       repositories.
2298
2299       To  delete a config value entirely, use --delete. To list the values of
2300       the configuration file or the default values, use --list.  To  get  and
2301       existing  key,  pass only the key name. To set a key, pass both the key
2302       name and the new value. Keys can  be  specified  in  the  format  "sec‐
2303       tion.name"  or  simply "name"; the section will default to "repository"
2304       and "cache" for the repo and cache configs, respectively.
2305
2306       By default, borg config manipulates the repository config  file.  Using
2307       --cache edits the repository cache's config file instead.
2308
2309       NOTE:
2310          The  repository  &  cache config files are some of the only directly
2311          manipulable parts of a repository that aren't  versioned  or  backed
2312          up, so be careful when making changes!
2313
2314   Examples
2315          # find cache directory
2316          $ cd ~/.cache/borg/$(borg config /path/to/repo id)
2317
2318          # reserve some space
2319          $ borg config /path/to/repo additional_free_space 2G
2320
2321          # make a repo append-only
2322          $ borg config /path/to/repo append_only 1
2323

BORG WITH-LOCK

2325          borg [common options] with-lock [options] REPOSITORY COMMAND [ARGS...]
2326
2327   Description
2328       This command runs a user-specified command while the repository lock is
2329       held.
2330
2331       It will first try to acquire the lock (make sure that no  other  opera‐
2332       tion  is running in the repo), then execute the given command as a sub‐
2333       process and wait for its termination, release the lock and  return  the
2334       user command's return code as borg's return code.
2335
2336       NOTE:
2337          If  you  copy  a  repository  with  the  lock held, the lock will be
2338          present in the copy. Thus, before using borg on the copy from a dif‐
2339          ferent host, you need to use "borg break-lock" on the copied reposi‐
2340          tory, because Borg is cautious and  does  not  automatically  remove
2341          stale locks made by a different host.
2342

BORG BREAK-LOCK

2344          borg [common options] break-lock [options] [REPOSITORY]
2345
2346   Description
2347       This  command  breaks the repository and cache locks.  Please use care‐
2348       fully and only while no borg process (on  any  machine)  is  trying  to
2349       access the Cache or the Repository.
2350

BORG BENCHMARK CRUD

2352          borg [common options] benchmark crud [options] REPOSITORY PATH
2353
2354   Description
2355       This command benchmarks borg CRUD (create, read, update, delete) opera‐
2356       tions.
2357
2358       It creates input data below the given PATH and backups this  data  into
2359       the given REPO.  The REPO must already exist (it could be a fresh empty
2360       repo or an existing repo, the command will create /  read  /  update  /
2361       delete some archives named borg-benchmark-crud* there.
2362
2363       Make  sure  you  have  free  space there, you'll need about 1GB each (+
2364       overhead).
2365
2366       If your repository is encrypted and borg needs a passphrase  to  unlock
2367       the key, use:
2368
2369          BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
2370
2371       Measurements  are done with different input file sizes and counts.  The
2372       file contents are very artificial (either all zero or all random), thus
2373       the  measurement  results  do  not necessarily reflect performance with
2374       real data.  Also, due to the kind of content used,  no  compression  is
2375       used in these benchmarks.
2376
2377       C-  ==  borg  create  (1st archive creation, no compression, do not use
2378       files cache)
2379              C-Z- == all-zero files. full dedup, this is primarily  measuring
2380              reader/chunker/hasher.   C-R- == random files. no dedup, measur‐
2381              ing throughput through all processing stages.
2382
2383       R- == borg extract (extract archive, dry-run, do everything, but do not
2384       write files to disk)
2385              R-Z-  ==  all  zero  files.  Measuring heavily duplicated files.
2386              R-R- == random files. No duplication here, measuring  throughput
2387              through all processing stages, except writing to disk.
2388
2389       U-  == borg create (2nd archive creation of unchanged input files, mea‐
2390       sure files cache speed)
2391              The throughput value is kind of virtual here, it does not  actu‐
2392              ally  read  the  file.   U-Z-  ==  needs to check the 2 all-zero
2393              chunks' existence in the repo.  U-R- == needs to check existence
2394              of a lot of different chunks in the repo.
2395
2396       D- == borg delete archive (delete last remaining archive, measure dele‐
2397       tion + compaction)
2398              D-Z- == few chunks to delete / few segments  to  compact/remove.
2399              D-R- == many chunks to delete / many segments to compact/remove.
2400
2401       Please  note  that there might be quite some variance in these measure‐
2402       ments.  Try multiple measurements and having a otherwise  idle  machine
2403       (and network, if you use it).
2404

MISCELLANEOUS HELP

2406   borg help patterns
2407       The  path/filenames  used  as input for the pattern matching start from
2408       the currently active recursion root. You  usually  give  the  recursion
2409       root(s) when invoking borg and these can be either relative or absolute
2410       paths.
2411
2412       So, when you give relative/ as root, the paths going into  the  matcher
2413       will look like relative/.../file.ext. When you give /absolute/ as root,
2414       they will look like /absolute/.../file.ext. This is meant when we  talk
2415       about "full path" below.
2416
2417       File  paths in Borg archives are always stored normalized and relative.
2418       This means that e.g. borg create /path/to/repo ../some/path will  store
2419       all  files  as  some/path/.../file.ext  and  borg  create /path/to/repo
2420       /home/user will store all files as  home/user/.../file.ext.  Therefore,
2421       always  use  relative paths in your patterns when matching archive con‐
2422       tent in commands like extract or mount. Starting with Borg 1.2 this be‐
2423       haviour will be changed to accept both absolute and relative paths.
2424
2425       File  patterns  support  these  styles: fnmatch, shell, regular expres‐
2426       sions, path prefixes and path full-matches. By default, fnmatch is used
2427       for  --exclude  patterns  and  shell-style is used for the experimental
2428       --pattern option.
2429
2430       If followed by a colon (':') the first two characters of a pattern  are
2431       used  as a style selector. Explicit style selection is necessary when a
2432       non-default style is desired or when the desired  pattern  starts  with
2433       two alphanumeric characters followed by a colon (i.e. aa:something/*).
2434
2435       Fnmatch, selector fm:
2436              This  is  the  default  style  for --exclude and --exclude-from.
2437              These patterns use a variant of shell pattern syntax,  with  '*'
2438              matching any number of characters, '?' matching any single char‐
2439              acter, '[...]' matching any single character specified,  includ‐
2440              ing  ranges,  and '[!...]' matching any character not specified.
2441              For the purpose of these patterns, the path separator (backslash
2442              for  Windows and '/' on other systems) is not treated specially.
2443              Wrap meta-characters in brackets for a literal match  (i.e.  [?]
2444              to  match  the  literal character ?). For a path to match a pat‐
2445              tern, the full path must match, or it must match from the  start
2446              of the full path to just before a path separator. Except for the
2447              root path, paths will never  end  in  the  path  separator  when
2448              matching  is attempted.  Thus, if a given pattern ends in a path
2449              separator, a '*' is appended before matching is attempted.
2450
2451       Shell-style patterns, selector sh:
2452              This is the default style  for  --pattern  and  --patterns-from.
2453              Like  fnmatch  patterns these are similar to shell patterns. The
2454              difference is that the pattern may include **/ for matching zero
2455              or  more directory levels, * for matching zero or more arbitrary
2456              characters with the exception of any path separator.
2457
2458       Regular expressions, selector re:
2459              Regular expressions similar to those  found  in  Perl  are  sup‐
2460              ported.  Unlike  shell  patterns  regular  expressions  are  not
2461              required to match the full path and any substring match is  suf‐
2462              ficient.  It  is  strongly recommended to anchor patterns to the
2463              start ('^'), to the end ('$') or both.  Path  separators  (back‐
2464              slash  for Windows and '/' on other systems) in paths are always
2465              normalized to a forward slash ('/') before applying  a  pattern.
2466              The  regular  expression syntax is described in the Python docu‐
2467              mentation for the re module.
2468
2469       Path prefix, selector pp:
2470              This pattern style is useful to match whole sub-directories. The
2471              pattern  pp:root/somedir  matches  root/somedir  and  everything
2472              therein.
2473
2474       Path full-match, selector pf:
2475              This pattern style is (only) useful to match full  paths.   This
2476              is  kind  of a pseudo pattern as it can not have any variable or
2477              unspecified   parts   -   the   full   path   must   be   given.
2478              pf:root/file.ext matches root/file.ext only.
2479
2480              Implementation note: this is implemented via very time-efficient
2481              O(1) hashtable lookups (this means you can have huge amounts  of
2482              such patterns without impacting performance much).  Due to that,
2483              this kind of pattern does not respect any context or order.   If
2484              you  use  such  a  pattern  to include a file, it will always be
2485              included (if the  directory  recursion  encounters  it).   Other
2486              include/exclude  patterns  that  would  normally  match  will be
2487              ignored.  Same logic applies for exclude.
2488
2489       NOTE:
2490          re:, sh: and fm: patterns are all implemented on top of  the  Python
2491          SRE  engine. It is very easy to formulate patterns for each of these
2492          types which requires an inordinate amount of time to match paths. If
2493          untrusted users are able to supply patterns, ensure they cannot sup‐
2494          ply re: patterns.  Further, ensure that sh: and  fm:  patterns  only
2495          contain a handful of wildcards at most.
2496
2497       Exclusions  can  be  passed via the command line option --exclude. When
2498       used from within a shell, the patterns should be quoted to protect them
2499       from expansion.
2500
2501       The  --exclude-from  option  permits  loading exclusion patterns from a
2502       text file with one pattern per line. Lines empty or starting  with  the
2503       number  sign  ('#') after removing whitespace on both ends are ignored.
2504       The optional style selector  prefix  is  also  supported  for  patterns
2505       loaded from a file. Due to whitespace removal, paths with whitespace at
2506       the beginning or end can only be excluded using regular expressions.
2507
2508       To test your exclusion patterns without performing an actual backup you
2509       can run borg create --list --dry-run ....
2510
2511       Examples:
2512
2513          # Exclude '/home/user/file.o' but not '/home/user/file.odt':
2514          $ borg create -e '*.o' backup /
2515
2516          # Exclude '/home/user/junk' and '/home/user/subdir/junk' but
2517          # not '/home/user/importantjunk' or '/etc/junk':
2518          $ borg create -e '/home/*/junk' backup /
2519
2520          # Exclude the contents of '/home/user/cache' but not the directory itself:
2521          $ borg create -e /home/user/cache/ backup /
2522
2523          # The file '/home/user/cache/important' is *not* backed up:
2524          $ borg create -e /home/user/cache/ backup / /home/user/cache/important
2525
2526          # The contents of directories in '/home' are not backed up when their name
2527          # ends in '.tmp'
2528          $ borg create --exclude 're:^/home/[^/]+\.tmp/' backup /
2529
2530          # Load exclusions from file
2531          $ cat >exclude.txt <<EOF
2532          # Comment line
2533          /home/*/junk
2534          *.tmp
2535          fm:aa:something/*
2536          re:^home/[^/]\.tmp/
2537          sh:home/*/.thumbnails
2538           # Example with spaces, no need to escape as it is processed by borg
2539          some file with spaces.txt
2540          EOF
2541          $ borg create --exclude-from exclude.txt backup /
2542       A  more  general and easier to use way to define filename matching pat‐
2543       terns  exists  with  the  experimental  --pattern  and  --patterns-from
2544       options.  Using  these,  you  may  specify  the  backup roots (starting
2545       points) and patterns for inclusion/exclusion.  A root path starts  with
2546       the prefix R, followed by a path (a plain path, not a file pattern). An
2547       include rule starts with the prefix +, an exclude rule starts with  the
2548       prefix  -,  an  exclude-norecurse rule starts with !, all followed by a
2549       pattern.
2550
2551       NOTE:
2552          Via --pattern or --patterns-from you can define BOTH  inclusion  and
2553          exclusion  of  files  using pattern prefixes + and -. With --exclude
2554          and --exlude-from ONLY excludes are defined.
2555
2556       Inclusion patterns are useful to include paths that are contained in an
2557       excluded path. The first matching pattern is used so if an include pat‐
2558       tern matches before an exclude pattern, the file is backed  up.  If  an
2559       exclude-norecurse pattern matches a directory, it won't recurse into it
2560       and won't discover any potential matches for include rules  below  that
2561       directory.
2562
2563       Note  that  the default pattern style for --pattern and --patterns-from
2564       is shell style  (sh:),  so  those  patterns  behave  similar  to  rsync
2565       include/exclude  patterns.  The pattern style can be set via the P pre‐
2566       fix.
2567
2568       Patterns (--pattern) and excludes (--exclude) from the command line are
2569       considered  first  (in  the  order  of  appearance). Then patterns from
2570       --patterns-from are added. Exclusion patterns from --exclude-from files
2571       are appended last.
2572
2573       Examples:
2574
2575          # backup pics, but not the ones from 2018, except the good ones:
2576          # note: using = is essential to avoid cmdline argument parsing issues.
2577          borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
2578
2579          # use a file with patterns:
2580          borg create --patterns-from patterns.lst repo::arch
2581
2582       The patterns.lst file could look like that:
2583
2584          # "sh:" pattern style is the default, so the following line is not needed:
2585          P sh
2586          R /
2587          # can be rebuild
2588          - /home/*/.cache
2589          # they're downloads for a reason
2590          - /home/*/Downloads
2591          # susan is a nice person
2592          # include susans home
2593          + /home/susan
2594          # don't backup the other home directories
2595          - /home/*
2596          # don't even look in /proc
2597          ! /proc
2598
2599   borg help placeholders
2600       Repository  (or Archive) URLs, --prefix, --glob-archives, --comment and
2601       --remote-path values support these placeholders:
2602
2603       {hostname}
2604              The (short) hostname of the machine.
2605
2606       {fqdn} The full name of the machine.
2607
2608       {reverse-fqdn}
2609              The full name of the machine in reverse domain name notation.
2610
2611       {now}  The current local date and time, by default in ISO-8601  format.
2612              You   can   also   supply   your   own   format   string,   e.g.
2613              {now:%Y-%m-%d_%H:%M:%S}
2614
2615       {utcnow}
2616              The current UTC date and time, by default  in  ISO-8601  format.
2617              You   can  also  supply  your  own  format  string,  e.g.  {utc‐
2618              now:%Y-%m-%d_%H:%M:%S}
2619
2620       {user} The user name (or UID, if no name is available) of the user run‐
2621              ning borg.
2622
2623       {pid}  The current process ID.
2624
2625       {borgversion}
2626              The version of borg, e.g.: 1.0.8rc1
2627
2628       {borgmajor}
2629              The version of borg, only the major version, e.g.: 1
2630
2631       {borgminor}
2632              The version of borg, only major and minor version, e.g.: 1.0
2633
2634       {borgpatch}
2635              The  version of borg, only major, minor and patch version, e.g.:
2636              1.0.8
2637
2638       If literal curly braces need to be used, double them for escaping:
2639
2640          borg create /path/to/repo::{{literal_text}}
2641
2642       Examples:
2643
2644          borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
2645          borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
2646          borg prune --prefix '{hostname}-' ...
2647
2648       NOTE:
2649          systemd uses a difficult, non-standard syntax for command  lines  in
2650          unit files (refer to the systemd.unit(5) manual page).
2651
2652          When  invoking  borg  from  unit  files, pay particular attention to
2653          escaping, especially when using the now/utcnow  placeholders,  since
2654          systemd performs its own %-based variable replacement even in quoted
2655          text. To avoid interference from systemd, double all  percent  signs
2656          ({hostname}-{now:%Y-%m-%d_%H:%M:%S}          becomes          {host‐
2657          name}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}).
2658
2659   borg help compression
2660       It is no problem to mix different  compression  methods  in  one  repo,
2661       deduplication  is done on the source data chunks (not on the compressed
2662       or encrypted data).
2663
2664       If some specific chunk was once compressed and stored  into  the  repo,
2665       creating  another  backup that also uses this chunk will not change the
2666       stored chunk.  So if you use different compression specs for the  back‐
2667       ups,  whichever  stores  a  chunk first determines its compression. See
2668       also borg recreate.
2669
2670       Compression is lz4 by default. If you want something else, you have  to
2671       specify what you want.
2672
2673       Valid compression specifiers are:
2674
2675       none   Do not compress.
2676
2677       lz4    Use  lz4  compression.  Very  high  speed, very low compression.
2678              (default)
2679
2680       zstd[,L]
2681              Use zstd ("zstandard") compression, a  modern  wide-range  algo‐
2682              rithm.   If  you do not explicitely give the compression level L
2683              (ranging from 1 to 22), it will  use  level  3.   Archives  com‐
2684              pressed with zstd are not compatible with borg < 1.1.4.
2685
2686       zlib[,L]
2687              Use  zlib  ("gz") compression. Medium speed, medium compression.
2688              If you do not explicitely give the compression level L  (ranging
2689              from  0  to  9), it will use level 6.  Giving level 0 (means "no
2690              compression", but still has zlib protocol overhead)  is  usually
2691              pointless, you better use "none" compression.
2692
2693       lzma[,L]
2694              Use  lzma  ("xz")  compression. Low speed, high compression.  If
2695              you do not explicitely give the  compression  level  L  (ranging
2696              from  0  to  9),  it will use level 6.  Giving levels above 6 is
2697              pointless and counterproductive because  it  does  not  compress
2698              better  due to the buffer size used by borg - but it wastes lots
2699              of CPU cycles and RAM.
2700
2701       auto,C[,L]
2702              Use a built-in heuristic to decide per chunk whether to compress
2703              or  not.   The heuristic tries with lz4 whether the data is com‐
2704              pressible.  For incompressible data, it will not use compression
2705              (uses  "none").   For compressible data, it uses the given C[,L]
2706              compression - with C[,L] being any valid compression specifier.
2707
2708       Examples:
2709
2710          borg create --compression lz4 REPO::ARCHIVE data
2711          borg create --compression zstd REPO::ARCHIVE data
2712          borg create --compression zstd,10 REPO::ARCHIVE data
2713          borg create --compression zlib REPO::ARCHIVE data
2714          borg create --compression zlib,1 REPO::ARCHIVE data
2715          borg create --compression auto,lzma,6 REPO::ARCHIVE data
2716          borg create --compression auto,lzma ...
2717

DEBUGGING FACILITIES

2719       There is a borg debug command that has some subcommands which  are  all
2720       not  intended  for  normal  use  and potentially very dangerous if used
2721       incorrectly.
2722
2723       For example, borg debug put-obj and borg debug delete-obj will only  do
2724       what  their  name suggests: put objects into repo / delete objects from
2725       repo.
2726
2727       Please note:
2728
2729       · they will not update the chunks cache (chunks index) about the object
2730
2731       · they will not update the  manifest  (so  no  automatic  chunks  index
2732         resync is triggered)
2733
2734       · they  will  not  check  whether  the  object  is  in use (e.g. before
2735         delete-obj)
2736
2737       · they will not update any metadata which may point to the object
2738
2739       They exist to improve  debugging  capabilities  without  direct  system
2740       access,  e.g.   in  case you ever run into some severe malfunction. Use
2741       them only if you know what you are doing or if a trusted Borg developer
2742       tells you what to do.
2743
2744       Borg has a --debug-topic TOPIC option to enable specific debugging mes‐
2745       sages. Topics are generally not documented.
2746
2747       A --debug-profile FILE option exists which writes a profile of the main
2748       program's  execution  to  a  file.  The  format  of  these files is not
2749       directly compatible with the Python profiling tools,  since  these  use
2750       the  "marshal"  format, which is not intended to be secure (quoting the
2751       Python docs: "Never unmarshal data received from an untrusted or  unau‐
2752       thenticated source.").
2753
2754       The  borg debug profile-convert command can be used to take a Borg pro‐
2755       file and convert it to a profile  file  that  is  compatible  with  the
2756       Python tools.
2757
2758       Additionally,  if  the filename specified for --debug-profile ends with
2759       ".pyprof" a Python  compatible  profile  is  generated.  This  is  only
2760       intended for local use by developers.
2761

ADDITIONAL NOTES

2763       Here  are misc. notes about topics that are maybe not covered in enough
2764       detail in the usage section.
2765
2766   --chunker-params
2767       The chunker params influence  how  input  files  are  cut  into  pieces
2768       (chunks)  which are then considered for deduplication. They also have a
2769       big impact on resource usage (RAM and disk  space)  as  the  amount  of
2770       resources  needed is (also) determined by the total amount of chunks in
2771       the repository (see cache-memory-usage for details).
2772
2773       --chunker-params=10,23,16,4095 results in a fine-grained deduplication|
2774       and  creates a big amount of chunks and thus uses a lot of resources to
2775       manage them. This is good for relatively small data volumes and if  the
2776       machine has a good amount of free RAM and disk space.
2777
2778       --chunker-params=19,23,21,4095  (default)  results  in a coarse-grained
2779       deduplication and creates a much smaller amount of chunks and thus uses
2780       less resources. This is good for relatively big data volumes and if the
2781       machine has a relatively low amount of free RAM and disk space.
2782
2783       If you already have made some archives in a  repository  and  you  then
2784       change  chunker  params,  this  of  course impacts deduplication as the
2785       chunks will be cut differently.
2786
2787       In the worst case (all files are big and were touched in between  back‐
2788       ups), this will store all content into the repository again.
2789
2790       Usually, it is not that bad though:
2791
2792       · usually  most  files  are not touched, so it will just re-use the old
2793         chunks it already has in the repo
2794
2795       · files smaller than the (both old and new) minimum chunksize result in
2796         only  one chunk anyway, so the resulting chunks are same and dedupli‐
2797         cation will apply
2798
2799       If you switch chunker params to save resources  for  an  existing  repo
2800       that  already  has  some  backup  archives,  you will see an increasing
2801       effect over time, when more and more files have been touched and stored
2802       again  using  the  bigger  chunksize  and all references to the smaller
2803       older chunks have been removed (by deleting / pruning archives).
2804
2805       If you want to see an immediate big effect on resource usage, you  bet‐
2806       ter start a new repository when changing chunker params.
2807
2808       For more details, see chunker_details.
2809
2810   --noatime / --noctime
2811       You can use these borg create options to not store the respective time‐
2812       stamp into the archive, in case you do not really need it.
2813
2814       Besides saving a little space for the not archived timestamp, it  might
2815       also  affect  metadata  stream  deduplication:  if  only this timestamp
2816       changes between backups and is stored into  the  metadata  stream,  the
2817       metadata stream chunks won't deduplicate just because of that.
2818
2819   --nobsdflags
2820       You  can  use this to not query and store (or not extract and set) bsd‐
2821       flags - in case you don't need them or if they are broken  somehow  for
2822       your fs.
2823
2824       On  Linux,  dealing  with  the  bsflags needs some additional syscalls.
2825       Especially when dealing with lots of small files, this causes a notica‐
2826       ble  overhead,  so  you can use this option also for speeding up opera‐
2827       tions.
2828
2829   --umask
2830       If you use --umask, make sure that all repository-modifying  borg  com‐
2831       mands  (create,  delete,  prune) that access the repository in question
2832       use the same --umask value.
2833
2834       If multiple machines access the same repository, this should hold  true
2835       for all of them.
2836
2837   --read-special
2838       The  --read-special  option  is special - you do not want to use it for
2839       normal full-filesystem backups, but rather after carefully picking some
2840       targets for it.
2841
2842       The option --read-special triggers special treatment for block and char
2843       device files as well as FIFOs. Instead of storing them as such a device
2844       (or  FIFO), they will get opened, their content will be read and in the
2845       backup archive they will show up like a regular file.
2846
2847       Symlinks will also get special treatment if (and only if) they point to
2848       such  a  special file: instead of storing them as a symlink, the target
2849       special file will get processed as described above.
2850
2851       One intended use case of this is backing up the contents of one or mul‐
2852       tiple  block  devices,  like e.g. LVM snapshots or inactive LVs or disk
2853       partitions.
2854
2855       You need to be careful about what you include  when  using  --read-spe‐
2856       cial, e.g. if you include /dev/zero, your backup will never terminate.
2857
2858       Restoring such files' content is currently only supported one at a time
2859       via --stdout option (and you have to redirect stdout to where  ever  it
2860       shall go, maybe directly into an existing device file of your choice or
2861       indirectly via dd).
2862
2863       To some extent, mounting a backup archive with the backups  of  special
2864       files via borg mount and then loop-mounting the image files from inside
2865       the mount point will work. If you plan to  access  a  lot  of  data  in
2866       there,  it  likely will scale and perform better if you do not work via
2867       the FUSE mount.
2868
2869   Example
2870       Imagine you have made some snapshots of logical volumes (LVs) you  want
2871       to backup.
2872
2873       NOTE:
2874          For  some  scenarios, this is a good method to get "crash-like" con‐
2875          sistency (I call it crash-like because it is the same as  you  would
2876          get  if you just hit the reset button or your machine would abruptly
2877          and completely crash).  This is better than no  consistency  at  all
2878          and  a good method for some use cases, but likely not good enough if
2879          you have databases running.
2880
2881       Then you create a backup archive of all  these  snapshots.  The  backup
2882       process  will  see  a  "frozen" state of the logical volumes, while the
2883       processes working in the original volumes continue  changing  the  data
2884       stored there.
2885
2886       You also add the output of lvdisplay to your backup, so you can see the
2887       LV sizes in case you ever need to recreate and restore them.
2888
2889       After the backup has completed, you remove the snapshots again.
2890
2891          $ # create snapshots here
2892          $ lvdisplay > lvdisplay.txt
2893          $ borg create --read-special /path/to/repo::arch lvdisplay.txt /dev/vg0/*-snapshot
2894          $ # remove snapshots here
2895
2896       Now, let's see how to restore some LVs from such a backup.
2897
2898          $ borg extract /path/to/repo::arch lvdisplay.txt
2899          $ # create empty LVs with correct sizes here (look into lvdisplay.txt).
2900          $ # we assume that you created an empty root and home LV and overwrite it now:
2901          $ borg extract --stdout /path/to/repo::arch dev/vg0/root-snapshot > /dev/vg0/root
2902          $ borg extract --stdout /path/to/repo::arch dev/vg0/home-snapshot > /dev/vg0/home
2903
2904   Append-only mode
2905       A repository can be made "append-only",  which  means  that  Borg  will
2906       never  overwrite  or  delete  committed data (append-only refers to the
2907       segment files, but borg will also reject to delete the repository  com‐
2908       pletely).  This  is  useful for scenarios where a backup client machine
2909       backups remotely to a backup server using borg serve,  since  a  hacked
2910       client machine cannot delete backups on the server permanently.
2911
2912       To  activate  append-only  mode, set append_only to 1 in the repository
2913       config:
2914
2915          borg config /path/to/repo append_only 1
2916
2917       Note that you can go  back-and-forth  between  normal  and  append-only
2918       operation with borg config; it's not a "one way trip."
2919
2920       In  append-only mode Borg will create a transaction log in the transac‐
2921       tions file, where each line is a transaction and a UTC timestamp.
2922
2923       In addition, borg serve can act as if a repository  is  in  append-only
2924       mode  with  its  option  --append-only.  This  can  be  very useful for
2925       fine-tuning access control in .ssh/authorized_keys:
2926
2927          command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustable backup clients>
2928          command="borg serve ..." ssh-rsa <key used for backup management>
2929
2930       Running borg init via a borg serve --append-only server will not create
2931       an  append-only  repository. Running borg init --append-only creates an
2932       append-only repository regardless of server settings.
2933
2934   Example
2935       Suppose an attacker remotely deleted all backups, but  your  repository
2936       was in append-only mode. A transaction log in this situation might look
2937       like this:
2938
2939          transaction 1, UTC time 2016-03-31T15:53:27.383532
2940          transaction 5, UTC time 2016-03-31T15:53:52.588922
2941          transaction 11, UTC time 2016-03-31T15:54:23.887256
2942          transaction 12, UTC time 2016-03-31T15:55:54.022540
2943          transaction 13, UTC time 2016-03-31T15:55:55.472564
2944
2945       From your security logs you conclude  the  attacker  gained  access  at
2946       15:54:00  and  all the backups where deleted or replaced by compromised
2947       backups. From the log you know that transactions 11 and later are  com‐
2948       promised.  Note that the transaction ID is the name of the last file in
2949       the transaction. For example, transaction 11 spans files 6 to 11.
2950
2951       In a real attack you'll likely want to keep the compromised  repository
2952       intact  to analyze what the attacker tried to achieve. It's also a good
2953       idea to make this copy just in case something  goes  wrong  during  the
2954       recovery.  Since  recovery  is done by deleting some files, a hard link
2955       copy (cp -al) is sufficient.
2956
2957       The first step to reset the  repository  to  transaction  5,  the  last
2958       uncompromised  transaction,  is  to  remove  the  hints.N,  index.N and
2959       integrity.N files in the repository (these  files  are  always  expend‐
2960       able). In this example N is 13.
2961
2962       Then  remove  or move all segment files from the segment directories in
2963       data/ starting with file 6:
2964
2965          rm data/**/{6..13}
2966
2967       That's all to do in the repository.
2968
2969       If you want to access this rollbacked repository  from  a  client  that
2970       already has a cache for this repository, the cache will reflect a newer
2971       repository state than what you actually have  in  the  repository  now,
2972       after the rollback.
2973
2974       Thus, you need to clear the cache:
2975
2976          borg delete --cache-only repo
2977
2978       The  cache  will  get rebuilt automatically. Depending on repo size and
2979       archive count, it may take a while.
2980
2981       You  also  will  need  to  remove  ~/.config/borg/security/REPOID/mani‐
2982       fest-timestamp.
2983
2984   Drawbacks
2985       As  data  is only appended, and nothing removed, commands like prune or
2986       delete won't free disk space, they merely tag data as deleted in a  new
2987       transaction.
2988
2989       Be  aware that as soon as you write to the repo in non-append-only mode
2990       (e.g. prune, delete or create archives from an admin machine), it  will
2991       remove  the  deleted  objects permanently (including the ones that were
2992       already marked as deleted, but not removed, in append-only mode). Auto‐
2993       mated  edits  to the repository (such as a cron job running borg prune)
2994       will render append-only mode moot if data is deleted.
2995
2996       Even if an archive appears to be available, it is possible an  attacker
2997       could delete just a few chunks from an archive and silently corrupt its
2998       data. While in append-only mode, this is  reversible,  but  borg  check
2999       should  be  run  before  a  writing/pruning operation on an append-only
3000       repository to catch accidental or malicious corruption:
3001
3002          # run without append-only mode
3003          borg check --verify-data repo
3004
3005       Aside from checking repository & archive integrity you may want to also
3006       manually check backups to ensure their content seems correct.
3007
3008   Further considerations
3009       Append-only  mode  is  not respected by tools other than Borg. rm still
3010       works on the repository. Make sure that backup client machines only get
3011       to access the repository via borg serve.
3012
3013       Ensure that no remote access is possible if the repository is temporar‐
3014       ily set to normal mode for e.g. regular pruning.
3015
3016       Further protections can be  implemented,  but  are  outside  of  Borg's
3017       scope. For example, file system snapshots or wrapping borg serve to set
3018       special permissions or ACLs on new data files.
3019
3020   SSH batch mode
3021       When running Borg using an automated script, ssh might still ask for  a
3022       password,  even  if there is an SSH key for the target server. Use this
3023       to make scripts more robust:
3024
3025          export BORG_RSH='ssh -oBatchMode=yes'
3026

AUTHOR

3028       The Borg Collective (see AUTHORS file)
3029
3031       2010-2021 Jonas Borgström, 2015-2020 The Borg Collective  (see  AUTHORS
3032       file)
3033
3034
3035
3036
30371.1.16                            2021-03-23                           BORG(1)
Impressum