NAME

       btrfstune - tune various filesystem parameters

SYNOPSIS

       btrfstune [options] <device> [<device>...]

DESCRIPTION

       btrfstune  can  be  used  to  enable,  disable,  or set various filesystem parameters. The
       filesystem must be unmounted.

       The common use case 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 Feature by version page.   Also,  the
       manual page mkfs.btrfs(8) contains more details about the features.

       Some of the features could be also enabled on a mounted filesystem by other means.  Please
       refer to the FILESYSTEM FEATURES in btrfs(5).

OPTIONS

       --convert-to-block-group-tree
              (since kernel 6.1)

              Convert portions of extent tree that tracks block groups to a separate block  group
              tree. This greatly reduces mount time. Can be also enabled at mkfs time.

       --convert-from-block-group-tree
              (since kernel 6.1)

              Convert block groups tracked in standalone block group tree back to extent tree and
              remove block-group-tree feature bit from the filesystem.

       --convert-to-free-space-tree
              (since kernel 4.5)

              Convert to free-space-tree feature (v2 of space cache).

       -f     Allow dangerous changes, e.g. clear the seeding flag or  change  fsid.   Make  sure
              that you are aware of the dangers.

       -m     (since kernel: 5.0)

              change fsid stored as metadata_uuid to a randomly generated UUID, see also -U

       -M <UUID>
              (since kernel: 5.0)

              change fsid stored as metadata_uuid to a given UUID, see also -U

              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 -U.

              The  new  metadata_uuid  can be used for mount by UUID and is also used to identify
              devices of a multi-device filesystem.

       -n     (since kernel: 3.14)

              Enable no-holes feature (more efficient representation of file holes),  enabled  by
              mkfs feature no-holes.

       -r     (since kernel: 3.7)

              Enable  extended  inode  refs  (hardlink  limit  per file in a directory is 65536),
              enabled by mkfs feature extref.

       -S <0|1>
              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.
              See also section SEEDING DEVICE in btrfs(5).

              WARNING:
                 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  seeding  device  as a base image. Clear the seeding flag,
                 update the filesystem and make it seeding again, provided that it's OK to  throw
                 away all filesystems built on top of the previous base.

       -u     Change fsid to a randomly generated UUID or continue previous fsid change operation
              in case it was interrupted.

       -U <UUID>
              Change fsid to UUID in all metadata blocks.

              The UUID should be a 36 bytes string in printf(3) format %08x-%04x-%04x-%04x-%012x.
              If  there  is  a previous unfinished fsid change, it will continue only if the UUID
              matches the unfinished one or if you use the option -u.

              All metadata blocks  are  rewritten,  this  may  take  some  time,  but  the  final
              filesystem compatibility is unaffected, unlike -M.

              WARNING:
                 Cancelling  or  interrupting  a  UUID  change operation will make the filesystem
                 temporarily unmountable.  To fix it, rerun btrfstune -u and let it complete.

       -x     (since kernel: 3.10)

              Enable skinny metadata extent refs  (more  efficient  representation  of  extents),
              enabled by mkfs feature skinny-metadata.

              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
              btrfs-balance(8).

EXIT STATUS

       btrfstune returns 0 if no error happened, 1 otherwise.

COMPATIBILITY NOTE

       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 btrfstune  will  be  declared
       obsolete and scheduled for removal.

SEE ALSO

       btrfs(5), btrfs-balance(8), mkfs.btrfs(8)