summaryrefslogtreecommitdiff
path: root/Documentation/btrfs-scrub.8
diff options
context:
space:
mode:
authorDimitri John Ledkov <xnox@ubuntu.com>2018-12-11 10:30:30 +1100
committerDimitri John Ledkov <xnox@ubuntu.com>2018-12-11 10:30:30 +1100
commit5b162a39be9dec46a22c815f43fc337b920b4252 (patch)
treee9d6f16368ffe614a45eade6b0d6f9a860cea508 /Documentation/btrfs-scrub.8
parent167651ca29ec522cff0d81b52dc0cc4ae4e3f535 (diff)
New upstream version 4.19.1
Diffstat (limited to 'Documentation/btrfs-scrub.8')
-rw-r--r--Documentation/btrfs-scrub.8189
1 files changed, 189 insertions, 0 deletions
diff --git a/Documentation/btrfs-scrub.8 b/Documentation/btrfs-scrub.8
new file mode 100644
index 00000000..a393a553
--- /dev/null
+++ b/Documentation/btrfs-scrub.8
@@ -0,0 +1,189 @@
+'\" t
+.\" Title: btrfs-scrub
+.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\" Date: 12/05/2018
+.\" Manual: Btrfs Manual
+.\" Source: Btrfs v4.19.1
+.\" Language: English
+.\"
+.TH "BTRFS\-SCRUB" "8" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+btrfs-scrub \- scrub btrfs filesystem, verify block checksums
+.SH "SYNOPSIS"
+.sp
+\fBbtrfs scrub\fR \fI<subcommand>\fR \fI<args>\fR
+.SH "DESCRIPTION"
+.sp
+\fBbtrfs scrub\fR is used to scrub a btrfs filesystem, which will read all data and metadata blocks from all devices and verify checksums\&. Automatically repair corrupted blocks if there\(cqs a correct copy available\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+Scrub is not a filesystem checker (fsck) and does not verify nor repair structural damage in the filesystem\&.
+.sp .5v
+.RE
+.sp
+The user is supposed to run it manually or via a periodic system service\&. The recommended period is a month but could be less\&. The estimated device bandwidth utilization is about 80% on an idle filesystem\&. The IO priority class is by default \fIidle\fR so background scrub should not significantly interfere with normal filesystem operation\&.
+.sp
+The scrubbing status is recorded in \fI/var/lib/btrfs/\fR in textual files named \fIscrub\&.status\&.UUID\fR for a filesystem identified by the given UUID\&. (Progress state is communicated through a named pipe in file \fIscrub\&.progress\&.UUID\fR in the same directory\&.) The status file is updated every 5 seconds\&. A resumed scrub will continue from the last saved position\&.
+.SH "SUBCOMMAND"
+.PP
+\fBcancel\fR \fI<path>\fR|\fI<device>\fR
+.RS 4
+If a scrub is running on the filesystem identified by
+\fIpath\fR
+cancel it\&.
+.sp
+If a
+\fIdevice\fR
+is specified, the corresponding filesystem is found and
+\fBbtrfs scrub cancel\fR
+behaves as if it was called on that filesystem\&.
+.RE
+.PP
+\fBresume\fR [\-BdqrR] [\-c \fI<ioprio_class>\fR \-n \fI<ioprio_classdata>\fR] \fI<path>\fR|\fI<device>\fR
+.RS 4
+Resume a cancelled or interrupted scrub on the filesystem identified by
+\fIpath\fR
+or on a given
+\fIdevice\fR\&.
+.sp
+Does not start a new scrub if the last scrub finished successfully\&.
+.sp
+\fBOptions\fR
+.sp
+see
+\fBscrub start\fR\&.
+.RE
+.PP
+\fBstart\fR [\-BdqrRf] [\-c \fI<ioprio_class>\fR \-n \fI<ioprio_classdata>\fR] \fI<path>\fR|\fI<device>\fR
+.RS 4
+Start a scrub on all devices of the filesystem identified by
+\fIpath\fR
+or on a single
+\fIdevice\fR\&. If a scrub is already running, the new one fails\&.
+.sp
+Without options, scrub is started as a background process\&.
+.sp
+The default IO priority of scrub is the idle class\&. The priority can be configured similar to the
+\fBionice\fR(1) syntax using
+\fI\-c\fR
+and
+\fI\-n\fR
+options\&.
+.sp
+\fBOptions\fR
+.PP
+\-B
+.RS 4
+do not background and print scrub statistics when finished
+.RE
+.PP
+\-d
+.RS 4
+print separate statistics for each device of the filesystem (\fI\-B\fR
+only) at the end
+.RE
+.PP
+\-q
+.RS 4
+be quiet, omit error messages and statistics
+.RE
+.PP
+\-r
+.RS 4
+run in read\-only mode, do not attempt to correct anything, can be run on a read\-only filesystem
+.RE
+.PP
+\-R
+.RS 4
+raw print mode, print full data instead of summary
+.RE
+.PP
+\-c \fI<ioprio_class>\fR
+.RS 4
+set IO priority class (see
+\fBionice\fR(1) manpage)
+.RE
+.PP
+\-n \fI<ioprio_classdata>\fR
+.RS 4
+set IO priority classdata (see
+\fBionice\fR(1) manpage)
+.RE
+.PP
+\-f
+.RS 4
+force starting new scrub even if a scrub is already running, this can useful when scrub status file is damaged and reports a running scrub although it is not, but should not normally be necessary
+.RE
+.RE
+.PP
+\fBstatus\fR [\-d] \fI<path>\fR|\fI<device>\fR
+.RS 4
+Show status of a running scrub for the filesystem identified by
+\fIpath\fR
+or for the specified
+\fIdevice\fR\&.
+.sp
+If no scrub is running, show statistics of the last finished or cancelled scrub for that filesystem or device\&.
+.sp
+\fBOptions\fR
+.PP
+\-d
+.RS 4
+print separate statistics for each device of the filesystem
+.RE
+.RE
+.SH "EXIT STATUS"
+.sp
+\fBbtrfs scrub\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure:
+.PP
+1
+.RS 4
+scrub couldn\(cqt be performed
+.RE
+.PP
+2
+.RS 4
+there is nothing to resume
+.RE
+.PP
+3
+.RS 4
+scrub found uncorrectable errors
+.RE
+.SH "AVAILABILITY"
+.sp
+\fBbtrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&.
+.SH "SEE ALSO"
+.sp
+\fBmkfs\&.btrfs\fR(8), \fBionice\fR(1)