diff options
| author | Helmut Grohne <helmut@subdivi.de> | 2023-02-28 08:56:29 +0100 |
|---|---|---|
| committer | Helmut Grohne <helmut@subdivi.de> | 2023-02-28 08:56:29 +0100 |
| commit | 1ad9158c46d7f468dc30dd9d49717ca7ef082d78 (patch) | |
| tree | ce63070a957dfa22e75afcc989bd6e20affe2cbc /docs | |
| parent | 3a85824c3a5b88ae5de1842ef2e7a759ed9ed481 (diff) | |
New upstream version 2.0.0b5
Diffstat (limited to 'docs')
89 files changed, 1093 insertions, 652 deletions
diff --git a/docs/changes.rst b/docs/changes.rst index 0496662f..dc607dac 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -12,7 +12,7 @@ This section provides information about security and corruption issues. Change Log 2.x ============== -Version 2.0.0b4 (2022-11-27) +Version 2.0.0b5 (2023-02-27) ---------------------------- Please note: @@ -40,7 +40,7 @@ Compatibility notes: - the scp-style REPO syntax was removed, please use ssh://..., #6697 - ssh:// URLs: removed support for /~otheruser/, #6855. If you used this, just replace it by: ssh://user@host:port/home/otheruser/ - - -P / --prefix option was removed, please use the similar -a / --glob-archives. + - -P / --prefix option was removed, please use the similar -a / --match-archives. - the archive name is always given separately from the repository (differently than with borg 1.x you must not give repo::archive). - the archive name is either given as a positional parameter, like: @@ -50,8 +50,8 @@ Compatibility notes: - or, if the command makes sense for an arbitrary amount of archives, archives can be selected using a glob pattern, like: - - borg delete -a 'myarchive*' - - borg recreate -a 'myarchive*' + - borg delete -a 'sh:myarchive*' + - borg recreate -a 'sh:myarchive*' - some borg 1.x commands that supported working on a repo AND on an archive were split into 2 commands, some others were renamed: @@ -82,6 +82,8 @@ Compatibility notes: - removed --numeric-owner (use --numeric-ids) - removed --nobsdflags (use --noflags) - removed --noatime (default now, see also --atime) + - removed --save-space option (does not change behaviour) +- using --list together with --progress is now disallowed (except with --log-json), #7219 - the --glob-archives option was renamed to --match-archives (the short option name -a is unchanged) and extended to support different pattern styles: @@ -94,6 +96,113 @@ Compatibility notes: borg 1.x: --glob-archives 'myserver-*' borg 2.0: --match-archives 'sh:myserver-*' +- use platformdirs 3.x.x instead of home-grown code. Due to that: + + - XDG_*_HOME is not honoured on macOS and on Windows. + - BORG_BASE_DIR can still be used to enforce some base dir + .config/ or .cache/. + - the default macOS config and cache dir will now be in ~/Library/Application Support/borg/. +- create: different included/excluded status chars, #7321 + + - dry-run: now uses "+" (was: "-") and "-" (was: "x") for included/excluded status + - non-dry-run: now uses "-" (was: "x") for excluded files + + Option --filter=... might need an update, if you filter for the status chars + that were changed. + + +New features: + +- create: implement retries for individual fs files + (e.g. if a file changed while we read it, if a file had an OSError) +- info: add used storage quota, #7121 +- transfer: support --progress +- create/recreate/import-tar: add --checkpoint-volume option +- support date-based matching for archive selection, + add --newer/--older/--newest/--oldest options, #7062 #7296 + +Fixes: + +- disallow --list with --progress, #7219 +- create: fix --list --dry-run output for directories, #7209 +- do no assume hardlink_master=True if not present, #7175 +- fix item_ptrs orphaned chunks of checkpoint archives +- avoid orphan content chunks on BackupOSError, #6709 +- transfer: fix bug in obfuscated data upgrade code +- fs.py: fix bug in f-string (thanks mypy!) +- recreate: when --target is given, do not detect "nothing to do", #7254 +- locking (win32): deal with os.rmdir/listdir PermissionErrors +- locking: thread id must be parsed as hex from lock file name +- extract: fix mtime when ResourceFork xattr is set (macOS specific), #7234 +- recreate: without --chunker-params borg shall not rechunk, #7336 +- allow mixing --progress and --list in log-json mode +- add "files changed while reading" to Statistics class, #7354 +- fixed keys determination in Statistics.__add__(), #7355 + +Other changes: + +- use local time / local timezone to output timestamps, #7283 +- update development.lock.txt, including a setuptools security fix, #7227 +- remove --save-space option (does not change behaviour) +- remove part files from final archive +- remove --consider-part-files, related stats code, update docs +- transfer: drop part files +- check: show id of orphaned chunks +- ArchiveItem.cmdline list-of-str -> .command_line str, #7246 +- Item: symlinks: rename .source to .target, #7245 +- Item: make user/group/uid/gid optional +- create: do not store user/group for stdin data by default, #7249 +- extract: chown only if we have u/g info in archived item, #7249 +- export-tar: for items w/o uid/gid, default to 0/0, #7249 +- fix some uid/gid lookup code / tests for win32 +- cache.py: be less verbose during cache sync +- update bash completion script commands and options, #7273 +- require and use platformdirs 3.x.x package, tests +- better included/excluded status chars, docs, #7321 +- undef NDEBUG for chunker and hashindex (make assert() work) +- assert_id: better be paranoid (add back same crypto code as in old borg), #7362 +- check --verify_data: always decompress and call assert_id(), #7362 +- make hashindex_compact simpler and probably faster, minor fixes, cleanups, more tests +- hashindex minor fixes, refactor, tweaks, tests +- pyinstaller: remove icon +- validation / placeholders / JSON: + + - implement (text|binary)_to_json: key (text), key_b64 (base64(binary)) + - remove bpath, barchive, bcomment placeholders / JSON keys + - archive metadata: make sure hostname and username have no surrogate escapes + - text attributes (like archive name, comment): validate more strictly, #2290 + - transfer: validate archive names and comment before transfer + - json output: use text_to_json (path, target), #6151 +- docs: + + - docs and comments consistency, readability and spelling fixes + - fix --progress display description, #7180 + - document how borg deals with non-unicode bytes in JSON output + - document another way to get UTF-8 encoding on stdin/stdout/stderr, #2273 + - pruning interprets timestamps in the local timezone where borg prune runs + - shellpattern: add license, use copyright/license markup + - key change-passphrase: fix --encryption value in examples + - remove BORG_LIBB2_PREFIX (not used any more) + - Installation: Update Fedora in distribution list, #7357 + - add .readthedocs.yaml (use py311, use non-shallow clone) +- tests: + + - fix archiver tests on Windows, add running the tests to Windows CI + - fix tox4 passenv issue, #7199 + - github actions updates (fix deprecation warnings) + - add tests for borg transfer/upgrade + - fix test hanging reading FIFO when `borg create` failed + - mypy inspired fixes / updates + - fix prune tests, prune in localtime + - do not look up uid 0 / gid 0, but current process uid/gid + - safe_unlink tests: use os.link to support win32 also + - fix test_size_on_disk_accurate for large st_blksize, #7250 + - relaxed timestamp comparisons, use same_ts_ns + - add test for extracted directory mtime + - use "fail" chunker to test erroneous input file skipping + + +Version 2.0.0b4 (2022-11-27) +---------------------------- Fixes: @@ -297,7 +406,7 @@ Changes: - compression: use the 2 bytes for type and level, #6698 - use version 2 for new archives - convert timestamps int/bigint -> msgpack.Timestamp, see #2323 - - all hardlinks have chunks, maybe chunks_healty, hlid + - all hardlinks have chunks, maybe chunks_healthy, hlid - remove the zlib type bytes hack - make sure items with chunks have precomputed size - removes the csize element from the tuples in the Item.chunks list diff --git a/docs/changes_0.x.rst b/docs/changes_0.x.rst index 52c0b035..39290a11 100644 --- a/docs/changes_0.x.rst +++ b/docs/changes_0.x.rst @@ -8,8 +8,8 @@ Version 0.30.0 (2016-01-23) Compatibility notes: -- you may need to use -v (or --info) more often to actually see output emitted - at INFO log level (because it is suppressed at the default WARNING log level). +- The new default logging level is WARNING. Previously, it was INFO, which was + more verbose. Use -v (or --info) to show once again log level INFO messages. See the "general" section in the usage docs. - for borg create, you need --list (additionally to -v) to see the long file list (was needed so you can have e.g. --stats alone without the long list) @@ -164,7 +164,7 @@ New features: - borg create --exclude-if-present TAGFILE - exclude directories that have the given file from the backup. You can additionally give --keep-tag-files to - preserve just the directory roots and the tag-files (but not backup other + preserve just the directory roots and the tag-files (but not back up other directory contents), #395, attic #128, attic #142 Other changes: @@ -419,10 +419,10 @@ Compatibility notes: Deprecations: - --compression N (with N being a number, as in 0.24) is deprecated. - We keep the --compression 0..9 for now to not break scripts, but it is + We keep the --compression 0..9 for now not to break scripts, but it is deprecated and will be removed later, so better fix your scripts now: --compression 0 (as in 0.24) is the same as --compression zlib,0 (now). - BUT: if you do not want compression, you rather want --compression none + BUT: if you do not want compression, use --compression none (which is the default). --compression 1 (in 0.24) is the same as --compression zlib,1 (now) --compression 9 (in 0.24) is the same as --compression zlib,9 (now) @@ -434,7 +434,7 @@ New features: - create --compression lz4 (super-fast, but not very high compression) - create --compression zlib,N (slower, higher compression, default for N is 6) - create --compression lzma,N (slowest, highest compression, default N is 6) -- honor the nodump flag (UF_NODUMP) and do not backup such items +- honor the nodump flag (UF_NODUMP) and do not back up such items - list --short just outputs a simple list of the files/directories in an archive Bug fixes: @@ -541,7 +541,7 @@ Other changes: - update internals doc about chunker params, memory usage and compression - added docs about development - add some words about resource usage in general - - document how to backup a raw disk + - document how to back up a raw disk - add note about how to run borg from virtual env - add solutions for (ll)fuse installation problems - document what borg check does, fixes #138 @@ -617,7 +617,7 @@ New features: - FUSE: reflect deduplication in allocated blocks - only allow whitelisted RPC calls in server mode - normalize source/exclude paths before matching -- use posix_fadvise to not spoil the OS cache, fixes attic #252 +- use posix_fadvise not to spoil the OS cache, fixes attic #252 - toplevel error handler: show tracebacks for better error analysis - sigusr1 / sigint handler to print current file infos - attic PR #286 - RPCError: include the exception args we get from remote diff --git a/docs/changes_1.x.rst b/docs/changes_1.x.rst index 16aad68d..3dae2a7b 100644 --- a/docs/changes_1.x.rst +++ b/docs/changes_1.x.rst @@ -776,7 +776,7 @@ Other changes: - docs: - improve description of path variables - - document how to completely delete data, #2929 + - document how to delete data completely, #2929 - add FAQ about Borg config dir, #4941 - add docs about errors not printed as JSON, #4073 - update usage_general.rst.inc @@ -864,7 +864,7 @@ New features: - ability to use a system-provided version of "xxhash" - create: - - changed the default behaviour to not store the atime of fs items. atime is + - changed the default behaviour not to store the atime of fs items. atime is often rather not interesting and fragile - it easily changes even if nothing else has changed and, if stored into the archive, spoils deduplication of the archive metadata stream. @@ -1781,7 +1781,7 @@ Fixes: - security fix: configure FUSE with "default_permissions", #3903 "default_permissions" is now enforced by borg by default to let the kernel check uid/gid/mode based permissions. - "ignore_permissions" can be given to not enforce "default_permissions". + "ignore_permissions" can be given not to enforce "default_permissions". - make "hostname" short, even on misconfigured systems, #4262 - fix free space calculation on macOS (and others?), #4289 - config: quit with error message when no key is provided, #4223 @@ -2149,7 +2149,7 @@ New features: - mount: added exclusion group options and paths, #2138 Reused some code to support similar options/paths as borg extract offers - - making good use of these to only mount a smaller subset of dirs/files can + making good use of these to mount only a smaller subset of dirs/files can speed up mounting a lot and also will consume way less memory. borg mount [options] repo_or_archive mountpoint path [paths...] @@ -2235,10 +2235,10 @@ Compatibility notes: - The deprecated --no-files-cache is not a global/common option any more, but only available for borg create (it is not needed for anything else). Use --files-cache=disabled instead of --no-files-cache. -- The nodump flag ("do not backup this file") is not honoured any more by +- The nodump flag ("do not back up this file") is not honoured any more by default because this functionality (esp. if it happened by error or unexpected) was rather confusing and unexplainable at first to users. - If you want that "do not backup NODUMP-flagged files" behaviour, use: + If you want that "do not back up NODUMP-flagged files" behaviour, use: borg create --exclude-nodump ... - If you are on Linux and do not need bsdflags archived, consider using ``--nobsdflags`` with ``borg create`` to avoid additional syscalls and @@ -3078,7 +3078,7 @@ New features: which includes the SHA1 and SHA2 family as well as MD5 - borg prune: - - to better visualize the "thinning out", we now list all archives in + - to visualize the "thinning out" better, we now list all archives in reverse time order. rephrase and reorder help text. - implement --keep-last N via --keep-secondly N, also --keep-minutely. assuming that there is not more than 1 backup archive made in 1s, @@ -3175,7 +3175,7 @@ Bug fixes: - security fix: configure FUSE with "default_permissions", #3903. "default_permissions" is now enforced by borg by default to let the kernel check uid/gid/mode based permissions. - "ignore_permissions" can be given to not enforce "default_permissions". + "ignore_permissions" can be given not to enforce "default_permissions". - xattrs: fix borg exception handling on ENOSPC error, #3808. New features: @@ -3371,7 +3371,7 @@ Other changes: - kill api page - added FAQ section about backing up root partition - add bountysource badge, #2558 - - create empty docs.txt reequirements, #2694 + - create empty docs.txt requirements, #2694 - README: how to help the project - note -v/--verbose requirement on affected options, #2542 - document borg init behaviour via append-only borg serve, #2440 @@ -3478,7 +3478,7 @@ Other changes: - docs: - language clarification - VM backup FAQ - - borg create: document how to backup stdin, #2013 + - borg create: document how to back up stdin, #2013 - borg upgrade: fix incorrect title levels - add CVE numbers for issues fixed in 1.0.9, #2106 - fix typos (taken from Debian package patch) @@ -3505,8 +3505,18 @@ Security fixes: CVE-2016-10099 was assigned to this vulnerability. - borg check: When rebuilding the manifest (which should only be needed very rarely) - duplicate archive names would be handled on a "first come first serve" basis, allowing - an attacker to apparently replace archives. + duplicate archive names would be handled on a "first come first serve" basis, + potentially opening an attack vector to replace archives. + + Example: were there 2 archives named "foo" in a repo (which can not happen + under normal circumstances, because borg checks if the name is already used) + and a "borg check" recreated a (previously lost) manifest, the first of the + archives it encountered would be in the manifest. The second archive is also + still in the repo, but not referenced in the manifest, in this case. If the + second archive is the "correct" one (and was previously referenced from the + manifest), it looks like it got replaced by the first one. In the manifest, + it actually got replaced. Both remain in the repo but the "correct" one is no + longer accessible via normal means - the manifest. CVE-2016-10100 was assigned to this vulnerability. @@ -3674,7 +3684,7 @@ Bug fixes: New features: - add "borg key export" / "borg key import" commands, #1555, so users are able - to backup / restore their encryption keys more easily. + to back up / restore their encryption keys more easily. Supported formats are the keyfile format used by borg internally and a special "paper" format with by line checksums for printed backups. For the @@ -4161,7 +4171,7 @@ Bug fixes: - do not sleep for >60s while waiting for lock, #773 - unpack file stats before passing to FUSE - fix build on illumos -- don't try to backup doors or event ports (Solaris and derivatives) +- don't try to back up doors or event ports (Solaris and derivatives) - remove useless/misleading libc version display, #738 - test suite: reset exit code of persistent archiver, #844 - RemoteRepository: clean up pipe if remote open() fails @@ -4234,20 +4244,20 @@ Compatibility notes: changed file and in the worst case (e.g. if your files cache was lost / is not used) by the size of every file (minus any compression you might use). - in case you want to immediately see a much lower resource usage (RAM / disk) + in case you want to see a much lower resource usage immediately (RAM / disk) for chunks management, it might be better to start with a new repo than - continuing in the existing repo (with an existing repo, you'ld have to wait - until all archives with small chunks got pruned to see a lower resource + to continue in the existing repo (with an existing repo, you have to wait + until all archives with small chunks get pruned to see a lower resource usage). if you used the old --chunker-params default value (or if you did not use - --chunker-params option at all) and you'ld like to continue using small + --chunker-params option at all) and you'd like to continue using small chunks (and you accept the huge resource usage that comes with that), just - explicitly use borg create --chunker-params=10,23,16,4095. + use explicitly borg create --chunker-params=10,23,16,4095. - archive timestamps: the 'time' timestamp now refers to archive creation start time (was: end time), the new 'time_end' timestamp refers to archive - creation end time. This might affect prune if your backups take rather long. - if you give a timestamp via cli this is stored into 'time', therefore it now + creation end time. This might affect prune if your backups take a long time. + if you give a timestamp via cli, this is stored into 'time'. therefore it now needs to mean archive creation start time. New features: @@ -4289,8 +4299,8 @@ Bug fixes: Other changes: -- it is now possible to use "pip install borgbackup[fuse]" to automatically - install the llfuse dependency using the correct version requirement +- it is now possible to use "pip install borgbackup[fuse]" to + install the llfuse dependency automatically, using the correct version requirement for it. you still need to care about having installed the FUSE / build related OS package first, though, so that building llfuse can succeed. - Vagrant: drop Ubuntu Precise (12.04) - does not have Python >= 3.4 diff --git a/docs/conf.py b/docs/conf.py index fd13fed4..44d33d5a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -245,6 +245,6 @@ extensions = [ ] extlinks = { - "issue": ("https://github.com/borgbackup/borg/issues/%s", "#"), + "issue": ("https://github.com/borgbackup/borg/issues/%s", "#%s"), "targz_url": ("https://pypi.python.org/packages/source/b/borgbackup/%%s-%s.tar.gz" % version, None), } diff --git a/docs/deployment/automated-local.rst b/docs/deployment/automated-local.rst index 3ed3cd46..3d60b059 100644 --- a/docs/deployment/automated-local.rst +++ b/docs/deployment/automated-local.rst @@ -168,13 +168,13 @@ after creating the backup. Rename the file to something else (e.g. ``/etc/backup when you want to do something with the drive after creating backups (e.g running check). Create the ``/etc/backups/backup-suspend`` file if the machine should suspend after completing -the backup. Don't forget to physically disconnect the device before resuming, +the backup. Don't forget to disconnect the device physically before resuming, otherwise you'll enter a cycle. You can also add an option to power down instead. Create an empty ``/etc/backups/backup.disks`` file, you'll register your backup drives there. -The last part is to actually enable the udev rules and services: +The last part is actually to enable the udev rules and services: .. code-block:: bash diff --git a/docs/deployment/central-backup-server.rst b/docs/deployment/central-backup-server.rst index 047ca443..d9502587 100644 --- a/docs/deployment/central-backup-server.rst +++ b/docs/deployment/central-backup-server.rst @@ -4,7 +4,7 @@ Central repository server with Ansible or Salt ============================================== -This section will give an example how to setup a borg repository server for multiple +This section will give an example how to set up a borg repository server for multiple clients. Machines @@ -103,7 +103,7 @@ The server should automatically change the current working directory to the `<cl borg init backup@backup01.srv.local:/home/backup/repos/johndoe.clnt.local/pictures When `johndoe.clnt.local` tries to access a not restricted path the following error is raised. -John Doe tries to backup into the Web 01 path: +John Doe tries to back up into the Web 01 path: :: @@ -202,7 +202,7 @@ Salt running on a Debian system. Enhancements ------------ -As this section only describes a simple and effective setup it could be further +As this section only describes a simple and effective setup, it could be further enhanced when supporting (a limited set) of client supplied commands. A wrapper for starting `borg serve` could be written. Or borg itself could be enhanced to autodetect it runs under SSH by checking the `SSH_ORIGINAL_COMMAND` environment diff --git a/docs/deployment/hosting-repositories.rst b/docs/deployment/hosting-repositories.rst index 24dc5213..55fd3e15 100644 --- a/docs/deployment/hosting-repositories.rst +++ b/docs/deployment/hosting-repositories.rst @@ -5,7 +5,7 @@ Hosting repositories ==================== -This sections shows how to securely provide repository storage for users. +This sections shows how to provide repository storage securely for users. Optionally, each user can have a storage quota. Repositories are accessed through SSH. Each user of the service should @@ -24,7 +24,7 @@ is assigned a home directory and repositories of the user reside in her home directory. The following ``~user/.ssh/authorized_keys`` file is the most important -piece for a correct deployment. It allows the user to login via +piece for a correct deployment. It allows the user to log in via their public key (which must be provided by the user), and restricts SSH access to safe operations only. diff --git a/docs/deployment/image-backup.rst b/docs/deployment/image-backup.rst index fd684c3f..e0cbae29 100644 --- a/docs/deployment/image-backup.rst +++ b/docs/deployment/image-backup.rst @@ -33,7 +33,7 @@ deduplicating. For backup, save the disk header and the contents of each partiti PARTNUM=$(echo $x | grep -Eo "[0-9]+$") ntfsclone -so - $x | borg create repo::hostname-part$PARTNUM - done - # to backup non-NTFS partitions as well: + # to back up non-NTFS partitions as well: echo "$PARTITIONS" | grep -v NTFS | cut -d' ' -f1 | while read x; do PARTNUM=$(echo $x | grep -Eo "[0-9]+$") borg create --read-special repo::hostname-part$PARTNUM $x @@ -77,7 +77,7 @@ Because the partitions were zeroed in place, restoration is only one command:: borg extract --stdout repo::hostname-disk | dd of=$DISK .. note:: The "traditional" way to zero out space on a partition, especially one already - mounted, is to simply ``dd`` from ``/dev/zero`` to a temporary file and delete + mounted, is simply to ``dd`` from ``/dev/zero`` to a temporary file and delete it. This is ill-advised for the reasons mentioned in the ``zerofree`` man page: - it is slow diff --git a/docs/deployment/pull-backup.rst b/docs/deployment/pull-backup.rst index 258a7fb7..ce593cdb 100644 --- a/docs/deployment/pull-backup.rst +++ b/docs/deployment/pull-backup.rst @@ -13,7 +13,7 @@ If you however require the backup server to initiate the connection or prefer it to initiate the backup run, one of the following workarounds is required to allow such a pull mode setup. -A common use case for pull mode is to backup a remote server to a local personal +A common use case for pull mode is to back up a remote server to a local personal computer. SSHFS @@ -161,7 +161,7 @@ Now we can run borg extract /borgrepo::archive PATH -to partially restore whatever we like. Finally, do the clean-up: +to restore whatever we like partially. Finally, do the clean-up: :: @@ -209,8 +209,8 @@ socat ===== In this setup a SSH connection from the backup server to the client is -established that uses SSH reverse port forwarding to transparently -tunnel data between UNIX domain sockets on the client and server and the socat +established that uses SSH reverse port forwarding to tunnel data +transparently between UNIX domain sockets on the client and server and the socat tool to connect these with the borg client and server processes, respectively. The program socat has to be available on the backup server and on the client @@ -277,7 +277,7 @@ forwarding can do this for us:: Warning: remote port forwarding failed for listen path /run/borg/reponame.sock - When you are done, you have to manually remove the socket file, otherwise + When you are done, you have to remove the socket file manually, otherwise you may see an error like this when trying to execute borg commands:: Remote: YYYY/MM/DD HH:MM:SS socat[XXX] E connect(5, AF=1 "/run/borg/reponame.sock", 13): Connection refused @@ -417,7 +417,7 @@ Parentheses are not needed when using a dedicated bash process. *ssh://borgs@borg-server/~/repo* refers to the repository *repo* within borgs's home directory on *borg-server*. - *StrictHostKeyChecking=no* is used to automatically add host keys to *~/.ssh/known_hosts* without user intervention. + *StrictHostKeyChecking=no* is used to add host keys automatically to *~/.ssh/known_hosts* without user intervention. ``kill "${SSH_AGENT_PID}"`` diff --git a/docs/faq.rst b/docs/faq.rst index f767a277..20f7a43a 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -24,7 +24,7 @@ SSHFS, the Borg client only can do file system operations and has no agent running on the remote side, so *every* operation needs to go over the network, which is slower. -Can I backup from multiple servers into a single repository? +Can I back up from multiple servers into a single repository? ------------------------------------------------------------ In order for the deduplication used by Borg to work, it @@ -86,7 +86,7 @@ run into this by yourself by restoring an older copy of your repository. "attack": maybe an attacker has replaced your repo by an older copy, trying to trick you into AES counter reuse, trying to break your repo encryption. -If you'ld decide to ignore this and accept unsafe operation for this repository, +If you decide to ignore this and accept unsafe operation for this repository, you could delete the manifest-timestamp and the local cache: :: @@ -115,8 +115,8 @@ Which file types, attributes, etc. are *not* preserved? Are there other known limitations? ---------------------------------- -- borg extract only supports restoring into an empty destination. After that, - the destination will exactly have the contents of the extracted archive. +- borg extract supports restoring only into an empty destination. After extraction, + the destination will have exactly the contents of the extracted archive. If you extract into a non-empty destination, borg will (for example) not remove files which are in the destination, but not in the archive. See :issue:`4598` for a workaround and more details. @@ -128,14 +128,14 @@ If a backup stops mid-way, does the already-backed-up data stay there? Yes, Borg supports resuming backups. -During a backup a special checkpoint archive named ``<archive-name>.checkpoint`` -is saved every checkpoint interval (the default value for this is 30 +During a backup, a special checkpoint archive named ``<archive-name>.checkpoint`` +is saved at every checkpoint interval (the default value for this is 30 minutes) containing all the data backed-up until that point. -This checkpoint archive is a valid archive, -but it is only a partial backup (not all files that you wanted to backup are -contained in it). Having it in the repo until a successful, full backup is -completed is useful because it references all the transmitted chunks up +This checkpoint archive is a valid archive, but it is only a partial backup +(not all files that you wanted to back up are contained in it and the last file +in it might be a partial file). Having it in the repo until a successful, full +backup is completed is useful because it references all the transmitted chunks up to the checkpoint. This means that in case of an interruption, you only need to retransfer the data since the last checkpoint. @@ -154,16 +154,14 @@ Once your backup has finished successfully, you can delete all ``<archive-name>.checkpoint`` archives. If you run ``borg prune``, it will also care for deleting unneeded checkpoints. -Note: the checkpointing mechanism creates hidden, partial files in an archive, -so that checkpoints even work while a big file is being processed. -They are named ``<filename>.borg_part_<N>`` and all operations usually ignore -these files, but you can make them considered by giving the option -``--consider-part-files``. You usually only need that option if you are -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: the checkpointing mechanism may create a partial (truncated) last file +in a checkpoint archive named ``<filename>.borg_part``. Such partial files +won't be contained in the final archive. +This is done so that checkpoints work cleanly and promptly while a big +file is being processed. -How can I backup huge file(s) over a unstable connection? + +How can I back up huge file(s) over a unstable connection? --------------------------------------------------------- Yes. For more details, see :ref:`checkpoints_parts`. @@ -171,10 +169,8 @@ Yes. For more details, see :ref:`checkpoints_parts`. How can I restore huge file(s) over an unstable connection? ----------------------------------------------------------- -If you cannot manage to extract the whole big file in one go, you can extract -all the part files and manually concatenate them together. - -For more details, see :ref:`checkpoints_parts`. +Try using ``borg mount`` and ``rsync`` (or a similar tool that supports +resuming a partial file copy from what's already copied). How can I switch append-only mode on and off? ----------------------------------------------------------------------------------------------------------------------------------- @@ -334,7 +330,7 @@ Assuming that all your chunks have a size of :math:`2^{21}` bytes (approximately and we have a "perfect" hash algorithm, we can think that the probability of collision would be of :math:`p^2/2^{n+1}` then, using SHA-256 (:math:`n=256`) and for example we have 1000 million chunks (:math:`p=10^9`) (1000 million chunks would be about 2100TB). -The probability would be around to 0.0000000000000000000000000000000000000000000000000000000000043. +The probability would be around 0.0000000000000000000000000000000000000000000000000000000000043. A mass-murderer space rock happens about once every 30 million years on average. This leads to a probability of such an event occurring in the next second to about :math:`10^{-15}`. @@ -342,9 +338,9 @@ That's **45** orders of magnitude more probable than the SHA-256 collision. Brie if you find SHA-256 collisions scary then your priorities are wrong. This example was grabbed from `this SO answer <https://stackoverflow.com/a/4014407/13359375>`_, it's great honestly. -Still, the real question is if Borg tries to not make this happen? +Still, the real question is whether Borg tries not to make this happen? -Well... it used to not check anything but there was a feature added which saves the size +Well... previously it did not check anything until there was a feature added which saves the size of the chunks too, so the size of the chunks is compared to the size that you got with the hash and if the check says there is a mismatch it will raise an exception instead of corrupting the file. This doesn't save us from everything but reduces the chances of corruption. @@ -364,7 +360,7 @@ How do I configure different prune policies for different directories? ---------------------------------------------------------------------- Say you want to prune ``/var/log`` faster than the rest of -``/``. How do we implement that? The answer is to backup to different +``/``. How do we implement that? The answer is to back up to different archive *names* and then implement different prune policies for different prefixes. For example, you could have a script that does:: @@ -467,7 +463,7 @@ Setting ``BORG_PASSPHRASE`` user <https://security.stackexchange.com/questions/14000/environment-variable-accessibility-in-linux/14009#14009>`_. -Using ``BORG_PASSCOMMAND`` with a properly permissioned file +Using ``BORG_PASSCOMMAND`` with a file of proper permissions Another option is to create a file with a password in it in your home directory and use permissions to keep anyone else from reading it. For example, first create a key:: @@ -489,7 +485,7 @@ Using keyfile-based encryption with a blank passphrase Using ``BORG_PASSCOMMAND`` with macOS Keychain macOS has a native manager for secrets (such as passphrases) which is safer than just using a file as it is encrypted at rest and unlocked manually - (fortunately, the login keyring automatically unlocks when you login). With + (fortunately, the login keyring automatically unlocks when you log in). With the built-in ``security`` command, you can access it from the command line, making it useful for ``BORG_PASSCOMMAND``. @@ -524,7 +520,7 @@ Using ``BORG_PASSCOMMAND`` with GNOME Keyring export BORG_PASSCOMMAND="secret-tool lookup borg-repository repo-name" - .. note:: For this to automatically unlock the keychain it must be run + .. note:: For this to unlock the keychain automatically it must be run in the ``dbus`` session of an unlocked terminal; for example, running a backup script as a ``cron`` job might not work unless you also ``export DISPLAY=:0`` so ``secret-tool`` can pick up your open session. `It gets even more complicated`__ @@ -567,13 +563,13 @@ otherwise make unavailable) all your backups. How can I protect against a hacked backup client? ------------------------------------------------- -Assume you backup your backup client machine C to the backup server S and +Assume you back up your backup client machine C to the backup server S and C gets hacked. In a simple push setup, the attacker could then use borg on C to delete all backups residing on S. These are your options to protect against that: -- Do not allow to permanently delete data from the repo, see :ref:`append_only_mode`. +- Do not allow to delete data permanently from the repo, see :ref:`append_only_mode`. - Use a pull-mode setup using ``ssh -R``, see :ref:`pull_backup` for more information. - Mount C's filesystem on another machine and then create a backup of it. - Do not give C filesystem-level access to S. @@ -738,13 +734,13 @@ This has some pros and cons, though: The long term plan to improve this is called "borgception", see :issue:`474`. -Can I backup my root partition (/) with Borg? +Can I back up my root partition (/) with Borg? --------------------------------------------- Backing up your entire root partition works just fine, but remember to -exclude directories that make no sense to backup, such as /dev, /proc, +exclude directories that make no sense to back up, such as /dev, /proc, /sys, /tmp and /run, and to use ``--one-file-system`` if you only want to -backup the root partition (and not any mounted devices e.g.). +back up the root partition (and not any mounted devices e.g.). If it crashes with a UnicodeError, what can I do? ------------------------------------------------- @@ -853,7 +849,7 @@ Then you do the backup and look at the log output: The metadata values used in this comparison are determined by the ``--files-cache`` option and could be e.g. size, ctime and inode number (see the ``borg create`` docs for more details and potential issues). - You can use the ``stat`` command on files to manually look at fs metadata to debug if + You can use the ``stat`` command on files to look at fs metadata manually to debug if there is any unexpected change triggering the ``M`` status. Also, the ``--debug-topic=files_cache`` option of ``borg create`` provides a lot of debug output helping to analyse why the files cache does not give its expected high performance. @@ -955,7 +951,7 @@ Another possible reason is that files don't always have the same path, for example if you mount a filesystem without stable mount points for each backup or if you are running the backup from a filesystem snapshot whose name is not stable. If the directory where you mount a filesystem is different every time, -Borg assumes they are different files. This is true even if you backup these +Borg assumes they are different files. This is true even if you back up these files with relative pathnames - borg uses full pathnames in files cache regardless. It is possible for some filesystems, such as ``mergerfs`` or network filesystems, @@ -1006,7 +1002,7 @@ How can I avoid unwanted base directories getting stored into archives? Possible use cases: -- Another file system is mounted and you want to backup it with original paths. +- Another file system is mounted and you want to back it up with original paths. - You have created a BTRFS snapshot in a ``/.snapshots`` directory for backup. To achieve this, run ``borg create`` within the mountpoint/snapshot directory: @@ -1156,7 +1152,7 @@ full when Borg starts a write command like `borg create`, it will abort immediately and the repository will stay as-is. If you run a backup that stops due to a disk running full, Borg will roll back, -delete the new new segment file and thus freeing disk space automatically. There +delete the new segment file and thus freeing disk space automatically. There may be a checkpoint archive left that has been saved before the disk got full. You can keep it to speed up the next backup or delete it to get back more disk space. diff --git a/docs/installation.rst b/docs/installation.rst index b0e7aaa4..59d20ae8 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -65,7 +65,7 @@ Ubuntu `Ubuntu packages`_, `Ubuntu PPA`_ ``apt install borgbac .. _Alpine repository: https://pkgs.alpinelinux.org/packages?name=borgbackup .. _[community]: https://www.archlinux.org/packages/?name=borg .. _Debian packages: https://packages.debian.org/search?keywords=borgbackup&searchon=names&exact=1&suite=all§ion=all -.. _Fedora official repository: https://apps.fedoraproject.org/packages/borgbackup +.. _Fedora official repository: https://packages.fedoraproject.org/pkgs/borgbackup/borgbackup/ .. _FreeBSD ports: https://www.freshports.org/archivers/py-borgbackup/ .. _ebuild: https://packages.gentoo.org/packages/app-backup/borgbackup .. _GNU Guix: https://www.gnu.org/software/guix/package-list.html#borg @@ -134,7 +134,7 @@ fail if /tmp has not enough free space or is mounted with the ``noexec`` option. You can change the temporary directory by setting the ``TEMP`` environment variable before running Borg. -If a new version is released, you will have to manually download it and replace +If a new version is released, you will have to download it manually and replace the old version using the same steps as shown above. .. _pyinstaller: http://www.pyinstaller.org @@ -331,7 +331,7 @@ optional, but recommended except for the most simple use cases. If you install into a virtual environment, you need to **activate** it first (``source borg-env/bin/activate``), before running ``borg``. Alternatively, symlink ``borg-env/bin/borg`` into some directory that is in - your ``PATH`` so you can just run ``borg``. + your ``PATH`` so you can run ``borg``. This will use ``pip`` to install the latest release from PyPi:: @@ -414,4 +414,4 @@ If you need to use a different version of Python you can install this using ``py source borg-env/bin/activate # always before using! ... -.. note:: As a developer or power user, you always want to use a virtual environment. +.. note:: As a developer or power user, you should always use a virtual environment. diff --git a/docs/internals.rst b/docs/internals.rst index d11f0bfe..e587803c 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -22,7 +22,7 @@ metadata, using :ref:`chunks` created by the chunker using the Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed blocksize algorithm ("fixed" chunker). -To actually perform the repository-wide deduplication, a hash of each +To perform the repository-wide deduplication, a hash of each chunk is checked against the :ref:`chunks cache <cache>`, which is a hash-table of all chunks that already exist. diff --git a/docs/internals/data-structures.rst b/docs/internals/data-structures.rst index fc3ba97c..f0fc9323 100644 --- a/docs/internals/data-structures.rst +++ b/docs/internals/data-structures.rst @@ -157,11 +157,11 @@ An object (the payload part of a segment file log entry) must be like: - compressed data (with an optional all-zero-bytes obfuscation trailer) -This new, more complex repo v2 object format was implemented to be able to efficiently -query the metadata without having to read, transfer and decrypt the (usually much bigger) +This new, more complex repo v2 object format was implemented to be able to query the +metadata efficiently without having to read, transfer and decrypt the (usually much bigger) data part. -The metadata is encrypted to not disclose potentially sensitive information that could be +The metadata is encrypted not to disclose potentially sensitive information that could be used for e.g. fingerprinting attacks. The compression `ctype` and `clevel` is explained in :ref:`data-compression`. @@ -542,7 +542,7 @@ The archive object itself further contains some metadata: in the manifest, but leaves the *name* field of the archives as it was. * *item_ptrs*, a list of "pointer chunk" IDs. Each "pointer chunk" contains a list of chunk IDs of item metadata. -* *cmdline*, the command line which was used to create the archive +* *command_line*, the command line which was used to create the archive * *hostname* * *username* * *time* and *time_end* are the start and end timestamps, respectively @@ -688,7 +688,7 @@ To determine whether a file has not changed, cached values are looked up via the key in the mapping and compared to the current file attribute values. If the file's size, timestamp and inode number is still the same, it is -considered to not have changed. In that case, we check that all file content +considered not to have changed. In that case, we check that all file content chunks are (still) present in the repository (we check that via the chunks cache). @@ -818,7 +818,7 @@ bucket is reached. This particular mode of operation is open addressing with linear probing. When the hash table is filled to 75%, its size is grown. When it's -emptied to 25%, its size is shrinked. Operations on it have a variable +emptied to 25%, its size is shrunken. Operations on it have a variable complexity between constant and linear with low factor, and memory overhead varies between 33% and 300%. @@ -1013,7 +1013,7 @@ while doing no compression at all (none) is a operation that takes no time, it likely will need to store more data to the storage compared to using lz4. The time needed to transfer and store the additional data might be much more than if you had used lz4 (which is super fast, but still might compress your -data about 2:1). This is assuming your data is compressible (if you backup +data about 2:1). This is assuming your data is compressible (if you back up already compressed data, trying to compress them at backup time is usually pointless). diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst index cd9b431c..fbd467e0 100644 --- a/docs/internals/frontends.rst +++ b/docs/internals/frontends.rst @@ -18,9 +18,6 @@ Important: JSON output is expected to be UTF-8, but currently borg depends on th for that (must be a UTF-8 locale and *not* "C" or "ascii"), so that Python will choose to encode to UTF-8. The same applies to any inputs read by borg, they are expected to be UTF-8 encoded also. -We consider this a bug (see :issue:`2273`) and might fix it later, so borg will use UTF-8 independent of -the locale. - On POSIX systems, you can usually set environment vars to choose a UTF-8 locale: :: @@ -29,6 +26,53 @@ On POSIX systems, you can usually set environment vars to choose a UTF-8 locale: export LC_CTYPE=en_US.UTF-8 +Another way to get Python's stdin/stdout/stderr streams to use UTF-8 encoding (without having +a UTF-8 locale / LANG / LC_CTYPE) is: + +:: + + export PYTHONIOENCODING=utf-8 + + +See :issue:`2273` for more details. + + +Dealing with non-unicode byte sequences and JSON limitations +------------------------------------------------------------ + +Paths on POSIX systems can have arbitrary bytes in them (except 0x00 which is used as string terminator in C). + +Nowadays, UTF-8 encoded paths (which decode to valid unicode) are the usual thing, but a lot of systems +still have paths from the past, when other, non-unicode codings were used. Especially old Samba shares often +have wild mixtures of misc. encodings, sometimes even very broken stuff. + +borg deals with such non-unicode paths ("with funny/broken characters") by decoding such byte sequences using +UTF-8 coding and "surrogateescape" error handling mode, which maps invalid bytes to special unicode code points +(surrogate escapes). When encoding such a unicode string back to a byte sequence, the original byte sequence +will be reproduced exactly. + +JSON should only contain valid unicode text without any surrogate escapes, so we can't just directly have a +surrogate-escaped path in JSON ("path" is only one example, this also affects other text-like content). + +Borg deals with this situation like this (since borg 2.0): + +For a valid unicode path (no surrogate escapes), the JSON will only have "path": path. + +For a non-unicode path (with surrogate escapes), the JSON will have 2 entries: + +- "path": path_approximation (pure valid unicode, all invalid bytes will show up as "?") +- "path_b64": path_bytes_base64_encoded (if you decode the base64, you get the original path byte string) + +JSON users need to pick whatever suits their needs best. The suggested procedure (shown for "path") is: + +- check if there is a "path_b64" key. +- if it is there, you will know that the original bytes path did not cleanly UTF-8-decode into unicode (has + some invalid bytes) and that the string given by the "path" key is only an approximation, but not the precise + path. if you need precision, you must base64-decode the value of "path_b64" and deal with the arbitrary byte + string you'll get. if an approximation is fine, use the value of the "path" key. +- if it is not there, the value of the "path" key is all you need (the original bytes path is its UTF-8 encoding). + + Logging ------- @@ -40,8 +84,6 @@ where each line is a JSON object. The *type* key of the object determines its ot parsing error will be printed in plain text, because logging set-up happens after all arguments are parsed. -Since JSON can only encode text, any string representing a file system path may miss non-text parts. - The following types are in use. Progress information is governed by the usual rules for progress information, it is not produced unless ``--progress`` is specified. @@ -438,8 +480,9 @@ Refer to the *borg list* documentation for the available keys and their meaning. Example (excerpt) of ``borg list --json-lines``:: - {"type": "d", "mode": "drwxr-xr-x", "user": "user", "group": "user", "uid": 1000, "gid": 1000, "path": "linux", "healthy": true, "source": "", "linktarget": "", "flags": null, "mtime": "2017-02-27T12:27:20.023407", "size": 0} - {"type": "d", "mode": "drwxr-xr-x", "user": "user", "group": "user", "uid": 1000, "gid": 1000, "path": "linux/baz", "healthy": true, "source": "", "linktarget": "", "flags": null, "mtime": "2017-02-27T12:27:20.585407", "size": 0} + {"type": "d", "mode": "drwxr-xr-x", "user": "user", "group": "user", "uid": 1000, "gid": 1000, "path": "linux", "healthy": true, "target": "", "flags": null, "mtime": "2017-02-27T12:27:20.023407", "size": 0} + {"type": "d", "mode": "drwxr-xr-x", "user": "user", "group": "user", "uid": 1000, "gid": 1000, "path": "linux/baz", "healthy": true, "target": "", "flags": null, "mtime": "2017-02-27T12:27:20.585407", "size": 0} + Archive Differencing ++++++++++++++++++++ @@ -546,7 +589,7 @@ Errors Buffer.MemoryLimitExceeded Requested buffer size {} is above the limit of {}. ExtensionModuleError - The Borg binary extension modules do not seem to be properly installed + The Borg binary extension modules do not seem to be installed properly IntegrityError Data integrity error: {} NoManifestError @@ -638,4 +681,4 @@ Prompts BORG_CHECK_I_KNOW_WHAT_I_AM_DOING For "This is a potentially dangerous function..." (check --repair) BORG_DELETE_I_KNOW_WHAT_I_AM_DOING - For "You requested to completely DELETE the repository *including* all archives it contains:" + For "You requested to DELETE the repository completely *including* all archives it contains:" diff --git a/docs/internals/security.rst b/docs/internals/security.rst index b719ffba..38d693d0 100644 --- a/docs/internals/security.rst +++ b/docs/internals/security.rst @@ -60,7 +60,7 @@ In other words, the object ID itself only authenticates the plaintext of the object and not its context or meaning. The latter is established by a different object referring to an object ID, thereby assigning a particular meaning to an object. For example, an archive item contains a list of object IDs that -represent packed file metadata. On their own it's not clear that these objects +represent packed file metadata. On their own, it's not clear that these objects would represent what they do, but by the archive item referring to them in a particular part of its own data structure assigns this meaning. @@ -277,7 +277,7 @@ SSH server -- Borg RPC does not contain *any* networking code. Networking is done by the SSH client running in a separate process, Borg only communicates over the standard pipes (stdout, stderr and stdin) with this process. This also means that Borg doesn't -have to directly use a SSH client (or SSH at all). For example, +have to use a SSH client directly (or SSH at all). For example, ``sudo`` or ``qrexec`` could be used as an intermediary. By using the system's SSH client and not implementing a diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1 index cffa5dfe..5cf1a841 100644 --- a/docs/man/borg-benchmark-cpu.1 +++ b/docs/man/borg-benchmark-cpu.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-BENCHMARK-CPU" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-benchmark-cpu \- Benchmark CPU bound operations. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 665039a4..3e2e76b6 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-BENCHMARK-CRUD" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index c08c6f4c..22117722 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-BENCHMARK" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command .SH SYNOPSIS diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index 1a1775d6..1befd2bf 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-BREAK-LOCK" 1 "2023-02-26" "" "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 diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 5edef416..724a800a 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-CHECK" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency .SH SYNOPSIS @@ -141,9 +141,6 @@ perform cryptographic archive data integrity verification (conflicts with \fB\-\ .B \-\-repair attempt to repair any inconsistencies found .TP -.B \-\-save\-space -work slower, but using less space -.TP .BI \-\-max\-duration \ SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited) .UNINDENT @@ -161,6 +158,18 @@ consider first N archives after other filters were applied .TP .BI \-\-last \ N consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SH SEE ALSO .sp diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index cb959688..3549b52f 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-COMMON" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands .SH SYNOPSIS @@ -87,9 +87,6 @@ set network upload rate limit in kiByte/s (default: 0=unlimited) .BI \-\-upload\-buffer \ UPLOAD_BUFFER set network upload buffer size in MiB. (default: 0=no buffer) .TP -.B \-\-consider\-part\-files -treat part files like normal files (e.g. to list/extract them) -.TP .BI \-\-debug\-profile \ FILE Write execution profile in Borg format into FILE. For local use a Python\-compatible file can be generated by suffixing FILE with \(dq.pyprof\(dq. .TP diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index c6a7b8b0..6141bb65 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-COMPACT" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-compact \- compact segment files in the repository .SH SYNOPSIS diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index 307a50b8..b72b51c6 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-COMPRESSION" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression .SH DESCRIPTION diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index ec345280..81e7887c 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-CONFIG" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-config \- get, set, and delete values in a repository or cache config file .SH SYNOPSIS diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 5bd06bf0..a83a6143 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-CREATE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-create \- Create new archive .SH SYNOPSIS @@ -107,9 +107,9 @@ creation of a new archive to ensure fast operation. This is because the file cac is used to determine changed files quickly uses absolute filenames. If this is not possible, consider creating a bind mount to a stable location. .sp -The \fB\-\-progress\fP option shows (from left to right) Original, Compressed and Deduplicated -(O, C and D, respectively), then the Number of files (N) processed so far, followed by -the currently processed path. +The \fB\-\-progress\fP option shows (from left to right) Original and (uncompressed) +deduplicated size (O and U respectively), then the Number of files (N) processed so far, +followed by the currently processed path. .sp When using \fB\-\-stats\fP, you will get some statistics about how much data was added \- the \(dqThis Archive\(dq deduplicated size there is most interesting as that is @@ -157,10 +157,10 @@ experimental: do not synchronize the cache. Implies not using the files cache. use NAME in archive for stdin data (default: \(aqstdin\(aq) .TP .BI \-\-stdin\-user \ USER -set user USER in archive for stdin data (default: \(aqroot\(aq) +set user USER in archive for stdin data (default: do not store user/uid) .TP .BI \-\-stdin\-group \ GROUP -set group GROUP in archive for stdin data (default: \(aqwheel\(aq) +set group GROUP in archive for stdin data (default: do not store group/gid) .TP .BI \-\-stdin\-mode \ M set mode to M in archive for stdin data (default: 0660) @@ -169,7 +169,7 @@ set mode to M in archive for stdin data (default: 0660) interpret PATH as command and store its stdout. See also section Reading from stdin below. .TP .B \-\-paths\-from\-stdin -read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories. +read DELIM\-separated list of paths to back up from stdin. Will not recurse into directories. .TP .B \-\-paths\-from\-command interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP @@ -252,6 +252,9 @@ manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH: .BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS write checkpoint every SECONDS seconds (Default: 1800) .TP +.BI \-\-checkpoint\-volume \ BYTES +write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) +.TP .BI \-\-chunker\-params \ PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 .TP @@ -334,9 +337,9 @@ $ cd /home/user/Documents $ 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 +# Use \-\-paths\-from\-stdin with find to back up only files less than 1MB in size $ 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 +# Use \-\-paths\-from\-command with find to back up files from only a given user $ 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 @@ -420,11 +423,11 @@ borg usually just stores their metadata: Other flags used include: .INDENT 0.0 .IP \(bu 2 -\(aqi\(aq = backup data was read from standard input (stdin) +\(aq+\(aq = included, item would be backed up (if not in dry\-run mode) .IP \(bu 2 -\(aq\-\(aq = dry run, item was \fInot\fP backed up +\(aq\-\(aq = excluded, item would not be / was not backed up .IP \(bu 2 -\(aqx\(aq = excluded, item was \fInot\fP backed up +\(aqi\(aq = backup data was read from standard input (stdin) .IP \(bu 2 \(aq?\(aq = missing status code (if you see this, please file a bug report!) .UNINDENT @@ -477,7 +480,7 @@ By default, the content read from stdin is stored in a file called \(aqstdin\(aq Use \fB\-\-stdin\-name\fP to change the name. .SH SEE ALSO .sp -\fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP +\fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP, \fIborg\-rcreate(1)\fP .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 7346994a..df37d69f 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-DELETE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-delete \- Delete archives .SH SYNOPSIS @@ -76,9 +76,6 @@ delete only the local cache for the given repository .B \-\-force force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work. .TP -.B \-\-save\-space -work slower, but using less space -.TP .BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS write checkpoint every SECONDS seconds (Default: 1800) .UNINDENT @@ -96,6 +93,18 @@ consider first N archives after other filters were applied .TP .BI \-\-last \ N consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SH EXAMPLES .INDENT 0.0 @@ -122,7 +131,7 @@ $ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq .UNINDENT .SH SEE ALSO .sp -\fIborg\-common(1)\fP, \fIborg\-compact(1)\fP +\fIborg\-common(1)\fP, \fIborg\-compact(1)\fP, \fIborg\-rdelete(1)\fP .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index dd6b3d41..eb085f69 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-DIFF" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives .SH SYNOPSIS diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 76b3809e..08c5f59b 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-EXPORT-TAR" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index bc0e42e6..a5acac87 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-EXTRACT" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents .SH SYNOPSIS diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index abcce34d..fafd99bf 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-IMPORT-TAR" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS @@ -122,6 +122,9 @@ manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH: .BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS write checkpoint every SECONDS seconds (Default: 1800) .TP +.BI \-\-checkpoint\-volume \ BYTES +write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) +.TP .BI \-\-chunker\-params \ PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 .TP @@ -166,7 +169,7 @@ 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\(ga +for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq\(ga do echo \(dqborg \-r repo1 export\-tar \-\-tar\-format=BORG $A \- | borg \-r repo2 import\-tar \-\-timestamp=$T $A \-\(dq done diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index a1b32468..2b368449 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-INFO" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used .SH SYNOPSIS @@ -68,6 +68,18 @@ consider first N archives after other filters were applied .TP .BI \-\-last \ N consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SH EXAMPLES .INDENT 0.0 @@ -95,7 +107,7 @@ Deduplicated size: 531 B .UNINDENT .SH SEE ALSO .sp -\fIborg\-common(1)\fP, \fIborg\-list(1)\fP, \fIborg\-diff(1)\fP +\fIborg\-common(1)\fP, \fIborg\-list(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-rinfo(1)\fP .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1 index 17d27914..cc76d1fd 100644 --- a/docs/man/borg-key-change-location.1 +++ b/docs/man/borg-key-change-location.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-LOCATION" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-key-change-location \- Change repository key location .SH SYNOPSIS diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 3fd1f5a9..3d541037 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS @@ -86,7 +86,7 @@ Fully automated using environment variables: .sp .nf .ft C -$ BORG_NEW_PASSPHRASE=old borg rcreate \-e=repokey +$ BORG_NEW_PASSPHRASE=old borg rcreate \-\-encryption=repokey\-aes\-ocb # now \(dqold\(dq is the current passphrase. $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase # now \(dqnew\(dq is the current passphrase. diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index c6169013..822f7509 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-KEY-EXPORT" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup .SH SYNOPSIS @@ -36,7 +36,7 @@ borg [common options] key export [options] [PATH] .SH DESCRIPTION .sp If repository encryption is used, the repository is inaccessible -without the key. This command allows one to backup this essential key. +without the key. This command allows one to back up this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index 0265ec92..e258f4e6 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-KEY-IMPORT" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup .SH SYNOPSIS diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 1c7a3dd8..54090616 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-KEY" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index 270aa147..1512e01a 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-LIST" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-list \- List archive contents .SH SYNOPSIS @@ -60,7 +60,7 @@ only print file/directory names, nothing else specify format for file listing (default: \(dq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(dq) .TP .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 \(dqbpath\(dq key is therefore not available. +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. .UNINDENT .SS Exclusion options .INDENT 0.0 @@ -150,7 +150,7 @@ 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 +NUL: NUL character for creating print0 / xargs \-0 like output .IP \(bu 2 SPACE .IP \(bu 2 @@ -176,13 +176,9 @@ user .IP \(bu 2 group .IP \(bu 2 -path: path interpreted as text (might be missing non\-text characters, see bpath) +path: file path .IP \(bu 2 -bpath: verbatim POSIX path, can contain any character except NUL -.IP \(bu 2 -source: link target for symlinks (identical to linktarget) -.IP \(bu 2 -linktarget +target: link target for symlinks .IP \(bu 2 hlid: hard link identity (same if hardlinking same fs object) .IP \(bu 2 @@ -238,13 +234,13 @@ archiveid .IP \(bu 2 archivename .IP \(bu 2 -extra: prepends {source} with \(dq \-> \(dq for soft links and \(dq link to \(dq for hard links +extra: prepends {target} with \(dq \-> \(dq for soft links and \(dq link to \(dq for hard links .IP \(bu 2 health: either \(dqhealthy\(dq (file ok) or \(dqbroken\(dq (if file has all\-zero replacement chunks) .UNINDENT .SH SEE ALSO .sp -\fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP +\fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-rlist(1)\fP .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-match-archives.1 b/docs/man/borg-match-archives.1 new file mode 100644 index 00000000..addd92fd --- /dev/null +++ b/docs/man/borg-match-archives.1 @@ -0,0 +1,75 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BORG-MATCH-ARCHIVES" 1 "2023-02-26" "" "borg backup tool" +.SH NAME +borg-match-archives \- Details regarding match-archives +.SH DESCRIPTION +.sp +The \fB\-\-match\-archives\fP option matches a given pattern against the list of all archive +names in the repository. +.sp +It uses pattern styles similar to the ones described by \fBborg help patterns\fP: +.INDENT 0.0 +.TP +.B Identical match pattern, selector \fBid:\fP (default) +Simple string match, must fully match exactly as given. +.TP +.B Shell\-style patterns, selector \fBsh:\fP +Match like on the shell, wildcards like \fI*\fP and \fI?\fP work. +.TP +.B \fI\%Regular expressions\fP, selector \fBre:\fP +Full regular expression support. +This is very powerful, but can also get rather complicated. +.UNINDENT +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# id: style +borg delete \-\-match\-archives \(aqid:archive\-with\-crap\(aq +borg delete \-a \(aqid:archive\-with\-crap\(aq # same, using short option +borg delete \-a \(aqarchive\-with\-crap\(aq # same, because \(aqid:\(aq is the default + +# sh: style +borg delete \-a \(aqsh:home\-kenny\-*\(aq + +# re: style +borg delete \-a \(aqre:pc[123]\-home\-(user1|user2)\-2022\-09\-.*\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index bb9a71ea..418fd8dc 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-MOUNT" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS @@ -91,7 +91,7 @@ of CPU cores. .sp When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process -to unintentionally delete data. +to delete data unintentionally. .sp When running in the foreground ^C/SIGINT unmounts cleanly, but other signals or crashes do not. @@ -136,6 +136,18 @@ consider first N archives after other filters were applied .TP .BI \-\-last \ N consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SS Exclusion options .INDENT 0.0 diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 817ade7e..6ee1a4a0 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -27,7 +27,7 @@ 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-11-26" "" "borg backup tool" +.TH "BORG-PATTERNS" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns .SH DESCRIPTION @@ -257,14 +257,14 @@ Examples: .sp .nf .ft C -# backup pics, but not the ones from 2018, except the good ones: +# back up pics, but not the ones from 2018, except the good ones: # note: using = is essential to avoid cmdline argument parsing issues. borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 archive pics -# backup only JPG/JPEG files (case insensitive) in all home directories: +# back up only JPG/JPEG files (case insensitive) in all home directories: borg create \-\-pattern \(aq+ re:\e.jpe?g(?i)$\(aq archive /home -# backup homes, but exclude big downloads (like .ISO files) or hidden files: +# back up homes, but exclude big downloads (like .ISO files) or hidden files: borg create \-\-exclude \(aqre:\e.iso(?i)$\(aq \-\-exclude \(aqsh:home/**/.*\(aq archive /home # use a file with patterns (recursion root \(aq/\(aq via command line): @@ -287,7 +287,7 @@ The patterns.lst file could look like that: + home/susan # also back up this exact file + pf:home/bobby/specialfile.txt -# don\(aqt backup the other home directories +# don\(aqt back up the other home directories \- home/* # don\(aqt even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too) ! re:^(dev|proc|run|sys|tmp) diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 008163b4..6fd2df3c 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -27,7 +27,7 @@ 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-PLACEHOLDERS" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-PLACEHOLDERS" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders .SH DESCRIPTION diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index dd5a1734..b505b077 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -27,7 +27,7 @@ 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-PRUNE" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-PRUNE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules .SH SYNOPSIS @@ -73,12 +73,12 @@ As an example, \fB\-\-keep\-daily 7\fP means to keep the latest backup on each d up to 7 most recent days with backups (days without backups do not count). The rules are applied from secondly to yearly, and backups selected by previous rules do not count towards those of later rules. The time that each backup -starts is used for pruning purposes. Dates and times are interpreted in -the local timezone, and weeks go from Monday to Sunday. Specifying a -negative number of archives to keep means that there is no limit. As of borg -1.2.0, borg will retain the oldest archive if any of the secondly, minutely, -hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet -its retention target. This enables the first chronological archive to continue +starts is used for pruning purposes. Dates and times are interpreted in the local +timezone of the system where borg prune runs, and weeks go from Monday to Sunday. +Specifying a negative number of archives to keep means that there is no limit. +As of borg 1.2.0, borg will retain the oldest archive if any of the secondly, +minutely, hourly, daily, weekly, monthly, or yearly rules was not otherwise able to +meet its retention target. This enables the first chronological archive to continue aging until it is replaced by a newer archive that meets the retention criteria. .sp The \fB\-\-keep\-last N\fP option is doing the same as \fB\-\-keep\-secondly N\fP (and it will @@ -131,9 +131,6 @@ number of monthly archives to keep .B \-y\fP,\fB \-\-keep\-yearly number of yearly archives to keep .TP -.B \-\-save\-space -work slower, but using less space -.TP .BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS write checkpoint every SECONDS seconds (Default: 1800) .UNINDENT @@ -142,6 +139,18 @@ write checkpoint every SECONDS seconds (Default: 1800) .TP .BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN only consider archive names matching the pattern. see \(dqborg help match\-archives\(dq. +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SH EXAMPLES .sp diff --git a/docs/man/borg-rcompress.1 b/docs/man/borg-rcompress.1 new file mode 100644 index 00000000..0dde9d8a --- /dev/null +++ b/docs/man/borg-rcompress.1 @@ -0,0 +1,100 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BORG-RCOMPRESS" 1 "2023-02-26" "" "borg backup tool" +.SH NAME +borg-rcompress \- Repository (re-)compression +.SH SYNOPSIS +.sp +borg [common options] rcompress [options] +.SH DESCRIPTION +.sp +Repository (re\-)compression (and/or re\-obfuscation). +.sp +Reads all chunks in the repository (in on\-disk order, this is important for +compaction) and recompresses them if they are not already using the compression +type/level and obfuscation level given via \fB\-\-compression\fP\&. +.sp +If the outcome of the chunk processing indicates a change in compression +type/level or obfuscation level, the processed chunk is written to the repository. +Please note that the outcome might not always be the desired compression +type/level \- if no compression gives a shorter output, that might be chosen. +.sp +Every \fB\-\-checkpoint\-interval\fP, progress is committed to the repository and +the repository is compacted (this is to keep temporary repo space usage in bounds). +A lower checkpoint interval means lower temporary repo space usage, but also +slower progress due to higher overhead (and vice versa). +.sp +Please note that this command can not work in low (or zero) free disk space +conditions. +.sp +If the \fBborg rcompress\fP process receives a SIGINT signal (Ctrl\-C), the repo +will be committed and compacted and borg will terminate cleanly afterwards. +.sp +Both \fB\-\-progress\fP and \fB\-\-stats\fP are recommended when \fBborg rcompress\fP +is used interactively. +.sp +You do \fBnot\fP need to run \fBborg compact\fP after \fBborg rcompress\fP\&. +.SH OPTIONS +.sp +See \fIborg\-common(1)\fP for common options of Borg commands. +.SS options +.INDENT 0.0 +.TP +.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION +select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. +.TP +.B \-s\fP,\fB \-\-stats +print statistics +.TP +.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS +write checkpoint every SECONDS seconds (Default: 1800) +.UNINDENT +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# recompress repo contents +$ borg rcompress \-\-progress \-\-compression=zstd,3 + +# recompress and obfuscate repo contents +$ borg rcompress \-\-progress \-\-compression=obfuscate,1,zstd,3 +.ft P +.fi +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fIborg\-common(1)\fP +.SH AUTHOR +The Borg Collective +.\" Generated by docutils manpage writer. +. diff --git a/docs/man/borg-rcreate.1 b/docs/man/borg-rcreate.1 index 8d89cca6..949ca879 100644 --- a/docs/man/borg-rcreate.1 +++ b/docs/man/borg-rcreate.1 @@ -27,7 +27,7 @@ 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-RCREATE" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-RCREATE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-rcreate \- Create a new, empty repository .SH SYNOPSIS @@ -110,7 +110,7 @@ The easiest way to find out about what\(aqs fastest is to run \fBborg benchmark \fIrepokey\fP modes: if you want ease\-of\-use and \(dqpassphrase\(dq security is good enough \- the key will be stored in the repository (in \fBrepo_dir/config\fP). .sp -\fIkeyfile\fP modes: if you rather want \(dqpassphrase and having\-the\-key\(dq security \- +\fIkeyfile\fP modes: if you want \(dqpassphrase and having\-the\-key\(dq security \- the key will be stored in your home directory (in \fB~/.config/borg/keys\fP). .sp The following table is roughly sorted in order of preference, the better ones are @@ -205,7 +205,7 @@ _ .\" nanorst: inline-replace . .sp -\fInone\fP mode uses no encryption and no authentication. You\(aqre advised to NOT use this mode +\fInone\fP mode uses no encryption and no authentication. You\(aqre advised NOT to use this mode as it would expose you to all sorts of issues (DoS, confidentiality, tampering, ...) in case of malicious activity in the repository. .sp @@ -277,7 +277,7 @@ $ borg rcreate \-\-encryption=keyfile\-aes\-ocb .UNINDENT .SH SEE ALSO .sp -\fIborg\-common(1)\fP, \fIborg\-rdelete(1)\fP, \fIborg\-rlist(1)\fP, \fIborg\-check(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP +\fIborg\-common(1)\fP, \fIborg\-rdelete(1)\fP, \fIborg\-rlist(1)\fP, \fIborg\-check(1)\fP, \fIborg\-benchmark\-cpu(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-rdelete.1 b/docs/man/borg-rdelete.1 index 0b83646c..e231e501 100644 --- a/docs/man/borg-rdelete.1 +++ b/docs/man/borg-rdelete.1 @@ -27,7 +27,7 @@ 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-RDELETE" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-RDELETE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-rdelete \- Delete a repository .SH SYNOPSIS @@ -72,7 +72,7 @@ keep the local security info when deleting a repository .ft C # delete the whole repository and the related local cache: $ borg rdelete -You requested to completely DELETE the repository *including* all archives it contains: +You requested to DELETE the repository completely *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 diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 757c2f80..cede6615 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -27,7 +27,7 @@ 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-RECREATE" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-RECREATE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives .SH SYNOPSIS @@ -59,8 +59,8 @@ There is no risk of data loss by this. used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives. .sp \fBUSE WITH CAUTION.\fP -Depending on the PATHs and patterns given, recreate can be used to permanently -delete files from archives. +Depending on the PATHs and patterns given, recreate can be used to +delete files from archives permanently. When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are interpreted. See \fIlist_item_flags\fP in \fBborg create\fP for details. .sp @@ -147,12 +147,27 @@ consider first N archives after other filters were applied .BI \-\-last \ N consider last N archives after other filters were applied .TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. +.TP .BI \-\-target \ TARGET create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) .TP .BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS write checkpoint every SECONDS seconds (Default: 1800) .TP +.BI \-\-checkpoint\-volume \ BYTES +write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) +.TP .BI \-\-comment \ COMMENT add a comment text to the archive .TP @@ -163,10 +178,10 @@ manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH: select compression algorithm, see the output of the \(dqborg help compression\(dq command for details. .TP .BI \-\-recompress \ MODE -recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIif\-different\fP: recompress if current compression is with a different compression algorithm or different level; \fIalways\fP: recompress unconditionally; and \fInever\fP: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, \fIif\-different\fP will be used. Not passing \-\-recompress is equivalent to \(dq\-\-recompress never\(dq. +recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIif\-different\fP: recompress if current compression is with a different compression algorithm or different level; \fIalways\fP: recompress unconditionally; and \fInever\fP: do not recompress (use this option explicitly to prevent recompression). If no MODE is given, \fIif\-different\fP will be used. Not passing \-\-recompress is equivalent to \(dq\-\-recompress never\(dq. .TP .BI \-\-chunker\-params \ PARAMS -specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: buzhash,19,23,21,4095 +rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the chunker defaults. default: do not rechunk .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 231e30dc..e4bacaf7 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -27,7 +27,7 @@ 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-RENAME" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-RENAME" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive .SH SYNOPSIS diff --git a/docs/man/borg-rinfo.1 b/docs/man/borg-rinfo.1 index 1761aa1b..6edf65d9 100644 --- a/docs/man/borg-rinfo.1 +++ b/docs/man/borg-rinfo.1 @@ -27,7 +27,7 @@ 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-RINFO" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-RINFO" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-rinfo \- Show repository infos .SH SYNOPSIS diff --git a/docs/man/borg-rlist.1 b/docs/man/borg-rlist.1 index e11b184d..414922da 100644 --- a/docs/man/borg-rlist.1 +++ b/docs/man/borg-rlist.1 @@ -27,7 +27,7 @@ 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-RLIST" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-RLIST" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-rlist \- List the archives contained in a repository .SH SYNOPSIS @@ -52,7 +52,7 @@ only print the archive names, nothing else specify format for archive listing (default: \(dq{archive:<36} {time} [{id}]{NL}\(dq) .TP .B \-\-json -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 \(dqbarchive\(dq key is therefore not available. +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. .UNINDENT .SS Archive filters .INDENT 0.0 @@ -68,6 +68,18 @@ consider first N archives after other filters were applied .TP .BI \-\-last \ N consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SH EXAMPLES .INDENT 0.0 @@ -119,7 +131,7 @@ 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 +NUL: NUL character for creating print0 / xargs \-0 like output .IP \(bu 2 SPACE .IP \(bu 2 @@ -133,15 +145,11 @@ LF 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) +archive: archive name .IP \(bu 2 name: alias of \(dqarchive\(dq .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 +comment: archive comment .IP \(bu 2 id: internal ID of the archive .IP \(bu 2 diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index 4436e401..cc53c3f3 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -27,7 +27,7 @@ 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-SERVE" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-SERVE" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. .SH SYNOPSIS @@ -43,10 +43,10 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .INDENT 0.0 .TP .BI \-\-restrict\-to\-path \ PATH -restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository. +restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to point directly to a repository. .TP .BI \-\-restrict\-to\-repository \ PATH -restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. +restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. .TP .B \-\-append\-only only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details. @@ -79,7 +79,7 @@ locations like \fB/etc/environment\fP or in the forced command itself (example b .sp .nf .ft C -# Allow an SSH keypair to only run borg, and only have access to /path/to/repo. +# Allow an SSH keypair to run only borg, and only have access to /path/to/repo. # Use key options to disable unneeded and potentially dangerous SSH functionality. # This will help to secure an automated remote backup system. $ cat ~/.ssh/authorized_keys @@ -100,7 +100,7 @@ The examples above use the \fBrestrict\fP directive. This does automatically block potential dangerous ssh features, even when they are added in a future update. Thus, this option should be preferred. .sp -If you\(aqre using openssh\-server < 7.2, however, you have to explicitly specify +If you\(aqre using openssh\-server < 7.2, however, you have to specify explicitly the ssh features to restrict and cannot simply use the restrict option as it has been introduced in v7.2. We recommend to use \fBno\-port\-forwarding,no\-X11\-forwarding,no\-pty,no\-agent\-forwarding,no\-user\-rc\fP diff --git a/docs/man/borg-transfer.1 b/docs/man/borg-transfer.1 index 481ef0c2..07c21e3b 100644 --- a/docs/man/borg-transfer.1 +++ b/docs/man/borg-transfer.1 @@ -27,7 +27,7 @@ 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-TRANSFER" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-TRANSFER" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-transfer \- archives transfer from other repository, optionally upgrade data format .SH SYNOPSIS @@ -104,6 +104,18 @@ consider first N archives after other filters were applied .TP .BI \-\-last \ N consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index c62e20a5..9270ad1b 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -27,7 +27,7 @@ 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-UMOUNT" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-UMOUNT" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem .SH SYNOPSIS @@ -104,7 +104,7 @@ root\-2016\-02\-01 root\-2016\-02\-2015 .INDENT 3.5 \fBborgfs\fP will be automatically provided if you used a distribution package, \fBpip\fP or \fBsetup.py\fP to install Borg. Users of the -standalone binary will have to manually create a symlink (see +standalone binary will have to create a symlink manually (see \fIpyinstaller\-binary\fP). .UNINDENT .UNINDENT diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index ffaf7e68..32b18448 100644 --- a/docs/man/borg-upgrade.1 +++ b/docs/man/borg-upgrade.1 @@ -56,8 +56,8 @@ except when noted otherwise in the changelog Use \fBborg upgrade \-\-tam REPO\fP to require manifest authentication introduced with Borg 1.0.9 to address security issues. This means that modifying the repository after doing this with a version prior -to 1.0.9 will raise a validation error, so only perform this upgrade -after updating all clients using the repository to 1.0.9 or newer. +to 1.0.9 will raise a validation error, so perform this upgrade +only after updating all clients using the repository to 1.0.9 or newer. .sp This upgrade should be done on each client for safety reasons. .sp diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 94493ea1..b16ed4b4 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -27,7 +27,7 @@ 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-WITH-LOCK" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG-WITH-LOCK" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held .SH SYNOPSIS diff --git a/docs/man/borg.1 b/docs/man/borg.1 index c00a3b03..027e93f8 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -27,7 +27,7 @@ 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" 1 "2022-11-26" "" "borg backup tool" +.TH "BORG" 1 "2023-02-26" "" "borg backup tool" .SH NAME borg \- deduplicating and encrypting backup tool .SH SYNOPSIS @@ -40,11 +40,11 @@ borg [common options] <command> [options] [arguments] BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. .sp -The main goal of Borg is to provide an efficient and secure way to backup data. +The main goal of Borg is to provide an efficient and secure way to back data up. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. -The authenticated encryption technique makes it suitable for backups to not -fully trusted targets. +The authenticated encryption technique makes it suitable for backups to targets not +fully trusted. .sp Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collection of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not @@ -54,7 +54,7 @@ it does not matter when or where archives were created (e.g. different hosts). .SS A step\-by\-step example .INDENT 0.0 .IP 1. 3 -Before a backup can be made a repository has to be initialized: +Before a backup can be made, a repository has to be initialized: .INDENT 3.0 .INDENT 3.5 .sp @@ -66,7 +66,7 @@ $ borg \-r /path/to/repo rcreate \-\-encryption=repokey\-aes\-ocb .UNINDENT .UNINDENT .IP 2. 3 -Backup the \fB~/src\fP and \fB~/Documents\fP directories into an archive called +Back up the \fB~/src\fP and \fB~/Documents\fP directories into an archive called \fIMonday\fP: .INDENT 3.0 .INDENT 3.5 @@ -91,7 +91,7 @@ $ borg \-r /path/to/repo create \-\-stats Tuesday ~/src ~/Documents .UNINDENT .UNINDENT .sp -This backup will be a lot quicker and a lot smaller since only new never +This backup will be a lot quicker and a lot smaller since only new, never before seen data is stored. The \fB\-\-stats\fP option causes Borg to output statistics about the newly created archive such as the deduplicated size (the amount of unique data not shared with other archives): @@ -189,7 +189,7 @@ $ borg \-r /path/to/repo compact \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 -Borg is quiet by default (it works on WARNING log level). +Borg is quiet by default (it defaults to WARNING log level). You can use options like \fB\-\-progress\fP or \fB\-\-list\fP to get specific reports during command execution. You can also add the \fB\-v\fP (or \fB\-\-verbose\fP or \fB\-\-info\fP) option to adjust the log level to INFO to @@ -404,7 +404,7 @@ If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence. When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for. This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also be checked. -Main usecase for this is to fully automate \fBborg change\-passphrase\fP\&. +Main usecase for this is to automate fully \fBborg change\-passphrase\fP\&. .TP .B BORG_DISPLAY_PASSPHRASE When set, use the value to answer the \(dqdisplay the passphrase for verification\(dq question when defining a new passphrase for encrypted repositories. @@ -413,7 +413,7 @@ When set, use the value to answer the \(dqdisplay the passphrase for verificatio Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns a unique id based on the MAC address of the network interface. Except if that MAC happens to be all\-zero \- in that case it returns a random value, which is not what we want (because it kills automatic stale lock removal). -So, if you have a all\-zero MAC address or other reasons to better externally control the host id, just set this +So, if you have a all\-zero MAC address or other reasons to control better externally the host id, just set this environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not, use \fI\%fqdn@uniqueid\fP\&. .TP @@ -441,7 +441,7 @@ cache entries for backup sources other than the current sources. .TP .B BORG_FILES_CACHE_TTL When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache -entries (default: 20). The files cache is used to quickly determine whether a file is unchanged. +entries (default: 20). The files cache is used to determine quickly whether a file is unchanged. The FAQ explains this more detailed in: \fIalways_chunking\fP .TP .B BORG_SHOW_SYSINFO @@ -509,7 +509,7 @@ For \(dqWarning: The repository at location ... was previously located at ...\(d For \(dqThis is a potentially dangerous function...\(dq (check \-\-repair) .TP .B BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES) -For \(dqYou requested to completely DELETE the repository \fIincluding\fP all archives it contains:\(dq +For \(dqYou requested to DELETE the repository completely \fIincluding\fP all archives it contains:\(dq .UNINDENT .sp Note: answers are case sensitive. setting an invalid answer value might either give the default @@ -567,10 +567,6 @@ Adds given OpenSSL header file directory to the default locations (setup.py). Adds given prefix directory to the default locations. If a \(aqinclude/lz4.h\(aq is found Borg will be linked against the system liblz4 instead of a bundled implementation. (setup.py) .TP -.B BORG_LIBB2_PREFIX -Adds given prefix directory to the default locations. If a \(aqinclude/blake2.h\(aq is found Borg -will be linked against the system libb2 instead of a bundled implementation. (setup.py) -.TP .B BORG_LIBZSTD_PREFIX Adds given prefix directory to the default locations. If a \(aqinclude/zstd.h\(aq is found Borg will be linked against the system libzstd instead of a bundled implementation. (setup.py) @@ -737,7 +733,7 @@ If your repository is remote, all deduplicated (and optionally compressed/ encrypted) data of course has to go over the connection (\fBssh://\fP repo url). If you use a locally mounted network filesystem, additionally some copy operations used for transaction support also go over the connection. If -you backup multiple sources to one target repository, additional traffic +you back up multiple sources to one target repository, additional traffic happens for cache resynchronization. .UNINDENT .SS Support for file metadata diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index c866a293..754d29cf 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -27,7 +27,7 @@ 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 "BORGFS" 1 "2022-11-26" "" "borg backup tool" +.TH "BORGFS" 1 "2023-02-26" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS @@ -80,6 +80,18 @@ consider first N archives after other filters were applied .TP .BI \-\-last \ N consider last N archives after other filters were applied +.TP +.BI \-\-oldest \ TIMESPAN +consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-newest \ TIMESPAN +consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m. +.TP +.BI \-\-older \ TIMESPAN +consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m. +.TP +.BI \-\-newer \ TIMESPAN +consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m. .UNINDENT .SS Exclusion options .INDENT 0.0 diff --git a/docs/man_intro.rst b/docs/man_intro.rst index 0a072f62..38c7dc66 100644 --- a/docs/man_intro.rst +++ b/docs/man_intro.rst @@ -13,11 +13,11 @@ DESCRIPTION BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. -The main goal of Borg is to provide an efficient and secure way to backup data. +The main goal of Borg is to provide an efficient and secure way to back data up. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. -The authenticated encryption technique makes it suitable for backups to not -fully trusted targets. +The authenticated encryption technique makes it suitable for backups to targets not +fully trusted. Borg stores a set of files in an *archive*. A *repository* is a collection of *archives*. The format of repositories is Borg-specific. Borg does not diff --git a/docs/misc/asciinema/Vagrantfile b/docs/misc/asciinema/Vagrantfile index 73d88249..75a25c6c 100644 --- a/docs/misc/asciinema/Vagrantfile +++ b/docs/misc/asciinema/Vagrantfile @@ -15,7 +15,7 @@ Vagrant.configure("2") do |config| SHELL config.vm.provision "record basic usage", type: "shell", inline: <<-SHELL # `rm` below allows quick re-exec via: - # vagrant vagrant provision --provision-with "record basic usage" + # vagrant provision --provision-with "record basic usage" # this is useful when testing changes rm -r /media/backup/borgdemo || true rm -r ~/.ssh/ || true diff --git a/docs/misc/asciinema/install.tcl b/docs/misc/asciinema/install.tcl index 3a9d8ff4..13456dc5 100644 --- a/docs/misc/asciinema/install.tcl +++ b/docs/misc/asciinema/install.tcl @@ -24,7 +24,7 @@ sudo chmod 755 /usr/local/bin/borg # Now check it: (possibly needs a terminal restart) borg -V -# That's it! Check out the other screencasts to see how to actually use borgbackup. +# That's it! Now check out the other screencasts to see how to use borgbackup. }] # wget may be slow diff --git a/docs/misc/create_chunker-params.txt b/docs/misc/create_chunker-params.txt index af602c5c..c091a2c1 100644 --- a/docs/misc/create_chunker-params.txt +++ b/docs/misc/create_chunker-params.txt @@ -45,7 +45,7 @@ to the ratio of the different target chunk sizes. Note: RAM needs were not a problem in this specific case (37GB data size). But just imagine, you have 37TB of such data and much less than 42GB RAM, - then you'ld definitely want the "lg" chunker params so you only need + then you should use the "lg" chunker params so you only need 2.6GB RAM. Or even bigger chunks than shown for "lg" (see "xl"). You also see compression works better for larger chunks, as expected. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index de9d501a..de3c8bb0 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -21,22 +21,22 @@ mount an archive to restore from a backup. *Repositories* are filesystem directories acting as self-contained stores of archives. Repositories can be accessed locally via path or remotely via ssh. Under the hood, -repositories contain data blocks and a manifest tracking which blocks are in each -archive. If some data hasn't changed from one backup to another, Borg can simply -reference an already uploaded data chunk (deduplication). +repositories contain data blocks and a manifest that tracks which blocks are in each +archive. If some data hasn't changed between backups, Borg simply +references an already uploaded data chunk (deduplication). .. _about_free_space: Important note about free space ------------------------------- -Before you start creating backups, please make sure that there is *always* -a good amount of free space on the filesystem that has your backup repository +Before you start creating backups, ensure that there is *always* plenty +of free space on the destination filesystem that has your backup repository (and also on ~/.cache). A few GB should suffice for most hard-drive sized repositories. See also :ref:`cache-memory-usage`. -Borg doesn't use space reserved for root on repository disks (even when run as root), -on file systems which do not support this mechanism (e.g. XFS) we recommend to reserve +Borg doesn't use space reserved for root on repository disks (even when run as root). +On file systems which do not support this mechanism (e.g. XFS) we recommend to reserve some space in Borg itself just to be safe by adjusting the ``additional_free_space`` setting (a good starting point is ``2G``):: @@ -47,7 +47,7 @@ can while aborting the current operation safely, which allows the user to free m by deleting/pruning archives. This mechanism is not bullet-proof in some circumstances [1]_. -If you *really* run out of disk space, it can be hard or impossible to free space, +If you do run out of disk space, it can be hard or impossible to free space, because Borg needs free space to operate - even to delete backup archives. You can use some monitoring process or just include the free space information @@ -71,16 +71,15 @@ Also helpful: Important note about permissions -------------------------------- -To avoid permissions issues (in your borg repository or borg cache), **always +To avoid permission issues (in your borg repository or borg cache), **always access the repository using the same user account**. -If you want to backup files of other users or the operating system, running -borg as root likely will be required (otherwise you'ld get `Permission denied` +If you want to back up files of other users or the operating system, running +borg as root likely will be required (otherwise you get `Permission denied` errors). -If you only back up your own files, you neither need nor want to run borg as -root, just run it as your normal user. +If you only back up your own files, run it as your normal user (i.e. not root). -For a local repository just always use the same user to invoke borg. +For a local repository always use the same user to invoke borg. For a remote repository: always use e.g. ssh://borg@remote_host. You can use this from different local users, the remote user running borg and accessing the @@ -116,14 +115,14 @@ common techniques to achieve this. - Shut down containers before backing up their storage volumes. -For some systems Borg might work well enough without these +For some systems, Borg might work well enough without these precautions. If you are simply backing up the files on a system that isn't very active (e.g. in a typical home directory), Borg usually works well enough without further care for consistency. Log files and caches might not be in a perfect state, but this is rarely a problem. For databases, virtual machines, and containers, there are specific -techniques for backing them up that do not simply use Borg to backup +techniques for backing them up that do not simply use Borg to back up the underlying filesystem. For databases, check your database documentation for techniques that will save the database state between transactions. For virtual machines, consider running the backup on @@ -139,8 +138,8 @@ complete operating system) to a repository ``~/backup/main`` on a remote server Some files which aren't necessarily needed in this backup are excluded. See :ref:`borg_patterns` on how to add more exclude options. -After the backup this script also uses the :ref:`borg_prune` subcommand to keep -only a certain number of old archives and deletes the others. +After the backup, this script also uses the :ref:`borg_prune` subcommand to keep +a certain number of old archives and deletes the others. Finally, it uses the :ref:`borg_compact` subcommand to remove deleted objects from the segment files in the repository to free disk space. @@ -152,8 +151,8 @@ by the root user, but not executable or readable by anyone else, i.e. root:root You can use this script as a starting point and modify it where it's necessary to fit your setup. -Do not forget to test your created backups to make sure everything you need is being -backed up and that the ``prune`` command is keeping and deleting the correct backups. +Do not forget to test your created backups to make sure everything you need is +backed up and that the ``prune`` command keeps and deletes the correct backups. :: @@ -171,7 +170,7 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac info "Starting backup" - # Backup the most important directories into an archive named after + # Back up the most important directories into an archive named after # the machine this script is currently running on: borg create \ @@ -236,7 +235,7 @@ Pitfalls with shell variables and environment variables ------------------------------------------------------- This applies to all environment variables you want Borg to see, not just -``BORG_PASSPHRASE``. The short explanation is: always ``export`` your variable, +``BORG_PASSPHRASE``. TL;DR: always ``export`` your variable, and use single quotes if you're unsure of the details of your shell's expansion behavior. E.g.:: @@ -256,7 +255,7 @@ For more information, refer to the sudo(8) man page and ``env_keep`` in the sudoers(5) man page. .. Tip:: - To debug what your borg process is actually seeing, find its PID + To debug what your borg process sees, find its PID (``ps aux|grep borg``) and then look into ``/proc/<PID>/environ``. .. passphrase_notes: @@ -264,29 +263,30 @@ the sudoers(5) man page. Passphrase notes ---------------- -If you use encryption (or authentication), Borg will interactively ask you +If you use encryption (or authentication), Borg will ask you interactively for a passphrase to encrypt/decrypt the keyfile / repokey. -A passphrase should be a single line of text, a trailing linefeed will be +A passphrase should be a single line of text. Any trailing linefeed will be stripped. -For your own safety, you maybe want to avoid empty passphrases as well -extremely long passphrase (much more than 256 bits of entropy). +Do not use empty passphrases, as these can be trivially guessed, which does not +leave any encrypted data secure. -Also avoid passphrases containing non-ASCII characters. -Borg is technically able to process all unicode text, but you might get into -trouble reproducing the same encoded utf-8 bytes or with keyboard layouts, -so better just avoid non-ASCII stuff. +Avoid passphrases containing non-ASCII characters. +Borg can process any unicode text, but problems may arise at input due to text +encoding or differing keyboard layouts, so best just avoid non-ASCII stuff. -If you want to automate, you can alternatively supply the passphrase -directly or indirectly using some environment variables. +See: https://xkcd.com/936/ -You can directly give a passphrase:: +If you want to automate, you can supply the passphrase +directly or indirectly with the use of environment variables. + +Supply a passphrase directly:: # use this passphrase (use safe permissions on the script!): export BORG_PASSPHRASE='my super secret passphrase' -Or ask an external program to supply the passphrase:: +Or delegate to an external program to supply the passphrase:: # use the "pass" password manager to get the passphrase: export BORG_PASSCOMMAND='pass show backup' @@ -424,22 +424,23 @@ be acceptable for backup usage. Restoring a backup ------------------ -Please note that we are only describing the most basic commands and options -here - please refer to the command reference to see more. +Please note that we describe only the most basic commands and options +here. Refer to the command reference to see more. + +To restore, work **on the same machine as the same user** +that was used to create the backups of the wanted files. Doing so +avoids issues such as: -For restoring, you usually want to work **on the same machine as the same user** -that was also used to create the backups of the wanted files. Doing it like -that avoids quite some issues: +- confusion relating to paths +- mapping of user/group names to user/group IDs +- permissions -- no confusion relating to paths -- same mapping of user/group names to user/group IDs -- no permission issues -- you likely already have a working borg setup there, +You likely already have a working borg setup there, including perhaps: - - maybe including a environment variable for the key passphrase (for encrypted repos), - - maybe including a keyfile for the repo (not needed for repokey mode), - - maybe including a ssh key for the repo server (not needed for locally mounted repos), - - maybe including a valid borg cache for that repo (quicker than cache rebuild). + - an environment variable for the key passphrase (for encrypted repos), + - a keyfile for the repo (not needed for repokey mode), + - a ssh key for the repo server (not needed for locally mounted repos), + - a valid borg cache for that repo (quicker than cache rebuild). The **user** might be: @@ -461,12 +462,12 @@ The **key** can be located: - in the repository (**repokey** mode). Easy, this will usually "just work". -- in the home directory of the user who did the backup (**keyfile** mode). +- in the home directory of the user who made the backup (**keyfile** mode). This may cause a bit more effort: - if you have just lost that home directory and you first need to restore the - borg key (e.g. from the separate backup you have made of it or from another + borg key (e.g. from the separate backup you made of it or from another user or machine accessing the same repository). - if you first must find out the correct machine / user / home directory (where the borg client was run to make the backups). @@ -483,19 +484,19 @@ There are **2 ways to restore** files from a borg backup repository: - **borg mount** - use this if: - - you don't precisely know what files you want to restore + - you don't know exactly which files you want to restore - you don't know which archive contains the files (in the state) you want - you need to look into files / directories before deciding what you want - you need a relatively low volume of data restored - - you don't care for restoring stuff that the FUSE mount is not implementing yet + - you don't care for restoring stuff that FUSE mount does not implement yet (like special fs flags, ACLs) - - you have a client with good resources (RAM, CPU, temp. disk space) - - you want to rather use some filemanager to restore (copy) files than borg + - you have a client with good resources (RAM, CPU, temporary disk space) + - you would rather use some filemanager to restore (copy) files than borg extract shell commands - **borg extract** - use this if: - - you precisely know what you want (repo, archive, path) + - you know precisely what you want (repo, archive, path) - you need a high volume of files restored (best speed) - you want a as-complete-as-it-gets reproduction of file metadata (like special fs flags, ACLs) diff --git a/docs/quickstart_example.rst.inc b/docs/quickstart_example.rst.inc index 2299483a..3d140f0f 100644 --- a/docs/quickstart_example.rst.inc +++ b/docs/quickstart_example.rst.inc @@ -1,8 +1,8 @@ -1. Before a backup can be made a repository has to be initialized:: +1. Before a backup can be made, a repository has to be initialized:: $ borg -r /path/to/repo rcreate --encryption=repokey-aes-ocb -2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called +2. Back up the ``~/src`` and ``~/Documents`` directories into an archive called *Monday*:: $ borg -r /path/to/repo create Monday ~/src ~/Documents @@ -11,7 +11,7 @@ $ borg -r /path/to/repo create --stats Tuesday ~/src ~/Documents - This backup will be a lot quicker and a lot smaller since only new never + This backup will be a lot quicker and a lot smaller since only new, never before seen data is stored. The ``--stats`` option causes Borg to output statistics about the newly created archive such as the deduplicated size (the amount of unique data not shared with other archives):: @@ -58,7 +58,7 @@ $ borg -r /path/to/repo compact .. Note:: - Borg is quiet by default (it works on WARNING log level). + Borg is quiet by default (it defaults to WARNING log level). You can use options like ``--progress`` or ``--list`` to get specific reports during command execution. You can also add the ``-v`` (or ``--verbose`` or ``--info``) option to adjust the log level to INFO to diff --git a/docs/usage/borgfs.rst.inc b/docs/usage/borgfs.rst.inc index 3488e936..1ea9e388 100644 --- a/docs/usage/borgfs.rst.inc +++ b/docs/usage/borgfs.rst.inc @@ -132,7 +132,7 @@ of CPU cores. When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process -to unintentionally delete data. +to delete data unintentionally. When running in the foreground ^C/SIGINT unmounts cleanly, but other signals or crashes do not.
\ No newline at end of file diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index beb9dc36..12605e09 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -12,35 +12,41 @@ borg check .. class:: borg-options-table - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--repository-only`` | only perform repository checks | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--archives-only`` | only perform archives checks | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--verify-data`` | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--repair`` | attempt to repair any inconsistencies found | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--max-duration SECONDS`` | do only a partial repo check for max. SECONDS seconds (Default: unlimited) | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--first N`` | consider first N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--last N`` | consider last N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--repository-only`` | only perform repository checks | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--archives-only`` | only perform archives checks | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--verify-data`` | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--repair`` | attempt to repair any inconsistencies found | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--max-duration SECONDS`` | do only a partial repo check for max. SECONDS seconds (Default: unlimited) | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--first N`` | consider first N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--last N`` | consider last N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ .. raw:: html @@ -59,7 +65,6 @@ borg check --archives-only only perform archives checks --verify-data perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) --repair attempt to repair any inconsistencies found - --save-space work slower, but using less space --max-duration SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited) @@ -71,6 +76,10 @@ borg check --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp --first N consider first N archives after other filters were applied --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. Description diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc index 55dfe05d..77f4728f 100644 --- a/docs/usage/common-options.rst.inc +++ b/docs/usage/common-options.rst.inc @@ -16,7 +16,6 @@ --remote-path PATH use PATH as borg executable on the remote (default: "borg") --upload-ratelimit RATE set network upload rate limit in kiByte/s (default: 0=unlimited) --upload-buffer UPLOAD_BUFFER set network upload buffer size in MiB. (default: 0=no buffer) ---consider-part-files treat part files like normal files (e.g. to list/extract them) --debug-profile FILE Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof". --rsh RSH Use this command to connect to the 'borg serve' process (default: 'ssh') -r REPO, --repo REPO repository to use diff --git a/docs/usage/create.rst b/docs/usage/create.rst index b4b978a3..8bc4c89a 100644 --- a/docs/usage/create.rst +++ b/docs/usage/create.rst @@ -74,9 +74,9 @@ Examples $ borg create 'daily-projectA-{now:%Y-%m-%d}' projectA # Use external command to determine files to archive - # Use --paths-from-stdin with find to only backup files less than 1MB in size + # Use --paths-from-stdin with find to back up only files less than 1MB in size $ 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 + # Use --paths-from-command with find to back up files from only a given user $ 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 \ diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 74b0aef6..0e60cc7e 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -35,15 +35,15 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') | + | | ``--stdin-user USER`` | set user USER in archive for stdin data (default: do not store user/uid) | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'wheel') | + | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: do not store group/gid) | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--paths-from-stdin`` | read DELIM-separated list of paths to backup from stdin. Will not recurse into directories. | + | | ``--paths-from-stdin`` | read DELIM-separated list of paths to back up from stdin. Will not recurse into directories. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -103,6 +103,8 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--checkpoint-volume BYTES`` | write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. | @@ -132,11 +134,11 @@ borg create --json output stats as JSON. Implies ``--stats``. --no-cache-sync experimental: do not synchronize the cache. Implies not using the files cache. --stdin-name NAME use NAME in archive for stdin data (default: 'stdin') - --stdin-user USER set user USER in archive for stdin data (default: 'root') - --stdin-group GROUP set group GROUP in archive for stdin data (default: 'wheel') + --stdin-user USER set user USER in archive for stdin data (default: do not store user/uid) + --stdin-group GROUP set group GROUP in archive for stdin data (default: do not store group/gid) --stdin-mode M set mode to M in archive for stdin data (default: 0660) --content-from-command interpret PATH as command and store its stdout. See also section Reading from stdin below. - --paths-from-stdin read DELIM-separated list of paths to backup from stdin. Will not recurse into directories. + --paths-from-stdin read DELIM-separated list of paths to back up from stdin. Will not recurse into directories. --paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin`` --paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) @@ -173,6 +175,7 @@ borg create --comment COMMENT add a comment text to the archive --timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) + --checkpoint-volume BYTES write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) --chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 -C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. @@ -241,9 +244,9 @@ creation of a new archive to ensure fast operation. This is because the file cac is used to determine changed files quickly uses absolute filenames. If this is not possible, consider creating a bind mount to a stable location. -The ``--progress`` option shows (from left to right) Original, Compressed and Deduplicated -(O, C and D, respectively), then the Number of files (N) processed so far, followed by -the currently processed path. +The ``--progress`` option shows (from left to right) Original and (uncompressed) +deduplicated size (O and U respectively), then the Number of files (N) processed so far, +followed by the currently processed path. When using ``--stats``, you will get some statistics about how much data was added - the "This Archive" deduplicated size there is most interesting as that is @@ -319,9 +322,9 @@ borg usually just stores their metadata: Other flags used include: +- '+' = included, item would be backed up (if not in dry-run mode) +- '-' = excluded, item would not be / was not backed up - 'i' = backup data was read from standard input (stdin) -- '-' = dry run, item was *not* backed up -- 'x' = excluded, item was *not* backed up - '?' = missing status code (if you see this, please file a bug report!) Reading from stdin diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index 63413584..3eed03e5 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -12,39 +12,45 @@ borg delete .. class:: borg-options-table - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not change repository | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--list`` | output verbose list of archives | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--consider-checkpoints`` | consider checkpoint archives for deletion (default: not considered). | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-s``, ``--stats`` | print statistics for the deleted archive | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--cache-only`` | delete only the local cache for the given repository | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--first N`` | consider first N archives after other filters were applied | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--last N`` | consider last N archives after other filters were applied | - +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not change repository | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of archives | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--consider-checkpoints`` | consider checkpoint archives for deletion (default: not considered). | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics for the deleted archive | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--cache-only`` | delete only the local cache for the given repository | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--first N`` | consider first N archives after other filters were applied | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--last N`` | consider last N archives after other filters were applied | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ .. raw:: html @@ -65,7 +71,6 @@ borg delete -s, --stats print statistics for the deleted archive --cache-only delete only the local cache for the given repository --force force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. - --save-space work slower, but using less space -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) @@ -77,6 +82,10 @@ borg delete --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp --first N consider first N archives after other filters were applied --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. Description diff --git a/docs/usage/general/environment.rst.inc b/docs/usage/general/environment.rst.inc index 46cd6bf2..e503e8c4 100644 --- a/docs/usage/general/environment.rst.inc +++ b/docs/usage/general/environment.rst.inc @@ -33,14 +33,14 @@ General: When set, use the value to answer the passphrase question when a **new** passphrase is asked for. This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also be checked. - Main usecase for this is to fully automate ``borg change-passphrase``. + Main usecase for this is to automate fully ``borg change-passphrase``. BORG_DISPLAY_PASSPHRASE When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories. BORG_HOST_ID Borg usually computes a host id from the FQDN plus the results of ``uuid.getnode()`` (which usually returns a unique id based on the MAC address of the network interface. Except if that MAC happens to be all-zero - in that case it returns a random value, which is not what we want (because it kills automatic stale lock removal). - So, if you have a all-zero MAC address or other reasons to better externally control the host id, just set this + So, if you have a all-zero MAC address or other reasons to control better externally the host id, just set this environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not, use fqdn@uniqueid. BORG_LOCK_WAIT @@ -62,7 +62,7 @@ General: cache entries for backup sources other than the current sources. BORG_FILES_CACHE_TTL When set to a numeric value, this determines the maximum "time to live" for the files cache - entries (default: 20). The files cache is used to quickly determine whether a file is unchanged. + entries (default: 20). The files cache is used to determine quickly whether a file is unchanged. The FAQ explains this more detailed in: :ref:`always_chunking` BORG_SHOW_SYSINFO When set to no (default: yes), system information (like OS, Python version, ...) in @@ -112,7 +112,7 @@ Some automatic "answerers" (if set, they automatically answer confirmation quest BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES) For "This is a potentially dangerous function..." (check --repair) BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES) - For "You requested to completely DELETE the repository *including* all archives it contains:" + For "You requested to DELETE the repository completely *including* all archives it contains:" Note: answers are case sensitive. setting an invalid answer value might either give the default answer or ask you interactively, depending on whether retries are allowed (they by default are @@ -156,9 +156,6 @@ Building: BORG_LIBLZ4_PREFIX Adds given prefix directory to the default locations. If a 'include/lz4.h' is found Borg will be linked against the system liblz4 instead of a bundled implementation. (setup.py) - BORG_LIBB2_PREFIX - Adds given prefix directory to the default locations. If a 'include/blake2.h' is found Borg - will be linked against the system libb2 instead of a bundled implementation. (setup.py) BORG_LIBZSTD_PREFIX Adds given prefix directory to the default locations. If a 'include/zstd.h' is found Borg will be linked against the system libzstd instead of a bundled implementation. (setup.py) diff --git a/docs/usage/general/resources.rst.inc b/docs/usage/general/resources.rst.inc index 4f55a4cd..d8ce1b24 100644 --- a/docs/usage/general/resources.rst.inc +++ b/docs/usage/general/resources.rst.inc @@ -91,5 +91,5 @@ Network (only for client/server operation): encrypted) data of course has to go over the connection (``ssh://`` repo url). If you use a locally mounted network filesystem, additionally some copy operations used for transaction support also go over the connection. If - you backup multiple sources to one target repository, additional traffic + you back up multiple sources to one target repository, additional traffic happens for cache resynchronization. diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index edf85c20..ef4df476 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -195,14 +195,14 @@ are added. Exclusion patterns from ``--exclude-from`` files are appended last. Examples:: - # backup pics, but not the ones from 2018, except the good ones: + # back up pics, but not the ones from 2018, except the good ones: # note: using = is essential to avoid cmdline argument parsing issues. borg create --pattern=+pics/2018/good --pattern=-pics/2018 archive pics - # backup only JPG/JPEG files (case insensitive) in all home directories: + # back up only JPG/JPEG files (case insensitive) in all home directories: borg create --pattern '+ re:\.jpe?g(?i)$' archive /home - # backup homes, but exclude big downloads (like .ISO files) or hidden files: + # back up homes, but exclude big downloads (like .ISO files) or hidden files: borg create --exclude 're:\.iso(?i)$' --exclude 'sh:home/**/.*' archive /home # use a file with patterns (recursion root '/' via command line): @@ -217,7 +217,7 @@ The patterns.lst file could look like that:: + home/susan # also back up this exact file + pf:home/bobby/specialfile.txt - # don't backup the other home directories + # don't back up the other home directories - home/* # don't even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too) ! re:^(dev|proc|run|sys|tmp) diff --git a/docs/usage/import-tar.rst.inc b/docs/usage/import-tar.rst.inc index 66afdb66..0cb7d631 100644 --- a/docs/usage/import-tar.rst.inc +++ b/docs/usage/import-tar.rst.inc @@ -43,6 +43,8 @@ borg import-tar +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--checkpoint-volume BYTES`` | write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) | + +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. | @@ -79,6 +81,7 @@ borg import-tar --comment COMMENT add a comment text to the archive --timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) + --checkpoint-volume BYTES write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) --chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 -C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc index f712f650..064f8a7a 100644 --- a/docs/usage/info.rst.inc +++ b/docs/usage/info.rst.inc @@ -12,25 +12,33 @@ borg info .. class:: borg-options-table - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--json`` | format output as JSON | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--first N`` | consider first N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--last N`` | consider last N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--json`` | format output as JSON | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--first N`` | consider first N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--last N`` | consider last N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ .. raw:: html @@ -56,6 +64,10 @@ borg info --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp --first N consider first N archives after other filters were applied --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. Description diff --git a/docs/usage/key.rst b/docs/usage/key.rst index 656cba2f..07b517a4 100644 --- a/docs/usage/key.rst +++ b/docs/usage/key.rst @@ -1,7 +1,5 @@ .. include:: key_change-location.rst.inc -.. include:: key_change-algorithm.rst.inc - .. _borg-change-passphrase: .. include:: key_change-passphrase.rst.inc @@ -39,7 +37,7 @@ Fully automated using environment variables: :: - $ BORG_NEW_PASSPHRASE=old borg rcreate -e=repokey + $ BORG_NEW_PASSPHRASE=old borg rcreate --encryption=repokey-aes-ocb # now "old" is the current passphrase. $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase # now "new" is the current passphrase. diff --git a/docs/usage/key_change-algorithm.rst.inc b/docs/usage/key_change-algorithm.rst.inc deleted file mode 100644 index 55e210ff..00000000 --- a/docs/usage/key_change-algorithm.rst.inc +++ /dev/null @@ -1,72 +0,0 @@ -.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! - -.. _borg_key_change-algorithm: - -borg key change-algorithm -------------------------- -.. code-block:: none - - borg [common options] key change-algorithm [options] ALGORITHM - -.. only:: html - - .. class:: borg-options-table - - +-------------------------------------------------------+---------------+----------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------+----------------------+ - | | ``ALGORITHM`` | select key algorithm | - +-------------------------------------------------------+---------------+----------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+---------------+----------------------+ - - .. raw:: html - - <script type='text/javascript'> - $(document).ready(function () { - $('.borg-options-table colgroup').remove(); - }) - </script> - -.. only:: latex - - ALGORITHM - select key algorithm - - - :ref:`common_options` - | - -Description -~~~~~~~~~~~ - -Change the algorithm we use to encrypt and authenticate the borg key. - -Important: In a `repokey` mode (e.g. repokey-blake2) all users share the same key. -In this mode upgrading to `argon2` will make it impossible to access the repo for users who use an old version of borg. -We recommend upgrading to the latest stable version. - -Important: In a `keyfile` mode (e.g. keyfile-blake2) each user has their own key (in ``~/.config/borg/keys``). -In this mode this command will only change the key used by the current user. -If you want to upgrade to `argon2` to strengthen security, you will have to upgrade each user's key individually. - -Your repository is encrypted and authenticated with a key that is randomly generated by ``borg init``. -The key is encrypted and authenticated with your passphrase. - -We currently support two choices: - -1. argon2 - recommended. This algorithm is used by default when initialising a new repository. - The key encryption key is derived from your passphrase via argon2-id. - Argon2 is considered more modern and secure than pbkdf2. -2. pbkdf2 - the legacy algorithm. Use this if you want to access your repo via old versions of borg. - The key encryption key is derived from your passphrase via PBKDF2-HMAC-SHA256. - -Examples:: - - # Upgrade an existing key to argon2 - borg key change-algorithm /path/to/repo argon2 - # Downgrade to pbkdf2 - use this if upgrading borg is not an option - borg key change-algorithm /path/to/repo pbkdf2 - diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc index 871355dc..35975e9a 100644 --- a/docs/usage/key_export.rst.inc +++ b/docs/usage/key_export.rst.inc @@ -54,7 +54,7 @@ Description ~~~~~~~~~~~ If repository encryption is used, the repository is inaccessible -without the key. This command allows one to backup this essential key. +without the key. This command allows one to back up this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index 422d9520..756c81b6 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -12,35 +12,35 @@ borg list .. class:: borg-options-table - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``NAME`` | specify the archive name | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``PATH`` | paths to list; patterns are supported | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **options** | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--short`` | only print file/directory names, nothing else | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}") | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--json-lines`` | Format output as JSON Lines. The form of ``--format`` 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. | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | - +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``NAME`` | specify the archive name | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``PATH`` | paths to list; patterns are supported | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **options** | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--short`` | only print file/directory names, nothing else | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}") | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json-lines`` | Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Exclusion options** | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | + +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -61,7 +61,7 @@ borg list options --short only print file/directory names, nothing else --format FORMAT specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}") - --json-lines Format output as JSON Lines. The form of ``--format`` 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. + --json-lines Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. :ref:`common_options` @@ -106,7 +106,7 @@ The following keys are always available: - 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 +- NUL: NUL character for creating print0 / xargs -0 like output - SPACE - TAB - CR @@ -120,10 +120,8 @@ Keys available only when listing files in an archive: - gid - user - group -- path: path interpreted as text (might be missing non-text characters, see bpath) -- bpath: verbatim POSIX path, can contain any character except NUL -- source: link target for symlinks (identical to linktarget) -- linktarget +- path: file path +- target: link target for symlinks - hlid: hard link identity (same if hardlinking same fs object) - flags @@ -155,6 +153,6 @@ Keys available only when listing files in an archive: - archiveid - archivename -- extra: prepends {source} with " -> " for soft links and " link to " for hard links +- extra: prepends {target} with " -> " for soft links and " link to " for hard links - health: either "healthy" (file ok) or "broken" (if file has all-zero replacement chunks) diff --git a/docs/usage/mount.rst b/docs/usage/mount.rst index a7075efa..fe740e15 100644 --- a/docs/usage/mount.rst +++ b/docs/usage/mount.rst @@ -49,5 +49,5 @@ borgfs ``borgfs`` will be automatically provided if you used a distribution package, ``pip`` or ``setup.py`` to install Borg. Users of the - standalone binary will have to manually create a symlink (see + standalone binary will have to create a symlink manually (see :ref:`pyinstaller-binary`). diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index d8b4bfa6..9a321d43 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -43,6 +43,14 @@ borg mount +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--last N`` | consider last N archives after other filters were applied | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ | **Exclusion options** | +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | @@ -87,6 +95,10 @@ borg mount --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp --first N consider first N archives after other filters were applied --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. Exclusion options @@ -152,7 +164,7 @@ of CPU cores. When the daemonized process receives a signal or crashes, it does not unmount. Unmounting in these cases could cause an active rsync or similar process -to unintentionally delete data. +to delete data unintentionally. When running in the foreground ^C/SIGINT unmounts cleanly, but other signals or crashes do not.
\ No newline at end of file diff --git a/docs/usage/notes.rst b/docs/usage/notes.rst index b4e1637a..79d42254 100644 --- a/docs/usage/notes.rst +++ b/docs/usage/notes.rst @@ -30,7 +30,7 @@ for block devices (like disks, partitions, LVM LVs) or raw disk image files. ``--chunker-params=fixed,4096,512`` results in fixed 4kiB sized blocks, but the first header block will only be 512B long. This might be useful to -dedup files with 1 header + N fixed size data blocks. Be careful to not +dedup files with 1 header + N fixed size data blocks. Be careful not to produce a too big amount of chunks (like using small block size for huge files). @@ -63,7 +63,7 @@ For more details, see :ref:`chunker_details`. ``--noatime / --noctime`` ~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use these ``borg create`` options to not store the respective timestamp +You can use these ``borg create`` options not to store the respective timestamp into the archive, in case you do not really need it. Besides saving a little space for the not archived timestamp, it might also @@ -74,7 +74,7 @@ won't deduplicate just because of that. ``--nobsdflags / --noflags`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use this to not query and store (or not extract and set) flags - in case +You can use this not to query and store (or not extract and set) flags - in case you don't need them or if they are broken somehow for your fs. On Linux, dealing with the flags needs some additional syscalls. Especially when @@ -132,7 +132,7 @@ scale and perform better if you do not work via the FUSE mount. Example +++++++ -Imagine you have made some snapshots of logical volumes (LVs) you want to backup. +Imagine you have made some snapshots of logical volumes (LVs) you want to back up. .. note:: @@ -309,8 +309,8 @@ operation on an append-only repository to catch accidental or malicious corrupti # run without append-only mode borg check --verify-data && borg compact -Aside from checking repository & archive integrity you may want to also manually check -backups to ensure their content seems correct. +Aside from checking repository & archive integrity you may also want to check +backups manually to ensure their content seems correct. Further considerations ++++++++++++++++++++++ diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index b56d3e9f..01a462ac 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -12,45 +12,51 @@ borg prune .. class:: borg-options-table - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not change repository | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--force`` | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-s``, ``--stats`` | print statistics for the deleted archive | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--list`` | output verbose list of archives it keeps/prunes | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--keep-within INTERVAL`` | keep all archives within this time interval | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--keep-minutely`` | number of minutely archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-d``, ``--keep-daily`` | number of daily archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | - +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not change repository | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--force`` | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics for the deleted archive | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of archives it keeps/prunes | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--keep-within INTERVAL`` | keep all archives within this time interval | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--keep-minutely`` | number of minutely archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-d``, ``--keep-daily`` | number of daily archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+ .. raw:: html @@ -77,7 +83,6 @@ borg prune -w, --keep-weekly number of weekly archives to keep -m, --keep-monthly number of monthly archives to keep -y, --keep-yearly number of yearly archives to keep - --save-space work slower, but using less space -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) @@ -86,6 +91,10 @@ borg prune Archive filters -a PATTERN, --match-archives PATTERN only consider archive names matching the pattern. see "borg help match-archives". + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. Description @@ -129,12 +138,12 @@ As an example, ``--keep-daily 7`` means to keep the latest backup on each day, up to 7 most recent days with backups (days without backups do not count). The rules are applied from secondly to yearly, and backups selected by previous rules do not count towards those of later rules. The time that each backup -starts is used for pruning purposes. Dates and times are interpreted in -the local timezone, and weeks go from Monday to Sunday. Specifying a -negative number of archives to keep means that there is no limit. As of borg -1.2.0, borg will retain the oldest archive if any of the secondly, minutely, -hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet -its retention target. This enables the first chronological archive to continue +starts is used for pruning purposes. Dates and times are interpreted in the local +timezone of the system where borg prune runs, and weeks go from Monday to Sunday. +Specifying a negative number of archives to keep means that there is no limit. +As of borg 1.2.0, borg will retain the oldest archive if any of the secondly, +minutely, hourly, daily, weekly, monthly, or yearly rules was not otherwise able to +meet its retention target. This enables the first chronological archive to continue aging until it is replaced by a newer archive that meets the retention criteria. The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will diff --git a/docs/usage/rcreate.rst.inc b/docs/usage/rcreate.rst.inc index 65d8b0bd..c6ef03b2 100644 --- a/docs/usage/rcreate.rst.inc +++ b/docs/usage/rcreate.rst.inc @@ -123,7 +123,7 @@ The easiest way to find out about what's fastest is to run ``borg benchmark cpu` `repokey` modes: if you want ease-of-use and "passphrase" security is good enough - the key will be stored in the repository (in ``repo_dir/config``). -`keyfile` modes: if you rather want "passphrase and having-the-key" security - +`keyfile` modes: if you want "passphrase and having-the-key" security - the key will be stored in your home directory (in ``~/.config/borg/keys``). The following table is roughly sorted in order of preference, the better ones are @@ -151,7 +151,7 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st .. nanorst: inline-replace -`none` mode uses no encryption and no authentication. You're advised to NOT use this mode +`none` mode uses no encryption and no authentication. You're advised NOT to use this mode as it would expose you to all sorts of issues (DoS, confidentiality, tampering, ...) in case of malicious activity in the repository. diff --git a/docs/usage/rdelete.rst b/docs/usage/rdelete.rst index e7b3acdd..deca35cd 100644 --- a/docs/usage/rdelete.rst +++ b/docs/usage/rdelete.rst @@ -6,7 +6,7 @@ Examples # delete the whole repository and the related local cache: $ borg rdelete - You requested to completely DELETE the repository *including* all archives it contains: + You requested to DELETE the repository completely *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 diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index e7c98816..1953c4d2 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -57,19 +57,29 @@ borg recreate +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--last N`` | consider last N archives after other filters were applied | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--target TARGET`` | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--checkpoint-volume BYTES`` | write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) | + +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--comment COMMENT`` | add a comment text to the archive | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". | + | | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option explicitly to prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095 | + | | ``--chunker-params PARAMS`` | rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the chunker defaults. default: do not rechunk | +-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -111,13 +121,18 @@ borg recreate --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp --first N consider first N archives after other filters were applied --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. --target TARGET create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) + --checkpoint-volume BYTES write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) --comment COMMENT add a comment text to the archive --timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. -C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. - --recompress MODE recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". - --chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095 + --recompress MODE recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option explicitly to prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". + --chunker-params PARAMS rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the chunker defaults. default: do not rechunk Description @@ -147,8 +162,8 @@ There is no risk of data loss by this. used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives. **USE WITH CAUTION.** -Depending on the PATHs and patterns given, recreate can be used to permanently -delete files from archives. +Depending on the PATHs and patterns given, recreate can be used to +delete files from archives permanently. When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are interpreted. See :ref:`list_item_flags` in ``borg create`` for details. diff --git a/docs/usage/rlist.rst.inc b/docs/usage/rlist.rst.inc index 9ded180d..72fa7818 100644 --- a/docs/usage/rlist.rst.inc +++ b/docs/usage/rlist.rst.inc @@ -12,31 +12,39 @@ borg rlist .. class:: borg-options-table - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--short`` | only print the archive names, nothing else | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--format FORMAT`` | specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--json`` | Format output as JSON. The form of ``--format`` 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. | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--first N`` | consider first N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--last N`` | consider last N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--short`` | only print the archive names, nothing else | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--format FORMAT`` | specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json`` | Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--first N`` | consider first N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--last N`` | consider last N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -54,7 +62,7 @@ borg rlist --consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden). --short only print the archive names, nothing else --format FORMAT specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") - --json Format output as JSON. The form of ``--format`` 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. + --json Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. :ref:`common_options` @@ -65,6 +73,10 @@ borg rlist --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp --first N consider first N archives after other filters were applied --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. Description @@ -99,7 +111,7 @@ The following keys are always available: - 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 +- NUL: NUL character for creating print0 / xargs -0 like output - SPACE - TAB - CR @@ -107,11 +119,9 @@ The following keys are always available: Keys available only when listing archives in a repository: -- archive: archive name interpreted as text (might be missing non-text characters, see barchive) +- archive: archive name - name: alias of "archive" -- barchive: verbatim archive name, can contain any character except NUL -- comment: archive comment interpreted as text (might be missing non-text characters, see bcomment) -- bcomment: verbatim archive comment, can contain any character except NUL +- comment: archive comment - id: internal ID of the archive - start: time (start) of creation of the archive diff --git a/docs/usage/serve.rst b/docs/usage/serve.rst index 96a53588..4438724a 100644 --- a/docs/usage/serve.rst +++ b/docs/usage/serve.rst @@ -21,7 +21,7 @@ locations like ``/etc/environment`` or in the forced command itself (example bel :: - # Allow an SSH keypair to only run borg, and only have access to /path/to/repo. + # Allow an SSH keypair to run only borg, and only have access to /path/to/repo. # Use key options to disable unneeded and potentially dangerous SSH functionality. # This will help to secure an automated remote backup system. $ cat ~/.ssh/authorized_keys @@ -36,7 +36,7 @@ locations like ``/etc/environment`` or in the forced command itself (example bel block potential dangerous ssh features, even when they are added in a future update. Thus, this option should be preferred. - If you're using openssh-server < 7.2, however, you have to explicitly specify + If you're using openssh-server < 7.2, however, you have to specify explicitly the ssh features to restrict and cannot simply use the restrict option as it has been introduced in v7.2. We recommend to use ``no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forwarding,no-user-rc`` diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc index e40692b5..c4a709bf 100644 --- a/docs/usage/serve.rst.inc +++ b/docs/usage/serve.rst.inc @@ -15,9 +15,9 @@ borg serve +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **options** | +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--restrict-to-path PATH`` | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository. | + | | ``--restrict-to-path PATH`` | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository. | +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. | + | | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. | +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--append-only`` | only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details. | +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -41,8 +41,8 @@ borg serve options - --restrict-to-path PATH restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository. - --restrict-to-repository PATH restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. + --restrict-to-path PATH restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository. + --restrict-to-repository PATH restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. --append-only only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details. --storage-quota QUOTA Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota. diff --git a/docs/usage/tar.rst b/docs/usage/tar.rst index 63a3aff0..05070c50 100644 --- a/docs/usage/tar.rst +++ b/docs/usage/tar.rst @@ -34,7 +34,7 @@ Outputs a script that copies all archives from repo1 to repo2: :: - for A T in `borg list --format='{archive} {time:%Y-%m-%dT%H:%M:%S}{LF}'` + for A T in `borg list --format='{archive} {time:%Y-%m-%dT%H:%M:%S}{NL}'` do echo "borg -r repo1 export-tar --tar-format=BORG $A - | borg -r repo2 import-tar --timestamp=$T $A -" done diff --git a/docs/usage/transfer.rst.inc b/docs/usage/transfer.rst.inc index 346d0824..d9df5e54 100644 --- a/docs/usage/transfer.rst.inc +++ b/docs/usage/transfer.rst.inc @@ -12,29 +12,37 @@ borg transfer .. class:: borg-options-table - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **options** | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not change repository, just check | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--other-repo SRC_REPOSITORY`` | transfer archives from the other repository | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--upgrader UPGRADER`` | use the upgrader to convert transferred data (default: no conversion) | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--first N`` | consider first N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--last N`` | consider last N archives after other filters were applied | - +-----------------------------------------------------------------------------+----------------------------------------------+--------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **options** | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not change repository, just check | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--other-repo SRC_REPOSITORY`` | transfer archives from the other repository | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--upgrader UPGRADER`` | use the upgrader to convert transferred data (default: no conversion) | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--first N`` | consider first N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--last N`` | consider last N archives after other filters were applied | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ + | | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. | + +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+ .. raw:: html @@ -62,6 +70,10 @@ borg transfer --sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp --first N consider first N archives after other filters were applied --last N consider last N archives after other filters were applied + --oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. + --newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. + --older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. + --newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. Description |