btrfs-scrub(8)

SYNOPSIS 概要 

btrfs scrub <subcommand> <args>
btrfs scrub <子命令> <参数>

DESCRIPTION 描述 

Scrub is a pass over all filesystem data and metadata and verifying the checksums. If a valid copy is available (replicated block group profiles) then the damaged one is repaired. All copies of the replicated profiles are validated.
擦洗是对所有文件系统数据和元数据进行遍历，并验证校验和。如果存在有效副本（复制的块组配置文件），则会修复损坏的副本。所有复制的配置文件的副本都会被验证。

Note 注意

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’t ensure the content of tree blocks is valid and consistent. There’s some validation performed when metadata blocks are read from disk (Tree checker) but it’s not extensive and cannot substitute full btrfs-check(8) run.
擦洗不是文件系统检查器（fsck），不会验证或修复文件系统中的结构损坏。它实际上只检查数据和树块的校验和，不确保树块的内容是有效和一致的。当从磁盘读取元数据块时会执行一些验证（树检查器），但这并不全面，不能替代完整的 btrfs-check(8)运行。

The user is supposed to run it manually or via a periodic system service. The recommended period is a month but it could be less. The estimated device bandwidth utilization is about 80% on an idle filesystem.
用户应该手动运行它或通过定期系统服务运行。推荐的周期是一个月，但也可以更短。估计设备带宽利用率在空闲文件系统上约为 80%。

The scrubbing status is recorded in /var/lib/btrfs/ in textual files named scrub.status.UUID for a filesystem identified by the given UUID. (Progress state is communicated through a named pipe in file scrub.progress.UUID in the same directory.) The status file is updated every 5 seconds. A resumed scrub will continue from the last saved position.
擦洗状态记录在名为 scrub.status.UUID 的文本文件中，用于由给定 UUID 标识的文件系统。 （进度状态通过同一目录中的名为 scrub.progress.UUID 的命名管道进行通信。）状态文件每 5 秒更新一次。恢复的擦洗将从上次保存的位置继续。

Scrub can be started only on a mounted filesystem, though it’s possible to scrub only a selected device. See btrfs scrub start for more.
只能在已挂载的文件系统上启动擦洗，尽管可以仅擦洗选定的设备。有关更多信息，请参阅 btrfs scrub start。

Bandwidth and IO limiting
带宽和 IO 限制

Note 注意

The ionice(1) may not be generally supported by all IO schedulers and the options to btrfs scrub start may not work as expected.
ionice(1) 可能不被所有 IO 调度程序普遍支持，而 btrfs scrub start 的选项可能不会按预期工作。

In the past when the CFQ IO scheduler was generally used the ionice(1) syscalls set the priority to idle so the IO would not interfere with regular IO. Since the kernel 5.0 the CFQ is not available.
在过去，当 CFQ IO 调度程序通常被使用时，ionice(1)系统调用将优先级设置为空闲，因此 IO 不会干扰常规 IO。自内核 5.0 以来，CFQ 不再可用。

The IO scheduler known to support that is BFQ, but first read the documentation before using it!
已知支持该功能的 IO 调度器是 BFQ，但在使用之前请先阅读文档！

For other commonly used schedulers like mq-deadline it’s recommended to use cgroup2 IO controller which could be managed by e.g. systemd (documented in systemd.resource-control). However, starting scrub like that is not yet completely straightforward. The IO controller must know the physical device of the filesystem and create a slice so all processes started from that belong to the same accounting group.
对于其他常用的调度器，如 mq-deadline，建议使用 cgroup2 IO 控制器，可以由例如 systemd 进行管理（在 systemd.resource-control 中有文档记录）。然而，像这样开始扫描还不是完全直接的。IO 控制器必须知道文件系统的物理设备并创建一个切片，以便所有从该切片启动的进程都属于同一会计组。

$ systemd-run -p "IOReadBandwidthMax=/dev/sdx 10M" btrfs scrub start -B /

Since linux 5.14 it’s possible to set the per-device bandwidth limits in a BTRFS-specific way using files /sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max. This setting is not persistent, lasts until the filesystem is unmounted. Currently set limits can be displayed by command btrfs scrub limit.
自 Linux 5.14 以来，可以使用文件 /sys/fs/btrfs/FSID/devinfo/DEVID/scrub_speed_max 以 BTRFS 特定的方式设置每个设备的带宽限制。此设置不是持久的，持续到文件系统卸载。当前设置的限制可以通过命令 btrfs scrub limit 显示。

$ echo 100m > /sys/fs/btrfs/9b5fd16e-1b64-4f9b-904a-74e74c0bbadc/devinfo/1/scrub_speed_max
$ btrfs scrub limit /
UUID: 9b5fd16e-1b64-4f9b-904a-74e74c0bbadc
Id      Limit      Path
--  ---------  --------
 1  100.00MiB  /dev/sdx

SUBCOMMAND 子命令 

cancel <path>|<device> 取消 <路径>|<设备>

If a scrub is running on the filesystem identified by path or device, cancel it.
如果正在对由路径或设备标识的文件系统进行 scrub，则取消它。

If a device is specified, the corresponding filesystem is found and btrfs scrub cancel behaves as if it was called on that filesystem. The progress is saved in the status file so btrfs scrub resume can continue from the last position.
如果指定了设备，则找到相应的文件系统，btrfs scrub cancel 的行为就好像在该文件系统上调用它一样。进度保存在状态文件中，因此 btrfs scrub resume 可以从上次位置继续。

limit [options] <path> 限制 [选项] <路径>

Show or set scrub limits on devices of the given filesystem.
显示或设置给定文件系统设备的扫描限制。

Options

