mirror of
https://github.com/kdave/btrfs-progs
synced 2025-01-18 11:40:56 +00:00
btrfs-progs: docs: annual typo, clarity, & grammar review & fixups
Signed-off-by: Nicholas D Steeves <nsteeves@gmail.com> Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
Nicholas D Steeves
David Sterba
parent
1f36022071
commit
8c5db79d0f
@ -21,8 +21,8 @@ filesystem.
|
||||
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.
|
||||
@ -201,10 +201,11 @@ ENOSPC
|
||||
------
|
||||
|
||||
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:
|
||||
@ -227,7 +228,7 @@ space. After that it might be possible to run other filters.
|
||||
|
||||
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
|
||||
--------
|
||||
@ -238,7 +239,7 @@ 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
|
||||
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.
|
||||
|
||||
@ -298,7 +299,7 @@ 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
|
||||
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.
|
||||
|
||||
@ -22,10 +22,10 @@ by the option '--readonly'.
|
||||
|
||||
*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
|
||||
@ -49,9 +49,8 @@ This can be combined with '--super' if some of the superblocks are damaged.
|
||||
--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
|
||||
@ -88,8 +87,8 @@ the free space cache for block groups that are modified while the filesystem is
|
||||
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.
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@ Supported filesystems:
|
||||
|
||||
* 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').
|
||||
@ -32,13 +32,14 @@ The conversion utilizes free space of the original filesystem. The exact
|
||||
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).
|
||||
|
||||
@ -52,8 +53,8 @@ metadata of the original filesystem 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 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**
|
||||
|
||||
@ -102,7 +103,7 @@ 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 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).
|
||||
|
||||
@ -124,7 +124,7 @@ statistics and the meaning.
|
||||
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.
|
||||
|
||||
@ -190,8 +190,8 @@ there's enough workspace for the conversion process, we can do:
|
||||
|
||||
$ 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
|
||||
|
||||
@ -3,7 +3,7 @@ btrfs-filesystem(8)
|
||||
|
||||
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
|
||||
--------
|
||||
@ -53,8 +53,9 @@ not total size of filesystem.
|
||||
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`
|
||||
+
|
||||
@ -93,10 +94,10 @@ You can also turn on compression in defragment operations.
|
||||
+
|
||||
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
|
||||
@ -174,7 +175,7 @@ show sizes in TiB, or TB with --si.
|
||||
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
|
||||
@ -359,9 +360,9 @@ specify the devid though.
|
||||
|
||||
*$ 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.
|
||||
|
||||
@ -17,7 +17,7 @@ root tree's objectid, generation, level.
|
||||
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>::
|
||||
|
||||
@ -136,16 +136,16 @@ resize operation, this may be useful before executing the actual resize operatio
|
||||
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)
|
||||
|
||||
@ -58,17 +58,17 @@ location.
|
||||
+
|
||||
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.
|
||||
@ -129,7 +129,7 @@ seconds (5 minutes). Use with care.
|
||||
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.
|
||||
@ -205,12 +205,20 @@ system at that point.
|
||||
*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
|
||||
@ -643,8 +651,8 @@ long as this attribute is set (obviously the exception is unsetting the attribut
|
||||
'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.
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@ SYNOPSIS
|
||||
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.
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ NOTE: To use qgroup you need to enable quota first using *btrfs quota enable*
|
||||
command.
|
||||
|
||||
WARNING: Qgroup is not stable yet and will impact performance in current mainline
|
||||
kernel (v3.14 so far).
|
||||
kernel (v4.14).
|
||||
|
||||
QGROUP
|
||||
------
|
||||
@ -56,13 +56,13 @@ Explicitly ask not to do a rescan.
|
||||
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
|
||||
|
||||
@ -15,24 +15,24 @@ The commands under *btrfs quota* are used to affect the global status of quotas
|
||||
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
|
||||
---------------------------------
|
||||
@ -52,7 +52,7 @@ On the other hand, the traditional approach has only a poor solution to
|
||||
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
|
||||
@ -181,7 +181,7 @@ own way how to integrate qgroups.
|
||||
`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.
|
||||
|
||||
|
||||
@ -81,7 +81,7 @@ should be protected from access by users until the receive operation
|
||||
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
|
||||
|
||||
@ -34,7 +34,7 @@ from the system, you have to use the devid parameter format.
|
||||
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`
|
||||
@ -45,10 +45,10 @@ only read from <srcdev> if no other zero-defect mirror exists.
|
||||
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::::
|
||||
|
||||
@ -67,8 +67,8 @@ This command will clear the filesystem log tree. This may fix a specific
|
||||
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
|
||||
|
||||
@ -21,8 +21,8 @@ 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 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
|
||||
|
||||
@ -29,12 +29,13 @@ are available on both the sending and receiving side can be used to reduce the
|
||||
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`
|
||||
|
||||
@ -53,7 +54,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.
|
||||
is useful to show the differences in metadata.
|
||||
|
||||
-v|--verbose::
|
||||
enable verbose output, print generated commands in a readable form, (each
|
||||
|
||||
@ -17,7 +17,7 @@ snapshots.
|
||||
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.
|
||||
|
||||
@ -66,7 +66,7 @@ If <subvolume> is not a subvolume, btrfs returns an error but continues if
|
||||
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
|
||||
@ -143,7 +143,11 @@ for --sort you can combine some items together by \',', just like
|
||||
--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.
|
||||
@ -166,10 +170,9 @@ If <source> is not a subvolume, btrfs returns an error.
|
||||
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`
|
||||
+
|
||||
|
||||
@ -25,9 +25,9 @@ page `btrfs`(5).
|
||||
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*.
|
||||
@ -106,10 +106,10 @@ COMMANDS
|
||||
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*:
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ SYNOPSIS
|
||||
|
||||
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.
|
||||
@ -20,8 +20,8 @@ complete list of features and kernel version of their introduction at
|
||||
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
|
||||
-------
|
||||
@ -86,9 +86,10 @@ EXIT STATUS
|
||||
|
||||
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
|
||||
--------
|
||||
|
||||
@ -13,16 +13,15 @@ DESCRIPTION
|
||||
-----------
|
||||
*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
|
||||
-------
|
||||
|
||||
@ -22,7 +22,7 @@ mount option. See section *MULTIPLE DEVICES* for more details.
|
||||
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>*::
|
||||
@ -74,7 +74,7 @@ default value is 16KiB (16384) or the page size, whichever is bigger. Must be a
|
||||
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.
|
||||
@ -167,7 +167,7 @@ root partition created with RAID1/10/5/6 profiles. The mount action can happen
|
||||
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
|
||||
@ -282,9 +282,9 @@ The mkfs utility will let the user create a filesystem with profiles that write
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user