diff options
author | TW <tw@waldmann-edv.de> | 2020-12-07 00:54:50 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-12-07 00:54:50 +0100 |
commit | c2118f16f1759565c68d5c587cbd9181ea8a4ffa (patch) | |
tree | b89a52ea96bb7303d6b58314e76cca8bafdf4a25 /docs/usage | |
parent | d2673c09f24f4ec9b9726bccc0d863c784057c77 (diff) | |
parent | 2031494f23986c895e42690966573c496e32a256 (diff) |
Merge pull request #5555 from ThomasWaldmann/rel120b1
Release 1.2.0b1
Diffstat (limited to 'docs/usage')
-rw-r--r-- | docs/usage/create.rst.inc | 196 | ||||
-rw-r--r-- | docs/usage/help.rst.inc | 31 |
2 files changed, 145 insertions, 82 deletions
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index e4bdfd677..f2b01b59a 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -12,87 +12,99 @@ borg create .. class:: borg-options-table - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``PATH`` | paths to archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | **optional arguments** | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not create a backup archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-s``, ``--stats`` | print statistics for the created archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--list`` | output verbose list of items (files, dirs, ...) | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--filter STATUSCHARS`` | only display items with the given status characters (see description) | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--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') | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | .. 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`` | experimental: include/exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-nodump`` | exclude files flagged NODUMP | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Filesystem options** | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--numeric-owner`` | only store numeric user and group identifiers | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noatime`` | do not store atime into archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--atime`` | do store atime into archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noctime`` | do not store ctime into archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--nobirthtime`` | do not store birthtime (creation date) into archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--nobsdflags`` | deprecated, use ``--noflags`` instead | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--read-special`` | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Archive options** | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--comment COMMENT`` | add a comment text to the archive | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--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. | - +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``PATH`` | paths to archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **optional arguments** | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not create a backup archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics for the created archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of items (files, dirs, ...) | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--filter STATUSCHARS`` | only display items with the given status characters (see description) | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--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: 'root') | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--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-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) | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. 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`` | experimental: include/exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-nodump`` | exclude files flagged NODUMP | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Filesystem options** | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--numeric-owner`` | only store numeric user and group identifiers | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noatime`` | do not store atime into archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--atime`` | do store atime into archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noctime`` | do not store ctime into archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--nobirthtime`` | do not store birthtime (creation date) into archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--nobsdflags`` | deprecated, use ``--noflags`` instead | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--read-special`` | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Archive options** | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--comment COMMENT`` | add a comment text to the archive | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--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. | + +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -118,7 +130,13 @@ 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: 'root') + --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-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) :ref:`common_options` @@ -136,7 +154,7 @@ borg create Filesystem options - -x, --one-file-system stay in the same file system and do not store mount points of other file systems + -x, --one-file-system stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. --numeric-owner only store numeric user and group identifiers --noatime do not store atime into archive --atime do store atime into archive @@ -209,6 +227,7 @@ ctime vs. mtime: safety vs. speed as it can not be set from userspace. But, a metadata-only change will already update the ctime, so there might be some unnecessary chunking/hashing even without content changes. Some filesystems do not support ctime (change time). + E.g. doing a chown or chmod to a file will change its ctime. - mtime usually works and only updates if file contents were changed. But mtime can be arbitrarily set from userspace, e.g. to set mtime back to the same value it had before a content change happened. This can be used maliciously as well as @@ -230,6 +249,7 @@ the state after creation. Also, the ``--stats`` and ``--dry-run`` options are mu exclusive because the data is not actually compressed and deduplicated during a dry run. See the output of the "borg help patterns" command for more help on exclude patterns. + See the output of the "borg help placeholders" command for more help on placeholders. .. man NOTES @@ -248,6 +268,18 @@ only include the objects specified by ``--exclude-if-present`` in your backup, and not include any other contents of the containing folder, this can be enabled through using the ``--keep-exclude-tags`` option. +The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them). +It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its +parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different +from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories +with device number different from their parent, which the kernel does not consider a mountpoint and also the +other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL +subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when +using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using +btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution +installer. + + .. _list_item_flags: Item flags diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index c78482667..6f8ffea49 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -138,6 +138,8 @@ Examples:: fm:aa:something/* re:^home/[^/]\.tmp/ sh:home/*/.thumbnails + # Example with spaces, no need to escape as it is processed by borg + some file with spaces.txt EOF $ borg create --exclude-from exclude.txt backup / @@ -313,6 +315,32 @@ auto,C[,L] For compressible data, it uses the given C[,L] compression - with C[,L] being any valid compression specifier. +obfuscate,SPEC,C[,L] + Use compressed-size obfuscation to make fingerprinting attacks based on + the observable stored chunk size more difficult. + Note: + - you must combine this with encryption or it won't make any sense. + - your repo size will be bigger, of course. + + The SPEC value will determine how the size obfuscation will work: + + Relative random reciprocal size variation: + Size will increase by a factor, relative to the compressed data size. + Smaller factors are often used, larger factors rarely. + 1: factor 0.01 .. 100.0 + 2: factor 0.1 .. 1000.0 + 3: factor 1.0 .. 10000.0 + 4: factor 10.0 .. 100000.0 + 5: factor 100.0 .. 1000000.0 |