diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man8/btrfs-convert.8 | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man8/btrfs-convert.8 b/upstream/opensuse-tumbleweed/man8/btrfs-convert.8 new file mode 100644 index 00000000..fded5087 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man8/btrfs-convert.8 @@ -0,0 +1,253 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BTRFS-CONVERT" "8" "Feb 14, 2024" "6.7.1" "BTRFS" +.SH NAME +btrfs-convert \- convert from ext2/3/4 or reiserfs filesystem to btrfs in-place +.SH SYNOPSIS +.sp +\fBbtrfs\-convert\fP [options] <device> +.SH DESCRIPTION +.sp +The \fBbtrfs\-convert\fP 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 \fIext2_saved\fP as file \fIimage\fP\&. +.sp +Supported filesystems: +.INDENT 0.0 +.IP \(bu 2 +ext2, ext3, ext4 \-\- original feature, always built in +.IP \(bu 2 +reiserfs \-\- since version 4.13, optionally built, requires libreiserfscore 3.6.27 +.IP \(bu 2 +NTFS \-\- external tool \fI\%https://github.com/maharmstone/ntfs2btrfs\fP +.UNINDENT +.sp +The list of supported source filesystem by a given binary is listed at the end +of help (option \fI\-\-help\fP). +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +If you are going to perform rollback to the original filesystem, you +should not execute \fBbtrfs balance\fP command on the converted filesystem. This +will change the extent layout and make \fBbtrfs\-convert\fP unable to rollback. +.UNINDENT +.UNINDENT +.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 (i.e. the same that would be valid for +\fBmkfs.btrfs\fP). This is typically the system page size (4KiB on x86_64 +machines). +.sp +\fBBEFORE YOU START\fP +.sp +The source filesystem must be clean, e.g. no journal to replay or no repairs +needed. The respective \fBfsck\fP utility must be run on the source filesystem prior +to conversion. Please refer to the manual pages in case you encounter problems. +.sp +For ext2/3/4: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# e2fsck \-fvy /dev/sdx +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For reiserfs: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# reiserfsck \-fy /dev/sdx +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Skipping that step could lead to incorrect results on the target filesystem, +but it may work. +.sp +\fBREMOVE THE ORIGINAL FILESYSTEM METADATA\fP +.sp +By removing the subvolume named like \fIext2_saved\fP or \fIreiserfs_saved\fP, all +metadata of the original filesystem will be removed: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs subvolume delete /mnt/ext2_saved +.ft P +.fi +.UNINDENT +.UNINDENT +.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\fP +.sp +An optional but recommended step is to run defragmentation on the entire +filesystem. This will attempt to make file extents more contiguous. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs filesystem defrag \-v \-r \-f \-t 32M /mnt/btrfs +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Verbose recursive defragmentation (\fI\-v\fP, \fI\-r\fP), flush data per\-file (\fI\-f\fP) with +target extent size 32MiB (\fI\-t\fP). +.sp +\fBATTEMPT TO MAKE BTRFS METADATA MORE COMPACT\fP +.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 +\fI\%btrfs\-balance(8)\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# btrfs balance start \-m /mnt/btrfs +.ft P +.fi +.UNINDENT +.UNINDENT +.SH OPTIONS +.INDENT 0.0 +.TP +.BI \-\-csum \ <type>\fR,\fB \ \-\-checksum \ <type> +Specify the checksum algorithm. Default is \fIcrc32c\fP\&. Valid values are \fIcrc32c\fP, +\fIxxhash\fP, \fIsha256\fP or \fIblake2\fP\&. To mount such filesystem kernel must support the +checksums as well. +.UNINDENT +.INDENT 0.0 +.TP +.B \-d|\-\-no\-datasum +disable data checksum calculations and set the NODATASUM file flag, this can speed +up the conversion +.TP +.B \-i|\-\-no\-xattr +ignore xattrs and ACLs of files +.TP +.B \-n|\-\-no\-inline +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 +.TP +.B \-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 +\fI\%mkfs.btrfs(8)\fP for more details. +.TP +.B \-r|\-\-rollback +rollback to the original ext2/3/4 filesystem if possible +.TP +.B \-l|\-\-label <LABEL> +set filesystem label during conversion +.TP +.B \-L|\-\-copy\-label +use label from the converted filesystem +.TP +.B \-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 \fI^\fP\&. +Description of the features is in section +\fI\%FILESYSTEM FEATURES\fP of +\fI\%mkfs.btrfs(8)\fP\&. +.sp +To see all available features that btrfs\-convert supports run: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +btrfs\-convert \-O list\-all +.ft P +.fi +.UNINDENT +.UNINDENT +.TP +.B \-p|\-\-progress +show progress of conversion (a heartbeat indicator and number of inodes +processed), on by default +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-no\-progress +disable progress and show only the main phases of conversion +.TP +.BI \-\-uuid \ <SPEC> +set the FSID of the new filesystem based on \(aqSPEC\(aq: +.INDENT 7.0 +.IP \(bu 2 +\fInew\fP \- (default) generate UUID for the FSID of btrfs +.IP \(bu 2 +\fIcopy\fP \- copy UUID from the source filesystem +.IP \(bu 2 +\fIUUID\fP \- a conforming UUID value, the 36 byte string representation +.UNINDENT +.UNINDENT +.SH EXIT STATUS +.sp +\fBbtrfs\-convert\fP will return 0 if no error happened. +If any problems happened, 1 will be returned. +.SH SEE ALSO +.sp +\fI\%mkfs.btrfs(8)\fP +.\" Generated by docutils manpage writer. +. |