diff options
Diffstat (limited to 'Documentation/btrfs-convert.8')
| -rw-r--r-- | Documentation/btrfs-convert.8 | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/Documentation/btrfs-convert.8 b/Documentation/btrfs-convert.8 new file mode 100644 index 00000000..7b5239ab --- /dev/null +++ b/Documentation/btrfs-convert.8 @@ -0,0 +1,217 @@ +'\" t +.\" Title: btrfs-convert +.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 12/05/2018 +.\" Manual: Btrfs Manual +.\" Source: Btrfs v4.19.1 +.\" Language: English +.\" +.TH "BTRFS\-CONVERT" "8" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +btrfs-convert \- convert from ext2/3/4 or reiserfs filesystem to btrfs in\-place +.SH "SYNOPSIS" +.sp +\fBbtrfs\-convert\fR [options] \fI<device>\fR +.SH "DESCRIPTION" +.sp +\fBbtrfs\-convert\fR is used to convert existing source filesystem image to a btrfs filesystem in\-place\&. The original filesystem image is accessible in subvolume named like \fIext2_saved\fR as file \fIimage\fR\&. +.sp +Supported filesystems: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ext2, ext3, ext4 \(em original feature, always built in +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +reiserfs \(em since version 4\&.13, optionally built, requires libreiserfscore 3\&.6\&.27 +.RE +.sp +The list of supported source filesystem by a given binary is listed at the end of help (option \fI\-\-help\fR)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +.sp +If you are going to perform rollback to the original filesystem, you should not execute \fBbtrfs balance\fR command on the converted filesystem\&. This will change the extent layout and make \fBbtrfs\-convert\fR unable to rollback\&. +.sp .5v +.RE +.sp +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\&. +.sp +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\*(Aq fragmentation, and also because the metadata blocks are bound to the original free space layout\&. +.sp +Due to different constraints, it is only possible to convert filesystems that have a supported data block size (ie\&. the same that would be valid for \fImkfs\&.btrfs\fR)\&. This is typically the system page size (4KiB on x86_64 machines)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.sp +The source filesystem should be clean, you are encouraged to run the \fIfsck\fR tool if you\(cqre not sure\&. +.sp .5v +.RE +.sp +\fBREMOVE THE ORIGINAL FILESYSTEM METADATA\fR +.sp +By removing the subvolume named like \fIext2_saved\fR or \fIreiserfs_saved\fR, all metadata of the original filesystem will be removed: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# btrfs subvolume delete /mnt/ext2_saved +.fi +.if n \{\ +.RE +.\} +.sp +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\&. +.sp +\fBMAKE FILE DATA MORE CONTIGUOUS\fR +.sp +An optional but recommended step is to run defragmentation on the entire filesystem\&. This will attempt to make file extents more contiguous\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# btrfs filesystem defrag \-v \-r \-f \-t 32M /mnt/btrfs +.fi +.if n \{\ +.RE +.\} +.sp +Verbose recursive defragmentation (\fI\-v\fR, \fI\-r\fR), flush data per\-file (\fI\-f\fR) with target extent size 32MiB (\fI\-t\fR)\&. +.sp +\fBATTEMPT TO MAKE BTRFS METADATA MORE COMPACT\fR +.sp +Optional but recommended step\&. +.sp +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\&. +.sp +Note that balance operation takes a lot of time, please see also \fBbtrfs\-balance\fR(8)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +# btrfs balance start \-m /mnt/btrfs +.fi +.if n \{\ +.RE +.\} +.SH "OPTIONS" +.PP +\-d|\-\-no\-datasum +.RS 4 +disable data checksum calculations and set the NODATASUM file flag, this can speed up the conversion +.RE +.PP +\-i|\-\-no\-xattr +.RS 4 +ignore xattrs and ACLs of files +.RE +.PP +\-n|\-\-no\-inline +.RS 4 +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 +.RE +.PP +\-N|\-\-nodesize \fI<SIZE>\fR +.RS 4 +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\&. See +\fBmkfs\&.btrfs\fR(8) for more details\&. +.RE +.PP +\-r|\-\-rollback +.RS 4 +rollback to the original ext2/3/4 filesystem if possible +.RE +.PP +\-l|\-\-label \fI<LABEL>\fR +.RS 4 +set filesystem label during conversion +.RE +.PP +\-L|\-\-copy\-label +.RS 4 +use label from the converted filesystem +.RE +.PP +\-O|\-\-features \fI<feature1>\fR[,\fI<feature2>\fR\&...] +.RS 4 +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 +\fI^\fR\&. Description of the features is in section +\fIFILESYSTEM FEATURES\fR +of +\fBmkfs\&.btrfs\fR(8)\&. +.sp +To see all available features that btrfs\-convert supports run: +.sp +\fBbtrfs\-convert \-O list\-all\fR +.RE +.PP +\-p|\-\-progress +.RS 4 +show progress of conversion (a heartbeat indicator and number of inodes processed), on by default +.RE +.PP +\-\-no\-progress +.RS 4 +disable progress and show only the main phases of conversion +.RE +.SH "EXIT STATUS" +.sp +\fBbtrfs\-convert\fR will return 0 if no error happened\&. If any problems happened, 1 will be returned\&. +.SH "SEE ALSO" +.sp +\fBmkfs\&.btrfs\fR(8) |