From 6ef6c07ef7068d99c5d0d2e803d7c766dd4fda5f Mon Sep 17 00:00:00 2001 From: David Sterba Date: Thu, 20 Apr 2023 00:48:49 +0200 Subject: [PATCH] btrfs-progs: docs: update scrub manual page Move ionice options, add example output of status with explanation. Issue: #200 Signed-off-by: David Sterba --- Documentation/btrfs-scrub.rst | 67 +++++++++++++++++++++++++++-------- 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/Documentation/btrfs-scrub.rst b/Documentation/btrfs-scrub.rst index 219e72e8..3854b0da 100644 --- a/Documentation/btrfs-scrub.rst +++ b/Documentation/btrfs-scrub.rst @@ -23,7 +23,7 @@ cancel | The progress is saved in the status file so **btrfs scrub resume** can continue from the last position. -resume [-BdqrR] [-c -n ] | +resume [-BdqrR] | 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. @@ -34,19 +34,15 @@ resume [-BdqrR] [-c -n ] | see **scrub start**. -start [-BdqrRf] [-c -n ] | +start [-BdrRf] | 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. + automatic repairs of damaged copies are performed by default for block + group profiles with redundancy. No-repair can be enabled by option *-r*. ``Options`` @@ -60,15 +56,21 @@ start [-BdqrRf] [-c -n ] | 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 + + ``Deprecated options`` + + -c + set IO priority class (see ``ionice(1)`` manpage) if the IO + scheduler configured for the device supports ionice. This is + not supported byg BFQ or Kyber but is *not* supported by + mq-deadline. + -n + set IO priority classdata (see ``ionice(1)`` manpage) -q (deprecated) alias for global *-q* option @@ -104,6 +106,44 @@ status [options] | --tbytes show sizes in TiB, or TB with --si + A status on a filesystem without any error looks like the following: + + .. code-block:: none + + # btrfs scrub start / + # btrfs scrub status / + UUID: 76fac721-2294-4f89-a1af-620cde7a1980 + Scrub started: Wed Apr 10 12:34:56 2023 + Status: running + Duration: 0:00:05 + Time left: 0:00:05 + ETA: Wed Apr 10 12:35:01 2023 + Total to scrub: 28.32GiB + Bytes scrubbed: 13.76GiB (48.59%) + Rate: 2.75GiB/s + Error summary: no errors found + + With some errors found: + + .. code-block:: none + + Error summary: csum=72 + Corrected: 2 + Uncorrectable: 72 + Unverified: 0 + + * *Corrected* -- number of bad blocks that were repaired from another copy + * *Uncorrectable* -- errors detected at read time but not possible to repair from other copy + * *Unverified* -- transient errors, first read failed but a retry + succeeded, may be affected by lower layers that group or split IO requests + * *Error summary* -- followed by a more detailed list of errors found + + * *csum* -- checksum mismatch + * *super* -- super block errors, unless the error is fixed + immediately, the next commit will overwrite superblock + * *verify* -- metadata block header errors + * *read* -- blocks can't be read due to IO errors + EXIT STATUS ----------- @@ -126,5 +166,4 @@ AVAILABILITY SEE ALSO -------- -:doc:`mkfs.btrfs(8)`, -``ionice(1)`` +:doc:`mkfs.btrfs(8)`