1 files changed, 142 insertions, 0 deletions
diff --git a/Documentation/btrfstune.8 b/Documentation/btrfstune.8
new file mode 100644
index 00000000..b83d9e9d
--- /dev/null
+++ b/Documentation/btrfstune.8
@@ -0,0 +1,142 @@
+'\" t
+.\"     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
+.\"    Manual: Btrfs Manual
+.\"    Source: Btrfs v4.19.1
+.\"  Language: English
+.\"
+.TH "BTRFSTUNE" "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"
+btrfstune \- tune various filesystem parameters
+.SH "SYNOPSIS"
+.sp
+\fBbtrfstune\fR [options] \fI<device>\fR [\fI<device>\fR\&...]
+.SH "DESCRIPTION"
+.sp
+\fBbtrfstune\fR can be used to enable, disable, or set various filesystem parameters\&. The filesystem must be unmounted\&.
+.sp
+The common usecase is to enable features that were not enabled at mkfs time\&. Please make sure that you have kernel support for the features\&. You can find a complete list of features and kernel version of their introduction at \m[blue]\fBhttps://btrfs\&.wiki\&.kernel\&.org/index\&.php/Changelog#By_feature\fR\m[] \&. Also, the manual page \fBmkfs\&.btrfs\fR(8) contains more details about the features\&.
+.sp
+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
+.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\&.
+.RE
+.PP
+\-r
+.RS 4
+(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
+\-x
+.RS 4
+(since kernel: 3\&.10)
+.sp
+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
+.PP
+\-n
+.RS 4
+(since kernel: 3\&.14)
+.sp
+Enable no\-holes feature (more efficient representation of file holes), enabled by mkfs feature
+\fIno\-holes\fR\&.
+.RE
+.PP
+\-f
+.RS 4
+Allow dangerous changes, e\&.g\&. clear the seeding flag or change fsid\&. Make sure that you are aware of the dangers\&.
+.RE
+.PP
+\-u
+.RS 4
+Change fsid to a randomly generated UUID or continue previous fsid change operation in case it was interrupted\&.
+.RE
+.PP
+\-U \fI<UUID>\fR
+.RS 4
+Change fsid to
+\fIUUID\fR\&.
+.sp
+The
+\fIUUID\fR
+should be a 36 bytes string in
+\fBprintf\fR(3) format
+\fI"%08x\-%04x\-%04x\-%04x\-%012x"\fR\&. If there is a previous unfinished fsid change, it will continue only if the
+\fIUUID\fR
+matches the unfinished one or if you use the option
+\fI\-u\fR\&.
+.RE
+.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
+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\&.
+.sp .5v
+.RE
+.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
+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
+.SH "EXIT STATUS"
+.sp
+\fBbtrfstune\fR returns 0 if no error happened, 1 otherwise\&.
+.SH "COMPATIBILITY NOTE"
+.sp
+This deprecated tool exists for historical reasons but is still in use today\&. Its functionality will be merged to the main tool, at which time \fBbtrfstune\fR will be declared obsolete and scheduled for removal\&.
+.SH "SEE ALSO"
+.sp
+\fBbtrfs\fR(5), \fBbtrfs\-balance\fR(8), \fBmkfs\&.btrfs\fR(8)