btrfs-convert(8)

SYNOPSIS 概要 

btrfs-convert [options] <device>
btrfs-convert [选项] <设备>

DESCRIPTION 描述 

The btrfs-convert tool can be used to convert existing source filesystem image to a btrfs filesystem in-place. The original filesystem image is accessible in subvolume named like ext2_saved as file image.
btrfs-convert 工具可用于将现有的源文件系统镜像转换为原地的 btrfs 文件系统。原始文件系统镜像可在名为 ext2_saved 的子卷中访问为文件镜像。

Supported filesystems: 支持的文件系统:

  • ext2, ext3, ext4 -- original feature, always built in
    ext2, ext3, ext4 -- 原始功能，始终内置

  • reiserfs -- since version 4.13, optionally built, requires libreiserfscore 3.6.27
    reiserfs -- 自 4.13 版本起，可选构建，需要 libreiserfscore 3.6.27

  • NTFS -- external tool https://github.com/maharmstone/ntfs2btrfs
    NTFS -- 外部工具 https://github.com/maharmstone/ntfs2btrfs

The list of supported source filesystem by a given binary is listed at the end of help (option --help).
给定二进制文件支持的源文件系统列表在帮助的末尾列出（选项 --help）。

Warning 警告

If you are going to perform rollback to the original filesystem, you should not execute btrfs balance command on the converted filesystem. This will change the extent layout and make btrfs-convert unable to rollback.
如果您要执行回滚到原始文件系统，则不应在转换后的文件系统上执行 btrfs balance 命令。这将更改范围布局并使 btrfs-convert 无法回滚。

The conversion utilizes free space of the original filesystem. The exact estimate of the required space cannot be foretold. The final btrfs metadata might occupy several gigabytes on a hundreds-gigabyte filesystem.
转换利用原始文件系统的空闲空间。所需空间的精确估计无法预测。最终的 btrfs 元数据可能占据数百千字节文件系统上的几千兆字节。

If the ability to rollback is no longer important, the it is recommended to perform a few more steps to transition the btrfs filesystem to a more compact layout. This is because the conversion inherits the original data blocks’ fragmentation, and also because the metadata blocks are bound to the original free space layout.
如果回滚的能力不再重要，则建议执行更多步骤将 btrfs 文件系统转换为更紧凑的布局。这是因为转换继承了原始数据块的碎片化，还因为元数据块绑定到原始的空闲空间布局。

Due to different constraints, it is only possible to convert filesystems that have a supported data block size (i.e. the same that would be valid for mkfs.btrfs). This is typically the system page size (4KiB on x86_64 machines).
由于不同的约束，只有支持的数据块大小的文件系统才能进行转换（即适用于 mkfs.btrfs 的大小）。这通常是系统页面大小（在 x86_64 机器上为 4KiB）。

Note 注意

Always consider if a mkfs and file copy would not be a better option than the in-place conversion given what was said above. The conversion depends on 3rd party libraries and the other filesystems could still evolve and add new features. Not all combinations are covered or tested.
始终考虑如果 mkfs 和文件复制不是比就地转换更好的选择，考虑到上面所说的。转换取决于第三方库，其他文件系统仍然可能发展并添加新功能。并非所有组合都被覆盖或测试。

BEFORE YOU START 在开始之前

The source filesystem must be clean, e.g. no journal to replay or no repairs needed. The respective fsck utility must be run on the source filesystem prior to conversion. Please refer to the manual pages in case you encounter problems.
源文件系统必须是干净的，例如没有要重放的日志或不需要修复。在转换之前必须在源文件系统上运行相应的 fsck 实用程序。如果遇到问题，请参考手册页面。

For ext2/3/4: 对于 ext2/3/4：

# e2fsck -fvy /dev/sdx

For reiserfs: 对于 reiserfs：

# reiserfsck -fy /dev/sdx

Skipping that step could lead to incorrect results on the target filesystem, but it may work.
跳过该步骤可能导致目标文件系统上的结果不正确，但也可能有效。

REMOVE THE ORIGINAL FILESYSTEM METADATA
删除原始文件系统元数据

By removing the subvolume named like ext2_saved or reiserfs_saved, all metadata of the original filesystem will be removed:
通过删除类似于 ext2_saved 或 reiserfs_saved 的子卷，将删除原始文件系统的所有元数据：

# btrfs subvolume delete /mnt/ext2_saved

At this point it is not possible to do a rollback. The filesystem is usable but may be impacted by the fragmentation inherited from the original filesystem.
此时无法执行回滚操作。文件系统可用，但可能受到继承自原始文件系统的碎片化影响。

MAKE FILE DATA MORE CONTIGUOUS
使文件数据更加连续

An optional but recommended step is to run defragmentation on the entire filesystem. This will attempt to make file extents more contiguous.
一个可选但建议的步骤是在整个文件系统上运行碎片整理。这将尝试使文件范围更加连续。

# btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs

Verbose recursive defragmentation (-v, -r), flush data per-file (-f) with target extent size 32MiB (-t).
详细递归碎片整理（-v，-r），每个文件刷新数据（-f），目标范围大小为 32MiB（-t）。

ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT
尝试使 BTRFS 元数据更紧凑

Optional but recommended step.
可选但建议的步骤。

The metadata block groups after conversion may be smaller than the default size (256MiB or 1GiB). Running a balance will attempt to merge the block groups. This depends on the free space layout (and fragmentation) and may fail due to lack of enough work space. This is a soft error leaving the filesystem usable but the block group layout may remain unchanged.
转换后的元数据块组可能比默认大小（256MiB 或 1GiB）小。运行平衡将尝试合并块组。这取决于空闲空间布局（和碎片化），可能由于缺乏足够的工作空间而失败。这是一个软错误，使文件系统可用，但块组布局可能保持不变。

Note that balance operation takes a lot of time, please see also btrfs-balance(8).
请注意，平衡操作需要很长时间，请参阅 btrfs-balance(8)。

# btrfs balance start -m /mnt/btrfs

OPTIONS 选项 

--csum <type>, --checksum <type>

Specify the checksum algorithm. Default is crc32c. Valid values are crc32c, xxhash, sha256 or blake2. To mount such filesystem kernel must support the checksums as well.
指定校验算法。默认值为 crc32c。有效值为 crc32c、xxhash、sha256 或 blake2。要挂载这种文件系统，内核必须支持校验和。

-d|--no-datasum

disable data checksum calculations and set the NODATASUM file flag, this can speed up the conversion
禁用数据校验计算并设置 NODATASUM 文件标志，这可以加快转换速度

-i|--no-xattr -i|--不使用扩展属性

ignore xattrs and ACLs of files
忽略文件的扩展属性和 ACL

-n|--no-inline -n|--不内联

disable inlining of small files to metadata blocks, this will decrease the metadata consumption and may help to convert a filesystem with low free space
禁用将小文件内联到元数据块，这将减少元数据消耗，并可能有助于转换具有低剩余空间的文件系统

-N|--nodesize <SIZE>

set filesystem nodesize, the tree block size in which btrfs stores its metadata. The default value is 16KiB (16384) or the page size, whichever is bigger. Must be a multiple of the sectorsize, but not larger than 65536. See mkfs.btrfs(8) for more details.
设置文件系统节点大小，即 btrfs 存储其元数据的树块大小。默认值为 16KiB（16384）或页面大小（以较大者为准）。必须是扇区大小的倍数，但不能大于 65536。有关更多详细信息，请参阅 mkfs.btrfs(8)。

-r|--rollback -r|--回滚

rollback to the original ext2/3/4 filesystem if possible
尽可能回滚到原始的 ext2/3/4 文件系统

-l|--label <LABEL> -l|--标签 <标签>

set filesystem label during conversion
在转换过程中设置文件系统标签

-L|--copy-label -L|--复制标签

use label from the converted filesystem
使用转换后文件系统的标签

-O|--features <feature1>[,<feature2>…]

A list of filesystem features enabled the at time of conversion. Not all features are supported by old kernels. To disable a feature, prefix it with ^. Description of the features is in section FILESYSTEM FEATURES of mkfs.btrfs(8).
转换时启用的文件系统功能列表。并非所有功能都受旧内核支持。要禁用功能，请在其前面加上^。功能的描述在 mkfs.btrfs(8) 的 FILESYSTEM FEATURES 部分中。

To see all available features that btrfs-convert supports run:
要查看 btrfs-convert 支持的所有可用功能，请运行：

btrfs-convert -O list-all
-p|--progress -p|--进度

show progress of conversion (a heartbeat indicator and number of inodes processed), on by default
显示转换进度（心跳指示器和处理的索引节点数），默认情况下为开启

--no-progress

disable progress and show only the main phases of conversion
禁用进度并仅显示转换的主要阶段

--uuid <SPEC>

set the FSID of the new filesystem based on ‘SPEC’:
根据“SPEC”设置新文件系统的 FSID

  • new - (default) generate UUID for the FSID of btrfs
    新建 - （默认）为 btrfs 的 FSID 生成 UUID

  • copy - copy UUID from the source filesystem
    复制 - 从源文件系统复制 UUID

  • UUID - a conforming UUID value, the 36 byte string representation
    UUID - 符合规范的 UUID 值，36 字节的字符串表示

EXIT STATUS 退出状态 

btrfs-convert will return 0 if no error happened. If any problems happened, 1 will be returned.
如果没有发生错误，btrfs-convert 将返回 0。如果发生任何问题，将返回 1。

SEE ALSO 参见 

mkfs.btrfs(8)