-d|--devid DEVID -d|--devid 设备 ID

select the device by DEVID to apply the limit
选择要应用限制的设备 ID

-l|--limit SIZE -l|--limit 大小

set the limit of the device to SIZE (size units with suffix), or 0 to reset to unlimited
将设备的限制设置为 SIZE（带有后缀的大小单位），或将其重置为无限制的 0

-a|--all -a|--全部

apply the limit to all devices
将限制应用于所有设备

--raw

print all numbers raw values in bytes without the B suffix
以字节的原始值打印所有数字，不带 B 后缀

--human-readable

print human friendly numbers, base 1024, this is the default
打印人类友好的数字，基数为 1024，这是默认设置

--iec

select the 1024 base for the following options, according to the IEC standard
根据 IEC 标准，为以下选项选择 1024 进制

--si

select the 1000 base for the following options, according to the SI standard
根据 SI 标准，为以下选项选择 1000 进制

--kbytes

show sizes in KiB, or kB with --si
以 KiB 显示大小，或者使用--si 选项显示 kB

--mbytes

show sizes in MiB, or MB with --si
以 MiB 显示大小，或使用 --si 选项显示 MB

--gbytes

show sizes in GiB, or GB with --si
以 GiB 显示大小，或使用 --si 选项显示 GB

--tbytes

show sizes in TiB, or TB with --si
以 TiB 显示大小，或者使用 --si 选项显示为 TB

resume [-BdqrR] <path>|<device>
恢复 [-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.
在由路径标识的文件系统上或在给定设备上恢复已取消或中断的扫描。如果存在状态文件，则从状态文件中读取起始点。

This does not start a new scrub if the last scrub finished successfully.
如果上次扫描成功完成，则不会启动新的扫描。

Options

see scrub start. 查看开始擦洗。

start [-BdrRf] <path>|<device>
开始 [-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 are performed by default for block group profiles with redundancy. No-repair can be enabled by option -r.
没有选项的情况下，擦洗作为后台进程启动。默认情况下，对具有冗余的块组配置文件执行损坏副本的自动修复。可以通过选项 -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
在结束时为文件系统的每个设备打印单独的统计信息（仅限 -B）

-r

run in read-only mode, do not attempt to correct anything, can be run on a read-only filesystem
在只读模式下运行，不要尝试更正任何内容，可以在只读文件系统上运行

-R

raw print mode, print full data instead of summary
原始打印模式，打印完整数据而不是摘要

-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 <ioprio_class>

set IO priority class (see 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 IO limiting.
如果为设备配置了 ionice 支持的 IO 调度程序，则设置 IO 优先级类别（请参阅 ionice(1) 手册页）。这仅由 BFQ 或 Kyber 支持，但 mq-deadline 不支持。请阅读有关 IO 限制的部分。

-n <ioprio_classdata>

set IO priority classdata (see ionice(1) manpage)
设置 IO 优先级类别数据（请参阅 ionice(1) 手册页）。

-q

(deprecated) alias for global -q option
(已弃用) 全局 -q 选项的别名

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.
如果没有正在运行的磁盘整理，则显示该文件系统或设备上最后完成或取消的磁盘整理的统计信息。

Options

-d

print separate statistics for each device of the filesystem
为文件系统的每个设备单独打印统计信息。

-R

print all raw statistics without postprocessing as returned by the status ioctl
打印所有原始统计数据，而不进行状态 ioctl 返回的后处理

--raw

print all numbers raw values in bytes without the B suffix
打印所有数字的原始字节值，而不带有 B 后缀

--human-readable

print human friendly numbers, base 1024, this is the default
打印人类友好的数字，基数为 1024，这是默认设置

--iec

select the 1024 base for the following options, according to the IEC standard
根据 IEC 标准，为以下选项选择 1024 进制

--si

select the 1000 base for the following options, according to the SI standard
根据 SI 标准，为以下选项选择 1000 进制

--kbytes

show sizes in KiB, or kB with --si
以 KiB 显示大小，或者使用--si 选项显示 kB

--mbytes

show sizes in MiB, or MB with --si
以 MiB 显示大小，或使用 --si 选项显示 MB

--gbytes

show sizes in GiB, or GB with --si
以 GiB 显示大小，或使用 --si 选项显示 GB

--tbytes

show sizes in TiB, or TB with --si
以 TiB 显示大小，或者使用 --si 选项显示为 TB

A status on a filesystem without any error looks like the following:
没有任何错误的文件系统状态如下：

# 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:
发现一些错误：

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
    未经验证 -- 瞬态错误，首次读取失败但重试成功，可能受到分组或拆分 IO 请求的较低层影响

  • Error summary -- followed by a more detailed list of errors found
    错误摘要 -- 后跟发现的错误更详细的列表

    • csum -- checksum mismatch
      csum -- 校验和不匹配

    • 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
      读取 -- 由于 IO 错误无法读取块

It’s possible to set a per-device limit via 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 scrub IO limiting.
可以通过文件 sysfs/fs/btrfs/FSID/devinfo/scrub_speed_max 设置每个设备的限制。在这种情况下，如果指定了选项-d，则限制将打印在速率行上，否则将在单设备文件系统上打印。在关于 IO 限制的章节中了解更多信息。

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:
在至少有一个设备限制的多设备文件系统上，总体统计数据无法在没有-d 的情况下打印限制，因此有一些限制被设置为不打印：

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:
如果 btrfs scrub 成功，则返回零退出状态。如果失败，则返回非零值：

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.
btrfs 是 btrfs-progs 的一部分。请参考 https://btrfs.readthedocs.io 上的文档。

SEE ALSO 参见 

mkfs.btrfs(8)