From 0263c9dd8a3b3b1c0915b983f7da7bf421d06e8e Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sun, 1 Oct 2017 02:24:54 +0200 Subject: [PATCH] build_usage --- docs/usage/change-passphrase.rst.inc | 7 +++- docs/usage/create.rst.inc | 47 +++++++++++++++++++----- docs/usage/key_change-passphrase.rst.inc | 7 +++- 3 files changed, 50 insertions(+), 11 deletions(-) diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc index 1114d3503..44edba19b 100644 --- a/docs/usage/change-passphrase.rst.inc +++ b/docs/usage/change-passphrase.rst.inc @@ -43,4 +43,9 @@ Description ~~~~~~~~~~~ The key files used for repository encryption are optionally passphrase -protected. This command can be used to change this passphrase. \ No newline at end of file +protected. This command can be used to change this passphrase. + +Please note that this command only changes the passphrase, but not any +secret protected by it (like e.g. encryption/MAC keys or chunker seed). +Thus, changing the passphrase after passphrase and borg key got compromised +does not protect future (nor past) backups to the same repository. \ No newline at end of file diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 3fc59dff4..444e4e2e9 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -31,7 +31,7 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--json`` | output stats as JSON. Implies ``--stats``. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies ``--no-files-cache``. | + | | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies not using the files cache. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | .. class:: borg-common-opt-ref | | | @@ -65,6 +65,8 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--ignore-inode`` | ignore inode data in the file metadata cache used to detect unchanged files. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--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** | @@ -102,7 +104,7 @@ borg create --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 ``--no-files-cache``. + --no-cache-sync experimental: do not synchronize the cache. Implies not using the files cache. :ref:`common_options` @@ -124,6 +126,7 @@ borg create --noatime do not store atime into archive --noctime do not store ctime into archive --ignore-inode ignore inode data in the file metadata cache used to detect unchanged files. + --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. @@ -157,13 +160,39 @@ In the archive name, you may use the following placeholders: {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others. Backup speed is increased by not reprocessing files that are already part of -existing archives and weren't modified. Normally, detecting file modifications -will take inode information into consideration. This is problematic for files -located on sshfs and similar network file systems which do not provide stable -inode numbers, such files will always be considered modified. The -``--ignore-inode`` flag can be used to prevent this and improve performance. -This flag will reduce reliability of change detection however, with files -considered unmodified as long as their size and modification time are unchanged. +existing archives and weren't modified. The detection of unmodified files is +done by comparing multiple file metadata values with previous values kept in +the files cache. + +This comparison can operate in different modes as given by ``--files-cache``: + +- ctime,size,inode (default) +- mtime,size,inode (default behaviour of borg versions older than 1.1.0rc4) +- ctime,size (ignore the inode number) +- mtime,size (ignore the inode number) +- rechunk,ctime (all files are considered modified - rechunk, cache ctime) +- rechunk,mtime (all files are considered modified - rechunk, cache mtime) +- disabled (disable the files cache, all files considered modified - rechunk) + +inode number: better safety, but often unstable on network filesystems + +Normally, detecting file modifications will take inode information into +consideration to improve the reliability of file change detection. +This is problematic for files located on sshfs and similar network file +systems which do not provide stable inode numbers, such files will always +be considered modified. You can use modes without `inode` in this case to +improve performance, but reliability of change detection might be reduced. + +ctime vs. mtime: safety vs. speed + +- ctime is a rather safe way to detect changes to a file (metadata and contents) + 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). +- 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 + well-meant, but in both cases mtime based cache modes can be problematic. The mount points of filesystems or filesystem snapshots should be the same for every creation of a new archive to ensure fast operation. This is because the file cache that diff --git a/docs/usage/key_change-passphrase.rst.inc b/docs/usage/key_change-passphrase.rst.inc index 64bc409c5..ab31b9fde 100644 --- a/docs/usage/key_change-passphrase.rst.inc +++ b/docs/usage/key_change-passphrase.rst.inc @@ -43,4 +43,9 @@ Description ~~~~~~~~~~~ The key files used for repository encryption are optionally passphrase -protected. This command can be used to change this passphrase. \ No newline at end of file +protected. This command can be used to change this passphrase. + +Please note that this command only changes the passphrase, but not any +secret protected by it (like e.g. encryption/MAC keys or chunker seed). +Thus, changing the passphrase after passphrase and borg key got compromised +does not protect future (nor past) backups to the same repository. \ No newline at end of file