mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-25 01:06:50 +00:00
build usage
This commit is contained in:
Thomas Waldmann
parent
77dd5e4d81
commit
4f7aa1a92f
2 changed files with 145 additions and 82 deletions
|
|
@ -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') |
|
||||
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--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 |
|
||||
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
6: factor 1000.0 .. 10000000.0
|
||||
|
||||
Add a randomly sized padding up to the given size:
|
||||
110: 1kiB
|
||||
...
|
||||
120: 1MiB
|
||||
...
|
||||
123: 8MiB (max.)
|
||||
|
||||
Examples::
|
||||
|
||||
borg create --compression lz4 REPO::ARCHIVE data
|
||||
|
|
@ -322,4 +350,7 @@ Examples::
|
|||
borg create --compression zlib,1 REPO::ARCHIVE data
|
||||
borg create --compression auto,lzma,6 REPO::ARCHIVE data
|
||||
borg create --compression auto,lzma ...
|
||||
borg create --compression obfuscate,3,none ...
|
||||
borg create --compression obfuscate,3,auto,zstd,10 ...
|
||||
borg create --compression obfuscate,2,zstd,6 ...
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue