'\" 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: 02/05/2021
.\"    Manual: Btrfs Manual
.\"    Source: Btrfs v5.10.1
.\"  Language: English
.\"
.TH "BTRFS\-SCRUB" "8" "02/05/2021" "Btrfs v5\&.10\&.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 mounted 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\&. It really only checks checksums of data and tree blocks, it doesn\(cqt ensure the content of tree blocks is valid and consistent\&. There\(cqs some validation performed when metadata blocks are read from disk but it\(cqs not extensive and cannot substitute full \fIbtrfs check\fR run\&.
.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\&. The IO scheduler set for the device(s) might not support the priority classes though\&.
.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\&.
.sp
Scrub can be started only on a mounted filesystem, though it\(cqs possible to scrub only a selected device\&. See \fBscrub start\fR for more\&.
.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
or
\fIdevice\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\&. The progress is saved in the status file so
\fBbtrfs scrub resume\fR
can continue from the last position\&.
.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\&. The starting point is read from the status file if it exists\&.
.sp
This 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 mounted filesystem identified by
\fIpath\fR
or on a single
\fIdevice\fR\&. If a scrub is already running, the new one will not start\&. A device of an unmounted filesystem cannot be scrubbed this way\&.
.sp
Without options, scrub is started as a background process\&. The automatic repairs of damaged copies is performed by default for block group profiles with redundancy\&.
.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\&. Note that not all IO schedulers honor the ionice settings\&.
.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
\-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
.PP
\-q
.RS 4
(deprecated) alias for global
\fI\-q\fR
option
.RE
.RE
.PP
\fBstatus\fR [options] \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
.PP
\-R
.RS 4
print all raw statistics without postprocessing as returned by the status ioctl
.RE
.PP
\-\-raw
.RS 4
print all numbers raw values in bytes without the
\fIB\fR
suffix
.RE
.PP
\-\-human\-readable
.RS 4
print human friendly numbers, base 1024, this is the default
.RE
.PP
\-\-iec
.RS 4
select the 1024 base for the following options, according to the IEC standard
.RE
.PP
\-\-si
.RS 4
select the 1000 base for the following options, according to the SI standard
.RE
.PP
\-\-kbytes
.RS 4
show sizes in KiB, or kB with \-\-si
.RE
.PP
\-\-mbytes
.RS 4
show sizes in MiB, or MB with \-\-si
.RE
.PP
\-\-gbytes
.RS 4
show sizes in GiB, or GB with \-\-si
.RE
.PP
\-\-tbytes
.RS 4
show sizes in TiB, or TB with \-\-si
.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)