mirror of
https://github.com/borgbackup/borg.git
synced 2026-09-01 14:13:19 +02:00
521 lines
No EOL
60 KiB
PHP
521 lines
No EOL
60 KiB
PHP
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
|
|
|
|
.. _borg_create:
|
|
|
|
borg create
|
|
-----------
|
|
.. code-block:: none
|
|
|
|
borg [common options] create [options] NAME [PATH...]
|
|
|
|
.. only:: html
|
|
|
|
.. class:: borg-options-table
|
|
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| **positional arguments** |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``NAME`` | specify the archive name |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``PATH`` | paths to archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| **options** |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``-n``, ``--dry-run`` | do not create a backup archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``-s``, ``--stats`` | print statistics for the created archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--list`` | output a 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``. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--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 a command and store its stdout. See also the section 'Reading backup data from stdin' below. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--paths-from-stdin`` | read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--paths-from-shell-command`` | interpret PATH as shell command and treat its output as ``--paths-from-stdin`` |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin``, ``--paths-from-command`` and ``--paths-from-shell-command`` (default: ``\n``) |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| .. class:: borg-common-opt-ref |
|
|
| |
|
|
| :ref:`common_options` |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| **Include/Exclude 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 |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (https://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``, do not omit the tag objects themselves from the backup archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--exclude-dataless`` | exclude files flagged DATALESS (macOS: placeholder files whose content is not materialized locally, e.g. not-downloaded cloud storage files) |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| **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 description below. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--numeric-ids`` | only store numeric user and group identifiers |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--atime`` | do store atime into archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--noctime`` | do not store ctime into archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--nobirthtime`` | do not store birthtime (creation date) into archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--noacls`` | do not read and store ACLs into archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--noxattrs`` | do not read and store xattrs into archive |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--sparse`` | detect sparse holes in input and seek over them instead of reading them |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--digests ALGOS`` | compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode (on Windows: mtime,size,inode, because ctime is file creation time there). |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--files-changed MODE`` | specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime (on Windows: mtime, because ctime is file creation time there). |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--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. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--read-special-timeout SECONDS`` | when reading from FIFOs or character devices (see --read-special): skip the file with an error if no data arrives for more than SECONDS (this includes waiting for a FIFO's writer to connect). Give 0 to wait forever. default: 1800 seconds. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--map MAPFILE`` | give a map file describing the content ranges of the (single) input file, so borg does not need to read all of it. See the *Input maps* section below. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--reuse-from ARCHIVE`` | reuse the chunks of this reference archive for the input map's ``same`` ranges (requires --map). See the *Input maps* section below. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--reuse-path PATH`` | archive-internal path of the reference item in the --reuse-from archive (only needed if that archive contains more than one file item). |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| **Archive options** |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--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. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2 |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| | ``--tags TAG`` | add tags to archive (comma-separated or multiple arguments) |
|
|
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
.. raw:: html
|
|
|
|
<script type='text/javascript'>
|
|
$(document).ready(function () {
|
|
$('.borg-options-table colgroup').remove();
|
|
})
|
|
</script>
|
|
|
|
.. only:: latex
|
|
|
|
NAME
|
|
specify the archive name
|
|
PATH
|
|
paths to archive
|
|
|
|
|
|
options
|
|
-n, --dry-run do not create a backup archive
|
|
-s, --stats print statistics for the created archive
|
|
--list output a 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``.
|
|
--stdin-name NAME use NAME in archive for stdin data (default: 'stdin')
|
|
--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 a command and store its stdout. See also the section 'Reading backup data from stdin' below.
|
|
--paths-from-stdin read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less.
|
|
--paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin``
|
|
--paths-from-shell-command interpret PATH as shell command and treat its output as ``--paths-from-stdin``
|
|
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin``, ``--paths-from-command`` and ``--paths-from-shell-command`` (default: ``\n``)
|
|
|
|
|
|
:ref:`common_options`
|
|
|
|
|
|
|
Include/Exclude 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
|
|
--exclude-caches exclude directories that contain a CACHEDIR.TAG file (https://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``, do not omit the tag objects themselves from the backup archive
|
|
--exclude-dataless exclude files flagged DATALESS (macOS: placeholder files whose content is not materialized locally, e.g. not-downloaded cloud storage files)
|
|
|
|
|
|
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 description below.
|
|
--numeric-ids only store numeric user and group identifiers
|
|
--atime do store atime into archive
|
|
--noctime do not store ctime into archive
|
|
--nobirthtime do not store birthtime (creation date) into archive
|
|
--noflags do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive
|
|
--noacls do not read and store ACLs into archive
|
|
--noxattrs do not read and store xattrs into archive
|
|
--sparse detect sparse holes in input and seek over them instead of reading them
|
|
--digests ALGOS compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none
|
|
--files-cache MODE operate files cache in MODE. default: ctime,size,inode (on Windows: mtime,size,inode, because ctime is file creation time there).
|
|
--files-changed MODE specify how to detect if a file has changed during backup (ctime, mtime, disabled). default: ctime (on Windows: mtime, because ctime is file creation time there).
|
|
--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.
|
|
--read-special-timeout SECONDS when reading from FIFOs or character devices (see --read-special): skip the file with an error if no data arrives for more than SECONDS (this includes waiting for a FIFO's writer to connect). Give 0 to wait forever. default: 1800 seconds.
|
|
--map MAPFILE give a map file describing the content ranges of the (single) input file, so borg does not need to read all of it. See the *Input maps* section below.
|
|
--reuse-from ARCHIVE reuse the chunks of this reference archive for the input map's ``same`` ranges (requires --map). See the *Input maps* section below.
|
|
--reuse-path PATH archive-internal path of the reference item in the --reuse-from archive (only needed if that archive contains more than one file item).
|
|
|
|
|
|
Archive options
|
|
--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.
|
|
--chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2
|
|
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
|
|
--tags TAG add tags to archive (comma-separated or multiple arguments)
|
|
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
|
|
This command creates a backup archive containing all files found while recursively
|
|
traversing all specified paths. Paths are added to the archive as they are given,
|
|
which means that if relative paths are desired, the command must be run from the correct
|
|
directory.
|
|
|
|
The slashdot hack in paths (recursion roots) is triggered by using ``/./``:
|
|
``/this/gets/stripped/./this/gets/archived`` means to process that fs object, but
|
|
strip the prefix on the left side of ``./`` from the archived items (in this case,
|
|
``this/gets/archived`` will be the path in the archived item).
|
|
|
|
If a recursion root (a path given on the command line or in a patterns file) is a
|
|
symlink, borg follows it and archives what it points to - using the path you gave.
|
|
If ``current`` is a symlink pointing to the directory ``20260801-2345``,
|
|
``borg create ARCHIVE current`` thus archives ``current`` as a directory (with the
|
|
metadata of ``20260801-2345``) and recurses into it, archiving the contained fs
|
|
objects as ``current/...``. As the archived paths do not change when the symlink
|
|
target changes, the files cache keeps working for such backups.
|
|
|
|
Note that the symlink itself is then not in the archive (and neither is its target
|
|
path), so restoring will create a real directory (or file) where the symlink was.
|
|
If you want the symlink archived as a symlink, do not give it as a recursion root,
|
|
but let borg find it while recursing (symlinks found that way are never followed).
|
|
A recursion root that is a symlink with a non-existing target is skipped with a warning.
|
|
|
|
If you give both a symlink and its target as recursion roots, borg archives the fs
|
|
objects only once, under the path given first (like for any other root given twice).
|
|
|
|
When specifying '-' as a path, borg will read data from standard input and create a
|
|
file named 'stdin' in the created archive from that data. In some cases, it is more
|
|
appropriate to use --content-from-command. See the section
|
|
*Reading backup data from stdin* below for details.
|
|
|
|
The archive will consume almost no disk space for files or parts of files that
|
|
have already been stored in other archives.
|
|
|
|
The ``--tags`` option can be used to add a list of tags to the new archive.
|
|
|
|
The archive name does not need to be unique; you can and should use the same
|
|
name for a series of archives. The unique archive identifier is its ID (hash),
|
|
and you can abbreviate the ID as long as it is unique.
|
|
|
|
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 were not 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 on POSIX systems)
|
|
- mtime,size,inode (default on Windows)
|
|
- 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 cannot 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
|
|
well-meant, but in both cases mtime-based cache modes can be problematic.
|
|
|
|
On Windows, ctime is the file *creation* time, not the "metadata change time" it is
|
|
on POSIX systems. A ctime based mode would therefore not notice content changes of a
|
|
file that keeps its size and inode number, so borg defaults to ``mtime,size,inode``
|
|
there. If a ctime based mode is given explicitly on Windows, borg warns and uses the
|
|
corresponding mtime based mode instead: ctime,size,inode -> mtime,size,inode,
|
|
ctime,size -> mtime,size, rechunk,ctime -> rechunk,mtime.
|
|
|
|
The ``--files-changed`` option controls how Borg detects if a file has changed during backup:
|
|
- ctime (default on POSIX): Use ctime to detect changes. This is the safest option.
|
|
Not supported on Windows (ctime is file creation time there).
|
|
- mtime (default on Windows): Use mtime to detect changes.
|
|
- disabled: Disable the "file has changed while we backed it up" detection completely.
|
|
This is not recommended unless you know what you're doing, as it could lead to
|
|
inconsistent backups if files change during the backup process.
|
|
|
|
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
|
|
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 and (uncompressed)
|
|
deduplicated size (O and U respectively), then the Number of files (N) processed so far,
|
|
followed by the currently processed path.
|
|
|
|
Sizes of GB and above are shown with enough decimal places that even MB-sized progress
|
|
stays visible. On a terminal, this needs a width of at least 110 columns - on narrower
|
|
terminals, the compact format is used, so that the path stays readable. If the output
|
|
does not go to a terminal (e.g. into a logfile), the precise format is always used.
|
|
|
|
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
|
|
how much your repository will grow. Please note that the "All archives" stats refer to
|
|
the state after creation.
|
|
|
|
When ``--stats`` is used together with ``--dry-run``, only the number of files and the
|
|
original size are reported. They are computed from file system metadata, without reading
|
|
the file contents, so a dry run stays fast. As data is not actually read, chunked, and
|
|
deduplicated during a dry run, the deduplicated size is unknown. The sizes of data read
|
|
from standard input, from a command's output, or from special files (``--read-special``)
|
|
are also unknown in a dry run and counted as zero.
|
|
|
|
The ``--stats`` output also reports the store statistics (lines prefixed with
|
|
"Store"), taken from the storage layer after this run. These cover the backend and
|
|
the local store cache: call counts and timings per operation, the load/store data
|
|
volumes and throughput, and cache hits/misses. "Store backend load volume" and
|
|
"Store backend store volume" are the bytes actually read from and sent to the
|
|
backend; a load counts only what missed the cache, and a store counts chunk data
|
|
together with Borg's own index and metadata writes. The values are approximate
|
|
because of write buffering and caching. On a repeated backup a near-zero store
|
|
volume means almost no new data had to be written, because the chunks already exist
|
|
in the repository (deduplication).
|
|
|
|
The "Added", "Modified" and "Unchanged" file counters come from the files-cache
|
|
comparison described above: "Unchanged" files matched the cached metadata and were
|
|
not read again (their existing chunks are reused); "Added" and "Modified" files did
|
|
not match and were read and chunked (new chunks are stored, already-known chunks are
|
|
deduplicated). The comparison uses the files cache, keyed by the file's absolute path.
|
|
|
|
For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
|
|
|
|
For more help on placeholders, see the :ref:`borg_placeholders` command output.
|
|
|
|
.. man NOTES
|
|
|
|
The ``--exclude`` patterns are not like tar. In tar ``--exclude`` .bundler/gems will
|
|
exclude foo/.bundler/gems. In borg it will not, you need to use ``--exclude``
|
|
'\*/.bundler/gems' to get the same effect.
|
|
|
|
In addition to using ``--exclude`` patterns, it is possible to use
|
|
``--exclude-if-present`` to specify the name of a filesystem object (e.g. a file
|
|
or folder name) which, when contained within another folder, will prevent the
|
|
containing folder from being backed up. By default, the containing folder and
|
|
all of its contents will be omitted from the backup. If, however, you wish to
|
|
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.
|
|
In general: be aware that there are directories with device number different from their parent, which the kernel
|
|
does not consider a mountpoint and also the other way around.
|
|
Linux examples for this 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).
|
|
macOS examples are the apfs mounts of a typical macOS installation.
|
|
Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended.
|
|
|
|
.. _list_item_flags:
|
|
|
|
Item flags
|
|
++++++++++
|
|
|
|
``--list`` outputs a list of all files, directories and other
|
|
file system items it considered (no matter whether they had content changes
|
|
or not). For each item, it prefixes a single-letter flag that indicates type
|
|
and/or status of the item.
|
|
|
|
If you are interested only in a subset of that output, you can give e.g.
|
|
``--filter=AME`` and it will only show regular files with A, M or E status (see
|
|
below).
|
|
|
|
A uppercase character represents the status of a regular file relative to the
|
|
"files" cache (not relative to the repo -- this is an issue if the files cache
|
|
is not used). Metadata is stored in any case and for 'A' and 'M' also new data
|
|
chunks are stored. For 'U' all data chunks refer to already existing chunks.
|
|
|
|
- 'A' = regular file, added (see also :ref:`a_status_oddity` in the FAQ)
|
|
- 'M' = regular file, modified
|
|
- 'U' = regular file, unchanged
|
|
- 'C' = regular file, it changed while we backed it up
|
|
- 'E' = regular file, an error happened while accessing/reading *this* file
|
|
|
|
A lowercase character means a file type other than a regular file,
|
|
borg usually just stores their metadata:
|
|
|
|
- 'd' = directory
|
|
- 'b' = block device
|
|
- 'c' = char device
|
|
- 'h' = regular file, hard link (to already seen inodes)
|
|
- 's' = symlink
|
|
- 'f' = fifo
|
|
|
|
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)
|
|
- 'x' = skipped due to ``--exclude-dataless`` (file is flagged DATALESS)
|
|
- '?' = missing status code (if you see this, please file a bug report!)
|
|
|
|
Errors and (incomplete) archives
|
|
++++++++++++++++++++++++++++++++
|
|
|
|
If an error happens during archive creation (e.g. some file could not be read
|
|
due to a permission error or some other OS error), borg will log a warning or
|
|
an error (depending on the type of issue) and continue with the next item.
|
|
|
|
At the end of the backup, if there were any such issues, borg will exit with
|
|
a non-zero exit code (usually 1 for warnings).
|
|
|
|
**The archive is still saved even if warnings or errors occurred**, but it will
|
|
only contain the data borg was able to read successfully.
|
|
|
|
You should always check the backup logs and the exit code of the borg command.
|
|
|
|
Reading backup data from stdin
|
|
++++++++++++++++++++++++++++++
|
|
|
|
There are two methods to read from stdin. Either specify ``-`` as path and
|
|
pipe directly to borg::
|
|
|
|
backup-vm --id myvm --stdout | borg create --repo REPO ARCHIVE -
|
|
|
|
Or use ``--content-from-command`` to have Borg manage the execution of the
|
|
command and piping. If you do so, the first PATH argument is interpreted
|
|
as command to execute and any further arguments are treated as arguments
|
|
to the command::
|
|
|
|
borg create --content-from-command --repo REPO ARCHIVE -- backup-vm --id myvm --stdout
|
|
|
|
``--`` is used to ensure ``--id`` and ``--stdout`` are **not** considered
|
|
arguments to ``borg`` but rather ``backup-vm``.
|
|
|
|
The difference between the two approaches is that piping to borg creates an
|
|
archive even if the command piping to borg exits with a failure. In this case,
|
|
**one can end up with truncated output being backed up**. Using
|
|
``--content-from-command``, in contrast, borg is guaranteed to fail without
|
|
creating an archive should the command fail. The command is considered failed
|
|
when it returned a non-zero exit code.
|
|
|
|
Reading from stdin yields just a stream of data without file metadata
|
|
associated with it, and the files cache is not needed at all. So it is
|
|
safe to disable it via ``--files-cache disabled`` and speed up backup
|
|
creation a bit.
|
|
|
|
By default, the content read from stdin is stored in a file called 'stdin'.
|
|
Use ``--stdin-name`` to change the name.
|
|
|
|
Input maps
|
|
++++++++++
|
|
|
|
Usually, borg reads the complete input to determine its contents. If you already
|
|
know the contents of parts of the input from an external source of truth, you can
|
|
give that information via ``--map MAPFILE`` and borg will not read the known parts.
|
|
The primary use case is backing up snapshots of large block devices (e.g. LVM thin
|
|
volumes), where the storage layer knows which ranges are in use.
|
|
|
|
The map file must describe the whole input: one range per line, in the form
|
|
``START LENGTH STATE`` (byte values, decimal or 0x-prefixed hexadecimal). The
|
|
ranges must be sorted, non-overlapping and contiguous, starting at offset 0 and
|
|
covering the exact input size. ``#`` starts a comment, empty lines are ignored.
|
|
STATE is one of:
|
|
|
|
- ``data``: the range's contents are read and backed up.
|
|
- ``zero``: the range is known to read as all-zero bytes. borg stores a hole
|
|
(all-zero range) of that size without reading the range.
|
|
- ``same``: the range is known to be identical to the same range of the input
|
|
backed up in the ``--reuse-from REFARCHIVE`` reference archive (usually: the
|
|
previous backup of an earlier snapshot of the same device). borg reuses the
|
|
reference archive's chunks for such ranges without reading them. This state
|
|
requires ``--reuse-from``.
|
|
|
|
**The map is trusted**: if it is wrong (e.g. a range marked ``zero`` actually
|
|
contains data, or a range marked ``same`` actually changed), the archive will
|
|
not match the input and borg cannot detect that. Independently verify the
|
|
source producing the maps, and consider doing a periodic full read backup
|
|
(without ``--map``).
|
|
|
|
For LVM thin volume snapshots, maps can be generated from ``thin_dump`` /
|
|
``thin_delta`` XML with the ``scripts/lvm-thin-map.py`` converter from the
|
|
borg sources; its docstring shows the complete workflow.
|
|
|
|
``--map`` requires giving exactly one input path, which must be a regular file or
|
|
(with ``--read-special``) a block device.
|
|
|
|
The reference archive must contain exactly one file item; if it contains more,
|
|
select the reference item with ``--reuse-path PATH`` (its archive-internal path).
|
|
Reference chunks that only partially overlap ``same`` ranges are re-read from
|
|
the input, so any chunker gives correct results - but a fixed block size chunker
|
|
(e.g. ``--chunker-params fixed,4194304``, same parameters as used for the
|
|
reference archive) avoids re-reading at the edges of changed ranges and gives
|
|
stable chunk boundaries across backups.
|
|
|
|
Feeding all file paths from externally
|
|
++++++++++++++++++++++++++++++++++++++
|
|
|
|
Usually, you give a starting path (recursion root) to borg and then borg
|
|
automatically recurses, finds and backs up all fs objects contained in
|
|
there (optionally considering include/exclude rules).
|
|
|
|
If you need more control and you want to give every single fs object path
|
|
to borg (maybe implementing your own recursion or your own rules), you can use
|
|
``--paths-from-stdin``, ``--paths-from-command`` or ``--paths-from-shell-command``
|
|
(with the latter two, borg will fail to create an archive should the command fail).
|
|
|
|
Borg supports paths with the slashdot hack to strip path prefixes here also.
|
|
So, be careful not to unintentionally trigger that.
|
|
|
|
Symlinks given this way are never followed (unlike recursion roots are), they are
|
|
archived as symlinks. |