btrfs-device(8)

SYNOPSIS 概要 

btrfs device <subcommand> <args>
btrfs 设备 <子命令> <参数>

DESCRIPTION 描述 

The btrfs device command group is used to manage devices of the btrfs filesystems.
btrfs 设备命令组用于管理 btrfs 文件系统的设备。

DEVICE MANAGEMENT 设备管理 

BTRFS filesystem can be created on top of single or multiple block devices. Devices can be then added, removed or replaced on demand. Data and metadata are organized in allocation profiles with various redundancy policies. There’s some similarity with traditional RAID levels, but this could be confusing to users familiar with the traditional meaning. Due to the similarity, the RAID terminology is widely used in the documentation. See mkfs.btrfs(8) for more details and the exact profile capabilities and constraints.
BTRFS 文件系统可以在单个或多个块设备的顶部创建。然后可以根据需要添加、删除或替换设备。数据和元数据以各种冗余策略组织在分配配置文件中。与传统的 RAID 级别有一些相似之处，但这可能会让熟悉传统含义的用户感到困惑。由于相似性，RAID 术语在文档中被广泛使用。有关更多详细信息和确切的配置文件功能和约束，请参阅 mkfs.btrfs(8)。

The device management works on a mounted filesystem. Devices can be added, removed or replaced, by commands provided by btrfs device and btrfs replace.
设备管理在挂载的文件系统上运行。设备可以通过 btrfs 设备和 btrfs 替换提供的命令进行添加、移除或替换。

The profiles can be also changed, provided there’s enough workspace to do the conversion, using the btrfs balance command and namely the filter convert.
如果有足够的工作空间进行转换，可以使用 btrfs 平衡命令以及特别是过滤器转换来更改配置文件。

Type 类型

The block group profile type is the main distinction of the information stored on the block device. User data are called Data, the internal data structures managed by filesystem are Metadata and System.
块组配置文件类型是存储在块设备上的信息的主要区别。用户数据称为数据，文件系统管理的内部数据结构称为元数据和系统。

Profile 配置文件

A profile describes an allocation policy based on the redundancy/replication constraints in connection with the number of devices. The profile applies to data and metadata block groups separately. E.g. single, RAID1.
配置文件描述了基于冗余/复制约束条件与设备数量相关的分配策略。配置文件分别应用于数据块组和元数据块组。例如，单个，RAID1。

RAID level RAID 等级

Where applicable, the level refers to a profile that matches constraints of the standard RAID levels. At the moment the supported ones are: RAID0, RAID1, RAID10, RAID5 and RAID6.
在适用的情况下，该级别指的是符合标准 RAID 级别约束的配置文件。目前支持的级别有：RAID0、RAID1、RAID10、RAID5 和 RAID6。

Typical use cases 典型用例 

Starting with a single-device filesystem
从单设备文件系统开始 

Assume we’ve created a filesystem on a block device /dev/sda with profile single/single (data/metadata), the device size is 50GiB and we’ve used the whole device for the filesystem. The mount point is /mnt.
假设我们已经在一个块设备 /dev/sda 上使用单个/single（数据/元数据）配置文件系统，设备大小为 50GiB，并且我们已经将整个设备用于文件系统。挂载点是 /mnt 。

The amount of data stored is 16GiB, metadata have allocated 2GiB.
存储的数据量为 16GiB，元数据已分配 2GiB。

Add new device 添加新设备

We want to increase the total size of the filesystem and keep the profiles. The size of the new device /dev/sdb is 100GiB.
我们希望增加文件系统的总大小并保留配置文件。新设备 /dev/sdb 的大小为 100GiB。

$ btrfs device add /dev/sdb /mnt

The amount of free data space increases by less than 100GiB, some space is allocated for metadata.
空闲数据空间的增加量不到 100GiB，一些空间被分配给元数据。

Convert to RAID1 转换为 RAID1 

Now we want to increase the redundancy level of both data and metadata, but we’ll do that in steps. Note, that the device sizes are not equal and we’ll use that to show the capabilities of split data/metadata and independent profiles.
现在我们希望增加数据和元数据的冗余级别，但我们将分步进行。请注意，设备大小不相等，我们将利用这一点来展示分割数据/元数据和独立配置文件的能力。

