summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/btrfs-balance.asciidoc153
-rw-r--r--Documentation/btrfs-convert.asciidoc33
-rw-r--r--Documentation/btrfs-filesystem.asciidoc23
-rw-r--r--Documentation/btrfs-man5.asciidoc34
-rw-r--r--Documentation/btrfs-scrub.asciidoc32
-rw-r--r--Documentation/btrfs-send.asciidoc1
-rw-r--r--Documentation/btrfs-subvolume.asciidoc47
-rw-r--r--Documentation/btrfs.asciidoc31
8 files changed, 299 insertions, 55 deletions
diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc
index 7df40b9c..c456898e 100644
--- a/Documentation/btrfs-balance.asciidoc
+++ b/Documentation/btrfs-balance.asciidoc
@@ -51,17 +51,32 @@ NOTE: A short syntax *btrfs balance <path>* works due to backward compatibility
but is deprecated and should not be used anymore. Use *btrfs balance start*
command instead.
+PERFORMANCE IMPLICATIONS
+------------------------
+
+Balance operation is intense namely in the IO respect, but can be also CPU
+intense. It affects other actions on the filesystem. There are typically lots
+of data being copied from one location to another, and lots of metadata get
+updated.
+
+Depending on the actual block group layout, it can be also seek-heavy. The
+performance on rotational devices is noticeably worse than on SSDs or fast
+arrays.
+
SUBCOMMAND
----------
*cancel* <path>::
-cancel running or paused balance
+cancel running or paused balance, the command will block and wait until the
+actually processed blockgroup is finished
*pause* <path>::
pause running balance operation, this will store the state of the balance
progress and used filters to the filesystem
*resume* <path>::
-resume interrupted balance
+resume interrupted balance, the balance status must be stored on the filesystem
+from previous run, eg. after it was forcibly interrupted and mounted again with
+'skip_balance'
*start* [options] <path>::
start the balance operation according to the specified filters, no filters
@@ -73,6 +88,10 @@ filesystem size. To prevent starting a full balance by accident, the user is
warned and has a few seconds to cancel the operation before it starts. The
warning and delay can be skipped with '--full-balance' option.
+
+Please note that the filters must be written together with the '-d', '-m' and
+'-s' options, because they're optional and bare '-d' etc alwo work and mean no
+filters.
++
`Options`
+
-d[<filters>]::::
@@ -85,6 +104,9 @@ act on system chunks (requires '-f'), see `FILTERS` section for details about 'f
be verbose and print balance filter arguments
-f::::
force reducing of metadata integrity, eg. when going from 'raid1' to 'single'
+--background|--bg::::
+run the balance operation asynchronously in the background, uses `fork`(2) to
+start the process that calls the kernel ioctl
*status* [-v] <path>::
Show status of running or paused balance.
@@ -94,7 +116,7 @@ If '-v' option is given, output will be verbose.
FILTERS
-------
From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the
-full filesystem, and can be used to change the replication configuration (e.g.
+whole filesystem, and can be used to change the replication configuration (e.g.
moving data from single to RAID1). This functionality is accessed through the
'-d', '-m' or '-s' options to btrfs balance start, which filter on data,
metadata and system blocks respectively.
@@ -140,6 +162,9 @@ parameters.
+
NOTE: starting with kernel 4.5, the 'data' chunks can be converted to/from the
'DUP' profile on a single device.
++
+NOTE: starting with kernel 4.6, all profiles can be converted to/from 'DUP' on
+multi-device filesystems.
*limit=<number>*::
*limit=<range>*::
@@ -206,6 +231,128 @@ Conversion to profiles based on striping (RAID0, RAID5/6) require the work
space on each device. An interrupted balance may leave partially filled block
groups that might consume the work space.
+EXAMPLES
+--------
+
+A more comprehensive example when going from one to multiple devices, and back,
+can be found in section 'TYPICAL USECASES' of `btrfs-device`(8).
+
+MAKING BLOCK GROUP LAYOUT MORE COMPACT
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The layout of block groups is not normally visible, most tools report only
+summarized numbers of free or used space, but there are still some hints
+provided.
+
+Let's use the following real life example and start with the output:
+
+--------------------
+$ btrfs fi df /path
+Data, single: total=75.81GiB, used=64.44GiB
+System, RAID1: total=32.00MiB, used=20.00KiB
+Metadata, RAID1: total=15.87GiB, used=8.84GiB
+GlobalReserve, single: total=512.00MiB, used=0.00B
+--------------------
+
+Roughly calculating for data, '75G - 64G = 11G', the used/total ratio is
+about '85%'. How can we can interpret that:
+
+* chunks are filled by 85% on average, ie. the 'usage' filter with anything
+ smaller than 85 will likely not affect anything
+* in a more realistic scenario, the space is distributed unevenly, we can
+ assume there are completely used chunks and the remaining are partially filled
+
+Compacting the layout could be used on both. In the former case it would spread
+data of a given chunk to the others and removing it. Here we can estimate that
+roughly 850 MiB of data have to be moved (85% of a 1 GiB chunk).
+
+In the latter case, targeting the partially used chunks will have to move less
+data and thus will be faster. A typical filter command would look like:
+
+--------------------
+# btrfs balance start -dusage=50 /path
+Done, had to relocate 2 out of 97 chunks
+
+$ btrfs fi df /path
+Data, single: total=74.03GiB, used=64.43GiB
+System, RAID1: total=32.00MiB, used=20.00KiB
+Metadata, RAID1: total=15.87GiB, used=8.84GiB
+GlobalReserve, single: total=512.00MiB, used=0.00B
+--------------------
+
+As you can see, the 'total' amount of data is decreased by just 1 GiB, which is
+an expected result. Let's see what will happen when we increase the estimated
+usage filter.
+
+--------------------
+# btrfs balance start -dusage=85 /path
+Done, had to relocate 13 out of 95 chunks
+
+$ btrfs fi df /path
+Data, single: total=68.03GiB, used=64.43GiB
+System, RAID1: total=32.00MiB, used=20.00KiB
+Metadata, RAID1: total=15.87GiB, used=8.85GiB
+GlobalReserve, single: total=512.00MiB, used=0.00B
+--------------------
+
+Now the used/total ratio is about 94% and we moved about '74G - 68G = 6G' of
+data to the remaining blockgroups, ie. the 6GiB are now free of filesystem
+structures, and can be reused for new data or metadata block groups.
+
+We can do a similar exercise with the metadata block groups, but this should
+not be typically necessary, unless the used/total ration is really off. Here
+the ratio is roughly 50% but the difference as an absolute number is "a few
+gigabytes", which can be considered normal for a workload with snapshots or
+reflinks updated frequently.
+
+--------------------
+# btrfs balance start -musage=50 /path
+Done, had to relocate 4 out of 89 chunks
+
+$ btrfs fi df /path
+Data, single: total=68.03GiB, used=64.43GiB
+System, RAID1: total=32.00MiB, used=20.00KiB
+Metadata, RAID1: total=14.87GiB, used=8.85GiB
+GlobalReserve, single: total=512.00MiB, used=0.00B
+--------------------
+
+Just 1 GiB decrease, which possibly means there are block groups with good
+utilization. Making the metadata layout more compact would in turn require
+updating more metadata structures, ie. lots of IO. As running out of metadata
+space is a more severe problem, it's not necessary to keep the utilization
+ratio too high. For the purpose of this example, let's see the effects of
+further compaction:
+
+--------------------
+# btrfs balance start -musage=70 /path
+Done, had to relocate 13 out of 88 chunks
+
+$ btrfs fi df .
+Data, single: total=68.03GiB, used=64.43GiB
+System, RAID1: total=32.00MiB, used=20.00KiB
+Metadata, RAID1: total=11.97GiB, used=8.83GiB
+GlobalReserve, single: total=512.00MiB, used=0.00B
+--------------------
+
+GETTING RID OF COMPLETELY UNUSED BLOCK GROUPS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Normally the balance operation needs a work space, to temporarily move the
+data before the old block groups gets removed. If there's no work space, it
+ends with 'no space left'.
+
+There's a special case when the block groups are completely unused, possibly
+left after removing lots of files or deleting snapshots. Removing empty block
+groups is automatic since 3.18. The same can be achieved manually with a
+notable exception that this operation does not require the work space. Thus it
+can be used to reclaim unused block groups to make it available.
+
+--------------------
+# btrfs balance start -dusage=0 /path
+--------------------
+
+This should lead to decrease in the 'total' numbers in the *btrfs fi df* output.
+
EXIT STATUS
-----------
*btrfs balance* returns a zero exit status if it succeeds. Non zero is
diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc
index ab3577db..ecc157cd 100644
--- a/Documentation/btrfs-convert.asciidoc
+++ b/Documentation/btrfs-convert.asciidoc
@@ -3,7 +3,7 @@ btrfs-convert(8)
NAME
----
-btrfs-convert - convert from ext2/3/4 filesystem to btrfs
+btrfs-convert - convert from ext2/3/4 filesystem to btrfs in-place
SYNOPSIS
--------
@@ -28,6 +28,11 @@ steps to transform the btrfs filesystem to a more compact layout. The
conversion inherits the original data block fragmentation and the metadata
blocks are bound to the original free space layout.
+Due to different constraints, it's possible to convert only filesystem that
+have supported data block size (ie. the same that would be valid for
+'mkfs.btrfs'). This is typically the system page size (4KiB on x86_64
+machines).
+
**REMOVE THE ORIGINAL FILESYSTEM METADATA**
By removing the 'ext2_saved' subvolume, all metadata of the original filesystem
@@ -36,7 +41,7 @@ will be removed:
# btrfs subvolume delete /mnt/ext2_saved
At this point it's not possible to do rollback. The filesystem is usable but may
-be impacted by the fragmentation.
+be impacted by the fragmentation inherited from the original filesystem.
**MAKE FILE DATA MORE CONTIGUOUS**
@@ -45,8 +50,8 @@ filesystem. This will attempt to make file extents more contiguous.
# btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs
-Verbose recursive defragmentation ('-v', '-r'), flush data per-file ('-f') with target
-extent size 32M ('-t').
+Verbose recursive defragmentation ('-v', '-r'), flush data per-file ('-f') with
+target extent size 32MiB ('-t').
**ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT**
@@ -54,18 +59,19 @@ Optional but recommended step.
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. This is
-a soft error leaving the filesystem usable but the block group layout may
-remain unchanged.
+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.
-Note that balance operation takes a lot of time.
+Note that balance operation takes a lot of time, please see also
+`btrfs-balance`(8).
# btrfs balance start -m /mnt/btrfs
OPTIONS
-------
-d|--no-datasum::
-disable data checksum calculations and set NODATASUM file flag, this can speed
+disable data checksum calculations and set the NODATASUM file flag, this can speed
up the conversion
-i|--no-xattr::
ignore xattrs and ACLs of files
@@ -84,17 +90,20 @@ set filesystem label during conversion
-L|--copy-label::
use label from the converted filesystem
-O|--features <feature1>[,<feature2>...]::
-A list of filesystem features turned on at btrfs-convert time. Not all features
+A list of filesystem features turned on at conversion time. Not all features
are supported by old kernels. To disable a feature, prefix it with '^'.
+Description of the features is in section 'FILESYSTEM FEATURES' of
+`mkfs.btrfs`(8).
+
To see all available features that btrfs-convert supports run:
+
+btrfs-convert -O list-all+
+
-p|--progress::
-show progress of conversion, on by default
+show progress of conversion (a heartbeat indicator and number of inodes
+processed), on by default
--no-progress::
-disable detailed progress and show only the main phases of conversion
+disable progress and show only the main phases of conversion
EXIT STATUS
-----------
diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc
index dc032faa..9782af9b 100644
--- a/Documentation/btrfs-filesystem.asciidoc
+++ b/Documentation/btrfs-filesystem.asciidoc
@@ -11,9 +11,10 @@ SYNOPSIS
DESCRIPTION
-----------
-*btrfs filesystem* is used to do the whole filesystem level tasks, including
-all the regular filesystem operations like resizing, space stats, label
-setting/getting, and defragmentation.
+*btrfs filesystem* is used to perform several whole filesystem level tasks,
+including all the regular filesystem operations like resizing, space stats,
+label setting/getting, and defragmentation. There are other whole filesystem
+taks like scrub or balance that are grouped in separate commands.
SUBCOMMAND
----------
@@ -116,15 +117,23 @@ compression. See also section 'EXAMPLES'.
-r::::
defragment files recursively in given directories
-f::::
-flush data for each file before going to the next file. This will limit the amount
-of dirty data to current file, otherwise the amount cumulates from several files
-and may increase system load.
+flush data for each file before going to the next file.
++
+This will limit the amount of dirty data to current file, otherwise the amount
+cumulates from several files and will increase system load. This can also lead
+to ENOSPC if there's too much dirty data to write and it's not possible to make
+the reservations for the new data (ie. how the COW design works).
++
-s <start>[kKmMgGtTpPeE]::::
defragmentation will start from the given offset, default is beginning of a file
-l <len>[kKmMgGtTpPeE]::::
defragment only up to 'len' bytes, default is the file size
-t <size>[kKmMgGtTpPeE]::::
-target extent size, do not touch extents bigger than 'size'
+target extent size, do not touch extents bigger than 'size', default: 32M
++
+The value is only advisory and the final size of the extents may differ,
+depending on the state of the free space and fragmentation or other internal
+logic. Reasonable values are from tens to hundreds of megabytes.
*du* [options] <path> [<path>..]::
Calculate disk usage of the target files using FIEMAP. For individual
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index 7dd323fa..467f11bf 100644
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -14,6 +14,8 @@ tools. Currently covers:
2. file attributes
+3. control device
+
MOUNT OPTIONS
-------------
@@ -455,11 +457,43 @@ When set on a directory, all newly created files will inherit this attribute.
No other attributes are supported. For the complete list please refer to the
`chattr`(1) manual page.
+CONTROL DEVICE
+--------------
+
+There's a character special device `/dev/btrfs-control` with major and minor
+numbers 10 and 234 (the device can be found under the 'misc' category).
+
+--------------------
+$ ls -l /dev/btrfs-control
+crw------- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs-control
+--------------------
+
+The device accepts some ioctl calls that can perform following actions on the
+filesyste module:
+
+* scan devices for btrfs filesytem (ie. to let multi-device filesystems mount
+ automatically) and register them with the kernel module
+* similar to scan, but also wait until the device scanning process is finished
+ for a given filesystem
+* get the supported features (can be also found under '/sys/fs/btrfs/features')
+
+
+The device is usually created by ..., but can be created manually:
+
+--------------------
+# mknod --mode=600 c 10 234 /dev/btrfs-control
+--------------------
+
+The device is not strictly required but the device scanning will not work and a
+workaround would need to be used to mount a multi-device filesystem. The mount
+option 'device' can trigger the device scanning during mount.
+
SEE ALSO
--------
`acl`(5),
`btrfs`(8),
`chattr`(1),
`fstrim`(8),
+`ioctl`(2),
`mkfs.btrfs`(8),
`mount`(8)
diff --git a/Documentation/btrfs-scrub.asciidoc b/Documentation/btrfs-scrub.asciidoc
index 83ddcaa7..40e793c2 100644
--- a/Documentation/btrfs-scrub.asciidoc
+++ b/Documentation/btrfs-scrub.asciidoc
@@ -12,16 +12,30 @@ SYNOPSIS
DESCRIPTION
-----------
*btrfs scrub* is used to scrub a btrfs filesystem, which will read all data
-and metadata blocks from all disks and verify checksums. Automatically repair
+and metadata blocks from all devices and verify checksums. Automatically repair
corrupted blocks if there's a correct copy available.
+NOTE: Scrub is not a filesystem checker (fsck) and does not verify nor repair
+structural damage in the filesystem.
+
+The user is supposed to run it manually or via a periodic system service. The
+recommended period is a month but could be less. The estimated device bandwidth
+utilization is about 80% on an idle filesytem. The IO priority class is by
+default 'idle' so background scrub should not interfere with normal filesystem
+operation significantly.
+
+The scrubbing status is recorded in '/var/lib/btrfs/' in textual files named
+'scrub.status.UUID' for a filesystem identified by the given UUID. (An
+itermediate progress is communicated through a named pipe in file
+'scrub.progress.UUID' in the same directory.) The status file is updated
+periodically every 5 seconds. An resumed scrub will continue from the last
+saved position.
+
SUBCOMMAND
----------
*cancel* <path>|<device>::
If a scrub is running on the filesystem identified by 'path>' cancel it.
+
-Progress is saved in the scrub progress file ('/var/lib/btrfs/scrub.status.UUID')
-and scrubbing can be resumed later using the *btrfs scrub resume* command.
If a 'device' is specified, the corresponding filesystem is found and
*btrfs scrub cancel* behaves as if it was called on that filesystem.
@@ -40,9 +54,6 @@ Start a scrub on all devices of the filesystem identified by 'path' or on
a single 'device'. If a scrub is already running, the new one fails.
+
Without options, scrub is started as a background process.
-Progress can be obtained with the *btrfs scrub status* command. Scrubbing
-involves reading all data from all disks and verifying checksums. Errors are
-corrected along the way if possible.
+
The default IO priority of scrub is the idle class. The priority can be
configured similar to the `ionice`(1) syntax using '-c' and '-n' options.
@@ -52,11 +63,11 @@ configured similar to the `ionice`(1) syntax using '-c' and '-n' options.
-B::::
do not background and print scrub statistics when finished
-d::::
-print separate statistics for each device of the filesystem ('-B' only)
+print separate statistics for each device of the filesystem ('-B' only) at the end
-q::::
be quiet, omit error messages and statistics
-r::::
-read only mode, do not attempt to correct anything, can be run on a read-only
+run in read-only mode, do not attempt to correct anything, can be run on a read-only
filesystem
-R::::
print raw statistics per-device instead of a summary
@@ -66,8 +77,8 @@ set IO priority class (see `ionice`(1) manpage)
set IO priority classdata (see `ionice`(1) manpage)
-f::::
force starting new scrub even if a scrub is already running,
-this is useful when scrub status file is damaged and reports a running
-scrub although it is not
+this can useful when scrub status file is damaged and reports a running
+scrub although it is not, but should not normally be necessary
*status* [-d] <path>|<device>::
Show status of a running scrub for the filesystem identified by 'path' or
@@ -95,3 +106,4 @@ further details.
SEE ALSO
--------
`mkfs.btrfs`(8),
+`ionice`(1)
diff --git a/Documentation/btrfs-send.asciidoc b/Documentation/btrfs-send.asciidoc
index 47b0b047..96659eed 100644
--- a/Documentation/btrfs-send.asciidoc
+++ b/Documentation/btrfs-send.asciidoc
@@ -53,6 +53,7 @@ send in 'NO_FILE_DATA' mode
The output stream does not contain any file
data and thus cannot be used to transfer changes. This mode is faster and
useful to show the differences in metadata.
+
-v|--verbose::
enable verbose output, print generated commands in a readable form, (each
occurrence of this option increases the verbosity level)
diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc
index fb64aa4a..2044b07d 100644
--- a/Documentation/btrfs-subvolume.asciidoc
+++ b/Documentation/btrfs-subvolume.asciidoc
@@ -3,7 +3,7 @@ btrfs-subvolume(8)
NAME
----
-btrfs-subvolume - control btrfs subvolume(s)
+btrfs-subvolume - manage btrfs subvolumes
SYNOPSIS
--------
@@ -11,35 +11,39 @@ SYNOPSIS
DESCRIPTION
-----------
-*btrfs subvolume* is used to control the filesystem to create/delete/list/show
-subvolumes and snapshots.
+*btrfs subvolume* is used to create/delete/list/show btrfs subvolumes and
+snapshots.
SUBVOLUME AND SNAPSHOT
----------------------
-A subvolume in btrfs is not like an LVM logical volume, which is quite
-independent from each other, a btrfs subvolume has its hierarchy and relations
-between other subvolumes.
-A subvolume in btrfs can be accessed in two ways.
+A subvolume is a part of filesystem with it's own and independent
+file/directory hierarchy. Subvolumes can share file extents. A snapshot is
+also subvolume, but with a given initial content of the original subvolume.
-1. From the parent subvolume +
-When accessing from the parent subvolume, the subvolume can be used just
-like a directory. It can have child subvolumes and its own files/directories.
+NOTE: A subvolume in btrfs is not like an LVM logical volume, which is
+block-level snapshot while btrfs subvolumes are file extent-based.
-2. Separate mounted filesystem +
-When `mount`(8) using 'subvol' or 'subvolid' mount option, one can access
-files/directories/subvolumes inside it, but nothing in parent subvolumes.
+A subvolume looks like a normal directory, with some additional operations
+described below. Subvolumes can be renamed or moved, nesting subvolumes is not
+restricted but has some implications regarding snapshotting.
-Also every btrfs filesystem has a default subvolume as its initially top-level
-subvolume, whose subvolume id is 5. (0 is also acceptable as an alias.)
+A subvolume in btrfs can be accessed in two ways:
-A btrfs snapshot is much like a subvolume, but shares its data(and metadata)
-with other subvolume/snapshot. Due to the capabilities of COW, modifications
-inside a snapshot will only show in a snapshot but not in its source subvolume.
+* like any other directory that is accessible to the user
+* like a separately mounted filesystem (options 'subvol' or 'subvolid')
-Although in btrfs, subvolumes/snapshots are treated as directories, only
-subvolume/snapshot can be the source of a snapshot, snapshot can not be made
-from normal directories.
+In the latter case the parent directory is not visible and accessible. This is
+similar to a bind mount, and in fact the subvolume mount does exactly that.
+
+A freshly created filesystem is also a subvolume, called 'top-level',
+internally has an id 5. This subvolume cannot be removed or replaced by another
+subvolume. This is also the subvolume that will be mounted by default, unless
+the default subvolume has been changed (see subcommand 'set-default').
+
+A snapshot is a subvolume like any other, with given initial content. By
+default, snapshots are created read-write. File modifications in a snapshot
+do not affect the files in the original subvolume.
SUBCOMMAND
-----------
@@ -178,5 +182,6 @@ further details.
SEE ALSO
--------
`mkfs.btrfs`(8),
+`mount`(8),
`btrfs-quota`(8),
`btrfs-qgroup`(8),
diff --git a/Documentation/btrfs.asciidoc b/Documentation/btrfs.asciidoc
index 6a77a852..1c37abf8 100644
--- a/Documentation/btrfs.asciidoc
+++ b/Documentation/btrfs.asciidoc
@@ -3,7 +3,7 @@ btrfs(8)
NAME
----
-btrfs - control a btrfs filesystem
+btrfs - a toolbox to manage btrfs filesystems
SYNOPSIS
--------
@@ -15,6 +15,10 @@ The *btrfs* utility is a toolbox for managing btrfs filesystems. There are
command groups to work with subvolumes, devices, for whole filesystem or other
specific actions. See section *COMMANDS*.
+There are also standalone tools for some tasks like *btrfs-convert* or
+*btrfstune* that were separate historically and/or haven't been merged to the
+main utility. See section 'STANDALONE TOOLS' for more details.
+
COMMAND SYNTAX
--------------
@@ -96,6 +100,27 @@ COMMANDS
Create/delete/list/manage btrfs subvolume. +
See `btrfs-subvolume`(8) for details.
+STANDALONE TOOLS
+----------------
+
+There are several standalone tools to provide certain functionality. If the
+functionality proves to be useful, the standalone tools are declared obsolete
+and their functionality copied to the main tool. The deprecation period is long
+(years) and the obsolete binaries are still provided.
+
+Tools that are still in active use without an equivalent in *btrfs*:
+
+*btrfs-convert*:: in-place conversion from ext2/3/4 filesystems to btrfs
+*btrfstune*:: tweak some filesystem properties on a unmounted filesystem
+*btrfs-select-super*:: rescue tool to overwrite primary superblock from a spare copy
+*btrfs-find-root*:: rescue helper to find tree roots in a filesystem
+
+Deprecated and obsolete tools:
+
+*btrfs-debug-tree*:: moved to *btrfs inspect-internal dump-tree*
+*btrfs-show-super*:: moved to *btrfs inspect-internal dump-super*
+*btrfs-zero-log*:: moved to *btrfs rescue zero-log*
+
EXIT STATUS
-----------
*btrfs* returns a zero exit status if it succeeds. Non zero is returned in
@@ -109,9 +134,9 @@ further details.
SEE ALSO
--------
-`mkfs.btrfs`(8), `ionice`(1),
`btrfs-balance`(8),
`btrfs-check`(8),
+`btrfs-convert`(8),
`btrfs-device`(8),
`btrfs-filesystem`(8),
`btrfs-inspect-internal`(8),
@@ -125,3 +150,5 @@ SEE ALSO
`btrfs-scrub`(8),
`btrfs-send`(8),
`btrfs-subvolume`(8),
+`btrfstune`(8),
+`mkfs.btrfs`(8)