mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-27 02:08:54 +00:00
Code Issues Releases Wiki Activity
borg/docs/usage/check.rst.inc

143 lines
15 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
python setup.py build_usage
2017-07-23 15:12:01 +00:00
borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
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
python setup.py build_usage
2017-07-23 15:12:01 +00:00
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to check consistency of |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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 |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--save-space`` | work slower, but using less space |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
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) |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
python setup.py build_usage
2017-07-23 15:12:01 +00:00
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-P PREFIX``, ``--prefix PREFIX`` | only consider archive names starting with this prefix. |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, 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 |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
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
REPOSITORY_OR_ARCHIVE
repository or archive to check consistency of
optional arguments
--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
--save-space work slower, but using less space
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
-P PREFIX, --prefix PREFIX only consider archive names starting with this prefix.
-a GLOB, --glob-archives GLOB only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, 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
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
~~~~~~~~~~~
The check command verifies the consistency of a repository and the corresponding archives.
First, the underlying repository data files are checked:
- For all segments the segment magic (header) is checked
- For all objects stored in the segments, all metadata (e.g. crc and size) and
all data is read. The read data is checked by size and CRC. Bit rot and other
types of accidental damage can be detected this way.
- If we are in repair mode and a integrity error is detected for a segment,
we try to recover as many objects from the segment as possible.
- In repair mode, it makes sure that the index is consistent with the data
stored in the segments.
- If you use a remote repo server via ssh:, the repo check is executed on the
repo server without causing significant network traffic.
python setup.py build_usage
2017-06-17 10:28:42 +00:00
- The repository check can be skipped using the ``--archives-only`` option.
build_usage
2019-04-22 16:00:28 +00:00
- A repository check can be time consuming. Partial checks are possible with the ``--max-duration`` option.
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
Second, the consistency and correctness of the archive metadata is verified:
- Is the repo manifest present? If not, it is rebuilt from archive metadata
chunks (this requires reading and decrypting of all metadata and data).
- Check if archive metadata chunk is present. if not, remove archive from
manifest.
- For all files (items) in the archive, for all chunks referenced by these
ran build_usage
2016-07-10 17:00:55 +00:00
files, check if chunk is present.
If a chunk is not present and we are in repair mode, replace it with a same-size
replacement chunk of zeros.
If a previously lost chunk reappears (e.g. via a later backup) and we are in
repair mode, the all-zero replacement chunk will be replaced by the correct chunk.
This requires reading of archive and file metadata, but not data.
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
- If we are in repair mode and we checked all the archives: delete orphaned
chunks from the repo.
- if you use a remote repo server via ssh:, the archive check is executed on
the client machine (because if encryption is enabled, the checks will require
decryption and this is always done client-side, because key access will be
required).
- The archive checks can be time consuming, they can be skipped using the
python setup.py build_usage
2017-06-17 10:28:42 +00:00
``--repository-only`` option.
Merge branch '1.0-maint'
2016-07-05 23:33:53 +00:00
build_usage
2019-04-22 16:00:28 +00:00
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 complete repository has been checked. Example: Assuming a full check took 7
hours, then running a daily check with --max-duration=3600 (1 hour) would result in one full check per week.
Attention: Partial checks can only do way less checks than a full check (only the CRC32 checks on segment file
entries are done) and cannot be combined with ``--repair``. Partial checks may therefore be useful only with very
large repositories where a full check would take too long. Doing a full repository check aborts a partial check;
the next partial check will start from the beginning.
python setup.py build_usage
2017-06-17 10:28:42 +00:00
The ``--verify-data`` option will perform a full integrity verification (as opposed to
Merge branch '1.0-maint'
2016-07-05 23:33:53 +00:00
checking the CRC32 of the segment) of data, which means reading the data from the
repository, decrypting and decompressing it. This is a cryptographic verification,
which will detect (accidental) corruption. For encrypted repositories it is
tamper-resistant as well, unless the attacker has access to the keys.
ran setup.py build_usage
2017-03-26 23:45:45 +00:00
It is also very slow.
Reference in a new issue Copy permalink