The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2 copies will be stored on the devices.
RAID1 的约束条件给出了最多 50GiB 的可用空间，并且确切地将 2 份副本存储在设备上。

First we’ll convert the metadata. As the metadata occupy less than 50GiB and there’s enough workspace for the conversion process, we can do:
首先，我们将转换元数据。由于元数据占用的空间不到 50GiB，并且转换过程有足够的工作空间，我们可以执行：

$ btrfs balance start -mconvert=raid1 /mnt

This operation can take a while, because all metadata have to be moved and all block pointers updated. Depending on the physical locations of the old and new blocks, the disk seeking is the key factor affecting performance.
这个操作可能需要一段时间，因为所有元数据都必须被移动，所有块指针都必须被更新。根据旧块和新块的物理位置，磁盘寻道是影响性能的关键因素。

You’ll note that the system block group has been also converted to RAID1, this normally happens as the system block group also holds metadata (the physical to logical mappings).
您会注意到系统块组也已转换为 RAID1，这通常发生在系统块组也保存元数据（物理到逻辑映射）的情况下。

What changed: 发生了什么变化：

  • available data space decreased by 3GiB, usable roughly (50 - 3) + (100 - 3) = 144 GiB
    可用数据空间减少了 3GiB，可用空间大约为(50 - 3) + (100 - 3) = 144 GiB

  • metadata redundancy increased
    元数据冗余增加

IOW, the unequal device sizes allow for combined space for data yet improved redundancy for metadata. If we decide to increase redundancy of data as well, we’re going to lose 50GiB of the second device for obvious reasons.
换句话说，不均匀的设备大小允许为数据提供组合空间，同时为元数据提供改进的冗余。如果我们决定增加数据的冗余，我们将因为明显的原因而失去第二个设备的 50GiB。

$ btrfs balance start -dconvert=raid1 /mnt

The balance process needs some workspace (i.e. a free device space without any data or metadata block groups) so the command could fail if there’s too much data or the block groups occupy the whole first device.
平衡过程需要一些工作空间（即没有任何数据或元数据块组的空闲设备空间），因此如果数据过多或块组占据整个第一个设备，则命令可能会失败。

The device size of /dev/sdb as seen by the filesystem remains unchanged, but the logical space from 50-100GiB will be unused.
由文件系统看到的 /dev/sdb 设备大小保持不变，但从 50-100GiB 的逻辑空间将不被使用。

Remove device 移除设备

Device removal must satisfy the profile constraints, otherwise the command fails. For example:
设备移除必须满足配置文件约束，否则命令将失败。例如：

$ btrfs device remove /dev/sda /mnt
ERROR: error removing device '/dev/sda': unable to go below two devices on raid1

In order to remove a device, you need to convert the profile in this case:
要移除设备，您需要转换配置文件，如下：

$ btrfs balance start -mconvert=dup -dconvert=single /mnt
$ btrfs device remove /dev/sda /mnt

SUBCOMMAND 子命令 

add [-Kf] <device> [<device>…] <path>
添加 [-Kf] <设备> [<设备>…] <路径>

Add device(s) to the filesystem identified by path.
将设备添加到由路径标识的文件系统中。

If applicable, a whole device discard (TRIM) operation is performed prior to adding the device. A device with existing filesystem detected by blkid(8) will prevent device addition and has to be forced. Alternatively the filesystem can be wiped from the device using e.g. the wipefs(8) tool.
如果适用，将在添加设备之前执行整个设备丢弃（TRIM）操作。通过 blkid(8) 检测到具有现有文件系统的设备将阻止设备添加，必须强制执行。或者可以使用例如 wipefs(8) 工具从设备中擦除文件系统。

The operation is instant and does not affect existing data. The operation merely adds the device to the filesystem structures and creates some block groups headers.
该操作是即时的，不会影响现有数据。该操作仅将设备添加到文件系统结构并创建一些块组头。

Options

-K|--nodiscard

do not perform discard (TRIM) by default
默认情况下不执行丢弃（TRIM）

-f|--force -f|--强制

force overwrite of existing filesystem on the given disk(s)
强制覆盖给定磁盘上现有的文件系统

