Manpage/btrfs-scrub

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
(Update from git, v5.14.2)
(remove content)
 
Line 1: Line 1:
=btrfs-scrub(8) manual page=
 
 
{{GeneratedManpage
 
{{GeneratedManpage
 
|name=btrfs-scrub}}
 
|name=btrfs-scrub}}
 
==NAME==
 
btrfs-scrub - scrub btrfs filesystem, verify block checksums
 
 
==SYNOPSIS==
 
 
<p><b>btrfs scrub</b> <em>&lt;subcommand&gt;</em> <em>&lt;args&gt;</em></p>
 
==DESCRIPTION==
 
 
<p><b>btrfs scrub</b> 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&#8217;s a correct copy available.</p>
 
<blockquote><b>Note:</b>
 
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&#8217;t ensure the content of tree blocks is valid and
 
consistent. There&#8217;s some validation performed when metadata blocks are read
 
from disk but it&#8217;s not extensive and cannot substitute full <em>btrfs check</em> run.</blockquote>
 
<p>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 <em>idle</em> 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.</p>
 
<p>The scrubbing status is recorded in <em>/var/lib/btrfs/</em> in textual files named
 
<em>scrub.status.UUID</em> for a filesystem identified by the given UUID. (Progress
 
state is communicated through a named pipe in file <em>scrub.progress.UUID</em> in the
 
same directory.) The status file is updated every 5 seconds. A resumed scrub
 
will continue from the last saved position.</p>
 
<p>Scrub can be started only on a mounted filesystem, though it&#8217;s possible to
 
scrub only a selected device. See <b>scrub start</b> for more.</p>
 
==SUBCOMMAND==
 
 
<dl>
 
<dt>
 
<b>cancel</b> <em>&lt;path&gt;</em>|<em>&lt;device&gt;</em>
 
<dd>
 
<p>
 
If a scrub is running on the filesystem identified by <em>path</em> or <em>device</em>,
 
cancel it.
 
</p>
 
<p>If a <em>device</em> is specified, the corresponding filesystem is found and
 
<b>btrfs scrub cancel</b> behaves as if it was called on that filesystem.
 
The progress is saved in the status file so <b>btrfs scrub resume</b> can continue
 
from the last position.</p>
 
 
<dt>
 
<b>resume</b> [-BdqrR] [-c <em>&lt;ioprio_class&gt;</em> -n <em>&lt;ioprio_classdata&gt;</em>] <em>&lt;path&gt;</em>|<em>&lt;device&gt;</em>
 
<dd>
 
<p>
 
Resume a cancelled or interrupted scrub on the filesystem identified by
 
<em>path</em> or on a given <em>device</em>. The starting point is read from the status file
 
if it exists.
 
</p>
 
<p>This does not start a new scrub if the last scrub finished successfully.</p>
 
<p><tt>Options</tt></p>
 
<p>see <b>scrub start</b>.</p>
 
 
<dt>
 
<b>start</b> [-BdqrRf] [-c <em>&lt;ioprio_class&gt;</em> -n <em>&lt;ioprio_classdata&gt;</em>] <em>&lt;path&gt;</em>|<em>&lt;device&gt;</em>
 
<dd>
 
<p>
 
Start a scrub on all devices of the mounted filesystem identified by <em>path</em> or
 
on a single <em>device</em>. If a scrub is already running, the new one will not
 
start. A device of an unmounted filesystem cannot be scrubbed this way.
 
</p>
 
<p>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.</p>
 
<p>The default IO priority of scrub is the idle class. The priority can be
 
