mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-27 18:28:42 +00:00
Code Issues Releases Wiki Activity

Docs: Improve borg check docs

Browse source
This commit is contained in:
Daniel Rudolf 2023-07-10 17:25:57 +02:00
parent a661da13ee
commit 2647673dc8
No known key found for this signature in database
GPG key ID: A061F02CD8DE4538
1 changed files with 26 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
src/borg/archiver/check_cmd.py
View file

@ -83,14 +83,15 @@ def build_parser_check(self, subparsers, common_parser, mid_common_parser):
server and do not cause significant network traffic. server and do not cause significant network traffic.
2. Checking consistency and correctness of the archive metadata and optionally 2. Checking consistency and correctness of the archive metadata and optionally
archive data (requires ``--verify-data`). This includes ensuring that the archive data (requires ``--verify-data``). This includes ensuring that the
repository manifest exists, the archive metadata chunk is present, and that repository manifest exists, the archive metadata chunk is present, and that
all chunks referencing files (items) in the archive exist. This requires all chunks referencing files (items) in the archive exist. This requires
reading archive and file metadata, but not data. To verify the cryptographic reading archive and file metadata, but not data. To cryptographically verify
archive data integrity pass ``--verify-data`, but keep in mind that this the file (content) data integrity pass ``--verify-data``, but keep in mind
requires reading all data and is hence very time consuming. When checking that this requires reading all data and is hence very time consuming. When
archives of a remote repository, archive checks run on the client machine checking archives of a remote repository, archive checks run on the client
because they require decrypting data and therefore the encryption key. machine because they require decrypting data and therefore the encryption
key.
Both steps can also be run independently. Pass ``--repository-only`` to run the 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 repository checks only, or pass ``--archives-only`` to run the archive checks
@ -105,8 +106,8 @@ def build_parser_check(self, subparsers, common_parser, mid_common_parser):
repository check aborts any previous partial check; the next partial check will repository check aborts any previous partial check; the next partial check will
restart from the beginning. With partial repository checks you can run neither restart from the beginning. With partial repository checks you can run neither
archive checks, nor enable repair mode. Consequently, if you want to use archive checks, nor enable repair mode. Consequently, if you want to use
``--max-duration`` you must also pass ``--repository-only``, and must pass ``--max-duration`` you must also pass ``--repository-only``, and must not pass
neither ``--archives-only``, nor ``--repair``. ``--archives-only``, nor ``--repair``.
**Warning:** Please note that partial repository checks (i.e. running it with **Warning:** Please note that partial repository checks (i.e. running it with
``--max-duration``) can only perform non-cryptographic checksum checks on the ``--max-duration``) can only perform non-cryptographic checksum checks on the
@ -119,7 +120,7 @@ def build_parser_check(self, subparsers, common_parser, mid_common_parser):
opposed to checking the CRC32 of the segment) of data, which means reading the opposed to checking the CRC32 of the segment) of data, which means reading the
data from the repository, decrypting and decompressing it. It is a complete data from the repository, decrypting and decompressing it. It is a complete
cryptographic verification and hence very time consuming, but will detect any cryptographic verification and hence very time consuming, but will detect any
accidental and malicious corruption. Tamper-resistance is only gauranteed for accidental and malicious corruption. Tamper-resistance is only guaranteed for
encrypted repositories against attackers without access to the keys. You can encrypted repositories against attackers without access to the keys. You can
not use ``--verify-data`` with ``--repository-only``. not use ``--verify-data`` with ``--repository-only``.
@ -149,7 +150,7 @@ def build_parser_check(self, subparsers, common_parser, mid_common_parser):
not mean recovering lost data: Borg can not magically restore data lost due to 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 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, for the sake of the repository as a whole and the remaining data. Hence it is,
by definition, a lossy task. by definition, a potentially lossy task.
In practice, repair mode hooks into both the repository and archive checks: In practice, repair mode hooks into both the repository and archive checks:
@ -165,20 +166,23 @@ def build_parser_check(self, subparsers, common_parser, mid_common_parser):
this lost chunk using the new chunk. Lastly, repair mode will also delete this lost chunk using the new chunk. Lastly, repair mode will also delete
orphaned chunks (e.g. caused by read errors while creating the archive). orphaned chunks (e.g. caused by read errors while creating the archive).
Most steps taken by repair mode have an onetime effect on the repository, like 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 removing a lost archive from the repository. However, replacing a corrupt or
lost chunk with a same-size all-zero replacement will have an ongoing effect on lost chunk with an all-zero replacement will have an ongoing effect on the
the repository: When attempting to extract a file referencing an all-zero repository: When attempting to extract a file referencing an all-zero chunk,
chunk, the ``extract`` command will distinctly warn about it. The ``mount`` the ``extract`` command will distinctly warn about it. The FUSE filesystem
command will reject reading such a "zero-patched" file unless a special mount created by the ``mount`` command will reject reading such a "zero-patched"
option is given. file unless a special mount option is given.
This ongoing effect of all-zero replacement chunks has a big advantage: If a As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in
previously lost chunk reappears (e.g. via a later backup), repair mode might repair mode, if all its previously lost chunks reappear (e.g. via a later
"heal" some of these "zero-patched" files and restore some of the previously backup). This is achieved by Borg not only keeping track of the all-zero
lost data. However, this "healing process" can only happen in repair mode. replacement chunks, but also by keeping metadata about the lost chunks. In
Thus it is advised to run ``--repair`` a second time after creating some new repair mode Borg will check whether a previously lost chunk reappeared and will
backups. 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
``--repair`` a second time after creating some new backups.
""" """
) )
subparser = subparsers.add_parser( subparser = subparsers.add_parser(