--enqueue

wait if there’s another exclusive operation running, otherwise continue
如果有另一个独占操作正在运行，则等待，否则继续

remove [options] <device>|<devid> [<device>|<devid>…] <path>
移除 [选项] <设备>|<设备 ID> [<设备>|<设备 ID>…] <路径>

Remove device(s) from a filesystem identified by <path>
从由<path>标识的文件系统中移除设备

Device removal must satisfy the profile constraints, otherwise the command fails and cannot be enforced. The filesystem must be converted to profile(s) that would allow the removal. This can for example happen when going down from 2 devices to 1 and using the RAID1 profile. See the section Typical use cases.
设备移除必须满足配置文件的约束条件，否则命令将失败且无法执行。文件系统必须转换为允许移除的配置文件，例如，当从 2 个设备减少到 1 个并使用 RAID1 配置文件时可能会发生这种情况。请参阅“典型用例”部分。

The operation can take long as it needs to move all data from the device.
该操作可能需要很长时间，因为它需要将设备上的所有数据移动。

Note 注意

It’s possible to specify more than one device on the command line but the devices will be removed one by one, not at once. This means that the remaining devices to be deleted can be still used for writes. In that case there’s a warning and safety timeout as this can be confusing and unexpected. The timeout can be overridden by option --force.
在命令行上可以指定多个设备，但设备将逐个而非一次性删除。这意味着待删除的剩余设备仍可用于写入。在这种情况下会有警告和安全超时，因为这可能会令人困惑和意外。超时可以通过选项 --force 覆盖。

It is possible to delete the device that was used to mount the filesystem. The device entry in the mount table (/proc/self/mounts) will be replaced by another device name with the lowest device id.
可以删除用于挂载文件系统的设备。挂载表中的设备条目（ /proc/self/mounts ）将被另一个具有最低设备 ID 的设备名称替换。

If the filesystem is mounted in degraded mode (-o degraded), special term missing can be used for device. In that case, the first device that is described by the filesystem metadata, but not present at the mount time will be removed.
如果文件系统以降级模式（-o degraded）挂载，可以使用特殊术语 missing 来表示设备。在这种情况下，文件系统元数据描述但在挂载时不存在的第一个设备将被移除。

Note 注意

In most cases, there is only one missing device in degraded mode, otherwise mount fails. If there are two or more devices missing (e.g. possible in RAID6), you need specify missing as many times as the number of missing devices to remove all of them.
在大多数情况下，降级模式中只有一个缺失设备，否则挂载会失败。如果有两个或更多缺失设备（例如在 RAID6 中可能出现），您需要多次指定缺失，以删除所有缺失设备。

Options

--enqueue

wait if there’s another exclusive operation running, otherwise continue
如果有另一个独占操作正在运行，则等待，否则继续

--force

skip the safety timeout when there are multiple devices for removal, this does not force removing devices that would break the profile constraints
当有多个设备需要移除时，跳过安全超时，这不会强制移除可能违反配置文件约束的设备

delete <device>|<devid> [<device>|<devid>…] <path>
删除 <设备>|<设备 ID> [<设备>|<设备 ID>…] <路径>

Alias of remove kept for backward compatibility
为了向后兼容而保留的别名

replace <command> [options] <path>
替换 <命令> [选项] <路径>

Alias of whole command group btrfs replace for convenience. See btrfs-replace(8).
为方便起见，整个命令组 btrfs replace 的别名。请参阅 btrfs-replace(8)。

ready <device> 准备好 <设备>

Wait until all devices of a multiple-device filesystem are scanned and registered within the kernel module. This is to provide a way for automatic filesystem mounting tools to wait before the mount can start. The device scan is only one of the preconditions and the mount can fail for other reasons. Normal users usually do not need this command and may safely ignore it.
等待直到多设备文件系统的所有设备被扫描并在内核模块中注册。这是为了提供一种自动文件系统挂载工具在挂载开始之前等待的方式。设备扫描只是先决条件之一，挂载可能因其他原因而失败。普通用户通常不需要此命令，可以安全地忽略它。

scan [options] [<device> [<device>…]]
扫描 [选项] [<设备> [<设备>…]]