configured similar to the [http://man7.org/linux/man-pages/man1/ionice.1.html ionice(1)] syntax using <em>-c</em> and <em>-n</em> options.
 
Note that not all IO schedulers honor the ionice settings.</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-B
 
<dd>
 
<p>
 
do not background and print scrub statistics when finished
 
</p>
 
 
<dt>
 
-d
 
<dd>
 
<p>
 
print separate statistics for each device of the filesystem (<em>-B</em> only) at the end
 
</p>
 
 
<dt>
 
-r
 
<dd>
 
<p>
 
run in read-only mode, do not attempt to correct anything, can be run on a read-only
 
filesystem
 
</p>
 
 
<dt>
 
-R
 
<dd>
 
<p>
 
raw print mode, print full data instead of summary
 
</p>
 
 
<dt>
 
-c <em>&lt;ioprio_class&gt;</em>
 
<dd>
 
<p>
 
set IO priority class (see [http://man7.org/linux/man-pages/man1/ionice.1.html ionice(1)] manpage)
 
</p>
 
 
<dt>
 
-n <em>&lt;ioprio_classdata&gt;</em>
 
<dd>
 
<p>
 
set IO priority classdata (see [http://man7.org/linux/man-pages/man1/ionice.1.html ionice(1)] manpage)
 
</p>
 
 
<dt>
 
-f
 
<dd>
 
<p>
 
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
 
</p>
 
 
<dt>
 
-q
 
<dd>
 
<p>
 
(deprecated) alias for global <em>-q</em> option
 
</p>
 
 
</dl>
 
 
<dt>
 
<b>status</b> [options] <em>&lt;path&gt;</em>|<em>&lt;device&gt;</em>
 
<dd>
 
<p>
 
Show status of a running scrub for the filesystem identified by <em>path</em> or
 
for the specified <em>device</em>.
 
</p>
 
<p>If no scrub is running, show statistics of the last finished or cancelled scrub
 
for that filesystem or device.</p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dt>
 
-d
 
<dd>
 
<p>
 
print separate statistics for each device of the filesystem
 
</p>
 
 
<dt>
 
-R
 
<dd>
 
<p>
 
print all raw statistics without postprocessing as returned by the status ioctl
 
</p>
 
 
<dt>
 
--raw
 
<dd>
 
<p>
 
print all numbers raw values in bytes without the <em>B</em> suffix
 
</p>
 
 
<dt>
 
--human-readable
 
<dd>
 
<p>
 
print human friendly numbers, base 1024, this is the default
 
</p>
 
 
<dt>
 
--iec
 
<dd>
 
<p>
 
select the 1024 base for the following options, according to the IEC standard
 
</p>
 
 
<dt>
 
--si
 
<dd>
 
<p>
 
select the 1000 base for the following options, according to the SI standard
 
</p>
 
 
<dt>
 
--kbytes
 
<dd>
 
<p>
 
show sizes in KiB, or kB with --si
 
</p>
 
 
<dt>
 
--mbytes
 
<dd>
 
<p>
 
show sizes in MiB, or MB with --si
 
</p>
 
 
<dt>
 
--gbytes
 
<dd>
 
<p>
 
show sizes in GiB, or GB with --si
 
</p>
 
 
<dt>
 
--tbytes
 
<dd>
 
<p>
 
show sizes in TiB, or TB with --si
 
</p>
 
 
</dl>
 
 
</dl>
 
==EXIT STATUS==
 
 
<p><b>btrfs scrub</b> returns a zero exit status if it succeeds. Non zero is
 
returned in case of failure:</p>
 
<dl>
 
<dt>
 
1
 
<dd>
 
<p>
 
scrub couldn&#8217;t be performed
 
</p>
 
 
<dt>
 
2
 
<dd>
 
<p>
 
there is nothing to resume
 
</p>
 
 
<dt>
 
3
 
<dd>
 
<p>
 
scrub found uncorrectable errors
 
</p>
 
 
</dl>
 
==AVAILABILITY==
 
 
<p><b>btrfs</b> is part of btrfs-progs.
 
Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 
further details.</p>
 
==SEE ALSO==
 
 
<p>[[Manpage/mkfs.btrfs|mkfs.btrfs(8)]],
 
[http://man7.org/linux/man-pages/man1/ionice.1.html ionice(1)]</p>
 
[[Category:Manpage]]
 

Latest revision as of 12:33, 12 January 2022

Note: manual pages are located at read-the-docs site, please update your links.


Personal tools