mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-23 16:26:29 +00:00
Code Issues Releases Wiki Activity
borg/docs/usage/check.rst.inc

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

205 lines
17 KiB
PHP
Raw Normal View History

update usage files
2016-07-05 21:30:08 +00:00
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
commit usage files directly into git the generation of those files was causing us way too much pain to justify automatically generating them all the time. those will have to be re-generated with `build_api` or `build_usage` as appropriate, for example when function signatures or commandline flags change. see #384
2015-11-13 15:42:16 +00:00
.. _borg_check:
borg check
----------
docs: usage: avoid bash highlight, [options] instead of <options>
2017-06-06 22:44:53 +00:00
.. code-block:: none
commit usage files directly into git the generation of those files was causing us way too much pain to justify automatically generating them all the time. those will have to be re-generated with `build_api` or `build_usage` as appropriate, for example when function signatures or commandline flags change. see #384
2015-11-13 15:42:16 +00:00
build_usage / build_man / doc updates
2022-06-23 23:19:19 +00:00
borg [common options] check [options]
Better help texts and Sphinx reproduction of usage - Group options - Nicer list of options in Sphinx - Deduplicate 'Common options' (including --help) The latter is done by explicitly declaring --help in the common_parser, which is then inherited by the sub-parsers; no change in observable behaviour.
2016-04-09 23:28:18 +00:00
ran build_usage
2017-06-20 13:22:24 +00:00
.. only:: html
.. class:: borg-options-table
build_usage
2024-02-20 16:11:43 +00:00
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
build_usage / build_man
2024-07-19 18:40:15 +00:00
| **optional arguments** |
build_usage
2024-02-20 16:11:43 +00:00
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--repository-only`` | only perform repository checks |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--archives-only`` | only perform archives checks |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--verify-data`` | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--repair`` | attempt to repair any inconsistencies found |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
build_usage / build_man
2024-09-07 20:31:48 +00:00
| | ``--undelete-archives`` | attempt to undelete archives (use with --repair) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
build_usage
2024-02-20 16:11:43 +00:00
| | ``--max-duration SECONDS`` | do only a partial repo check for max. SECONDS seconds (Default: unlimited) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--first N`` | consider first N archives after other filters were applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--last N`` | consider last N archives after other filters were applied |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
ran build_usage
2017-06-20 13:22:24 +00:00
.. raw:: html
<script type='text/javascript'>
docs: use DOM ready event, not document loaded event
2017-06-20 13:48:30 +00:00
$(document).ready(function () {
ran build_usage
2017-06-20 13:22:24 +00:00
$('.borg-options-table colgroup').remove();
})
</script>
.. only:: latex
build_usage / build_man
2024-07-19 18:40:15 +00:00
optional arguments
ran build_usage
2017-06-20 13:22:24 +00:00
--repository-only only perform repository checks
--archives-only only perform archives checks
--verify-data perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
--repair attempt to repair any inconsistencies found
build_usage / build_man
2024-09-07 20:31:48 +00:00
--undelete-archives attempt to undelete archives (use with --repair)
build_usage
2019-03-10 23:11:16 +00:00
--max-duration SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited)
ran build_usage
2017-06-20 13:22:24 +00:00
:ref:`common_options`
|
python setup.py build_usage
2017-07-23 15:12:01 +00:00
Archive filters
build_man / build_usage
2022-10-02 13:51:17 +00:00
-a PATTERN, --match-archives PATTERN only consider archive names matching the pattern. see "borg help match-archives".
build_usage
2024-02-20 16:11:43 +00:00
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id; default is: timestamp
build_man / build_usage
2022-10-02 13:51:17 +00:00
--first N consider first N archives after other filters were applied
--last N consider last N archives after other filters were applied
build_usage
2023-02-26 20:30:28 +00:00
--oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
--newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m.
build_usage
2024-02-20 16:11:43 +00:00
--older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d or 12m.
build_usage
2023-02-26 20:30:28 +00:00
--newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.
ran build_usage
2017-06-20 09:49:26 +00:00
ran build_usage had merge conflicts in the usage files, decided to just recreate them afterwards.
2016-11-28 01:25:56 +00:00
commit usage files directly into git the generation of those files was causing us way too much pain to justify automatically generating them all the time. those will have to be re-generated with `build_api` or `build_usage` as appropriate, for example when function signatures or commandline flags change. see #384
2015-11-13 15:42:16 +00:00
Description
~~~~~~~~~~~
build_usage / build_man
2023-09-14 13:52:08 +00:00
The check command verifies the consistency of a repository and its archives.
It consists of two major steps:
1. Checking the consistency of the repository itself. This includes checking
build_usage / build_man
2024-09-07 20:31:48 +00:00
the file magic headers, and both the metadata and data of all objects in
the repository. The read data is checked by size and hash. Bit rot and other
build_usage / build_man
2023-09-14 13:52:08 +00:00
types of accidental damage can be detected this way. Running the repository
check can be split into multiple partial checks using ``--max-duration``.
When checking a remote repository, please note that the checks run on the
server and do not cause significant network traffic.
2. Checking consistency and correctness of the archive metadata and optionally
archive data (requires ``--verify-data``). This includes ensuring that the
repository manifest exists, the archive metadata chunk is present, and that
all chunks referencing files (items) in the archive exist. This requires
reading archive and file metadata, but not data. To cryptographically verify
the file (content) data integrity pass ``--verify-data``, but keep in mind
that this requires reading all data and is hence very time consuming. When
checking archives of a remote repository, archive checks run on the client
machine because they require decrypting data and therefore the encryption
key.
Both steps can also be run independently. Pass ``--repository-only`` to run the
repository checks only, or pass ``--archives-only`` to run the archive checks
only.
The ``--max-duration`` option can be used to split a long-running repository
check into multiple partial checks. After the given number of seconds the check
is interrupted. The next partial check will continue where the previous one
stopped, until the full repository has been checked. Assuming a complete check
would take 7 hours, then running a daily check with ``--max-duration=3600``
(1 hour) would result in one full repository check per week. Doing a full
repository check aborts any previous partial check; the next partial check will
restart from the beginning. With partial repository checks you can run neither
archive checks, nor enable repair mode. Consequently, if you want to use
``--max-duration`` you must also pass ``--repository-only``, and must not pass
``--archives-only``, nor ``--repair``.
**Warning:** Please note that partial repository checks (i.e. running it with
``--max-duration``) can only perform non-cryptographic checksum checks on the
build_usage / build_man
2024-09-07 20:31:48 +00:00
repository files. Enabling partial repository checks excepts archive checks
for the same reason. Therefore partial checks may be useful with very large
repositories only where a full check would take too long.
build_usage / build_man
2023-09-14 13:52:08 +00:00
The ``--verify-data`` option will perform a full integrity verification (as
build_usage / build_man
2024-09-07 20:31:48 +00:00
opposed to checking just the xxh64) of data, which means reading the
build_usage / build_man
2023-09-14 13:52:08 +00:00
data from the repository, decrypting and decompressing it. It is a complete
cryptographic verification and hence very time consuming, but will detect any
accidental and malicious corruption. Tamper-resistance is only guaranteed for
encrypted repositories against attackers without access to the keys. You can
not use ``--verify-data`` with ``--repository-only``.
About repair mode
+++++++++++++++++
The check command is a readonly task by default. If any corruption is found,
Borg will report the issue and proceed with checking. To actually repair the
issues found, pass ``--repair``.
.. note::
``--repair`` is a **POTENTIALLY DANGEROUS FEATURE** and might lead to data
loss! This does not just include data that was previously lost anyway, but
might include more data for kinds of corruption it is not capable of
dealing with. **BE VERY CAREFUL!**
build_usage
2020-10-04 18:32:38 +00:00
add notice about defective hardware to check documentation (#5753)
2021-06-17 05:24:32 +00:00
Pursuant to the previous warning it is also highly recommended to test the
build_usage / build_man
2023-09-14 13:52:08 +00:00
reliability of the hardware running Borg with stress testing software. This
especially includes storage and memory testers. Unreliable hardware might lead
to additional data loss.
It is highly recommended to create a backup of your repository before running
in repair mode (i.e. running it with ``--repair``).
Repair mode will attempt to fix any corruptions found. Fixing corruptions does
not mean recovering lost data: Borg can not magically restore data lost due to
e.g. a hardware failure. Repairing a repository means sacrificing some data
for the sake of the repository as a whole and the remaining data. Hence it is,
by definition, a potentially lossy task.
In practice, repair mode hooks into both the repository and archive checks:
build_usage / build_man
2024-09-07 20:31:48 +00:00
1. When checking the repository's consistency, repair mode removes corrupted
objects from the repository after it did a 2nd try to read them correctly.
build_usage / build_man
2023-09-14 13:52:08 +00:00
2. When checking the consistency and correctness of archives, repair mode might
remove whole archives from the manifest if their archive metadata chunk is
corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
will replace corrupt or lost chunks with a same-size replacement chunk of
zeroes. If a previously zeroed chunk reappears, repair mode will restore
build_usage / build_man
2024-09-07 20:31:48 +00:00
this lost chunk using the new chunk.
build_usage / build_man
2023-09-14 13:52:08 +00:00
Most steps taken by repair mode have a one-time effect on the repository, like
removing a lost archive from the repository. However, replacing a corrupt or
lost chunk with an all-zero replacement will have an ongoing effect on the
repository: When attempting to extract a file referencing an all-zero chunk,
the ``extract`` command will distinctly warn about it. The FUSE filesystem
created by the ``mount`` command will reject reading such a "zero-patched"
file unless a special mount option is given.
As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in
repair mode, if all its previously lost chunks reappear (e.g. via a later
backup). This is achieved by Borg not only keeping track of the all-zero
replacement chunks, but also by keeping metadata about the lost chunks. In
repair mode Borg will check whether a previously lost chunk reappeared and will
replace the all-zero replacement chunk by the reappeared chunk. If all lost
chunks of a "zero-patched" file reappear, this effectively "heals" the file.
Consequently, if lost chunks were repaired earlier, it is advised to run
build_usage / build_man
2024-09-07 20:31:48 +00:00
``--repair`` a second time after creating some new backups.
If ``--repair --undelete-archives`` is given, Borg will scan the repository
for archive metadata and if it finds some where no corresponding archives
directory entry exists, it will create the entries. This is basically undoing
``borg delete archive`` or ``borg prune ...`` commands and only possible before
``borg compact`` would remove the archives' data completely.
Reference in a new issue Copy permalink