Scan devices for a btrfs filesystem and register them with the kernel module. This allows mounting multiple-device filesystem by specifying just one from the whole group.
扫描设备以查找 btrfs 文件系统，并将它们注册到内核模块中。这允许通过仅指定整个组中的一个来挂载多设备文件系统。

If no devices are passed, all block devices that blkid reports to contain btrfs are scanned.
如果没有传递设备，则将扫描 blkid 报告包含 btrfs 的所有块设备。

The options --all-devices or -d can be used as a fallback in case blkid is not available. If used, behavior is the same as if no devices are passed.
可以使用选项 --all-devices 或 -d 作为备用选项，以防 blkid 不可用。如果使用，行为与未传递设备时相同。

The command can be run repeatedly. Devices that have been already registered remain as such. Reloading the kernel module will drop this information. There’s an alternative way of mounting multiple-device filesystem without the need for prior scanning. See the mount option device (in btrfs-man5).
该命令可以重复运行。已经注册的设备将保持不变。重新加载内核模块将删除此信息。有一种替代方法可以挂载多设备文件系统，无需事先扫描。请参阅挂载选项设备（在 btrfs-man5 中）。

Options

-d|--all-devices

Enumerate and register all devices, use as a fallback in case blkid is not available.
枚举并注册所有设备，在 blkid 不可用时作为后备选项。

-u|--forget -u|--忘记

Unregister a given device or all stale devices if no path is given, the device must be unmounted otherwise it’s an error.
取消注册给定设备或所有过期设备（如果未提供路径，则必须卸载设备，否则将出错）。

stats [options] <path>|<device>
统计 [选项] <路径>|<设备>

Read and print the device IO error statistics for all devices of the given filesystem identified by path or for a single device. The filesystem must be mounted. See section DEVICE STATS for more information about the reported statistics and the meaning.
读取并打印由路径标识的给定文件系统的所有设备的设备 IO 错误统计信息，或者针对单个设备。文件系统必须已挂载。有关报告的统计信息和含义，请参阅“设备统计”部分。

Options

-z|--reset -z|--重置

Print the stats and reset the values to zero afterwards.
打印统计信息并在之后将值重置为零。

-c|--check -c|--检查

Check if the stats are all zeros and return 0 if it is so. Set bit 6 of the return code if any of the statistics is no-zero. The error values is 65 if reading stats from at least one device failed, otherwise it’s 64.
检查统计数据是否全为零，如果是，则返回 0。如果任何统计数据不为零，则设置返回代码的第 6 位。如果从至少一个设备读取统计数据失败，则错误值为 65，否则为 64。

-T

Print stats in a tabular form, devices as rows and stats as columns
以表格形式打印统计数据，设备作为行，统计数据作为列

usage [options] <path> [<path>…]::
用法 [选项] <路径> [<路径>…]::

Show detailed information about internal allocations on devices.
显示有关设备上内部分配的详细信息。

The level of detail can differ if the command is run under a regular or the root user (due to use of restricted ioctls). The first example below is for normal user (warning included) and the next one with root on the same filesystem:
如果命令在常规用户或根用户下运行（由于使用受限制的 ioctls），详细级别可能有所不同。下面的第一个示例是针对普通用户的（包括警告），下一个示例是在相同文件系统上使用 root 用户的：

WARNING: cannot read detailed chunk info, per-device usage will not be shown, run as root
/dev/sdc1, ID: 1
   Device size:           931.51GiB
   Device slack:              0.00B
   Unallocated:           931.51GiB

