btrfs-progs: docs: enhance the manual page for convert
Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
David Sterba
parent
bfb2659d12
commit
26d6392f70
|
|
@ -3,7 +3,7 @@ btrfs-convert(8)
|
|||
|
||||
NAME
|
||||
----
|
||||
btrfs-convert - convert from ext2/3/4 filesystem to btrfs or rollback
|
||||
btrfs-convert - convert from ext2/3/4 filesystem to btrfs
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
|
@ -11,42 +11,82 @@ SYNOPSIS
|
|||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
*btrfs-convert* is used to convert existed ext2/3/4 to btrfs filesystem,
|
||||
and the original filesystem image is accessible as from separate subvolume
|
||||
named 'ext2_saved' as file image.
|
||||
*btrfs-convert* is used to convert existing ext2/3/4 filesystem image to a
|
||||
btrfs filesystem in-place. The original filesystem image is accessible
|
||||
subvolume named 'ext2_saved' as file 'image'.
|
||||
|
||||
WARNING: If one hopes to rollback to ext2/3/4, they should not execute
|
||||
*btrfs balance* command on converted btrfs, since it will change the extent
|
||||
layout and make *btrfs-convert* unable to rollback.
|
||||
WARNING: If you are going to perform rollback to ext2/3/4, you should not
|
||||
execute *btrfs balance* command on the converted filesystem. This will change
|
||||
the extent layout and make *btrfs-convert* unable to rollback.
|
||||
|
||||
NOTE: If one is satisfied with converted btrfs, and not longer wants to
|
||||
rollback to ext2/3/4, it is highly recommended to remove 'ext2_saved' subvolume
|
||||
and execute *btrfs filesystem defragment* and *btrfs balance* command on the
|
||||
converted btrfs.
|
||||
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.
|
||||
|
||||
If you decide not to rollback anymore, it is recommended to perform a few more
|
||||
steps to transform the btrfs filesystem to a more compact layout. The
|
||||
conversion inherits the original data block fragmentation and the metadata
|
||||
blocks are bound to the original free space layout.
|
||||
|
||||
**REMOVE THE ORIGINAL FILESYSTEM METADATA**
|
||||
|
||||
By removing the 'ext2_saved' subvolume, all metadata of the original filesystem
|
||||
will be removed:
|
||||
|
||||
# btrfs subvolume delete /mnt/ext2_saved
|
||||
|
||||
At this point it's not possible to do rollback. The filesystem is usable but may
|
||||
be impacted by the fragmentation.
|
||||
|
||||
**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 32M ('-t').
|
||||
|
||||
**ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT**
|
||||
|
||||
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. This is
|
||||
a soft error leaving the filesystem usable but the block group layout may
|
||||
remain unchanged.
|
||||
|
||||
Note that balance operation takes a lot of time.
|
||||
|
||||
# btrfs balance start -m /mnt/btrfs
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
-d|--no-datasum::
|
||||
Disable data checksum calculations and set NODATASUM file flag. This can speed
|
||||
up the conversion.
|
||||
disable data checksum calculations and set NODATASUM file flag, this can speed
|
||||
up the conversion
|
||||
-i|--no-xattr::
|
||||
Ignore xattrs and ACLs.
|
||||
ignore xattrs and ACLs of files
|
||||
-n|--no-inline::
|
||||
Disable inlining of small files to metadata blocks.
|
||||
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 data.
|
||||
set filesystem nodesize, the tree block size in which btrfs stores its metadata.
|
||||
The default value is 16KB (16384) or the page size, whichever is bigger.
|
||||
Must be a multiple of the sectorsize, but not larger than 65536.
|
||||
Must be a multiple of the sectorsize, but not larger than 65536. Se
|
||||
`mkfs.btrfs`(8) for more details.
|
||||
-r|--rollback::
|
||||
Roll back to ext2fs.
|
||||
rollback to the original ext2/3/4 filesystem if possible
|
||||
-l|--label <LABEL>::
|
||||
set filesystem label during conversion.
|
||||
set filesystem label during conversion
|
||||
-L|--copy-label::
|
||||
use label from the converted filesystem.
|
||||
use label from the converted filesystem
|
||||
-p|--progress::
|
||||
Show progress of conversion, on by default.
|
||||
show progress of conversion, on by default
|
||||
--no-progress::
|
||||
Disable detailed progress and show only the main phases of conversion.
|
||||
disable detailed progress and show only the main phases of conversion
|
||||
|
||||
EXIT STATUS
|
||||
-----------
|
||||
|
|
@ -56,4 +96,3 @@ If any problems happened, 1 will be returned.
|
|||
SEE ALSO
|
||||
--------
|
||||
`mkfs.btrfs`(8)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue