1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
btrfs-scrub(8)
==============
SYNOPSIS
--------
**btrfs scrub** <subcommand> <args>
DESCRIPTION
-----------
.. include:: ch-scrub-intro.rst
SUBCOMMAND
----------
cancel <path>|<device>
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
:command:`btrfs scrub cancel` behaves as if it was called on that filesystem.
The progress is saved in the status file so :command:`btrfs scrub resume` can
continue from the last position.
.. _man-scrub-limit:
limit [options] <path>
Show or set scrub limits on devices of the given filesystem.
``Options``
-d|--devid DEVID
select the device by DEVID to apply the limit
-l|--limit SIZE
set the limit of the device to SIZE (size units with suffix),
or 0 to reset to *unlimited*
-a|--all
apply the limit to all devices
--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
resume [-BdqrR] <path>|<device>
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 :command:`scrub start`.
.. _man-scrub-start:
start [options] <path>|<device>
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 are performed by default for block
group profiles with redundancy. No-repair can be enabled by option *-r*.
``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
Note that a read-only scrub on a read-write filesystem can
still cause writes into the filesystem due to some internal
limitations. Only a read-only scrub on a read-only filesystem
can avoid writes from scrub.
-R
raw print mode, print full data instead of summary
--limit <limit>
set the scrub throughput limit for each device.
If the scrub is for the whole filesystem, it's the same as
:command:`btrfs scrub limit --all --limit <value>`.
If the scrub is for a single device, it's the same as
:command:`btrfs scrub limit --devid <devid> -l <value>`.
The value is bytes per second, and accepts the usual KMGT suffixes.
After the scrub is finished, the throughput limit will be reset to
the old value of each device.
-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``
The priority settings work only with certain schedulers, in particular
they *don't* work with the most common one *mq-deadline*.
-c <ioprio_class>
set IO priority class (see :manref:`ionice(1)` manual page) if the IO
scheduler configured for the device supports ionice. This is
only supported by BFQ or Kyber but is *not* supported by
mq-deadline. Please read the section about
:docref:`IO limiting <btrfs-scrub:scrub-io-limiting>`.
-n <ioprio_classdata>
set IO priority classdata (see :manref:`ionice(1)` manpage)
-q
(deprecated) alias for global *-q* option
status [options] <path>|<device>
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. The status is read from
the file located in :file:`/var/lib/btrfs`.
``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
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
It's possible to set a per-device limit via file
:file:`sysfs/fs/btrfs/FSID/devinfo/scrub_speed_max`. In that case
the limit is printed on the *Rate:* line if option *-d* is specified,
or without it on a single-device filesystem. Read more about tat in
section about :docref:`scrub IO limiting <btrfs-scrub:scrub-io-limiting>`.
.. code-block:: none
Rate: 989.0MiB/s (limit 1.0G/s)
On a multi-device filesystem with at least one device limit the
overall stats cannot print the limit without *-d* so there's a not that
some limits are set:
.. code-block:: none
Rate: 36.37MiB/s (some device limits set)
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 documentation at
`https://btrfs.readthedocs.io <https://btrfs.readthedocs.io>`_.
SEE ALSO
--------
:doc:`mkfs.btrfs`
|