/dev/sdc1, ID: 1
   Device size:           931.51GiB
   Device slack:              0.00B
   Data,single:           641.00GiB
   Data,RAID0/3:            1.00GiB
   Metadata,single:        19.00GiB
   System,single:          32.00MiB
   Unallocated:           271.48GiB

  • Device size -- size of the device as seen by the filesystem (may be different than actual device size)
    设备大小 -- 文件系统看到的设备大小（可能与实际设备大小不同）

  • Device slack -- portion of device not used by the filesystem but still available in the physical space provided by the device, e.g. after a device shrink
    设备保留空间 -- 文件系统未使用但仍可在设备提供的物理空间中使用的部分，例如在设备收缩后

  • Data,single, Metadata,single, System,single -- in general, list of block group type (Data, Metadata, System) and profile (single, RAID1, …) allocated on the device
    数据，单个，元数据，单个，系统，单个 -- 一般来说，分配在设备上的块组类型（数据，元数据，系统）和配置文件（单个，RAID1，...）的列表

  • Data,RAID0/3 -- in particular, striped profiles RAID0/RAID10/RAID5/RAID6 with the number of devices on which the stripes are allocated, multiple occurrences of the same profile can appear in case a new device has been added and all new available stripes have been used for writes
    数据，RAID0/3 -- 特别是，条带配置 RAID0/RAID10/RAID5/RAID6，带有分配条带的设备数量，如果添加了新设备并且所有新可用的条带都已用于写入，则同一配置的多个出现可能会出现

  • Unallocated -- remaining space that the filesystem can still use for new block groups
    未分配 -- 文件系统仍然可以用于新块组的剩余空间

Options

-b|--raw -b|--原始

raw numbers in bytes, without the B suffix
以字节为单位的原始数字，不带 B 后缀

-h|--human-readable

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

-H

print human friendly numbers, base 1000
打印人类友好的数字，基数 1000

--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 进制

-k|--kbytes -k|--千字节

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

-m|--mbytes -m|--兆字节

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

-g|--gbytes

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

-t|--tbytes

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

If conflicting options are passed, the last one takes precedence.
如果传递了冲突的选项，则以最后一个为准。

DEVICE STATS 设备统计 

The device stats keep persistent record of several error classes related to doing IO. The current values are printed at mount time and updated during filesystem lifetime or from a scrub run.
设备统计保留了与执行 IO 相关的几个错误类别的持久记录。当前值在挂载时打印，并在文件系统生命周期中或从一次 scrub 运行中进行更新。

$ btrfs device stats /dev/sda3
[/dev/sda3].write_io_errs   0
[/dev/sda3].read_io_errs    0
[/dev/sda3].flush_io_errs   0
[/dev/sda3].corruption_errs 0
[/dev/sda3].generation_errs 0
write_io_errs 写入 IO 错误

Failed writes to the block devices, means that the layers beneath the filesystem were not able to satisfy the write request.
写入块设备失败，意味着文件系统下面的层无法满足写入请求。

read_io_errors 读取输入/输出错误

Read request analogy to write_io_errs.
读取请求类比于写入输入/输出错误。

flush_io_errs 刷新 IO 错误

Number of failed writes with the FLUSH flag set. The flushing is a method of forcing a particular order between write requests and is crucial for implementing crash consistency. In case of btrfs, all the metadata blocks must be permanently stored on the block device before the superblock is written.
具有 FLUSH 标志设置的失败写入次数。刷新是一种强制写入请求之间特定顺序的方法，对于实现崩溃一致性至关重要。在 btrfs 的情况下，所有元数据块必须在写入超级块之前永久存储在块设备上。

corruption_errs 损坏错误

A block checksum mismatched or a corrupted metadata header was found.
发现块校验和不匹配或损坏的元数据头。

generation_errs

The block generation does not match the expected value (e.g. stored in the parent node).
块生成与预期值不匹配（例如，存储在父节点中的值）。

Since kernel 5.14 the device stats are also available in textual form in /sys/fs/btrfs/FSID/devinfo/DEVID/error_stats.
从内核 5.14 开始，设备统计信息也以文本形式在 /sys/fs/btrfs/FSID/devinfo/DEVID/error_stats 中可用。

EXIT STATUS 退出状态 

btrfs device returns a zero exit status if it succeeds. Non zero is returned in case of failure.
如果 btrfs 设备成功，则返回零退出状态。如果失败则返回非零值。

If the -c option is used, btrfs device stats will add 64 to the exit status if any of the error counters is non-zero.
如果使用了 -c 选项，btrfs 设备统计信息将在任何错误计数器非零时将 64 添加到退出状态。

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 参见 

btrfs-balance(8) btrfs-device(8), btrfs-replace(8), mkfs.btrfs(8)
btrfs-balance(8)、btrfs-device(8)、btrfs-replace(8)、mkfs.btrfs(8)