mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-28 19:01:58 +00:00
209 lines
9 KiB
Groff
209 lines
9 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "BORG-CHECK" 1 "2023-09-14" "" "borg backup tool"
|
|
.SH NAME
|
|
borg-check \- Check repository consistency
|
|
.SH SYNOPSIS
|
|
.sp
|
|
borg [common options] check [options]
|
|
.SH DESCRIPTION
|
|
.sp
|
|
The check command verifies the consistency of a repository and its archives.
|
|
It consists of two major steps:
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
Checking the consistency of the repository itself. This includes checking
|
|
the segment magic headers, and both the metadata and data of all objects in
|
|
the segments. The read data is checked by size and CRC. Bit rot and other
|
|
types of accidental damage can be detected this way. Running the repository
|
|
check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
|
|
When checking a remote repository, please note that the checks run on the
|
|
server and do not cause significant network traffic.
|
|
.IP 2. 3
|
|
Checking consistency and correctness of the archive metadata and optionally
|
|
archive data (requires \fB\-\-verify\-data\fP). 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 \fB\-\-verify\-data\fP, 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.
|
|
.UNINDENT
|
|
.sp
|
|
Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run the
|
|
repository checks only, or pass \fB\-\-archives\-only\fP to run the archive checks
|
|
only.
|
|
.sp
|
|
The \fB\-\-max\-duration\fP 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 \fB\-\-max\-duration=3600\fP
|
|
(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
|
|
\fB\-\-max\-duration\fP you must also pass \fB\-\-repository\-only\fP, and must not pass
|
|
\fB\-\-archives\-only\fP, nor \fB\-\-repair\fP\&.
|
|
.sp
|
|
\fBWarning:\fP Please note that partial repository checks (i.e. running it with
|
|
\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
|
|
segment files. A full repository check (i.e. without \fB\-\-max\-duration\fP) can
|
|
also do a repository index check. 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.
|
|
.sp
|
|
The \fB\-\-verify\-data\fP 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. 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 \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&.
|
|
.SS About repair mode
|
|
.sp
|
|
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 \fB\-\-repair\fP\&.
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
\fB\-\-repair\fP is a \fBPOTENTIALLY DANGEROUS FEATURE\fP 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. \fBBE VERY CAREFUL!\fP
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Pursuant to the previous warning it is also highly recommended to test the
|
|
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.
|
|
.sp
|
|
It is highly recommended to create a backup of your repository before running
|
|
in repair mode (i.e. running it with \fB\-\-repair\fP).
|
|
.sp
|
|
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.
|
|
.sp
|
|
In practice, repair mode hooks into both the repository and archive checks:
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
When checking the repository\(aqs consistency, repair mode will try to recover
|
|
as many objects from segments with integrity errors as possible, and ensure
|
|
that the index is consistent with the data stored in the segments.
|
|
.IP 2. 3
|
|
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
|
|
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).
|
|
.UNINDENT
|
|
.sp
|
|
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 \fBextract\fP command will distinctly warn about it. The FUSE filesystem
|
|
created by the \fBmount\fP command will reject reading such a \(dqzero\-patched\(dq
|
|
file unless a special mount option is given.
|
|
.sp
|
|
As mentioned earlier, Borg might be able to \(dqheal\(dq a \(dqzero\-patched\(dq 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 \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file.
|
|
Consequently, if lost chunks were repaired earlier, it is advised to run
|
|
\fB\-\-repair\fP a second time after creating some new backups.
|
|
.SH OPTIONS
|
|
.sp
|
|
See \fIborg\-common(1)\fP for common options of Borg commands.
|
|
.SS options
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-repository\-only
|
|
only perform repository checks
|
|
.TP
|
|
.B \-\-archives\-only
|
|
only perform archives checks
|
|
.TP
|
|
.B \-\-verify\-data
|
|
perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP)
|
|
.TP
|
|
.B \-\-repair
|
|
attempt to repair any inconsistencies found
|
|
.TP
|
|
.BI \-\-max\-duration \ SECONDS
|
|
do only a partial repo check for max. SECONDS seconds (Default: unlimited)
|
|
.UNINDENT
|
|
.SS Archive filters
|
|
.INDENT 0.0
|
|
.TP
|
|
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
|
|
only consider archive names matching the pattern. see \(dqborg help match\-archives\(dq.
|
|
.TP
|
|
.BI \-\-sort\-by \ KEYS
|
|
Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
|
|
.TP
|
|
.BI \-\-first \ N
|
|
consider first N archives after other filters were applied
|
|
.TP
|
|
.BI \-\-last \ N
|
|
consider last N archives after other filters were applied
|
|
.TP
|
|
.BI \-\-oldest \ TIMESPAN
|
|
consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
|
|
.TP
|
|
.BI \-\-newest \ TIMESPAN
|
|
consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g. 7d or 12m.
|
|
.TP
|
|
.BI \-\-older \ TIMESPAN
|
|
consider archives older than (now \- TIMESPAN), e.g. 7d oder 12m.
|
|
.TP
|
|
.BI \-\-newer \ TIMESPAN
|
|
consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
|
|
.UNINDENT
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fIborg\-common(1)\fP
|
|
.SH AUTHOR
|
|
The Borg Collective
|
|
.\" Generated by docutils manpage writer.
|
|
.
|