Debian Codegraph @

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

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