BORG-CHECK(1) borg backup tool BORG-CHECK(1)
NAME
borg-check - Check repository consistency
SYNOPSIS
borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
DESCRIPTION
The check command verifies the consistency of a repository and the cor-
responding archives.
check --repair is a potentially dangerous function and might lead to
data loss (for kinds of corruption it is not capable of dealing with).
BE VERY CAREFUL!
Pursuant to the previous warning it is also highly recommended to test
the reliability of the hardware running this software with stress test-
ing software such as memory testers. Unreliable hardware can also lead
to data loss especially when this command is run in repair mode.
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.
• In repair mode, if an integrity error is detected in a segment, try
to recover as many objects from the segment as possible.
• In repair mode, make sure that the index is consistent with the data
stored in the segments.
• If checking a remote repo via ssh:, the repo check is executed on the
server without causing significant network traffic.
• The repository check can be skipped using the --archives-only option.
• A repository check can be time consuming. Partial checks are possible
with the --max-duration option.
Second, the consistency and correctness of the archive metadata is ver-
ified:
• 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 files, check if chunk is present. In repair mode, if a chunk is
not present, replace it with a same-size replacement chunk of zeroes.
If a previously lost chunk reappears (e.g. via a later backup), 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.
• In repair mode, when all the archives were checked, orphaned chunks
are deleted from the repo. One cause of orphaned chunks are input
file related errors (like read errors) in the archive creation
process.
• In verify-data mode, a complete cryptographic verification of the ar-
chive data integrity is performed. This conflicts with --reposi-
tory-only as this mode only makes sense if the archive checks are en-
abled. The full details of this mode are documented below.
• If checking a remote repo via ssh:, the archive check is executed on
the client machine because it requires decryption, and this is always
done client-side as key access is needed.
• The archive checks can be time consuming; they can be skipped using
the --repository-only option.
The --max-duration option can be used to split a long-running reposi-
tory check into multiple partial checks. After the given number of sec-
onds 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 complete check took 7 hours, then running
a daily check with --max-duration=3600 (1 hour) resulted in one com-
pleted check per week.
Attention: A partial --repository-only check can only do way less
checking than a full --repository-only check: only the non-crypto-
graphic checksum checks on segment file entries are done, while a full
--repository-only check would also do a repo index check. A partial
check cannot be combined with the --repair option. 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 par-
tial check; the next partial check will restart from the beginning.
The --verify-data option will perform a full integrity verification (as
opposed to 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. It is also very slow.
OPTIONS
See borg-common(1) for common options of Borg commands.
arguments
REPOSITORY_OR_ARCHIVE
repository or archive to check consistency of
options
--repository-only
only perform repository checks
--archives-only
only perform archives checks
--verify-data
perform cryptographic archive data integrity verification (con-
flicts with --repository-only)
--repair
attempt to repair any inconsistencies found
--save-space
work slower, but using less space
--max-duration SECONDS
do only a partial repo check for max. SECONDS seconds (Default:
unlimited)
Archive filters
-P PREFIX, --prefix PREFIX
only consider archive names starting with this prefix. (depre-
cated)
-a GLOB, --glob-archives GLOB
only consider archive names matching the glob. sh: rules apply,
see "borg help patterns".
--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
SEE ALSO
borg-common(1)
AUTHOR
The Borg Collective
2023-03-22 BORG-CHECK(1)
Generated by dwww version 1.15 on Sat Jun 29 02:21:36 CEST 2024.