summaryrefslogtreecommitdiff
path: root/Documentation/btrfstune.8
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfstune.8')
-rw-r--r--Documentation/btrfstune.8104
1 files changed, 68 insertions, 36 deletions
diff --git a/Documentation/btrfstune.8 b/Documentation/btrfstune.8
index b83d9e9d..77351c0a 100644
--- a/Documentation/btrfstune.8
+++ b/Documentation/btrfstune.8
@@ -2,12 +2,12 @@
.\" Title: btrfstune
.\" 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
+.\" Date: 01/23/2019
.\" Manual: Btrfs Manual
-.\" Source: Btrfs v4.19.1
+.\" Source: Btrfs v4.20.1
.\" Language: English
.\"
-.TH "BTRFSTUNE" "8" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual"
+.TH "BTRFSTUNE" "8" "01/23/2019" "Btrfs v4\&.20\&.1" "Btrfs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -41,30 +41,34 @@ The common usecase is to enable features that were not enabled at mkfs time\&. P
Some of the features could be also enabled on a mounted filesystem by other means\&. Please refer to the \fIFILESYSTEM FEATURES\fR in \fBbtrfs\fR(5)\&.
.SH "OPTIONS"
.PP
-\-S \fI<0|1>\fR
+\-f
.RS 4
-Enable seeding on a given device\&. Value 1 will enable seeding, 0 will disable it\&.
-
-A seeding filesystem is forced to be mounted read\-only\&. A new device can be added to the filesystem and will capture all writes keeping the seeding device intact\&.
+Allow dangerous changes, e\&.g\&. clear the seeding flag or change fsid\&. Make sure that you are aware of the dangers\&.
.RE
.PP
-\-r
+\-m
.RS 4
-(since kernel: 3\&.7)
+(since kernel: 5\&.0)
.sp
-Enable extended inode refs (hardlink limit per file in a directory is 65536), enabled by mkfs feature
-\fIextref\fR\&.
+change fsid stored as
+\fImetadata_uuid\fR
+to a randomly generated UUID, see also
+\fI\-U\fR
.RE
.PP
-\-x
+\-M \fI<UUID>\fR
.RS 4
-(since kernel: 3\&.10)
+(since kernel: 5\&.0)
.sp
-Enable skinny metadata extent refs (more efficient representation of extents), enabled by mkfs feature
-\fIskinny\-metadata\fR\&.
+change fsid stored as
+\fImetadata_uuid\fR
+to a given UUID, see also
+\fI\-U\fR
.sp
-All newly created extents will use the new representation\&. To completely switch the entire filesystem, run a full balance of the metadata\&. Please refer to
-\fBbtrfs\-balance\fR(8)\&.
+The metadata_uuid is stored only in the superblock and is a backward incompatible change\&. The fsid in metadata blocks remains unchanged and is not overwritten, thus the whole operation is significantly faster than
+\fI\-U\fR\&.
+.sp
+The new metadata_uuid can be used for mount by UUID and is also used to identify devices of a multi\-device filesystem\&.
.RE
.PP
\-n
@@ -75,9 +79,37 @@ Enable no\-holes feature (more efficient representation of file holes), enabled
\fIno\-holes\fR\&.
.RE
.PP
-\-f
+\-r
.RS 4
-Allow dangerous changes, e\&.g\&. clear the seeding flag or change fsid\&. Make sure that you are aware of the dangers\&.
+(since kernel: 3\&.7)
+.sp
+Enable extended inode refs (hardlink limit per file in a directory is 65536), enabled by mkfs feature
+\fIextref\fR\&.
+.RE
+.PP
+\-S \fI<0|1>\fR
+.RS 4
+Enable seeding on a given device\&. Value 1 will enable seeding, 0 will disable it\&.
+
+A seeding filesystem is forced to be mounted read\-only\&. A new device can be added to the filesystem and will capture all writes keeping the seeding device intact\&.
+.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
+Clearing the seeding flag on a device may be dangerous\&. If a previously\-seeding device is changed, all filesystems that used that device will become unmountable\&. Setting the seeding flag back will not fix that\&.
+
+A valid usecase is
+\fIseeding device as a base image\fR\&. Clear the seeding flag, update the filesystem and make it seeding again, provided that it\(cqs OK to throw away all filesystems built on top of the previous base\&.
+.sp .5v
+.RE
.RE
.PP
\-u
@@ -88,7 +120,8 @@ Change fsid to a randomly generated UUID or continue previous fsid change operat
\-U \fI<UUID>\fR
.RS 4
Change fsid to
-\fIUUID\fR\&.
+\fIUUID\fR
+in all metadata blocks\&.
.sp
The
\fIUUID\fR
@@ -98,7 +131,9 @@ should be a 36 bytes string in
\fIUUID\fR
matches the unfinished one or if you use the option
\fI\-u\fR\&.
-.RE
+.sp
+All metadata blocks are rewritten, this may take some time, but the final filesystem compatibility is unaffected, unlike
+\fI\-M\fR\&.
.if n \{\
.sp
.\}
@@ -111,25 +146,22 @@ matches the unfinished one or if you use the option
\fBWarning\fR
.ps -1
.br
-.sp
-Cancelling or interrupting a UUID change operation will make the filesystem temporarily unmountable\&. To fix it, rerun \fIbtrfstune \-u\fR to restore the UUID and let it complete\&.
+Cancelling or interrupting a UUID change operation will make the filesystem temporarily unmountable\&. To fix it, rerun
+\fIbtrfstune \-u\fR
+and let it complete\&.
.sp .5v
.RE
-.if n \{\
-.sp
-.\}
+.RE
+.PP
+\-x
.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
+(since kernel: 3\&.10)
.sp
-Clearing the seeding flag on a device may be dangerous\&. If a previously\-seeding device is changed, all filesystems that used that device will become unmountable\&. Setting the seeding flag back will not fix that\&. A valid usecase is \fIseeding device as a base image\fR\&. Clear the seeding flag, update the filesystem and make it seeding again, provided that it\(cqs OK to throw away all filesystems built on top of the previous base\&.
-.sp .5v
+Enable skinny metadata extent refs (more efficient representation of extents), enabled by mkfs feature
+\fIskinny\-metadata\fR\&.
+.sp
+All newly created extents will use the new representation\&. To completely switch the entire filesystem, run a full balance of the metadata\&. Please refer to
+\fBbtrfs\-balance\fR(8)\&.
.RE
.SH "EXIT STATUS"
.sp