'\" 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: 02/05/2021
.\"    Manual: Btrfs Manual
.\"    Source: Btrfs v5.10.1
.\"  Language: English
.\"
.TH "BTRFSTUNE" "8" "02/05/2021" "Btrfs v5\&.10\&.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
\-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
\-m
.RS 4
(since kernel: 5\&.0)
.sp
change fsid stored as
\fImetadata_uuid\fR
to a randomly generated UUID, see also
\fI\-U\fR
.RE
.PP
\-M \fI<UUID>\fR
.RS 4
(since kernel: 5\&.0)
.sp
change fsid stored as
\fImetadata_uuid\fR
to a given UUID, see also
\fI\-U\fR
.sp
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
.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
\-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
\-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
.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
in all metadata blocks\&.
.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\&.
.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
.\}
.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
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
.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
.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)