Debian Codegraph @

upstream/debian-trixie/man8/btrfs-scrub.8

raw
1 .\" Man page generated from reStructuredText.
2 .
3 .
4 .nr rst2man-indent-level 0
5 .
6 .de1 rstReportMargin
7 \\$1 \\n[an-margin]
8 level \\n[rst2man-indent-level]
9 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
10 -
11 \\n[rst2man-indent0]
12 \\n[rst2man-indent1]
13 \\n[rst2man-indent2]
14 ..
15 .de1 INDENT
16 .\" .rstReportMargin pre:
17 . RS \\$1
18 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
19 . nr rst2man-indent-level +1
20 .\" .rstReportMargin post:
21 ..
22 .de UNINDENT
23 . RE
24 .\" indent \\n[an-margin]
25 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
26 .nr rst2man-indent-level -1
27 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
29 ..
30 .TH "BTRFS-SCRUB" "8" "May 18, 2026" "7.0" "BTRFS"
31 .SH NAME
32 btrfs-scrub \- scrub btrfs filesystem, verify block checksums
33 .SH SYNOPSIS
34 .sp
35 \fBbtrfs scrub\fP <subcommand> <args>
36 .SH DESCRIPTION
37 .sp
38 Scrub is a validation pass over all filesystem data and metadata that detects
39 data checksum errors, basic super block errors, basic metadata block header errors,
40 and disk read errors.
41 .sp
42 Scrub is done on a per\-device base, if a device is specified to \fBbtrfs scrub start\fP,
43 then only that device will be scrubbed. Although btrfs will also try to read
44 other device to find a good copy, if the mirror on that specified device failed
45 to be read or pass verification.
46 .sp
47 If a path of btrfs is specified to \fBbtrfs scrub start\fP, btrfs will scrub
48 all devices in parallel.
49 .sp
50 On filesystems that use replicated block group profiles (e.g. RAID1), read\-write
51 scrub will also automatically repair any damage by copying verified good data
52 from one of the other replicas.
53 .sp
54 Such automatic repair is also carried out when reading metadata or data from a
55 read\-write mounted filesystem.
56 .sp
57 \fBWARNING:\fP
58 .INDENT 0.0
59 .INDENT 3.5
60 As currently implemented, setting the \fBNOCOW\fP file attribute (by
61 \fBchattr +C\fP) on a file implicitly enables
62 \fBNODATASUM\fP\&. This means that while metadata for these files continues to
63 be validated and corrected by scrub, the actual file data is not.
64 .sp
65 Furthermore, btrfs does not currently mark missing or failed disks as
66 unreliable, so will continue to load\-balance reads to potentially damaged
67 replicas. This is not a problem normally because damage is detected by
68 checksum validation, but because \fBNOCOW\fP files are
69 not protected by checksums, btrfs has no idea which mirror is good thus it can
70 return the bad contents to the user space tool.
71 .sp
72 Detecting and recovering from such failure requires manual intervention.
73 .sp
74 Notably, \X'tty: link https://github.com/systemd/systemd/commit/11689d2a021d95a8447d938180e0962cd9439763'\fI\%systemd sets +C on journals by default\fP\X'tty: link',
75 and \X'tty: link https://www.libvirt.org/news.html#v6-6-0-2020-08-02'\fI\%libvirt ≥ 6.6 sets +C on storage pool directories by default\fP\X'tty: link'\&.
76 Other applications or distributions may also set \fB+C\fP to try to improve
77 performance.
78 .UNINDENT
79 .UNINDENT
80 .sp
81 \fBNOTE:\fP
82 .INDENT 0.0
83 .INDENT 3.5
84 Scrub is not a filesystem checker (fsck, \fI\%btrfs\-check(8)\fP). It can only detect
85 filesystem damage using the checksum validation, and it can only repair
86 filesystem damage by copying from other known good replicas.
87 .sp
88 \fI\%btrfs\-check(8)\fP performs more exhaustive checking and can sometimes be
89 used, with expert guidance, to rebuild certain corrupted filesystem structures
90 in the absence of any good replica.
91 .UNINDENT
92 .UNINDENT
93 .sp
94 \fBNOTE:\fP
95 .INDENT 0.0
96 .INDENT 3.5
97 Read\-only scrub on a read\-write filesystem will cause some writes into the
98 filesystem.
99 .sp
100 This is due to the design limitation to prevent race between marking block
101 group read\-only and writing back block group items.
102 .sp
103 To avoid any writes from scrub, one has to run read\-only scrub on read\-only
104 filesystem.
105 .UNINDENT
106 .UNINDENT
107 .sp
108 \fBNOTE:\fP
109 .INDENT 0.0
110 .INDENT 3.5
111 Scrub can be interrupted by various events after v6.19 kernel, including
112 but not limited to power management suspend/hibernate, filesystem freezing,
113 cgroup freezing (utilized by systemd for slice freezing) and pending signals.
114 .sp
115 The running scrub will be cancelled after such interruption, and can be resumed
116 by \fBbtrfs scrub resume\fP command.
117 .UNINDENT
118 .UNINDENT
119 .sp
120 The user is supposed to run it manually or via a periodic system service. The
121 recommended period is a month but it could be less. The estimated device bandwidth
122 utilization is about 80% on an idle filesystem.
123 .sp
124 The scrubbing status is recorded in \fB/var/lib/btrfs/\fP in textual files named
125 \fIscrub.status.UUID\fP for a filesystem identified by the given UUID. (Progress
126 state is communicated through a named pipe in file \fIscrub.progress.UUID\fP in the
127 same directory.) The status file is updated every 5 seconds. A resumed scrub
128 will continue from the last saved position.
129 .sp
130 Scrub can be started only on a mounted filesystem, though it\(aqs possible to
131 scrub only a selected device. See \fI\%btrfs scrub start\fP for more.
132 .SS Bandwidth and IO limiting
133 .sp
134 \fBNOTE:\fP
135 .INDENT 0.0
136 .INDENT 3.5
137 The \X'tty: link https://man7.org/linux/man-pages/man1/ionice.1.html'\fI\%ionice(1)\fP\X'tty: link' may not be generally supported by all IO schedulers and
138 the options to \fBbtrfs scrub start\fP may not work as expected.
139 .UNINDENT
140 .UNINDENT
141 .sp
142 In the past when the \X'tty: link https://en.wikipedia.org/wiki/Completely_fair_queueing'\fI\%CFQ IO scheduler\fP\X'tty: link' was generally used
143 the \X'tty: link https://man7.org/linux/man-pages/man1/ionice.1.html'\fI\%ionice(1)\fP\X'tty: link' syscalls set the priority to \fIidle\fP so the IO would not
144 interfere with regular IO. Since the kernel 5.0 the CFQ is not available.
145 .sp
146 The IO scheduler known to support that is \X'tty: link https://docs.kernel.org/block/bfq-iosched.html'\fI\%BFQ\fP\X'tty: link', but first read the
147 documentation before using it!
148 .sp
149 For other commonly used schedulers like \X'tty: link https://docs.kernel.org/block/blk-mq.html'\fI\%mq\-deadline\fP\X'tty: link' it\(aqs recommended to use
150 \fIcgroup2 IO controller\fP which could be managed by e.g. \fIsystemd\fP
151 (documented in \fBsystemd.resource\-control\fP). However, starting scrub like that
152 is not yet completely straightforward. The IO controller must know the physical
153 device of the filesystem and create a slice so all processes started from that
154 belong to the same accounting group.
155 .INDENT 0.0
156 .INDENT 3.5
157 .sp
158 .EX
159 $ systemd\-run \-p \(dqIOReadBandwidthMax=/dev/sdx 10M\(dq btrfs scrub start \-B /
160 .EE
161 .UNINDENT
162 .UNINDENT
163 .sp
164 Since linux 5.14 it\(aqs possible to set the per\-device bandwidth limits in a
165 BTRFS\-specific way using files \fB/sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max\fP\&.
166 This setting is not persistent, lasts until the filesystem is unmounted.
167 Currently set limits can be displayed by command \fI\%btrfs scrub
168 limit\fP\&.
169 .INDENT 0.0
170 .INDENT 3.5
171 .sp
172 .EX
173 $ echo 100m > /sys/fs/btrfs/9b5fd16e\-1b64\-4f9b\-904a\-74e74c0bbadc/devinfo/1/scrub_speed_max
174 $ btrfs scrub limit /
175 UUID: 9b5fd16e\-1b64\-4f9b\-904a\-74e74c0bbadc
176 Id Limit Path
177 \-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-
178 1 100.00MiB /dev/sdx
179 .EE
180 .UNINDENT
181 .UNINDENT
182 .SH SUBCOMMAND
183 .INDENT 0.0
184 .TP
185 .B cancel <path>|<device>
186 If a scrub is running on the filesystem identified by \fIpath\fP or
187 \fIdevice\fP, cancel it.
188 .sp
189 If a \fIdevice\fP is specified, the corresponding filesystem is found and
190 \fBbtrfs scrub cancel\fP behaves as if it was called on that filesystem.
191 The progress is saved in the status file so \fBbtrfs scrub resume\fP can
192 continue from the last position.
193 .UNINDENT
194 .INDENT 0.0
195 .TP
196 .B limit [options] <path>
197 Show or set scrub limits on devices of the given filesystem.
198 .sp
199 \fBOptions\fP
200 .INDENT 7.0
201 .TP
202 .B \-d|\-\-devid DEVID
203 select the device by DEVID to apply the limit
204 .TP
205 .B \-l|\-\-limit SIZE
206 set the limit of the device to SIZE (size units with suffix),
207 or 0 to reset to \fIunlimited\fP
208 .TP
209 .B \-a|\-\-all
210 apply the limit to all devices
211 .UNINDENT
212 .INDENT 7.0
213 .TP
214 .B \-\-raw
215 print all numbers raw values in bytes without the \fIB\fP suffix
216 .TP
217 .B \-\-human\-readable
218 print human friendly numbers, base 1024, this is the default
219 .TP
220 .B \-\-iec
221 select the 1024 base for the following options, according to
222 the IEC standard
223 .TP
224 .B \-\-si
225 select the 1000 base for the following options, according to the SI standard
226 .TP
227 .B \-\-kbytes
228 show sizes in KiB, or kB with \-\-si
229 .TP
230 .B \-\-mbytes
231 show sizes in MiB, or MB with \-\-si
232 .TP
233 .B \-\-gbytes
234 show sizes in GiB, or GB with \-\-si
235 .TP
236 .B \-\-tbytes
237 show sizes in TiB, or TB with \-\-si
238 .UNINDENT
239 .TP
240 .B resume [\-BdqrR] <path>|<device>
241 Resume a cancelled or interrupted scrub on the filesystem identified by
242 \fIpath\fP or on a given \fIdevice\fP\&. The starting point is read from the
243 status file if it exists.
244 .sp
245 This does not start a new scrub if the last scrub finished successfully.
246 .sp
247 \fBOptions\fP
248 .sp
249 see \fBscrub start\fP\&.
250 .UNINDENT
251 .INDENT 0.0
252 .TP
253 .B start [options] <path>|<device>
254 Start a scrub on all devices of the mounted filesystem identified by
255 \fIpath\fP or on a single \fIdevice\fP\&. If a scrub is already running, the new
256 one will not start. A device of an unmounted filesystem cannot be
257 scrubbed this way.
258 .sp
259 Without options, scrub is started as a background process. The
260 automatic repairs of damaged copies are performed by default for block
261 group profiles with redundancy. No\-repair can be enabled by option \fI\-r\fP\&.
262 .sp
263 \fBOptions\fP
264 .INDENT 7.0
265 .TP
266 .B \-B
267 do not background and print scrub statistics when finished
268 .TP
269 .B \-d
270 print separate statistics for each device of the filesystem
271 (\fI\-B\fP only) at the end
272 .TP
273 .B \-r
274 run in read\-only mode, do not attempt to correct anything, can
275 be run on a read\-only filesystem
276 .sp
277 Note that a read\-only scrub on a read\-write filesystem can
278 still cause writes into the filesystem due to some internal
279 limitations. Only a read\-only scrub on a read\-only filesystem
280 can avoid writes from scrub.
281 .TP
282 .B \-R
283 raw print mode, print full data instead of summary
284 .TP
285 .BI \-\-limit \ <limit>
286 set the scrub throughput limit for each device.
287 .sp
288 If the scrub is for the whole filesystem, it\(aqs the same as
289 \fBbtrfs scrub limit \-\-all \-\-limit <value>\fP\&.
290 If the scrub is for a single device, it\(aqs the same as
291 \fBbtrfs scrub limit \-\-devid <devid> \-l <value>\fP\&.
292 .sp
293 The value is bytes per second, and accepts the usual KMGT suffixes.
294 After the scrub is finished, the throughput limit will be reset to
295 the old value of each device.
296 .TP
297 .B \-f
298 force starting new scrub even if a scrub is already running,
299 this can useful when scrub status file is damaged and reports a
300 running scrub although it is not, but should not normally be
301 necessary
302 .UNINDENT
303 .sp
304 \fBDeprecated options\fP
305 .sp
306 The priority settings work only with certain schedulers, in particular
307 they \fIdon\(aqt\fP work with the most common one \fImq\-deadline\fP\&.
308 .INDENT 7.0
309 .TP
310 .BI \-c \ <ioprio_class>
311 set IO priority class (see \X'tty: link https://man7.org/linux/man-pages/man1/ionice.1.html'\fI\%ionice(1)\fP\X'tty: link' manual page) if the IO
312 scheduler configured for the device supports ionice. This is
313 only supported by BFQ or Kyber but is \fInot\fP supported by
314 mq\-deadline. Please read the section about
315 \fI\%IO limiting\fP\&.
316 .TP
317 .BI \-n \ <ioprio_classdata>
318 set IO priority classdata (see \X'tty: link https://man7.org/linux/man-pages/man1/ionice.1.html'\fI\%ionice(1)\fP\X'tty: link' manpage)
319 .TP
320 .B \-q
321 (deprecated) alias for global \fI\-q\fP option
322 .UNINDENT
323 .TP
324 .B status [options] <path>|<device>
325 Show status of a running scrub for the filesystem identified by \fIpath\fP
326 or for the specified \fIdevice\fP\&.
327 .sp
328 If no scrub is running, show statistics of the last finished or
329 cancelled scrub for that filesystem or device. The status is read from
330 the file located in \fB/var/lib/btrfs\fP\&.
331 .sp
332 \fBOptions\fP
333 .INDENT 7.0
334 .TP
335 .B \-d
336 print separate statistics for each device of the filesystem
337 .TP
338 .B \-R
339 print all raw statistics without postprocessing as returned by
340 the status ioctl
341 .TP
342 .B \-\-raw
343 print all numbers raw values in bytes without the \fIB\fP suffix
344 .TP
345 .B \-\-human\-readable
346 print human friendly numbers, base 1024, this is the default
347 .TP
348 .B \-\-iec
349 select the 1024 base for the following options, according to
350 the IEC standard
351 .TP
352 .B \-\-si
353 select the 1000 base for the following options, according to the SI standard
354 .TP
355 .B \-\-kbytes
356 show sizes in KiB, or kB with \-\-si
357 .TP
358 .B \-\-mbytes
359 show sizes in MiB, or MB with \-\-si
360 .TP
361 .B \-\-gbytes
362 show sizes in GiB, or GB with \-\-si
363 .TP
364 .B \-\-tbytes
365 show sizes in TiB, or TB with \-\-si
366 .UNINDENT
367 .sp
368 A status on a filesystem without any error looks like the following:
369 .INDENT 7.0
370 .INDENT 3.5
371 .sp
372 .EX
373 # btrfs scrub start /
374 # btrfs scrub status /
375 UUID: 76fac721\-2294\-4f89\-a1af\-620cde7a1980
376 Scrub started: Wed Apr 10 12:34:56 2023
377 Status: running
378 Duration: 0:00:05
379 Time left: 0:00:05
380 ETA: Wed Apr 10 12:35:01 2023
381 Total to scrub: 28.32GiB
382 Bytes scrubbed: 13.76GiB (48.59%)
383 Rate: 2.75GiB/s
384 Error summary: no errors found
385 .EE
386 .UNINDENT
387 .UNINDENT
388 .sp
389 With some errors found:
390 .INDENT 7.0
391 .INDENT 3.5
392 .sp
393 .EX
394 Error summary: csum=72
395 Corrected: 2
396 Uncorrectable: 72
397 Unverified: 0
398 .EE
399 .UNINDENT
400 .UNINDENT
401 .INDENT 7.0
402 .IP \(bu 2
403 \fICorrected\fP \-\- number of bad blocks that were repaired from another copy
404 .IP \(bu 2
405 \fIUncorrectable\fP \-\- errors detected at read time but not possible to repair from other copy
406 .IP \(bu 2
407 \fIUnverified\fP \-\- transient errors, first read failed but a retry
408 succeeded, may be affected by lower layers that group or split IO requests
409 .IP \(bu 2
410 \fIError summary\fP \-\- followed by a more detailed list of errors found
411 .INDENT 2.0
412 .IP \(bu 2
413 \fIcsum\fP \-\- checksum mismatch
414 .IP \(bu 2
415 \fIsuper\fP \-\- super block errors, unless the error is fixed
416 immediately, the next commit will overwrite superblock
417 .IP \(bu 2
418 \fIverify\fP \-\- metadata block header errors
419 .IP \(bu 2
420 \fIread\fP \-\- blocks can\(aqt be read due to IO errors
421 .UNINDENT
422 .UNINDENT
423 .sp
424 It\(aqs possible to set a per\-device limit via file
425 \fBsysfs/fs/btrfs/FSID/devinfo/scrub_speed_max\fP\&. In that case
426 the limit is printed on the \fIRate:\fP line if option \fI\-d\fP is specified,
427 or without it on a single\-device filesystem. Read more about tat in
428 section about \fI\%scrub IO limiting\fP\&.
429 .INDENT 7.0
430 .INDENT 3.5
431 .sp
432 .EX
433 Rate: 989.0MiB/s (limit 1.0G/s)
434 .EE
435 .UNINDENT
436 .UNINDENT
437 .sp
438 On a multi\-device filesystem with at least one device limit the
439 overall stats cannot print the limit without \fI\-d\fP so there\(aqs a not that
440 some limits are set:
441 .INDENT 7.0
442 .INDENT 3.5
443 .sp
444 .EX
445 Rate: 36.37MiB/s (some device limits set)
446 .EE
447 .UNINDENT
448 .UNINDENT
449 .UNINDENT
450 .SH EXIT STATUS
451 .sp
452 \fBbtrfs scrub\fP returns a zero exit status if it succeeds. Non zero is
453 returned in case of failure:
454 .INDENT 0.0
455 .TP
456 .B 1
457 scrub couldn\(aqt be performed
458 .TP
459 .B 2
460 there is nothing to resume
461 .TP
462 .B 3
463 scrub found uncorrectable errors
464 .UNINDENT
465 .SH AVAILABILITY
466 .sp
467 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
468 \X'tty: link https://btrfs.readthedocs.io'\fI\%https://btrfs.readthedocs.io\fP\X'tty: link'\&.
469 .SH SEE ALSO
470 .sp
471 \fI\%mkfs.btrfs(8)\fP
472 .\" Generated by docutils manpage writer.
473 .