diff --git a/Documentation/btrfs-scrub.rst b/Documentation/btrfs-scrub.rst new file mode 100644 index 00000000..5f19365e --- /dev/null +++ b/Documentation/btrfs-scrub.rst @@ -0,0 +1,157 @@ +btrfs-scrub(8) +============== + +SYNOPSIS +-------- + +**btrfs scrub** + +DESCRIPTION +----------- + +**btrfs scrub** 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's a correct copy available. + +.. note:: + 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't ensure the content of tree blocks is valid and + consistent. There's some validation performed when metadata blocks are read + from disk but it's not extensive and cannot substitute full *btrfs check* + run. + +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 *idle* 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. + +The scrubbing status is recorded in */var/lib/btrfs/* in textual files named +*scrub.status.UUID* for a filesystem identified by the given UUID. (Progress +state is communicated through a named pipe in file *scrub.progress.UUID* in the +same directory.) The status file is updated every 5 seconds. A resumed scrub +will continue from the last saved position. + +Scrub can be started only on a mounted filesystem, though it's possible to +scrub only a selected device. See **scrub start** for more. + +SUBCOMMAND +---------- + +cancel | + If a scrub is running on the filesystem identified by *path* or + *device*, cancel it. + + If a *device* is specified, the corresponding filesystem is found and + **btrfs scrub cancel** behaves as if it was called on that filesystem. + The progress is saved in the status file so **btrfs scrub resume** can + continue from the last position. + +resume [-BdqrR] [-c -n ] | + Resume a cancelled or interrupted scrub on the filesystem identified by + *path* or on a given *device*. The starting point is read from the + status file if it exists. + + This does not start a new scrub if the last scrub finished successfully. + + ``Options`` + + see **scrub start**. + +start [-BdqrRf] [-c -n ] | + Start a scrub on all devices of the mounted filesystem identified by + *path* or on a single *device*. If a scrub is already running, the new + one will not start. A device of an unmounted filesystem cannot be + scrubbed this way. + + 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. + + The default IO priority of scrub is the idle class. The priority can be + configured similar to the ``ionice(1)`` syntax using *-c* and *-n* + options. Note that not all IO schedulers honor the ionice settings. + + ``Options`` + + -B + do not background and print scrub statistics when finished + -d + print separate statistics for each device of the filesystem + (*-B* only) at the end + -r + run in read-only mode, do not attempt to correct anything, can + be run on a read-only filesystem + -R + raw print mode, print full data instead of summary + -c + set IO priority class (see ``ionice(1)`` manpage) + -n + set IO priority classdata (see ``ionice(1)`` manpage) + -f + 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 + -q + (deprecated) alias for global *-q* option + +status [options] | + Show status of a running scrub for the filesystem identified by *path* + or for the specified *device*. + + If no scrub is running, show statistics of the last finished or + cancelled scrub for that filesystem or device. + + ``Options`` + + -d + print separate statistics for each device of the filesystem + -R + print all raw statistics without postprocessing as returned by + the status ioctl + --raw + print all numbers raw values in bytes without the *B* suffix + --human-readable + print human friendly numbers, base 1024, this is the default + --iec + select the 1024 base for the following options, according to + the IEC standard + --si + select the 1000 base for the following options, according to the SI standard + --kbytes + show sizes in KiB, or kB with --si + --mbytes + show sizes in MiB, or MB with --si + --gbytes + show sizes in GiB, or GB with --si + --tbytes + show sizes in TiB, or TB with --si + +EXIT STATUS +----------- + +**btrfs scrub** returns a zero exit status if it succeeds. Non zero is +returned in case of failure: + +1 + scrub couldn't be performed +2 + there is nothing to resume +3 + scrub found uncorrectable errors + +AVAILABILITY +------------ + +**btrfs** is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- + +``mkfs.btrfs(8)``, +``ionice(1)`` diff --git a/Documentation/conf.py b/Documentation/conf.py index e8210676..166a015d 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -44,4 +44,5 @@ man_pages = [ ('btrfstune', 'btrfstune', 'tune various filesystem parameters', '', 8), ('fsck.btrfs', 'fsck.btrfs', 'do nothing, successfully', '', 8), ('btrfs-send', 'btrfs-send', 'generate a stream of changes between two subvolume snapshots', '', 8), + ('btrfs-scrub', 'btrfs-scrub', 'scrub btrfs filesystem, verify block checksums', '', 8), ] diff --git a/Documentation/man-index.rst b/Documentation/man-index.rst index 596ec2f9..05636105 100644 --- a/Documentation/man-index.rst +++ b/Documentation/man-index.rst @@ -6,6 +6,7 @@ Manual pages .. toctree:: :maxdepth: 1 + btrfs-scrub btrfs-select-super btrfs-send btrfstune