The balance operation is cancellable by the user. The on-disk state of the
filesystem is always consistent so an unexpected interruption (eg. system crash,
reboot) does not corrupt the filesystem. The progress of the balance operation
-is temporarily stored and will be resumed upon mount, unless the mount option
-'skip_balance' is specified.
+is temporarily stored as an internal state and will be resumed upon mount,
+unless the mount option 'skip_balance' is specified.
WARNING: running balance without filters will take a lot of time as it basically
rewrites the entire filesystem and needs to update all block pointers.
------
The way balance operates, it usually needs to temporarily create a new block
-group and move the old data there. For that it needs work space, otherwise
-it fails for ENOSPC reasons.
+group and move the old data there, before the old block group can be removed.
+For that it needs the work space, otherwise it fails for ENOSPC reasons.
This is not the same ENOSPC as if the free space is exhausted. This refers to
-the space on the level of block groups.
+the space on the level of block groups, which are bigger parts of the filesytem
+that contain many file extents.
The free work space can be calculated from the output of the *btrfs filesystem show*
command:
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.
+groups that consume the work space.
EXAMPLES
--------
MAKING BLOCK GROUP LAYOUT MORE COMPACT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The layout of block groups is not normally visible, most tools report only
+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.
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
+not typically be necessary, unless the used/total ratio 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.
*btrfsck* is an alias of *btrfs check* command and is now deprecated.
-WARNING: Do not use '--repair' unless you are advised to by a developer, an
-experienced user or accept the fact that 'fsck' cannot possibly fix all sorts
-of damage that could happen to a filesystem because of software and hardware
-bugs.
+WARNING: Do not use '--repair' unless you are advised to do so by a developer
+or an experienced user, and then only after having accepted that no 'fsck'
+successfully repair all types of filesystem corruption. Eg. some other software
+or hardware bugs can fatally damage a volume.
The structural integrity check verifies if internal filesystem objects or
data structures satisfy the constraints, point to the right objects or are
--check-data-csum::
verify checksums of data blocks
+
-This expects that the filesystem is otherwise
-OK, so this is basically and offline 'scrub' but does not repair data from
-spare copies.
+This expects that the filesystem is otherwise OK, and is basically and offline
+'scrub' but does not repair data from spare copies.
--chunk-root <bytenr>::
use the given offset 'bytenr' for the chunk tree root
mounted with that option. Thus, using this option with 'v1' makes it possible
to actually clear the entire free space cache.
+
-For free space cache 'v2', the 'clear_cache' kernel mount option does destroy
-the entire free space cache. This option with 'v2' provides an alternative
+For free space cache 'v2', the 'clear_cache' kernel mount option destroys
+the entire free space cache. This option, with 'v2' provides an alternative
method of clearing the free space cache that doesn't require mounting the
filesystem.
* ext2, ext3, ext4 -- original feature, always built in
-* reiserfs -- since version 4.13, opptinally built, requires libreiserfscore 3.6.27
+* reiserfs -- since version 4.13, optionally built, requires libreiserfscore 3.6.27
The list of supported source filesystem by a given binary is listed at the end
of help (option '--help').
estimate of the required space cannot be foretold. The final btrfs metadata
might occupy several gigabytes on a hundreds-gigabyte filesystem.
-If you decide not to rollback anymore, it is recommended to perform a few more
-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.
+If the ability to rollback is no longer important, the it is recommended to
+perform a few more steps to transition the btrfs filesystem to a more compact
+layout. This is because the conversion inherits the original data blocks'
+fragmentation, and also because 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
+Due to different constraints, it is only possible to convert filesystems that
+have a 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).
# 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 inherited from the original filesystem.
+At this point it is not possible to do a rollback. The filesystem is usable but
+may be impacted by the fragmentation inherited from the original filesystem.
**MAKE FILE DATA MORE CONTIGUOUS**
-L|--copy-label::
use label from the converted filesystem
-O|--features <feature1>[,<feature2>...]::
-A list of filesystem features turned on at conversion time. Not all features
+A list of filesystem features enabled the at time of conversion. 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).
Print the stats and reset the values to zero afterwards.
-c|--check::::
-Check if the stats are all zeros and return 0 it it is so. Set bit 6 of the
+Check if the stats are all zeros and return 0 it this is so. Set bit 6 of the
return code if any of the statistics is no-zero. The error values is 65 if
reading stats from at least one device failed, otherwise it's 64.
$ btrfs balance start -mconvert=raid1 /mnt
-This operation can take a while as the metadata have to be moved and all block
-pointers updated. Depending on the physical locations of the old and new
+This operation can take a while, because al metadata have to be moved and all
+block pointers updated. Depending on the physical locations of the old and new
blocks, the disk seeking is the key factor affecting performance.
You'll note that the system block group has been also converted to RAID1, this
NAME
----
-btrfs-filesystem - command group of btrfs that usually work on the whole filesystem
+btrfs-filesystem - command group othat primarily does work on the whole filesystems
SYNOPSIS
--------
when the filesystem is full. Its 'total' size is dynamic based on the
filesystem size, usually not larger than 512MiB, 'used' may fluctuate.
+
-The global block reserve is accounted within Metadata. In case the filesystem
-metadata are exhausted, 'GlobalReserve/total + Metadata/used = Metadata/total'.
+The GlobalReserve is a portion of Metadata. In case the filesystem metadata is
+exhausted, 'GlobalReserve/total + Metadata/used = Metadata/total'. Otherwise
+there appears to be some unused space of Metadata.
+
`Options`
+
+
WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as well as
with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up
-the ref-links of COW data (for example files copied with `cp --reflink`,
+the reflinks of COW data (for example files copied with `cp --reflink`,
snapshots or de-duplicated data).
This may cause considerable increase of space usage depending on the broken up
-ref-links.
+reflinks.
+
NOTE: Directory arguments without '-r' do not defragment files recursively but will
defragment certain internal trees (extent tree and the subvolume tree). This has been
Show or update the label of a filesystem. This works on a mounted filesystem or
a filesystem image.
+
-The 'newlabel' argument is optional. Current label is printed if the the argument
+The 'newlabel' argument is optional. Current label is printed if the argument
is omitted.
+
NOTE: the maximum allowable length shall be less than 256 chars and must not contain
*$ btrfs filesystem resize 1:max /path*
-Let's assume that devid 1 exists, the filesystem does not occupy the whole block
-device, eg. it has been enlarged and we wan the grow the filesystem. Simply using
-'max' as size we will achieve that.
+Let's assume that devid 1 exists and the filesystem does not occupy the whole
+block device, eg. it has been enlarged and we wan the grow the filesystem. By
+simply using 'max' as size we will achieve that.
NOTE: There are two ways to minimize the filesystem on a given device. The
*btrfs inspect-internal min-dev-size* command, or iteratively shrink in steps.
OPTIONS
-------
-a::
-Search through all the metadata extents, even the root is already found.
+Search through all metadata extents, even the root has been already found.
-g <generation>::
Filter root tree by it's original transaction id, tree root's generation in default.
-o <objectid>::
specify the device 'id' to query, default is 1 if this option is not used
*rootid* <path>::
-for a given file or directory, return the containing tree root id, for a
-subvolume itself return it's own tree id (ie. subvol id)
+for a given file or directory, return the containing tree root id, but for a
+subvolume itself return its own tree id (ie. subvol id)
+
NOTE: The result is undefined for the so-called empty subvolumes (identified by
-inode number 2), but such subvolume does not contain any files anyway
+inode number 2), but such a subvolume does not contain any files anyway
*subvolid-resolve* <subvolid> <path>::
(needs root privileges)
+
-resolve the absolute path of a the subvolume id 'subvolid'
+resolve the absolute path of the subvolume id 'subvolid'
*tree-stats* [options] <device>::
(needs root privileges)
+
WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as
well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or
-≥ 3.13.4 will break up the ref-links of CoW data (for example files
+≥ 3.13.4 will break up the reflinks of COW data (for example files
copied with `cp --reflink`, snapshots or de-duplicated data).
This may cause considerable increase of space usage depending on the
-broken up ref-links.
+broken up reflinks.
*barrier*::
*nobarrier*::
(default: on)
+
Ensure that all IO write operations make it through the device cache and are stored
-permanently when the filesystem is at it's consistency checkpoint. This
+permanently when the filesystem is at its consistency checkpoint. This
typically means that a flush command is sent to the device that will
synchronize all pending data and ordinary metadata blocks, then writes the
superblock and issues another flush.
Control BTRFS file data compression. Type may be specified as 'zlib',
'lzo', 'zstd' or 'no' (for no compression, used for remounting). If no type
is specified, 'zlib' is used. If 'compress-force' is specified,
-the compression will always be attempted, but the data may end up uncompressed
+then compression will always be attempted, but the data may end up uncompressed
if the compression would make them larger.
+
Otherwise some simple heuristics are applied to detect an incompressible file.
*nodiscard*::
(default: off)
+
-Enable discarding of freed file blocks using the TRIM operation. This is useful
-for SSD devices, thinly provisioned LUNs or virtual machine images where the
-backing device understands the operation. Depending on support of the
-underlying device, the operation may severely hurt performance in case the TRIM
-operation is synchronous (eg. with SATA devices up to revision 3.0).
-+
+Enable discarding of freed file blocks. This is useful for SSD devices, thinly
+provisioned LUNs, or virtual machine images; however, every storage layer must
+support discard for it to work. if the backing device does not support
+asynchronous queued TRIM, then this operation can severly degrade performance,
+because a synchronous TRIM operation will be attempted instead. Queued TRIM
+requires newer than SATA revision 3.1 chipsets and devices.
+
+If it is not necessary to immediately discard freed blocks, then the `fstrim`
+tool can be used to discard all free blocks in a batch. Scheduling a TRIM
+during a period of low system activity will prevent latent interference with
+the performance of other operations. Also, a device may ignore the TRIM command
+if the range is too small, so running a batch discard has a greater probability
+of actually discarding the blocks.
+
If discarding is not necessary to be done at the block freeing time, there's
`fstrim`(8) tool that lets the filesystem discard all free blocks in a batch,
possibly not much interfering with other operations. Also, the the device may
'O_DSYNC'
*X*::
-'no compression', permanently turn off compression on the given file, other
-compression mount options will not affect that
+'no compression', permanently turn off compression on the given file. Any
+compression mount options will not affect this file.
+
When set on a directory, all newly created files will inherit this attribute.
DESCRIPTION
-----------
*btrfs-map-logical* can be used to find out what the physical offsets are
-on the mirrors, the result is dumped into stdout in default.
+on the mirrors, the result is dumped to stdout by default.
Mainly used for debug purpose.
command.
WARNING: Qgroup is not stable yet and will impact performance in current mainline
-kernel (v3.14 so far).
+kernel (v4.14).
QGROUP
------
Create a subvolume quota group.
+
For the '0/<subvolume id>' qgroup, a qgroup can be created even before the
-subvolume created.
+subvolume is created.
*destroy* <qgroupid> <path>::
Destroy a qgroup.
+
-If a qgroup is no isolated,which means it is a parent or child qgroup, it
-can't be destroyed.
+If a qgroup is not isolated, meaning it is a parent or child qgroup, then it
+can only be destroyed after the relationship is removed.
*limit* [options] <size>|none [<qgroupid>] <path>::
Limit the size of a qgroup to <size> or no limit in the btrfs filesystem
of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
`btrfs qgroup`(8).
-NOTE: the qgroups are different than the traditional user quotas and designed
+NOTE: Qgroups are different than the traditional user quotas and designed
to track shared and exclusive data per-subvolume. Please refer to the section
'HIERARCHICAL QUOTA GROUP CONCEPTS' for a detailed description.
PERFORMANCE IMPLICATIONS
~~~~~~~~~~~~~~~~~~~~~~~~
-When the quotas are turned on, they affect all extent processing, taking a
-performance hit. It is not recommended to turn on qgroups unless the user
+When quotas are activated, they affect all extent processing, which takes a
+performance hit. Activation of qgroups is not recommended unless the user
intends to actually use them.
STABILITY STATUS
~~~~~~~~~~~~~~~~
The qgroup implementation has turned out to be quite difficult as it affects
-the core of the filesystem operation. The users have hit various corner cases
-over time, eg. wrong accounting or system instability. The situation is
-gradually improving but currently (4.7) there are still issues found and fixed.
+the core of the filesystem operation. Qgroup users have hit various corner cases
+over time, such as incorrect accounting or system instability. The situation is
+gradually improving and issues found and fixed.
HIERARCHICAL QUOTA GROUP CONCEPTS
---------------------------------
restrict directories.
At installation time, the harddisk can be partitioned so that every directory
(eg. /usr, /var/, ...) that needs a limit gets its own partition. The obvious
-problem is, that those limits cannot be changed without a reinstallation. The
+problem is that those limits cannot be changed without a reinstallation. The
btrfs subvolume feature builds a bridge. Subvolumes correspond in many ways to
partitions, as every subvolume looks like its own filesystem. With subvolume
quota, it is now possible to restrict each subvolume like a partition, but keep
`Replacement for partitions`
The simplest use case is to use qgroups as simple replacement for partitions.
-Btrfs takes the disk as a whole, and /, /usr, /var etc. are created as
+Btrfs takes the disk as a whole, and /, /usr, /var, etc. are created as
subvolumes. As each subvolume gets it own qgroup automatically, they can
simply be restricted. No hierarchy is needed for that.
has completed and the subvolume is set to read-only.
Additionally, receive does not currently do a very good job of validating
-that an incremental send streams actually makes sense, and it is thus
+that an incremental send stream actually makes sense, and it is thus
possible for a specially crafted send stream to create a subvolume with
reflinks to arbitrary files in the same filesystem. Because of this,
users are advised to not use *btrfs receive* on send streams from
The <targetdev> needs to be same size or larger than the <srcdev>.
+
NOTE: the filesystem has to be resized to fully take advantage of a
-larger target device, this can be achieved with
+larger target device; this can be achieved with
`btrfs filesystem resize <devid>:max /path`
+
`Options`
slow)
-f::::
force using and overwriting <targetdev> even if it looks like
-containing a valid btrfs filesystem.
+it contains a valid btrfs filesystem.
+
A valid filesystem is assumed if a btrfs superblock is found which contains a
-correct checksum. Devices which are currently mounted are
+correct checksum. Devices that are currently mounted are
never allowed to be used as the <targetdev>.
+
-B::::
set of problem when the filesystem mount fails due to the log replay. See below
for sample stacktraces that may show up in system log.
+
-The common case where this happens has been fixed a long time ago,
-so it is unlikely that you will see this particular problem, but the utility is
+The common case where this happens was fixed a long time ago,
+so it is unlikely that you will see this particular problem, but the command is
kept around.
+
NOTE: clearing the log may lead to loss of changes that were made since the
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 filesystem. The IO priority class is by
-default 'idle' so background scrub should not interfere with normal filesystem
-operation significantly.
+default 'idle' so background scrub should not significantly interfere with
+normal filesystem operation.
The scrubbing status is recorded in '/var/lib/btrfs/' in textual files named
'scrub.status.UUID' for a filesystem identified by the given UUID. (Progress
amount of information that has to be sent to reconstruct the sent snapshot on a
different filesystem.
-It is allowed to omit the '-p <parent>' option when '-c <clone-src>' options
-are given, in which case *btrfs send* will determine a suitable parent among the
-clone sources itself.
+The '-p <parent>' option can be omitted when '-c <clone-src>' options are
+given, in which case *btrfs send* will determine a suitable parent from among
+the clone sources.
You must not specify clone sources unless you guarantee that these snapshots
-are exactly in the same state on both sides, the sender and the receiver.
+are exactly in the same state on both sides--both for the sender and the
+receiver.
`Options`
+
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.
+is useful to show the differences in metadata.
-v|--verbose::
enable verbose output, print generated commands in a readable form, (each
SUBVOLUME AND SNAPSHOT
----------------------
-A subvolume is a part of filesystem with its own and independent
+A subvolume is a part of filesystem with its own independent
file/directory hierarchy. Subvolumes can share file extents. A snapshot is
also subvolume, but with a given initial content of the original subvolume.
there are more arguments to process.
+
The corresponding directory is removed instantly but the data blocks are
-removed later in the background. The command returns immediatelly. See `btrfs
+removed later in the background. The command returns immediately. See `btrfs
subvolume sync` how to wait until the subvolume gets completely removed.
+
The deletion does not involve full transaction commit by default due to
--sort=+ogen,-gen,path,rootid.
*set-default* [<subvolume>|<id> <path>]::
-Set the default subvolume of the (mounted) filesystem.
+Set the default subvolume for the (mounted) filesystem.
+
+Set the default subvolume for the (mounted) filesystem at <path>. This will hide
+the top-level subvolume (ie. the one mounted with 'subvol=/' or 'subvolid=5').
+Takes action on next mount.
+
There are two ways how to specify the subvolume, by <id> or by the <subvolume>
path.
Make the new snapshot read only.
*sync* <path> [subvolid...]::
-Wait until given subvolume(s) are completely removed from the filesystem
-after deletion. If no subvolume id is given, wait until all current deletion
-requests are completed, but do not wait for subvolumes deleted meanwhile.
-The status of subvolume ids is checked periodically.
+Wait until given subvolume(s) are completely removed from the filesystem after
+deletion. If no subvolume id is given, wait until all current deletion requests
+are completed, but do not wait for subvolumes deleted in the meantime.
+
`Options`
+
COMMAND SYNTAX
--------------
-Any command name can be shortened as far as it stays unambiguous,
-however it is recommended to use full command names in scripts.
-All command groups have their manual page named *btrfs-<group>*.
+Any command name can be shortened so long as the shortened form is unambiguous,
+however, it is recommended to use full command names in scripts. All command
+groups have their manual page named *btrfs-<group>*.
For example: it is possible to run *btrfs sub snaps* instead of
*btrfs subvolume snapshot*.
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.
+New functionality could be provided using a standalone tool. If the functionality
+proves to be useful, then the standalone tool is declared obsolete and its
+functionality is copied to the main tool. Obsolete tools are removed after a
+long (years) depreciation period.
Tools that are still in active use without an equivalent in *btrfs*:
DESCRIPTION
-----------
-*btrfstune* can be used to enable, disable or set various filesystem
+*btrfstune* can be used to enable, disable, or set various filesystem
parameters. The filesystem must be unmounted.
The common usecase is to enable features that were not enabled at mkfs time.
https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature . Also, the
manual page `mkfs.btrfs`(8) contains more details about the features.
-Some of the features could be enabled on a mounted filesystem. Please refer to
-the respective section in `btrfs`(5).
+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
-------
COMPATIBILITY NOTE
------------------
-This tool exists for historical reasons but is still in use today. The
-functionality is about to be merged to the main tool someday and *btrfstune*
-will become deprecated and removed afterwards.
+
+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
--------
-----------
*fsck.btrfs* is a type of utility that should exist for any filesystem and is
called during system setup when the corresponding `/etc/fstab` entries
-contain non-zero value for `fs_passno` , see `fstab`(5) for more.
+contain non-zero value for `fs_passno`, see `fstab`(5) for more.
Traditional filesystems need to run their respective fsck utility in case the
filesystem was not unmounted cleanly and the log needs to be replayed before
mount. This is not needed for BTRFS. You should set fs_passno to 0.
If you wish to check the consistency of a BTRFS filesystem or repair a damaged
-filesystem, see `btrfs-check`(8). By default the filesystem
-consistency is checked, the repair mode is enabled via '--repair' option (use
-with care!).
+filesystem, see `btrfs-check`(8). By default filesystem consistency is checked,
+the repair mode is enabled via the '--repair' option (use with care!).
OPTIONS
-------
OPTIONS
-------
*-b|--byte-count <size>*::
-Specify the size of the filesystem. If this option is not used,
+Specify the size of the filesystem. If this option is not used, then
mkfs.btrfs uses the entire device space for the filesystem.
*-d|--data <profile>*::
multiple of the sectorsize and a power of 2, but not larger than 64KiB (65536).
Leafsize always equals nodesize and the options are aliases.
+
-Smaller node size increases fragmentation but leads to higher b-trees which in
+Smaller node size increases fragmentation but leads to taller b-trees which in
turn leads to lower locking contention. Higher node sizes give better packing
and less fragmentation at the cost of more expensive memory operations while
updating the metadata blocks.
before all block devices are discovered. The waiting is usually done on the
initramfs/initrd systems.
-As of kernel 4.9, RAID5/6 is still considered experimental and shouldn't be
+As of kernel 4.14, RAID5/6 is still considered experimental and shouldn't be
employed for production use.
FILESYSTEM FEATURES
the logical blocks to 2 physical locations. Whether there are really 2
physical copies highly depends on the underlying device type.
-For example, a SSD drive can remap the blocks internally to a single copy thus
+For example, a SSD drive can remap the blocks internally to a single copy--thus
deduplicating them. This negates the purpose of increased redundancy and just
-wastes filesystem space without the expected level of redundancy.
+wastes filesystem space without providing the expected level of redundancy.
The duplicated data/metadata may still be useful to statistically improve the
chances on a device that might perform some internal optimizations. The actual