From 51cf85e627233feaae689b53950372dd8298b743 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Fri, 24 Jun 2022 01:19:19 +0200 Subject: [PATCH] build_usage / build_man / doc updates --- docs/faq.rst | 247 ++--------------- docs/installation.rst | 4 +- docs/internals/data-structures.rst | 7 +- docs/internals/frontends.rst | 4 +- docs/internals/security.rst | 117 +------- docs/man/borg-benchmark-cpu.1 | 14 +- docs/man/borg-benchmark-crud.1 | 11 +- docs/man/borg-benchmark.1 | 6 +- docs/man/borg-break-lock.1 | 14 +- docs/man/borg-check.1 | 27 +- docs/man/borg-common.1 | 35 +-- docs/man/borg-compact.1 | 21 +- docs/man/borg-compression.1 | 6 +- docs/man/borg-config.1 | 23 +- docs/man/borg-create.1 | 110 ++++---- docs/man/borg-delete.1 | 63 ++--- docs/man/borg-diff.1 | 57 +--- docs/man/borg-export-tar.1 | 16 +- docs/man/borg-extract.1 | 44 +-- docs/man/borg-import-tar.1 | 38 +-- docs/man/borg-info.1 | 82 ++---- docs/man/borg-key-change-algorithm.1 | 10 +- docs/man/borg-key-change-location.1 | 27 +- docs/man/borg-key-change-passphrase.1 | 21 +- docs/man/borg-key-export.1 | 14 +- docs/man/borg-key-import.1 | 12 +- docs/man/borg-key.1 | 6 +- docs/man/borg-list.1 | 136 ++------- docs/man/borg-mount.1 | 21 +- docs/man/borg-patterns.1 | 258 ++++++++++-------- docs/man/borg-placeholders.1 | 8 +- docs/man/borg-prune.1 | 48 ++-- docs/man/{borg-init.1 => borg-rcreate.1} | 86 +++--- docs/man/borg-rdelete.1 | 90 ++++++ docs/man/borg-recreate.1 | 57 ++-- docs/man/borg-rename.1 | 22 +- docs/man/borg-rinfo.1 | 83 ++++++ docs/man/borg-rlist.1 | 160 +++++++++++ docs/man/borg-serve.1 | 8 +- docs/man/borg-transfer.1 | 100 +++++++ docs/man/borg-umount.1 | 25 +- docs/man/borg-upgrade.1 | 24 +- docs/man/borg-with-lock.1 | 11 +- docs/man/borg.1 | 117 ++++---- docs/man/borgfs.1 | 23 +- docs/man_intro.rst | 4 +- docs/quickstart.rst | 51 ++-- docs/quickstart_example.rst.inc | 53 ++-- docs/usage.rst | 20 +- docs/usage/benchmark_cpu.rst.inc | 1 + docs/usage/benchmark_crud.rst.inc | 24 +- docs/usage/break-lock.rst.inc | 18 +- docs/usage/check.rst.inc | 11 +- docs/usage/common-options.rst.inc | 35 +-- docs/usage/compact.rst | 7 +- docs/usage/compact.rst.inc | 8 +- docs/usage/config.rst | 6 +- docs/usage/config.rst.inc | 6 +- docs/usage/create.rst | 48 ++-- docs/usage/create.rst.inc | 12 +- docs/usage/delete.rst | 18 +- docs/usage/delete.rst.inc | 26 +- docs/usage/diff.rst | 33 +-- docs/usage/diff.rst.inc | 12 +- docs/usage/export-tar.rst.inc | 8 +- docs/usage/extract.rst | 12 +- docs/usage/extract.rst.inc | 8 +- docs/usage/general.rst | 4 +- docs/usage/general/environment.rst.inc | 7 +- .../general/positional-arguments.rst.inc | 8 +- .../general/repository-locations.rst.inc | 15 +- docs/usage/general/repository-urls.rst.inc | 24 +- docs/usage/help.rst.inc | 233 ++++++++-------- docs/usage/import-tar.rst.inc | 8 +- docs/usage/info.rst | 64 +---- docs/usage/info.rst.inc | 10 +- docs/usage/init.rst | 22 -- docs/usage/key.rst | 10 +- docs/usage/key_change-algorithm.rst.inc | 24 +- docs/usage/key_change-location.rst.inc | 16 +- docs/usage/key_change-passphrase.rst.inc | 18 +- docs/usage/key_export.rst.inc | 36 ++- docs/usage/key_import.rst.inc | 32 +-- docs/usage/list.rst | 17 +- docs/usage/list.rst.inc | 134 +++------ docs/usage/mount.rst | 19 +- docs/usage/mount.rst.inc | 6 +- docs/usage/notes.rst | 16 +- docs/usage/prune.rst | 10 +- docs/usage/prune.rst.inc | 8 +- docs/usage/rcreate.rst | 25 ++ docs/usage/{init.rst.inc => rcreate.rst.inc} | 31 +-- docs/usage/rdelete.rst | 13 + docs/usage/rdelete.rst.inc | 66 +++++ docs/usage/recreate.rst | 19 +- docs/usage/recreate.rst.inc | 125 +++++---- docs/usage/rename.rst | 8 +- docs/usage/rename.rst.inc | 30 +- docs/usage/rinfo.rst | 16 ++ docs/usage/rinfo.rst.inc | 56 ++++ docs/usage/rlist.rst | 13 + docs/usage/rlist.rst.inc | 125 +++++++++ docs/usage/tar.rst | 18 +- docs/usage/transfer.rst | 1 + docs/usage/transfer.rst.inc | 87 ++++++ docs/usage/upgrade.rst.inc | 8 +- docs/usage/with-lock.rst.inc | 28 +- src/borg/archiver.py | 73 ++--- 108 files changed, 2134 insertions(+), 2083 deletions(-) rename docs/man/{borg-init.1 => borg-rcreate.1} (81%) create mode 100644 docs/man/borg-rdelete.1 create mode 100644 docs/man/borg-rinfo.1 create mode 100644 docs/man/borg-rlist.1 create mode 100644 docs/man/borg-transfer.1 delete mode 100644 docs/usage/init.rst create mode 100644 docs/usage/rcreate.rst rename docs/usage/{init.rst.inc => rcreate.rst.inc} (91%) create mode 100644 docs/usage/rdelete.rst create mode 100644 docs/usage/rdelete.rst.inc create mode 100644 docs/usage/rinfo.rst create mode 100644 docs/usage/rinfo.rst.inc create mode 100644 docs/usage/rlist.rst create mode 100644 docs/usage/rlist.rst.inc create mode 100644 docs/usage/transfer.rst create mode 100644 docs/usage/transfer.rst.inc diff --git a/docs/faq.rst b/docs/faq.rst index b91c0ea5..9566fdec 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -27,13 +27,7 @@ which is slower. Can I backup from multiple servers into a single repository? ------------------------------------------------------------ -Yes, this is *possible* from the technical standpoint, but it is -*not recommended* from the security perspective. BorgBackup is -built upon a defined :ref:`attack_model` that cannot provide its -guarantees for multiple clients using the same repository. See -:ref:`borg_security_critique` for a detailed explanation. - -Also, in order for the deduplication used by Borg to work, it +In order for the deduplication used by Borg to work, it needs to keep a local cache containing checksums of all file chunks already stored in the repository. This cache is stored in ``~/.cache/borg/``. If Borg detects that a repository has been @@ -49,7 +43,7 @@ Can I back up to multiple, swapped backup targets? -------------------------------------------------- It is possible to swap your backup disks if each backup medium is assigned its -own repository by creating a new one with :ref:`borg_init`. +own repository by creating a new one with :ref:`borg_rcreate`. Can I copy or synchronize my repo to another location? ------------------------------------------------------ @@ -57,8 +51,8 @@ Can I copy or synchronize my repo to another location? If you want to have redundant backup repositories (preferably at separate locations), the recommended way to do that is like this: -- ``borg init repo1`` -- ``borg init repo2`` +- ``borg rcreate repo1`` +- ``borg rcreate repo2`` - client machine ---borg create---> repo1 - client machine ---borg create---> repo2 @@ -94,10 +88,6 @@ Also, you must not run borg against multiple instances of the same repo think they are identical and e.g. use the same local cache for them (which is an issue if they happen to be not the same). See :issue:`4272` for an example. -- Encryption security issues if you would update repo and copy-of-repo - independently, due to AES counter reuse (when using legacy encryption modes). - -See also: :ref:`faq_corrupt_repo` "this is either an attack or unsafe" warning -------------------------------------------- @@ -118,9 +108,9 @@ you could delete the manifest-timestamp and the local cache: :: - borg config repo id # shows the REPO_ID + borg config id # shows the REPO_ID rm ~/.config/borg/security/REPO_ID/manifest-timestamp - borg delete --cache-only REPO + borg rdelete --cache-only This is an unsafe and unsupported way to use borg, you have been warned. @@ -199,11 +189,6 @@ really desperate (e.g. if you have no completed backup of that file and you'ld rather get a partial file extracted than nothing). You do **not** want to give that option under any normal circumstances. -Note that checkpoints inside files are created only since version 1.1, make -sure you have an up-to-date version of borgbackup if you want to continue -instead of retransferring a huge file. In some cases, there is only an outdated -version shipped with your distribution (e.g. Debian). See :ref:`installation`. - How can I backup huge file(s) over a unstable connection? --------------------------------------------------------- @@ -241,33 +226,9 @@ then use ``tar`` to perform the comparison: :: - borg export-tar /path/to/repo::archive-name - | tar --compare -f - -C /path/to/compare/to + borg export-tar archive-name - | tar --compare -f - -C /path/to/compare/to -.. _faq_corrupt_repo: - -My repository is corrupt, how can I restore from an older copy of it? ---------------------------------------------------------------------- - -Note: this is only required for repos using legacy encryption modes. - -If your repositories are encrypted and have the same ID, the recommended method -is to delete the corrupted repository, but keep its security info, and then copy -the working repository to the same location: - -:: - - borg delete --keep-security-info /path/to/repo - rsync -aH /path/to/repo-working/ /path/to/repo # Note the trailing slash. - -A plain delete command would remove the security info in -``~/.config/borg/security``, including the nonce value. In BorgBackup -:ref:`security_encryption` is AES-CTR, where the nonce is a counter. When the -working repo was used later for creating new archives, Borg would re-use nonce -values due to starting from a lower counter value given by the older copy of the -repository. To prevent this, the ``keep-security-info`` option is applied so -that the client-side nonce counter is kept. - Can Borg add redundancy to the backup data to deal with hardware malfunction? ----------------------------------------------------------------------------- @@ -296,7 +257,7 @@ SMR (shingled magnetic recording) hard drives are very different from regular hard drives. Applications have to behave in certain ways or performance will be heavily degraded. -Borg 1.1 ships with default settings suitable for SMR drives, +Borg ships with default settings suitable for SMR drives, and has been successfully tested on *Seagate Archive v2* drives using the ext4 file system. @@ -436,16 +397,16 @@ Say you want to prune ``/var/log`` faster than the rest of archive *names* and then implement different prune policies for different prefixes. For example, you could have a script that does:: - borg create --exclude var/log $REPOSITORY:main-$(date +%Y-%m-%d) / - borg create $REPOSITORY:logs-$(date +%Y-%m-%d) /var/log + borg create --exclude var/log main-$(date +%Y-%m-%d) / + borg create logs-$(date +%Y-%m-%d) /var/log Then you would have two different prune calls with different policies:: - borg prune --verbose --list -d 30 --prefix main- "$REPOSITORY" - borg prune --verbose --list -d 7 --prefix logs- "$REPOSITORY" + borg prune --verbose --list -d 30 --prefix main- + borg prune --verbose --list -d 7 --prefix logs- -This will keep 7 days of logs and 30 days of everything else. Borg 1.1 -also supports the ``--glob-archives`` parameter. +This will keep 7 days of logs and 30 days of everything else. +Borg also supports the ``--glob-archives`` parameter. How do I remove files from an existing backup? ---------------------------------------------- @@ -476,37 +437,6 @@ to change them. Security ######## -.. _borg_security_critique: - -Isn't BorgBackup's legacy AES-CTR-based crypto broken? ------------------------------------------------------- - -Note: in borg 1.3 new AEAD cipher based modes with session keys were added, -solving the issues of the legacy modes. - -If a nonce (counter) value is reused, AES-CTR mode crypto is broken. - -To exploit the AES counter management issue, an attacker would need to have -access to the borg repository. - -By tampering with the repo, the attacker could bring the repo into a state so -that it reports a lower "highest used counter value" than the one that actually -was used. The client would usually notice that, because it rather trusts the -clientside stored "highest used counter value" than trusting the server. - -But there are situations, where this is simply not possible: - -- If clients A and B used the repo, the client A can only know its own highest - CTR value, but not the one produced by B. That is only known to (B and) the - server (the repo) and thus the client A needs to trust the server about the - value produced by B in that situation. You can't do much about this except - not having multiple clients per repo. - -- Even if there is only one client, if client-side information is completely - lost (e.g. due to disk defect), the client also needs to trust the value from - server side. You can avoid this by not continuing to write to the repository - after you have lost clientside borg information. - .. _home_config_borg: How important is the $HOME/.config/borg directory? @@ -583,7 +513,7 @@ Using ``BORG_PASSCOMMAND`` with a properly permissioned file Using keyfile-based encryption with a blank passphrase It is possible to encrypt your repository in ``keyfile`` mode instead of the default ``repokey`` mode and use a blank passphrase for the key file (simply press Enter twice - when ``borg init`` asks for the password). See :ref:`encrypted_repos` + when ``borg rcreate`` asks for the password). See :ref:`encrypted_repos` for more details. Using ``BORG_PASSCOMMAND`` with macOS Keychain @@ -717,34 +647,6 @@ Send a private email to the :ref:`security contact ` if you think you have discovered a security issue. Please disclose security issues responsibly. -How important are the nonce files? ------------------------------------- - -This only applies to repositories using legacy encryption modes. - -Borg uses :ref:`AES-CTR encryption `. An -essential part of AES-CTR is a sequential counter that must **never** -repeat. If the same value of the counter is used twice in the same repository, -an attacker can decrypt the data. The counter is stored in the home directory -of each user ($HOME/.config/borg/security/$REPO_ID/nonce) as well as -in the repository (/path/to/repo/nonce). When creating a new archive borg uses -the highest of the two values. The value of the counter in the repository may be -higher than your local value if another user has created an archive more recently -than you did. - -Since the nonce is not necessary to read the data that is already encrypted, -``borg info``, ``borg list``, ``borg extract`` and ``borg mount`` should work -just fine without it. - -If the nonce file stored in the repo is lost, but you still have your local copy, -borg will recreate the repository nonce file the next time you run ``borg create``. -This should be safe for repositories that are only used from one user account -on one machine. - -For repositories that are used by multiple users and/or from multiple machines -it is safest to avoid running *any* commands that modify the repository after -the nonce is deleted or if you suspect it may have been tampered with. See :ref:`attack_model`. - Common issues ############# @@ -789,9 +691,9 @@ How can I deal with my very unstable SSH connection? If you have issues with lost connections during long-running borg commands, you could try to work around: -- Make partial extracts like ``borg extract REPO PATTERN`` to do multiple +- Make partial extracts like ``borg extract PATTERN`` to do multiple smaller extraction runs that complete before your connection has issues. -- Try using ``borg mount REPO MOUNTPOINT`` and ``rsync -avH`` from +- Try using ``borg mount MOUNTPOINT`` and ``rsync -avH`` from ``MOUNTPOINT`` to your desired extraction directory. If the connection breaks down, just repeat that over and over again until rsync does not find anything to do any more. Due to the way borg mount works, this might be less efficient @@ -846,7 +748,7 @@ space for chunks.archive.d (see :issue:`235` for details): :: # this assumes you are working with the same user as the backup. - cd ~/.cache/borg/$(borg config /path/to/repo id) + cd ~/.cache/borg/$(borg config id) rm -rf chunks.archive.d ; touch chunks.archive.d This deletes all the cached archive chunk indexes and replaces the directory @@ -1151,7 +1053,7 @@ To achieve this, run ``borg create`` within the mountpoint/snapshot directory: # Example: Some file system mounted in /mnt/rootfs. cd /mnt/rootfs - borg create /path/to/repo::rootfs_backup . + borg create rootfs_backup . I am having troubles with some network/FUSE/special filesystem, why? @@ -1240,7 +1142,7 @@ This can happen for CIFS- or FUSE shares. If you are sure that your target volum will always have enough disk space, you can use the following workaround to disable checking for free disk space:: - borg config -- $REPO_LOCATION additional_free_space -2T + borg config -- additional_free_space -2T How do I rename a repository? ----------------------------- @@ -1279,112 +1181,3 @@ libraries are actually loaded and used. In the borg git repository, there is scripts/glibc_check.py that can determine (based on the symbols' versions they want to link to) whether a set of given (Linux) binaries works with a given glibc version. - - -Why was Borg forked from Attic? -------------------------------- - -Borg was created in May 2015 in response to the difficulty of getting new -code or larger changes incorporated into Attic and establishing a bigger -developer community / more open development. - -More details can be found in `ticket 217 -`_ that led to the fork. - -Borg intends to be: - -* simple: - - * as simple as possible, but no simpler - * do the right thing by default, but offer options -* open: - - * welcome feature requests - * accept pull requests of good quality and coding style - * give feedback on PRs that can't be accepted "as is" - * discuss openly, don't work in the dark -* changing: - - * Borg is not compatible with Attic - * do not break compatibility accidentally, without a good reason - or without warning. allow compatibility breaking for other cases. - * if major version number changes, it may have incompatible changes - -Migrating from Attic -#################### - -What are the differences between Attic and Borg? ------------------------------------------------- - -Borg is a fork of `Attic`_ and maintained by "`The Borg collective`_". - -.. _Attic: https://github.com/jborg/attic -.. _The Borg collective: https://borgbackup.readthedocs.org/en/latest/authors.html - -Here's a (incomplete) list of some major changes: - -* lots of attic issues fixed - (see `issue #5 `_), - including critical data corruption bugs and security issues. -* more open, faster paced development - (see `issue #1 `_) -* less chunk management overhead (less memory and disk usage for chunks index) -* faster remote cache resync (useful when backing up multiple machines into same repo) -* compression: no, lz4, zstd, zlib or lzma compression, adjustable compression levels -* repokey replaces problematic passphrase mode (you can't change the passphrase - nor the pbkdf2 iteration count in "passphrase" mode) -* simple sparse file support, great for virtual machine disk files -* can read special files (e.g. block devices) or from stdin, write to stdout -* rename-based locking is more compatible than attic's posix locking -* uses fadvise to not spoil / blow up the fs cache -* better error messages / exception handling -* better logging, screen output, progress indication -* tested on misc. Linux systems, 32 and 64bit, FreeBSD, OpenBSD, NetBSD, macOS - -Please read the :ref:`changelog` (or ``docs/changes.rst`` in the source distribution) for more -information. - -Borg is not compatible with original Attic (but there is a one-way conversion). - -How do I migrate from Attic to Borg? ------------------------------------- - -Use :ref:`borg_upgrade`. This is a one-way process that cannot be reversed. - -There are some caveats: - -- The upgrade can only be performed on local repositories. - It cannot be performed on remote repositories. - -- If the repository is in "keyfile" encryption mode, the keyfile must - exist locally or it must be manually moved after performing the upgrade: - - 1. Get the repository ID with ``borg config /path/to/repo id``. - 2. Locate the attic key file at ``~/.attic/keys/``. The correct key for the - repository starts with the line ``ATTIC_KEY ``. - 3. Copy the attic key file to ``~/.config/borg/keys/`` - 4. Change the first line from ``ATTIC_KEY ...`` to ``BORG_KEY ...``. - 5. Verify that the repository is now accessible (e.g. ``borg list ``). -- Attic and Borg use different :ref:`"chunker params" `. - This means that data added by Borg won't deduplicate with the existing data - stored by Attic. The effect is lessened if the files cache is used with Borg. -- Repositories in "passphrase" mode *must* be migrated to "repokey" mode using - "borg key migrate-to-repokey" (only available in borg <= 1.2.x). Borg does not - support the "passphrase" mode in any other way. - -Why is my backup bigger than with attic? ----------------------------------------- - -Attic was rather unflexible when it comes to compression, it always -compressed using zlib level 6 (no way to switch compression off or -adjust the level or algorithm). - -The default in Borg is lz4, which is fast enough to not use significant CPU time -in most cases, but can only achieve modest compression. It still compresses -easily compressed data fairly well. - -Borg also offers zstd, zlib and lzma compression, choose wisely. - -Which choice is the best option depends on a number of factors, like -bandwidth to the repository, how well the data compresses, available CPU -power and so on. diff --git a/docs/installation.rst b/docs/installation.rst index 1ff65787..60b05e45 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -177,8 +177,8 @@ following dependencies first: * optionally, if you wish to mount an archive as a FUSE filesystem, you need a FUSE implementation for Python: - - Either pyfuse3_ (preferably, newer and maintained) or llfuse_ (older, - unmaintained now). See also the BORG_FUSE_IMPL env variable. + - Either pyfuse3_ (preferably, newer) or llfuse_ (older). + See also the BORG_FUSE_IMPL env variable. - See setup.py about the version requirements. If you have troubles finding the right package names, have a look at the diff --git a/docs/internals/data-structures.rst b/docs/internals/data-structures.rst index 8de20761..b494fde5 100644 --- a/docs/internals/data-structures.rst +++ b/docs/internals/data-structures.rst @@ -79,7 +79,7 @@ Normally the keys are computed like this:: key = id = id_hash(unencrypted_data) -The id_hash function depends on the :ref:`encryption mode `. +The id_hash function depends on the :ref:`encryption mode `. As the id / key is used for deduplication, id_hash must be a cryptographically strong hash or MAC. @@ -736,7 +736,6 @@ The chunks cache is a key -> value mapping and contains: - reference count - size - - encrypted/compressed size The chunks cache is a HashIndex_. Due to some restrictions of HashIndex, the reference count of each given chunk is limited to a constant, MAX_VALUE @@ -754,9 +753,9 @@ Here is the estimated memory usage of Borg - it's complicated:: chunk_size ~= 2 ^ HASH_MASK_BITS (for buzhash chunker, BLOCK_SIZE for fixed chunker) chunk_count ~= total_file_size / chunk_size - repo_index_usage = chunk_count * 40 + repo_index_usage = chunk_count * 48 - chunks_cache_usage = chunk_count * 44 + chunks_cache_usage = chunk_count * 40 files_cache_usage = total_file_count * 240 + chunk_count * 80 diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst index d0ebed48..7ef96c78 100644 --- a/docs/internals/frontends.rst +++ b/docs/internals/frontends.rst @@ -208,7 +208,7 @@ Passphrase prompts should be handled differently. Use the environment variables and *BORG_NEW_PASSPHRASE* (see :ref:`env_vars` for reference) to pass passphrases to Borg, don't use the interactive passphrase prompts. -When setting a new passphrase (:ref:`borg_init`, :ref:`borg_key_change-passphrase`) normally +When setting a new passphrase (:ref:`borg_rcreate`, :ref:`borg_key_change-passphrase`) normally Borg prompts whether it should display the passphrase. This can be suppressed by setting the environment variable *BORG_DISPLAY_PASSPHRASE* to *no*. @@ -252,7 +252,7 @@ last_modified The *encryption* key, if present, contains: mode - Textual encryption mode name (same as :ref:`borg_init` ``--encryption`` names) + Textual encryption mode name (same as :ref:`borg_rcreate` ``--encryption`` names) keyfile Path to the local key file used for access. Depending on *mode* this key may be absent. diff --git a/docs/internals/security.rst b/docs/internals/security.rst index 69f22a80..b7b247d0 100644 --- a/docs/internals/security.rst +++ b/docs/internals/security.rst @@ -38,9 +38,6 @@ Under these circumstances Borg guarantees that the attacker cannot The attacker can always impose a denial of service per definition (he could forbid connections to the repository, or delete it entirely). -When the above attack model is extended to include multiple clients -independently updating the same repository, then Borg fails to provide -confidentiality (i.e. guarantees 3) and 4) do not apply any more). .. _security_structural_auth: @@ -78,7 +75,7 @@ the root node of a DAG through its edges, since the root node has no incoming ed With the scheme as described so far an attacker could easily replace the manifest, therefore Borg includes a tertiary authentication mechanism (TAM) that is applied -to the manifest since version 1.0.9 (see :ref:`tam_vuln`). +to the manifest (see :ref:`tam_vuln`). TAM works by deriving a separate key through HKDF_ from the other encryption and authentication keys and calculating the HMAC of the metadata to authenticate [#]_:: @@ -129,12 +126,12 @@ AEAD modes Modes: --encryption (repokey|keyfile)-[blake2-](aes-ocb|chacha20-poly1305) -Supported: borg 1.3+ +Supported: borg 2.0+ Encryption with these modes is based on AEAD ciphers (authenticated encryption with associated data) and session keys. -Depending on the chosen mode (see :ref:`borg_init`) different AEAD ciphers are used: +Depending on the chosen mode (see :ref:`borg_rcreate`) different AEAD ciphers are used: - AES-256-OCB - super fast, single-pass algorithm IF you have hw accelerated AES. - chacha20-poly1305 - very fast, purely software based AEAD cipher. @@ -201,106 +198,13 @@ Legacy modes Modes: --encryption (repokey|keyfile)-[blake2] -Supported: all borg versions, blake2 since 1.1 +Supported: borg < 2.0 -DEPRECATED. We strongly suggest you use the safer AEAD modes, see above. +These were the AES-CTR based modes in previous borg versions. -Encryption with these modes is based on the Encrypt-then-MAC construction, -which is generally seen as the most robust way to create an authenticated -encryption scheme from encryption and message authentication primitives. +borg 2.0 does not support creating new repos using these modes, +but ``borg transfer`` can still read such existing repos. -Every operation (encryption, MAC / authentication, chunk ID derivation) -uses independent, random keys generated by `os.urandom`_. - -Borg does not support unauthenticated encryption -- only authenticated encryption -schemes are supported. No unauthenticated encryption schemes will be added -in the future. - -Depending on the chosen mode (see :ref:`borg_init`) different primitives are used: - -- Legacy encryption modes use AES-256 in CTR mode. The - counter is added in plaintext, since it is needed for decryption, - and is also tracked locally on the client to avoid counter reuse. - -- The authentication primitive is either HMAC-SHA-256 or BLAKE2b-256 - in a keyed mode. - - Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis - and have proven secure against known attacks. The known vulnerability - of SHA-256 against length extension attacks does not apply to HMAC-SHA-256. - - The authentication primitive should be chosen based upon SHA hardware support. - With SHA hardware support, hmac-sha256 is likely to be much faster. - If no hardware support is provided, Blake2b-256 will outperform hmac-sha256. - To find out if you have SHA hardware support, use:: - - $ borg benchmark cpu - - The output will include an evaluation of cryptographic hashes/MACs like:: - - Cryptographic hashes / MACs ==================================== - hmac-sha256 1GB 0.436s - blake2b-256 1GB 1.579s - - Based upon your output, choose the primitive that is faster (in the above - example, hmac-sha256 is much faster, which indicates SHA hardware support). - -- The primitive used for authentication is always the same primitive - that is used for deriving the chunk ID, but they are always - used with independent keys. - -Encryption:: - - id = AUTHENTICATOR(id_key, data) - compressed = compress(data) - - iv = reserve_iv() - encrypted = AES-256-CTR(enc_key, 8-null-bytes || iv, compressed) - authenticated = type-byte || AUTHENTICATOR(enc_hmac_key, encrypted) || iv || encrypted - - -Decryption:: - - # Given: input *authenticated* data, possibly a *chunk-id* to assert - type-byte, mac, iv, encrypted = SPLIT(authenticated) - - ASSERT(type-byte is correct) - ASSERT( CONSTANT-TIME-COMPARISON( mac, AUTHENTICATOR(enc_hmac_key, encrypted) ) ) - - decrypted = AES-256-CTR(enc_key, 8-null-bytes || iv, encrypted) - decompressed = decompress(decrypted) - - ASSERT( CONSTANT-TIME-COMPARISON( chunk-id, AUTHENTICATOR(id_key, decompressed) ) ) - -The client needs to track which counter values have been used, since -encrypting a chunk requires a starting counter value and no two chunks -may have overlapping counter ranges (otherwise the bitwise XOR of the -overlapping plaintexts is revealed). - -The client does not directly track the counter value, because it -changes often (with each encrypted chunk), instead it commits a -"reservation" to the security database and the repository by taking -the current counter value and adding 4 GiB / 16 bytes (the block size) -to the counter. Thus the client only needs to commit a new reservation -every few gigabytes of encrypted data. - -This mechanism also avoids reusing counter values in case the client -crashes or the connection to the repository is severed, since any -reservation would have been committed to both the security database -and the repository before any data is encrypted. Borg uses its -standard mechanism (SaveFile) to ensure that reservations are durable -(on most hardware / storage systems), therefore a crash of the -client's host would not impact tracking of reservations. - -However, this design is not infallible, and requires synchronization -between clients, which is handled through the repository. Therefore in -a multiple-client scenario a repository can trick a client into -reusing counter values by ignoring counter reservations and replaying -the manifest (which will fail if the client has seen a more recent -manifest or has a more recent nonce reservation). If the repository is -untrusted, but a trusted synchronization channel exists between -clients, the security database could be synchronized between them over -said trusted channel. This is not part of Borg's functionality. .. _key_encryption: @@ -468,13 +372,12 @@ Compression and Encryption Combining encryption with compression can be insecure in some contexts (e.g. online protocols). -There was some discussion about this in `github issue #1040`_ and for Borg some developers +There was some discussion about this in :issue:`1040` and for Borg some developers concluded this is no problem at all, some concluded this is hard and extremely slow to exploit and thus no problem in practice. No matter what, there is always the option not to use compression if you are worried about this. -.. _github issue #1040: https://github.com/borgbackup/borg/issues/1040 Fingerprinting ============== @@ -490,7 +393,7 @@ output of the chunker. The sizes of these stored chunks are influenced by the compression, encryption and authentication. buzhash chunker -+++++++++++++++ +~~~~~~~~~~~~~~~ The buzhash chunker chunks according to the input data, the chunker's parameters and the secret chunker seed (which all influence the chunk boundary @@ -501,7 +404,7 @@ chunk (identical content / size as the original file), bigger files result in multiple chunks. fixed chunker -+++++++++++++ +~~~~~~~~~~~~~ This chunker yields fixed sized chunks, with optional support of a differently sized header chunk. The last chunk is not required to have the full block size diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1 index e6c51936..9c3f4e0d 100644 --- a/docs/man/borg-benchmark-cpu.1 +++ b/docs/man/borg-benchmark-cpu.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK-CPU 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-benchmark-cpu \- Benchmark CPU bound operations. . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-BENCHMARK-CPU" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-benchmark-cpu \- Benchmark CPU bound operations. .SH SYNOPSIS .sp borg [common options] benchmark cpu [options] @@ -39,8 +39,12 @@ This command benchmarks misc. CPU bound borg operations. .sp It creates input data in memory, runs the operation and then displays throughput. To reduce outside influence on the timings, please make sure to run this with: -\- an otherwise as idle as possible machine -\- enough free memory so there will be no slow down due to paging activity +.INDENT 0.0 +.IP \(bu 2 +an otherwise as idle as possible machine +.IP \(bu 2 +enough free memory so there will be no slow down due to paging activity +.UNINDENT .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index efa4df55..89cd546e 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK-CRUD 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-BENCHMARK-CRUD" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS .sp -borg [common options] benchmark crud [options] REPOSITORY PATH +borg [common options] benchmark crud [options] PATH .SH DESCRIPTION .sp This command benchmarks borg CRUD (create, read, update, delete) operations. @@ -88,9 +88,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B REPOSITORY -repository to use for benchmark (must exist) -.TP .B PATH path were to create benchmark input data .UNINDENT diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index 0cd5e90c..c832a792 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-benchmark \- benchmark command . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-BENCHMARK" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-benchmark \- benchmark command .SH SYNOPSIS .nf borg [common options] benchmark crud ... diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index bd01367c..81c29060 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BREAK-LOCK 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-BREAK-LOCK" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. .SH SYNOPSIS .sp -borg [common options] break\-lock [options] [REPOSITORY] +borg [common options] break\-lock [options] .SH DESCRIPTION .sp This command breaks the repository and cache locks. @@ -41,12 +41,6 @@ trying to access the Cache or the Repository. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. -.SS arguments -.INDENT 0.0 -.TP -.B REPOSITORY -repository for which to break the locks -.UNINDENT .SH SEE ALSO .sp \fIborg\-common(1)\fP diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 0dfbc27b..9ec8e69f 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHECK 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-check \- Check repository consistency . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-CHECK" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-check \- Check repository consistency .SH SYNOPSIS .sp -borg [common options] check [options] [REPOSITORY_OR_ARCHIVE] +borg [common options] check [options] .SH DESCRIPTION .sp The check command verifies the consistency of a repository and the corresponding archives. @@ -126,28 +126,25 @@ slow. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. -.SS arguments -.INDENT 0.0 -.TP -.B REPOSITORY_OR_ARCHIVE -repository or archive to check consistency of -.UNINDENT .SS optional arguments .INDENT 0.0 .TP -.B \-\-repository\-only +.BI \-\-name \ NAME +specify the archive name +.TP +.B \-\-repository\-only only perform repository checks .TP -.B \-\-archives\-only +.B \-\-archives\-only only perform archives checks .TP -.B \-\-verify\-data +.B \-\-verify\-data perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP) .TP -.B \-\-repair +.B \-\-repair attempt to repair any inconsistencies found .TP -.B \-\-save\-space +.B \-\-save\-space work slower, but using less space .TP .BI \-\-max\-duration \ SECONDS diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 85b46e70..5e960b71 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMMON 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-common \- Common options of Borg commands . .nr rst2man-indent-level 0 . @@ -30,49 +27,52 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-COMMON" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-common \- Common options of Borg commands .SH SYNOPSIS .INDENT 0.0 .TP -.B \-h\fP,\fB \-\-help +.B \-h\fP,\fB \-\-help show this help message and exit .TP -.B \-\-critical +.B \-\-critical work on log level CRITICAL .TP -.B \-\-error +.B \-\-error work on log level ERROR .TP -.B \-\-warning +.B \-\-warning work on log level WARNING (default) .TP -.B \-\-info\fP,\fB \-v\fP,\fB \-\-verbose +.B \-\-info\fP,\fB \-v\fP,\fB \-\-verbose work on log level INFO .TP -.B \-\-debug +.B \-\-debug enable debug output, work on log level DEBUG .TP .BI \-\-debug\-topic \ TOPIC enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug. if TOPIC is not fully qualified. .TP -.B \-p\fP,\fB \-\-progress +.B \-p\fP,\fB \-\-progress show progress information .TP -.B \-\-iec +.B \-\-iec format using IEC units (1KiB = 1024B) .TP -.B \-\-log\-json +.B \-\-log\-json Output one JSON object per log line instead of formatted text. .TP .BI \-\-lock\-wait \ SECONDS wait at most SECONDS for acquiring a repository/cache lock (default: 1). .TP -.B \-\-bypass\-lock +.B \-\-bypass\-lock Bypass locking mechanism .TP -.B \-\-show\-version +.B \-\-show\-version show/log the borg version .TP -.B \-\-show\-rc +.B \-\-show\-rc show/log the return code (rc) .TP .BI \-\-umask \ M @@ -93,7 +93,7 @@ deprecated, use \fB\-\-upload\-buffer\fP instead .BI \-\-upload\-buffer \ UPLOAD_BUFFER set network upload buffer size in MiB. (default: 0=no buffer) .TP -.B \-\-consider\-part\-files +.B \-\-consider\-part\-files treat part files like normal files (e.g. to list/extract them) .TP .BI \-\-debug\-profile \ FILE @@ -101,6 +101,9 @@ Write execution profile in Borg format into FILE. For local use a Python\-compat .TP .BI \-\-rsh \ RSH Use this command to connect to the \(aqborg serve\(aq process (default: \(aqssh\(aq) +.TP +.BI \-r \ REPO\fR,\fB \ \-\-repo \ REPO +repository to use .UNINDENT .SH SEE ALSO .sp diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 79f8fc4e..18d79ee7 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPACT 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-compact \- compact segment files in the repository . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-COMPACT" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-compact \- compact segment files in the repository .SH SYNOPSIS .sp -borg [common options] compact [options] [REPOSITORY] +borg [common options] compact [options] .SH DESCRIPTION .sp This command frees repository space by compacting segments. @@ -60,16 +60,10 @@ See \fIseparate_compaction\fP in Additional Notes for more details. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. -.SS arguments -.INDENT 0.0 -.TP -.B REPOSITORY -repository to compact -.UNINDENT .SS optional arguments .INDENT 0.0 .TP -.B \-\-cleanup\-commits +.B \-\-cleanup\-commits cleanup commit\-only 17\-byte segment files .TP .BI \-\-threshold \ PERCENT @@ -82,10 +76,7 @@ set minimum threshold for saved space in PERCENT (Default: 10) .nf .ft C # compact segments and free repo disk space -$ borg compact /path/to/repo - -# same as above plus clean up 17byte commit\-only segments -$ borg compact \-\-cleanup\-commits /path/to/repo +$ borg compact .ft P .fi .UNINDENT diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index a55a7dba..ff348a7e 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPRESSION 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-compression \- Details regarding compression . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-COMPRESSION" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-compression \- Details regarding compression .SH DESCRIPTION .sp It is no problem to mix different compression methods in one repo, diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index 26ccffdd..35cc426d 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CONFIG 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-config \- get, set, and delete values in a repository or cache config file . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-CONFIG" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-config \- get, set, and delete values in a repository or cache config file .SH SYNOPSIS .sp -borg [common options] config [options] [REPOSITORY] [NAME] [VALUE] +borg [common options] config [options] [NAME] [VALUE] .SH DESCRIPTION .sp This command gets and sets options in a local repository or cache config file. @@ -53,9 +53,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B REPOSITORY -repository to configure -.TP .B NAME name of config key .TP @@ -65,13 +62,13 @@ new value for key .SS optional arguments .INDENT 0.0 .TP -.B \-c\fP,\fB \-\-cache +.B \-c\fP,\fB \-\-cache get and set values from the repo cache .TP -.B \-d\fP,\fB \-\-delete +.B \-d\fP,\fB \-\-delete delete the key from the config file .TP -.B \-l\fP,\fB \-\-list +.B \-l\fP,\fB \-\-list list the configuration of the repo .UNINDENT .SH EXAMPLES @@ -90,13 +87,13 @@ making changes! .nf .ft C # find cache directory -$ cd ~/.cache/borg/$(borg config /path/to/repo id) +$ cd ~/.cache/borg/$(borg config id) # reserve some space -$ borg config /path/to/repo additional_free_space 2G +$ borg config additional_free_space 2G # make a repo append\-only -$ borg config /path/to/repo append_only 1 +$ borg config append_only 1 .ft P .fi .UNINDENT diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 88781462..7d36f094 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CREATE 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-create \- Create new archive . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-CREATE" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-create \- Create new archive .SH SYNOPSIS .sp -borg [common options] create [options] ARCHIVE [PATH...] +borg [common options] create [options] NAME [PATH...] .SH DESCRIPTION .sp This command creates a backup archive containing all files found while recursively @@ -126,8 +126,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B ARCHIVE -name of archive to create (must be also a valid directory name) +.B NAME +specify the archive name .TP .B PATH paths to archive @@ -135,22 +135,22 @@ paths to archive .SS optional arguments .INDENT 0.0 .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not create a backup archive .TP -.B \-s\fP,\fB \-\-stats +.B \-s\fP,\fB \-\-stats print statistics for the created archive .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .TP .BI \-\-filter \ STATUSCHARS only display items with the given status characters (see description) .TP -.B \-\-json +.B \-\-json output stats as JSON. Implies \fB\-\-stats\fP\&. .TP -.B \-\-no\-cache\-sync +.B \-\-no\-cache\-sync experimental: do not synchronize the cache. Implies not using the files cache. .TP .BI \-\-stdin\-name \ NAME @@ -160,18 +160,18 @@ use NAME in archive for stdin data (default: \(aqstdin\(aq) set user USER in archive for stdin data (default: \(aqroot\(aq) .TP .BI \-\-stdin\-group \ GROUP -set group GROUP in archive for stdin data (default: \(aqroot\(aq) +set group GROUP in archive for stdin data (default: \(aqwheel\(aq) .TP .BI \-\-stdin\-mode \ M set mode to M in archive for stdin data (default: 0660) .TP -.B \-\-content\-from\-command +.B \-\-content\-from\-command interpret PATH as command and store its stdout. See also section Reading from stdin below. .TP -.B \-\-paths\-from\-stdin +.B \-\-paths\-from\-stdin read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories. .TP -.B \-\-paths\-from\-command +.B \-\-paths\-from\-command interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP .TP .BI \-\-paths\-delimiter \ DELIM @@ -192,61 +192,61 @@ include/exclude paths matching PATTERN .BI \-\-patterns\-from \ PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line .TP -.B \-\-exclude\-caches +.B \-\-exclude\-caches exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP) .TP .BI \-\-exclude\-if\-present \ NAME exclude directories that are tagged by containing a filesystem object with the given NAME .TP -.B \-\-keep\-exclude\-tags +.B \-\-keep\-exclude\-tags if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive .TP -.B \-\-exclude\-nodump +.B \-\-exclude\-nodump exclude files flagged NODUMP .UNINDENT .SS Filesystem options .INDENT 0.0 .TP -.B \-x\fP,\fB \-\-one\-file\-system +.B \-x\fP,\fB \-\-one\-file\-system stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. .TP -.B \-\-numeric\-owner +.B \-\-numeric\-owner deprecated, use \fB\-\-numeric\-ids\fP instead .TP -.B \-\-numeric\-ids +.B \-\-numeric\-ids only store numeric user and group identifiers .TP -.B \-\-noatime +.B \-\-noatime do not store atime into archive .TP -.B \-\-atime +.B \-\-atime do store atime into archive .TP -.B \-\-noctime +.B \-\-noctime do not store ctime into archive .TP -.B \-\-nobirthtime +.B \-\-nobirthtime do not store birthtime (creation date) into archive .TP -.B \-\-nobsdflags +.B \-\-nobsdflags deprecated, use \fB\-\-noflags\fP instead .TP -.B \-\-noflags +.B \-\-noflags do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive .TP -.B \-\-noacls +.B \-\-noacls do not read and store ACLs into archive .TP -.B \-\-noxattrs +.B \-\-noxattrs do not read and store xattrs into archive .TP -.B \-\-sparse +.B \-\-sparse detect sparse holes in input (supported only by fixed chunker) .TP .BI \-\-files\-cache \ MODE operate files cache in MODE. default: ctime,size,inode .TP -.B \-\-read\-special +.B \-\-read\-special open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. .UNINDENT .SS Archive options @@ -274,86 +274,84 @@ select compression algorithm, see the output of the "borg help compression" comm .nf .ft C # Backup ~/Documents into an archive named "my\-documents" -$ borg create /path/to/repo::my\-documents ~/Documents +$ borg create my\-documents ~/Documents # same, but list all files as we process them -$ borg create \-\-list /path/to/repo::my\-documents ~/Documents +$ borg create \-\-list my\-documents ~/Documents # Backup ~/Documents and ~/src but exclude pyc files -$ borg create /path/to/repo::my\-files \e +$ borg create my\-files \e ~/Documents \e ~/src \e \-\-exclude \(aq*.pyc\(aq # Backup home directories excluding image thumbnails (i.e. only # /home//.thumbnails is excluded, not /home/*/*/.thumbnails etc.) -$ borg create /path/to/repo::my\-files /home \e - \-\-exclude \(aqsh:/home/*/.thumbnails\(aq +$ borg create my\-files /home \-\-exclude \(aqsh:home/*/.thumbnails\(aq # Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD" # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio) -$ borg create \-C zlib,6 \-\-one\-file\-system /path/to/repo::root\-{now:%Y\-%m\-%d} / +$ borg create \-C zlib,6 \-\-one\-file\-system root\-{now:%Y\-%m\-%d} / -# Backup onto a remote host ("push" style) via ssh to port 2222, -# logging in as user "borg" and storing into /path/to/repo -$ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}\-root\-{now} / +# Backup into an archive name like FQDN\-root\-TIMESTAMP +$ borg create \(aq{fqdn}\-root\-{now}\(aq / # Backup a remote host locally ("pull" style) using sshfs $ mkdir sshfs\-mount $ sshfs root@example.com:/ sshfs\-mount $ cd sshfs\-mount -$ borg create /path/to/repo::example.com\-root\-{now:%Y\-%m\-%d} . +$ borg create example.com\-root\-{now:%Y\-%m\-%d} . $ cd .. $ fusermount \-u sshfs\-mount # Make a big effort in fine granular deduplication (big chunk management # overhead, needs a lot of RAM and disk space, see formula in internals # docs \- same parameters as borg < 1.0 or attic): -$ borg create \-\-chunker\-params buzhash,10,23,16,4095 /path/to/repo::small /smallstuff +$ borg create \-\-chunker\-params buzhash,10,23,16,4095 small /smallstuff # Backup a raw device (must not be active/in use/mounted at that time) -$ borg create \-\-read\-special \-\-chunker\-params fixed,4194304 /path/to/repo::my\-sdx /dev/sdX +$ borg create \-\-read\-special \-\-chunker\-params fixed,4194304 my\-sdx /dev/sdX # Backup a sparse disk image (must not be active/in use/mounted at that time) -$ borg create \-\-sparse \-\-chunker\-params fixed,4194304 /path/to/repo::my\-disk my\-disk.raw +$ borg create \-\-sparse \-\-chunker\-params fixed,4194304 my\-disk my\-disk.raw # No compression (none) -$ borg create \-\-compression none /path/to/repo::arch ~ +$ borg create \-\-compression none arch ~ # Super fast, low compression (lz4, default) -$ borg create /path/to/repo::arch ~ +$ borg create arch ~ # Less fast, higher compression (zlib, N = 0..9) -$ borg create \-\-compression zlib,N /path/to/repo::arch ~ +$ borg create \-\-compression zlib,N arch ~ # Even slower, even higher compression (lzma, N = 0..9) -$ borg create \-\-compression lzma,N /path/to/repo::arch ~ +$ borg create \-\-compression lzma,N arch ~ # Only compress compressible data with lzma,N (N = 0..9) -$ borg create \-\-compression auto,lzma,N /path/to/repo::arch ~ +$ borg create \-\-compression auto,lzma,N arch ~ # Use short hostname, user name and current time in archive name -$ borg create /path/to/repo::{hostname}\-{user}\-{now} ~ +$ borg create \(aq{hostname}\-{user}\-{now}\(aq ~ # Similar, use the same datetime format that is default as of borg 1.1 -$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S} ~ +$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S}\(aq ~ # As above, but add nanoseconds -$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~ +$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f}\(aq ~ # Backing up relative paths by moving into the correct directory first $ cd /home/user/Documents # The root directory of the archive will be "projectA" -$ borg create /path/to/repo::daily\-projectA\-{now:%Y\-%m\-%d} projectA +$ borg create \(aqdaily\-projectA\-{now:%Y\-%m\-%d}\(aq projectA # Use external command to determine files to archive # Use \-\-paths\-from\-stdin with find to only backup files less than 1MB in size -$ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin /path/to/repo::small\-files\-only +$ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin small\-files\-only # Use \-\-paths\-from\-command with find to only backup files from a given user -$ borg create \-\-paths\-from\-command /path/to/repo::joes\-files \-\- find /srv/samba/shared \-user joe +$ borg create \-\-paths\-from\-command joes\-files \-\- find /srv/samba/shared \-user joe # Use \-\-paths\-from\-stdin with \-\-paths\-delimiter (for example, for filenames with newlines in them) $ find ~ \-size \-1000k \-print0 | borg create \e \-\-paths\-from\-stdin \e \-\-paths\-delimiter "\e0" \e - /path/to/repo::smallfiles\-handle\-newline + smallfiles\-handle\-newline .ft P .fi .UNINDENT diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 68639c1e..7a213de1 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DELETE 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-delete \- Delete an existing repository or archives . .nr rst2man-indent-level 0 . @@ -30,21 +27,19 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-DELETE" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-delete \- Delete archives .SH SYNOPSIS .sp -borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...] +borg [common options] delete [options] .SH DESCRIPTION .sp -This command deletes an archive from the repository or the complete repository. +This command deletes archives from the repository. .sp Important: When deleting archives, repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&. .sp -When you delete a complete repository, the security info and local cache for it -(if any) are also deleted. Alternatively, you can delete just the local cache -with the \fB\-\-cache\-only\fP option, or keep the security info with the -\fB\-\-keep\-security\-info\fP option. -.sp When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be deleted. .sp When using \fB\-\-stats\fP, you will get some statistics about how much data was @@ -58,43 +53,35 @@ pattern to match multiple archives using the \fB\-\-glob\-archives GLOB\fP optio (for more info on these patterns, see \fIborg_patterns\fP). Note that these two options are mutually exclusive. .sp -To avoid accidentally deleting archives, especially when using glob patterns, -it might be helpful to use the \fB\-\-dry\-run\fP to test out the command without -actually making any changes to the repository. +Always first use \fB\-\-dry\-run \-\-list\fP to see what would be deleted. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. -.SS arguments -.INDENT 0.0 -.TP -.B REPOSITORY_OR_ARCHIVE -repository or archive to delete -.TP -.B ARCHIVE -archives to delete -.UNINDENT .SS optional arguments .INDENT 0.0 .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not change repository .TP -.B \-\-list +.B \-\-list output verbose list of archives .TP -.B \-s\fP,\fB \-\-stats +.B \-\-consider\-checkpoints +consider checkpoint archives for deletion (default: not considered). +.TP +.B \-s\fP,\fB \-\-stats print statistics for the deleted archive .TP -.B \-\-cache\-only +.B \-\-cache\-only delete only the local cache for the given repository .TP -.B \-\-force +.B \-\-force force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work. .TP -.B \-\-keep\-security\-info +.B \-\-keep\-security\-info keep the local security info when deleting a repository .TP -.B \-\-save\-space +.B \-\-save\-space work slower, but using less space .UNINDENT .SS Archive filters @@ -122,26 +109,18 @@ consider last N archives after other filters were applied .nf .ft C # delete a single backup archive: -$ borg delete /path/to/repo::Monday +$ borg delete Monday # actually free disk space: -$ borg compact /path/to/repo +$ borg compact # delete all archives whose names begin with the machine\(aqs hostname followed by "\-" -$ borg delete \-\-prefix \(aq{hostname}\-\(aq /path/to/repo +$ borg delete \-\-prefix \(aq{hostname}\-\(aq # delete all archives whose names contain "\-2012\-" -$ borg delete \-\-glob\-archives \(aq*\-2012\-*\(aq /path/to/repo +$ borg delete \-a \(aq*\-2012\-*\(aq # see what would be deleted if delete was run without \-\-dry\-run -$ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq /path/to/repo - -# delete the whole repository and the related local cache: -$ borg delete /path/to/repo -You requested to completely DELETE the repository *including* all archives it contains: -repo Mon, 2016\-02\-15 19:26:54 -root\-2016\-02\-15 Mon, 2016\-02\-15 19:36:29 -newname Mon, 2016\-02\-15 19:50:19 -Type \(aqYES\(aq if you understand this and want to continue: YES +$ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq .ft P .fi .UNINDENT diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index 2ccf05e0..27b026d2 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DIFF 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-diff \- Diff contents of two archives . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-DIFF" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-diff \- Diff contents of two archives .SH SYNOPSIS .sp -borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...] +borg [common options] diff [options] ARCHIVE1 ARCHIVE2 [PATH...] .SH DESCRIPTION .sp This command finds differences (file contents, user/group/mode) between archives. @@ -57,11 +57,11 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B REPO::ARCHIVE1 -repository location and ARCHIVE1 name +.B ARCHIVE1 +ARCHIVE1 name .TP .B ARCHIVE2 -ARCHIVE2 name (no repository location allowed) +ARCHIVE2 name .TP .B PATH paths of items inside the archives to compare; patterns are supported @@ -69,19 +69,19 @@ paths of items inside the archives to compare; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-numeric\-owner +.B \-\-numeric\-owner deprecated, use \fB\-\-numeric\-ids\fP instead .TP -.B \-\-numeric\-ids +.B \-\-numeric\-ids only consider numeric user and group identifiers .TP -.B \-\-same\-chunker\-params +.B \-\-same\-chunker\-params Override check of chunker parameters. .TP -.B \-\-sort +.B \-\-sort Sort the output lines by file path. .TP -.B \-\-json\-lines +.B \-\-json\-lines Format output as JSON Lines. .UNINDENT .SS Exclusion options @@ -105,44 +105,17 @@ read include/exclude patterns from PATTERNFILE, one per line .sp .nf .ft C -$ borg init \-e=none testrepo -$ mkdir testdir -$ cd testdir -$ echo asdf > file1 -$ dd if=/dev/urandom bs=1M count=4 > file2 -$ touch file3 -$ borg create ../testrepo::archive1 . - -$ chmod a+x file1 -$ echo "something" >> file2 -$ borg create ../testrepo::archive2 . - -$ echo "testing 123" >> file1 -$ rm file3 -$ touch file4 -$ borg create ../testrepo::archive3 . - -$ cd .. -$ borg diff testrepo::archive1 archive2 -[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1 - +135 B \-252 B file2 - -$ borg diff testrepo::archive2 archive3 - +17 B \-5 B file1 -added 0 B file4 -removed 0 B file3 - -$ borg diff testrepo::archive1 archive3 +$ borg diff archive1 archive2 +17 B \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1 +135 B \-252 B file2 added 0 B file4 removed 0 B file3 -$ borg diff \-\-json\-lines testrepo::archive1 archive3 +$ borg diff archive1 archive2 {"path": "file1", "changes": [{"type": "modified", "added": 17, "removed": 5}, {"type": "mode", "old_mode": "\-rw\-r\-\-r\-\-", "new_mode": "\-rwxr\-xr\-x"}]} {"path": "file2", "changes": [{"type": "modified", "added": 135, "removed": 252}]} {"path": "file4", "changes": [{"type": "added", "size": 0}]} -{"path": "file3", "changes": [{"type": "removed", "size": 0}] +{"path": "file3", "changes": [{"type": "removed", "size": 0}]} .ft P .fi .UNINDENT diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 437aad53..93900a55 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXPORT-TAR 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-export-tar \- Export archive contents as a tarball . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-EXPORT-TAR" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS .sp -borg [common options] export\-tar [options] ARCHIVE FILE [PATH...] +borg [common options] export\-tar [options] NAME FILE [PATH...] .SH DESCRIPTION .sp This command creates a tarball from an archive. @@ -115,8 +115,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B ARCHIVE -archive to export +.B NAME +specify the archive name .TP .B FILE output tar file. "\-" to write to stdout instead. @@ -127,10 +127,10 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-tar\-filter +.B \-\-tar\-filter filter program to pipe data through .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .TP .BI \-\-tar\-format \ FMT diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 69d2a0e4..a5e70b1f 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXTRACT 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-extract \- Extract archive contents . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-EXTRACT" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-extract \- Extract archive contents .SH SYNOPSIS .sp -borg [common options] extract [options] ARCHIVE [PATH...] +borg [common options] extract [options] NAME [PATH...] .SH DESCRIPTION .sp This command extracts the contents of an archive. By default the entire @@ -66,8 +66,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B ARCHIVE -archive to extract +.B NAME +specify the archive name .TP .B PATH paths to extract; patterns are supported @@ -75,34 +75,34 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not actually change any files .TP -.B \-\-numeric\-owner +.B \-\-numeric\-owner deprecated, use \fB\-\-numeric\-ids\fP instead .TP -.B \-\-numeric\-ids +.B \-\-numeric\-ids only obey numeric user and group identifiers .TP -.B \-\-nobsdflags +.B \-\-nobsdflags deprecated, use \fB\-\-noflags\fP instead .TP -.B \-\-noflags +.B \-\-noflags do not extract/set flags (e.g. NODUMP, IMMUTABLE) .TP -.B \-\-noacls +.B \-\-noacls do not extract/set ACLs .TP -.B \-\-noxattrs +.B \-\-noxattrs do not extract/set xattrs .TP -.B \-\-stdout +.B \-\-stdout write all extracted data to stdout .TP -.B \-\-sparse +.B \-\-sparse create holes in output sparse file from all\-zero chunks .UNINDENT .SS Exclusion options @@ -130,22 +130,22 @@ Remove the specified number of leading path elements. Paths with fewer elements .nf .ft C # Extract entire archive -$ borg extract /path/to/repo::my\-files +$ borg extract my\-files # Extract entire archive and list files while processing -$ borg extract \-\-list /path/to/repo::my\-files +$ borg extract \-\-list my\-files # Verify whether an archive could be successfully extracted, but do not write files to disk -$ borg extract \-\-dry\-run /path/to/repo::my\-files +$ borg extract \-\-dry\-run my\-files # Extract the "src" directory -$ borg extract /path/to/repo::my\-files home/USERNAME/src +$ borg extract my\-files home/USERNAME/src # Extract the "src" directory but exclude object files -$ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq +$ borg extract my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq # Restore a raw device (must not be active/in use/mounted at that time) -$ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M +$ borg extract \-\-stdout my\-sdx | dd of=/dev/sdx bs=10M .ft P .fi .UNINDENT diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index dc843977..9af05ce3 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-IMPORT-TAR 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-import-tar \- Create a backup archive from a tarball . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-IMPORT-TAR" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS .sp -borg [common options] import\-tar [options] ARCHIVE TARFILE +borg [common options] import\-tar [options] NAME TARFILE .SH DESCRIPTION .sp This command creates a backup archive from a tarball. @@ -86,8 +86,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B ARCHIVE -name of archive to create (must be also a valid directory name) +.B NAME +specify the archive name .TP .B TARFILE input tar file. "\-" to read from stdin instead. @@ -95,19 +95,19 @@ input tar file. "\-" to read from stdin instead. .SS optional arguments .INDENT 0.0 .TP -.B \-\-tar\-filter +.B \-\-tar\-filter filter program to pipe data through .TP -.B \-s\fP,\fB \-\-stats +.B \-s\fP,\fB \-\-stats print statistics for the created archive .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .TP .BI \-\-filter \ STATUSCHARS only display items with the given status characters .TP -.B \-\-json +.B \-\-json output stats as JSON (implies \-\-stats) .UNINDENT .SS Archive options @@ -135,25 +135,25 @@ select compression algorithm, see the output of the "borg help compression" comm .nf .ft C # export as uncompressed tar -$ borg export\-tar /path/to/repo::Monday Monday.tar +$ borg export\-tar Monday Monday.tar # import an uncompressed tar -$ borg import\-tar /path/to/repo::Monday Monday.tar +$ borg import\-tar Monday Monday.tar # exclude some file types, compress using gzip -$ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq +$ borg export\-tar Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq # use higher compression level with gzip -$ borg export\-tar \-\-tar\-filter="gzip \-9" repo::Monday Monday.tar.gz +$ borg export\-tar \-\-tar\-filter="gzip \-9" Monday Monday.tar.gz # copy an archive from repoA to repoB -$ borg export\-tar \-\-tar\-format=BORG repoA::archive \- | borg import\-tar repoB::archive \- +$ borg \-r repoA export\-tar \-\-tar\-format=BORG archive \- | borg \-r repoB import\-tar archive \- # export a tar, but instead of storing it on disk, upload it to remote site using curl -$ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST +$ borg export\-tar Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST # remote extraction via "tarpipe" -$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x" +$ borg export\-tar Monday \- | ssh somewhere "cd extracted; tar x" .ft P .fi .UNINDENT @@ -166,9 +166,9 @@ Outputs a script that copies all archives from repo1 to repo2: .sp .nf .ft C -for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{LF}\(aq repo1\(ga +for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{LF}\(aq\(ga do - echo "borg export\-tar \-\-tar\-format=BORG repo1::$A \- | borg import\-tar \-\-timestamp=$T repo2::$A \-" + echo "borg \-r repo1 export\-tar \-\-tar\-format=BORG $A \- | borg \-r repo2 import\-tar \-\-timestamp=$T $A \-" done .ft P .fi diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index dfc2487d..fccf6ee6 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INFO 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-info \- Show archive details such as disk space used . .nr rst2man-indent-level 0 . @@ -30,12 +27,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-INFO" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-info \- Show archive details such as disk space used .SH SYNOPSIS .sp -borg [common options] info [options] [REPOSITORY_OR_ARCHIVE] +borg [common options] info [options] .SH DESCRIPTION .sp -This command displays detailed information about the specified archive or repository. +This command displays detailed information about the specified archive. .sp Please note that the deduplicated sizes of the individual archives do not add up to the deduplicated size of the repository ("all archives"), because the two @@ -53,16 +53,10 @@ This is shown as \fIutilization of maximum supported archive size\fP\&. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. -.SS arguments -.INDENT 0.0 -.TP -.B REPOSITORY_OR_ARCHIVE -repository or archive to display information about -.UNINDENT .SS optional arguments .INDENT 0.0 .TP -.B \-\-json +.B \-\-json format output as JSON .UNINDENT .SS Archive filters @@ -89,58 +83,20 @@ consider last N archives after other filters were applied .sp .nf .ft C -$ borg info /path/to/repo::2017\-06\-29T11:00\-srv -Archive name: 2017\-06\-29T11:00\-srv -Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5 +$ borg info Tuesday2022\-06\-25T20:51:39 +Archive name: Tuesday2022\-06\-25T20:51:39 +Archive fingerprint: f7dea0788dfc026cc2be1c0f5b94beb4e4084eb3402fc40c38d8719b1bf2d943 Comment: -Hostname: myhostname -Username: root -Time (start): Thu, 2017\-06\-29 11:03:07 -Time (end): Thu, 2017\-06\-29 11:03:13 -Duration: 5.66 seconds -Number of files: 17037 -Command line: /usr/sbin/borg create /path/to/repo::2017\-06\-29T11:00\-srv /srv -Utilization of max. archive size: 0% -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - Original size Compressed size Deduplicated size -This archive: 12.53 GB 12.49 GB 1.62 kB -All archives: 121.82 TB 112.41 TB 215.42 GB - - Unique chunks Total chunks -Chunk index: 1015213 626934122 - -$ borg info /path/to/repo \-\-last 1 -Archive name: 2017\-06\-29T11:00\-srv -Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5 -Comment: -Hostname: myhostname -Username: root -Time (start): Thu, 2017\-06\-29 11:03:07 -Time (end): Thu, 2017\-06\-29 11:03:13 -Duration: 5.66 seconds -Number of files: 17037 -Command line: /usr/sbin/borg create /path/to/repo::2017\-06\-29T11:00\-srv /srv -Utilization of max. archive size: 0% -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - Original size Compressed size Deduplicated size -This archive: 12.53 GB 12.49 GB 1.62 kB -All archives: 121.82 TB 112.41 TB 215.42 GB - - Unique chunks Total chunks -Chunk index: 1015213 626934122 - -$ borg info /path/to/repo -Repository ID: d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5 -Location: /path/to/repo -Encrypted: Yes (repokey) -Cache: /root/.cache/borg/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5 -Security dir: /root/.config/borg/security/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5 -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- - Original size Compressed size Deduplicated size -All archives: 121.82 TB 112.41 TB 215.42 GB - - Unique chunks Total chunks -Chunk index: 1015213 626934122 +Hostname: mba2020 +Username: tw +Time (start): Sat, 2022\-06\-25 20:51:40 +Time (end): Sat, 2022\-06\-25 20:51:40 +Duration: 0.03 seconds +Command line: /Users/tw/w/borg\-env/bin/borg \-r path/to/repo create \-\-stats \(aqTuesday{now}\(aq src \-\-progress +Utilization of maximum supported archive size: 0% +Number of files: 244 +Original size: 13.80 MB +Deduplicated size: 531 B .ft P .fi .UNINDENT diff --git a/docs/man/borg-key-change-algorithm.1 b/docs/man/borg-key-change-algorithm.1 index efcb6374..6308a926 100644 --- a/docs/man/borg-key-change-algorithm.1 +++ b/docs/man/borg-key-change-algorithm.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-CHANGE-ALGORITHM 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-key-change-algorithm \- Change repository key algorithm . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-CHANGE-ALGORITHM" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-key-change-algorithm \- Change repository key algorithm .SH SYNOPSIS .sp -borg [common options] key change\-algorithm [options] [REPOSITORY] ALGORITHM +borg [common options] key change\-algorithm [options] ALGORITHM .SH DESCRIPTION .sp Change the algorithm we use to encrypt and authenticate the borg key. @@ -77,8 +77,6 @@ borg key change\-algorithm /path/to/repo pbkdf2 .sp See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments -.sp -REPOSITORY .INDENT 0.0 .TP .B ALGORITHM diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1 index f40e8341..a0b62642 100644 --- a/docs/man/borg-key-change-location.1 +++ b/docs/man/borg-key-change-location.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-CHANGE-LOCATION 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-key-change-location \- Change repository key location . .nr rst2man-indent-level 0 . @@ -30,26 +27,30 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-CHANGE-LOCATION" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-key-change-location \- Change repository key location .SH SYNOPSIS .sp -borg [common options] key change\-location [options] [REPOSITORY] KEY_LOCATION +borg [common options] key change\-location [options] KEY_LOCATION .SH DESCRIPTION .sp Change the location of a borg key. The key can be stored at different locations: -.sp -keyfile: locally, usually in the home directory -repokey: inside the repo (in the repo config) .INDENT 0.0 -.TP -.B Note: this command does NOT change the crypto algorithms, just the key location, -thus you must ONLY give the key location (keyfile or repokey). +.IP \(bu 2 +keyfile: locally, usually in the home directory +.IP \(bu 2 +repokey: inside the repo (in the repo config) .UNINDENT +.sp +Please note: +.sp +This command does NOT change the crypto algorithms, just the key location, +thus you must ONLY give the key location (keyfile or repokey). .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments -.sp -REPOSITORY .INDENT 0.0 .TP .B KEY_LOCATION @@ -58,7 +59,7 @@ select key location .SS optional arguments .INDENT 0.0 .TP -.B \-\-keep +.B \-\-keep keep the key also at the current location (default: remove it) .UNINDENT .SH SEE ALSO diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 9567c6eb..1a3b169a 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-key-change-passphrase \- Change repository key file passphrase . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS .sp -borg [common options] key change\-passphrase [options] [REPOSITORY] +borg [common options] key change\-passphrase [options] .SH DESCRIPTION .sp The key files used for repository encryption are optionally passphrase @@ -45,9 +45,6 @@ does not protect future (nor past) backups to the same repository. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. -.SS arguments -.sp -REPOSITORY .SH EXAMPLES .INDENT 0.0 .INDENT 3.5 @@ -55,7 +52,7 @@ REPOSITORY .nf .ft C # Create a key file protected repository -$ borg init \-\-encryption=keyfile \-v /path/to/repo +$ borg rcreate \-\-encryption=keyfile \-v Initializing repository at "/path/to/repo" Enter new passphrase: Enter same passphrase again: @@ -67,7 +64,7 @@ Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0. Done. # Change key file passphrase -$ borg key change\-passphrase \-v /path/to/repo +$ borg key change\-passphrase \-v Enter passphrase for key /root/.config/borg/keys/mnt_backup: Enter new passphrase: Enter same passphrase again: @@ -77,7 +74,7 @@ Key updated # Import a previously\-exported key into the specified # key file (creating or overwriting the output key) # (keyfile repositories only) -$ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/repo /path/to/exported +$ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/exported .ft P .fi .UNINDENT @@ -89,9 +86,9 @@ Fully automated using environment variables: .sp .nf .ft C -$ BORG_NEW_PASSPHRASE=old borg init \-e=repokey repo +$ BORG_NEW_PASSPHRASE=old borg rcreate \-e=repokey # now "old" is the current passphrase. -$ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase repo +$ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase # now "new" is the current passphrase. .ft P .fi diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 1202f32a..0405d58f 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-EXPORT 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-key-export \- Export the repository key for backup . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-EXPORT" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-key-export \- Export the repository key for backup .SH SYNOPSIS .sp -borg [common options] key export [options] [REPOSITORY] [PATH] +borg [common options] key export [options] [PATH] .SH DESCRIPTION .sp If repository encryption is used, the repository is inaccessible @@ -78,8 +78,6 @@ borg key export \-\-qr\-html /path/to/repo encrypted\-key\-backup.html .sp See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments -.sp -REPOSITORY .INDENT 0.0 .TP .B PATH @@ -88,10 +86,10 @@ where to store the backup .SS optional arguments .INDENT 0.0 .TP -.B \-\-paper +.B \-\-paper Create an export suitable for printing and later type\-in .TP -.B \-\-qr\-html +.B \-\-qr\-html Create an html file suitable for printing and later type\-in or qr scan .UNINDENT .SH SEE ALSO diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index e2a7acd2..cb466d96 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-IMPORT 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-key-import \- Import the repository key from backup . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-IMPORT" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-key-import \- Import the repository key from backup .SH SYNOPSIS .sp -borg [common options] key import [options] [REPOSITORY] [PATH] +borg [common options] key import [options] [PATH] .SH DESCRIPTION .sp This command restores a key previously backed up with the export command. @@ -53,8 +53,6 @@ key import\fP creates a new key file in \fB$BORG_KEYS_DIR\fP\&. .sp See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments -.sp -REPOSITORY .INDENT 0.0 .TP .B PATH @@ -63,7 +61,7 @@ path to the backup (\(aq\-\(aq to read from stdin) .SS optional arguments .INDENT 0.0 .TP -.B \-\-paper +.B \-\-paper interactively import from a backup done with \fB\-\-paper\fP .UNINDENT .SH SEE ALSO diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 5cb2a6b4..82780ff8 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-key \- Manage a keyfile or repokey of a repository . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS .nf borg [common options] key export ... diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index d34fdf54..6b366005 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-LIST 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-list \- List archive or repository contents . .nr rst2man-indent-level 0 . @@ -30,12 +27,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-LIST" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-list \- List archive contents .SH SYNOPSIS .sp -borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...] +borg [common options] list [options] NAME [PATH...] .SH DESCRIPTION .sp -This command lists the contents of a repository or an archive. +This command lists the contents of an archive. .sp For more help on include/exclude patterns, see the \fIborg_patterns\fP command output. .SH OPTIONS @@ -44,8 +44,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B REPOSITORY_OR_ARCHIVE -repository or archive to list contents of +.B NAME +specify the archive name .TP .B PATH paths to list; patterns are supported @@ -53,38 +53,14 @@ paths to list; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-consider\-checkpoints -Show checkpoint archives in the repository contents list (default: hidden). -.TP -.B \-\-short +.B \-\-short only print file/directory names, nothing else .TP .BI \-\-format \ FORMAT -specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}") +specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}") .TP -.B \-\-json -Only valid for listing repository contents. Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. -.TP -.B \-\-json\-lines -Only valid for listing archive contents. Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. -.UNINDENT -.SS Archive filters -.INDENT 0.0 -.TP -.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX -only consider archive names starting with this prefix. -.TP -.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB -only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. -.TP -.BI \-\-sort\-by \ KEYS -Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp -.TP -.BI \-\-first \ N -consider first N archives after other filters were applied -.TP -.BI \-\-last \ N -consider last N archives after other filters were applied +.B \-\-json\-lines +Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. .UNINDENT .SS Exclusion options .INDENT 0.0 @@ -107,14 +83,7 @@ read include/exclude patterns from PATTERNFILE, one per line .sp .nf .ft C -$ borg list /path/to/repo -Monday Mon, 2016\-02\-15 19:15:11 -repo Mon, 2016\-02\-15 19:26:54 -root\-2016\-02\-15 Mon, 2016\-02\-15 19:36:29 -newname Mon, 2016\-02\-15 19:50:19 -\&... - -$ borg list /path/to/repo::root\-2016\-02\-15 +$ borg list root\-2016\-02\-15 drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 . drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 bin \-rwxr\-xr\-x root root 1029624 Thu, 2014\-11\-13 00:08:51 bin/bash @@ -122,14 +91,14 @@ lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdif \-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff \&... -$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern "\- bin/ba*" +$ borg list root\-2016\-02\-15 \-\-pattern "\- bin/ba*" drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 . drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 bin lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff \-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff \&... -$ borg list /path/to/repo::archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}" +$ borg list archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}" drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 . drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject @@ -137,11 +106,11 @@ drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text \&... -$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:\e.ext$\(aq +$ borg list archiveA \-\-pattern \(aqre:\e.ext$\(aq \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext \&... -$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:.ext$\(aq +$ borg list archiveA \-\-pattern \(aqre:.ext$\(aq \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text \&... @@ -160,23 +129,13 @@ Examples: .sp .nf .ft C -$ borg list \-\-format \(aq{archive}{NL}\(aq /path/to/repo -ArchiveFoo -ArchiveBar -\&... - -# {VAR:NUMBER} \- pad to NUMBER columns. -# Strings are left\-aligned, numbers are right\-aligned. -# Note: time columns except \(ga\(gaisomtime\(ga\(ga, \(ga\(gaisoctime\(ga\(ga and \(ga\(gaisoatime\(ga\(ga cannot be padded. -$ borg list \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq /path/to/repo -ArchiveFoo Thu, 2021\-12\-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274] -$ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo +$ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(aq ArchiveFoo \-rw\-rw\-r\-\- user user 1024 Thu, 2021\-12\-09 10:22:17 file\-foo \&... # {VAR:NUMBER} \- pad to NUMBER columns right\-aligned. -$ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo +$ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq ArchiveFoo \-rw\-rw\-r\-\- user user 1024 Thu, 2021\-12\-09 10:22:17 file\-foo \&... .ft P @@ -185,50 +144,13 @@ $ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{ .UNINDENT .sp The following keys are always available: -.INDENT 0.0 -.IP \(bu 2 -NEWLINE: OS dependent line separator -.IP \(bu 2 -NL: alias of NEWLINE -.IP \(bu 2 -NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below -.IP \(bu 2 -SPACE -.IP \(bu 2 -TAB -.IP \(bu 2 -CR -.IP \(bu 2 -LF -.UNINDENT -.sp -Keys available only when listing archives in a repository: -.INDENT 0.0 -.IP \(bu 2 -archive: archive name interpreted as text (might be missing non\-text characters, see barchive) -.IP \(bu 2 -name: alias of "archive" -.IP \(bu 2 -barchive: verbatim archive name, can contain any character except NUL -.IP \(bu 2 -comment: archive comment interpreted as text (might be missing non\-text characters, see bcomment) -.IP \(bu 2 -bcomment: verbatim archive comment, can contain any character except NUL -.IP \(bu 2 -id: internal ID of the archive -.IP \(bu 2 -start: time (start) of creation of the archive -.IP \(bu 2 -time: alias of "start" -.IP \(bu 2 -end: time (end) of creation of the archive -.IP \(bu 2 -command_line: command line which was used to create the archive -.IP \(bu 2 -hostname: hostname of host on which this archive was created -.IP \(bu 2 -username: username of user who created this archive -.UNINDENT +\- NEWLINE: OS dependent line separator +\- NL: alias of NEWLINE +\- NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below +\- SPACE +\- TAB +\- CR +\- LF .sp Keys available only when listing files in an archive: .INDENT 0.0 @@ -249,20 +171,18 @@ path: path interpreted as text (might be missing non\-text characters, see bpath .IP \(bu 2 bpath: verbatim POSIX path, can contain any character except NUL .IP \(bu 2 -source: link target for links (identical to linktarget) +source: link target for symlinks (identical to linktarget) .IP \(bu 2 linktarget .IP \(bu 2 +hlid: hard link identity (same if hardlinking same fs object) +.IP \(bu 2 flags .IP \(bu 2 size .IP \(bu 2 -csize: compressed size -.IP \(bu 2 dsize: deduplicated size .IP \(bu 2 -dcsize: deduplicated compressed size -.IP \(bu 2 num_chunks: number of chunks in this file .IP \(bu 2 unique_chunks: number of unique chunks in this file diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 182c5411..4ebbcf75 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-MOUNT 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-mount \- Mount archive or an entire repository as a FUSE filesystem . .nr rst2man-indent-level 0 . @@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-MOUNT" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS .sp -borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...] +borg [common options] mount [options] MOUNTPOINT [PATH...] .SH DESCRIPTION .sp This command mounts an archive as a FUSE filesystem. This can be useful for @@ -98,9 +98,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B REPOSITORY_OR_ARCHIVE -repository or archive to mount -.TP .B MOUNTPOINT where to mount filesystem .TP @@ -110,19 +107,19 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-consider\-checkpoints +.B \-\-consider\-checkpoints Show checkpoint archives in the repository contents list (default: hidden). .TP -.B \-f\fP,\fB \-\-foreground +.B \-f\fP,\fB \-\-foreground stay in foreground, do not daemonize .TP -.B \-o +.B \-o Extra mount options .TP -.B \-\-numeric\-owner +.B \-\-numeric\-owner deprecated, use \fB\-\-numeric\-ids\fP instead .TP -.B \-\-numeric\-ids +.B \-\-numeric\-ids use numeric user and group identifiers from archive(s) .UNINDENT .SS Archive filters diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 546cd925..bcf2adf5 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PATTERNS 1 "2022-04-14" "" "borg backup tool" -.SH NAME -borg-patterns \- Details regarding patterns . .nr rst2man-indent-level 0 . @@ -30,45 +27,47 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-PATTERNS" 1 "2022-06-25" "" "borg backup tool" +.SH NAME +borg-patterns \- Details regarding patterns .SH DESCRIPTION .sp -The path/filenames used as input for the pattern matching start from the -currently active recursion root. You usually give the recursion root(s) -when invoking borg and these can be either relative or absolute paths. +When specifying one or more file paths in a Borg command that supports +patterns for the respective option or argument, you can apply the +patterns described here to include only desired files and/or exclude +unwanted ones. Patterns can be used +.INDENT 0.0 +.IP \(bu 2 +for \fB\-\-exclude\fP option, +.IP \(bu 2 +in the file given with \fB\-\-exclude\-from\fP option, +.IP \(bu 2 +for \fB\-\-pattern\fP option, +.IP \(bu 2 +in the file given with \fB\-\-patterns\-from\fP option and +.IP \(bu 2 +for \fBPATH\fP arguments that explicitly support them. +.UNINDENT .sp -So, when you give \fIrelative/\fP as root, the paths going into the matcher -will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as -root, they will look like \fI/absolute/.../file.ext\fP\&. +Borg always stores all file paths normalized and relative to the +current recursion root. The recursion root is also named \fBPATH\fP in +Borg commands like \fIborg create\fP that do a file discovery, so do not +confuse the root with the \fBPATH\fP argument of e.g. \fIborg extract\fP\&. .sp -File paths in Borg archives are always stored normalized and relative. -This means that e.g. \fBborg create /path/to/repo ../some/path\fP will -store all files as \fIsome/path/.../file.ext\fP and \fBborg create -/path/to/repo /home/user\fP will store all files as -\fIhome/user/.../file.ext\fP\&. +Starting with Borg 1.2, paths that are matched against patterns always +appear relative. If you give \fB/absolute/\fP as root, the paths going +into the matcher will look relative like \fBabsolute/.../file.ext\fP\&. +If you give \fB\&../some/path\fP as root, the paths will look like +\fBsome/path/.../file.ext\fP\&. .sp -A directory exclusion pattern can end either with or without a slash (\(aq/\(aq). -If it ends with a slash, such as \fIsome/path/\fP, the directory will be -included but not its content. If it does not end with a slash, such as -\fIsome/path\fP, both the directory and content will be excluded. -.sp -File patterns support these styles: fnmatch, shell, regular expressions, -path prefixes and path full\-matches. By default, fnmatch is used for -\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP -option. For commands that support patterns in their \fBPATH\fP argument -like (\fBborg list\fP), the default pattern is path prefix. -.sp -Starting with Borg 1.2, for all but regular expression pattern matching -styles, all paths are treated as relative, meaning that a leading path -separator is removed after normalizing and before matching. This allows -you to use absolute or relative patterns arbitrarily. -.sp -If followed by a colon (\(aq:\(aq) the first two characters of a pattern are -used as a style selector. Explicit style selection is necessary when a -non\-default style is desired or when the desired pattern starts with -two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP). +File patterns support five different styles. If followed by a colon \(aq:\(aq, +the first two characters of a pattern are used as a style selector. +Explicit style selection is necessary if a non\-default style is desired +or when the desired pattern starts with two alphanumeric characters +followed by a colon (i.e. \fBaa:something/*\fP). .INDENT 0.0 .TP -.B \fI\%Fnmatch\fP, selector \fIfm:\fP +.B \fI\%Fnmatch\fP, selector \fBfm:\fP This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&. These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq @@ -76,7 +75,7 @@ matching any single character specified, including ranges, and \(aq[!...]\(aq matching any character not specified. For the purpose of these patterns, the path separator (backslash for Windows and \(aq/\(aq on other systems) is not treated specially. Wrap meta\-characters in brackets for a literal -match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path +match (i.e. \fB[?]\fP to match the literal character \(aq?\(aq). For a path to match a pattern, the full path must match, or it must match from the start of the full path to just before a path separator. Except for the root path, paths will never end in the path separator when @@ -84,33 +83,31 @@ matching is attempted. Thus, if a given pattern ends in a path separator, a \(aq*\(aq is appended before matching is attempted. A leading path separator is always removed. .TP -.B Shell\-style patterns, selector \fIsh:\fP +.B Shell\-style patterns, selector \fBsh:\fP This is the default style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP\&. Like fnmatch patterns these are similar to shell patterns. The difference -is that the pattern may include \fI**/\fP for matching zero or more directory -levels, \fI*\fP for matching zero or more arbitrary characters with the +is that the pattern may include \fB**/\fP for matching zero or more directory +levels, \fB*\fP for matching zero or more arbitrary characters with the exception of any path separator. A leading path separator is always removed. .TP -.B Regular expressions, selector \fIre:\fP -Regular expressions similar to those found in Perl are supported. Unlike -shell patterns regular expressions are not required to match the full +.B \fI\%Regular expressions\fP, selector \fBre:\fP +Unlike shell patterns, regular expressions are not required to match the full path and any substring match is sufficient. It is strongly recommended to anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path separators (backslash for Windows and \(aq/\(aq on other systems) in paths are -always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The -regular expression syntax is described in the \fI\%Python documentation for -the re module\fP\&. +always normalized to a forward slash \(aq/\(aq before applying a pattern. .TP -.B Path prefix, selector \fIpp:\fP +.B Path prefix, selector \fBpp:\fP This pattern style is useful to match whole sub\-directories. The pattern -\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein. A leading -path separator is always removed. +\fBpp:root/somedir\fP matches \fBroot/somedir\fP and everything therein. +A leading path separator is always removed. .TP -.B Path full\-match, selector \fIpf:\fP +.B Path full\-match, selector \fBpf:\fP This pattern style is (only) useful to match full paths. This is kind of a pseudo pattern as it can not have any variable or -unspecified parts \- the full path must be given. \fIpf:root/file.ext\fP matches -\fIroot/file.ext\fP only. A leading path separator is always removed. +unspecified parts \- the full path must be given. \fBpf:root/file.ext\fP +matches \fBroot/file.ext\fP only. A leading path separator is always +removed. .sp Implementation note: this is implemented via very time\-efficient O(1) hashtable lookups (this means you can have huge amounts of such patterns @@ -125,12 +122,12 @@ Same logic applies for exclude. \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -\fIre:\fP, \fIsh:\fP and \fIfm:\fP patterns are all implemented on top of the Python SRE -engine. It is very easy to formulate patterns for each of these types which -requires an inordinate amount of time to match paths. If untrusted users -are able to supply patterns, ensure they cannot supply \fIre:\fP patterns. -Further, ensure that \fIsh:\fP and \fIfm:\fP patterns only contain a handful of -wildcards at most. +\fBre:\fP, \fBsh:\fP and \fBfm:\fP patterns are all implemented on top of +the Python SRE engine. It is very easy to formulate patterns for each +of these types which requires an inordinate amount of time to match +paths. If untrusted users are able to supply patterns, ensure they +cannot supply \fBre:\fP patterns. Further, ensure that \fBsh:\fP and +\fBfm:\fP patterns only contain a handful of wildcards at most. .UNINDENT .UNINDENT .sp @@ -139,8 +136,8 @@ from within a shell, the patterns should be quoted to protect them from expansion. .sp The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text -file with one pattern per line. Lines empty or starting with the number sign -(\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style +file with one pattern per line. Lines empty or starting with the hash sign +\(aq#\(aq after removing whitespace on both ends are ignored. The optional style selector prefix is also supported for patterns loaded from a file. Due to whitespace removal, paths with whitespace at the beginning or end can only be excluded using regular expressions. @@ -155,74 +152,101 @@ Examples: .nf .ft C # Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq: -$ borg create \-e \(aq*.o\(aq backup / +$ borg create \-e \(aq*.o\(aq archive / # Exclude \(aq/home/user/junk\(aq and \(aq/home/user/subdir/junk\(aq but # not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq: -$ borg create \-e \(aq/home/*/junk\(aq backup / +$ borg create \-e \(aqhome/*/junk\(aq archive / # Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself: -$ borg create \-e home/user/cache/ backup / +$ borg create \-e home/user/cache/ archive / # The file \(aq/home/user/cache/important\(aq is *not* backed up: -$ borg create \-e /home/user/cache/ backup / /home/user/cache/important +$ borg create \-e home/user/cache/ archive / /home/user/cache/important # The contents of directories in \(aq/home\(aq are not backed up when their name # ends in \(aq.tmp\(aq -$ borg create \-\-exclude \(aqre:^/home/[^/]+\e.tmp/\(aq backup / +$ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq archive / # Load exclusions from file $ cat >exclude.txt <