summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Sterba <dsterba@suse.com>2016-01-08 19:33:02 +0100
committerDavid Sterba <dsterba@suse.com>2016-01-12 15:01:07 +0100
commitcf0fce7ed408b8955d43e1a7d3d15f9488160e35 (patch)
treed8e6c3f350b3f1d6070d5cfddcdb83c58da64fae /Documentation
parent154c389e92e325033f1d38d204d9d0c4e62f860f (diff)
btrfs-progs: docs, enhance the mount option manual page
Signed-off-by: David Sterba <dsterba@suse.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/btrfs-mount.asciidoc292
1 files changed, 197 insertions, 95 deletions
diff --git a/Documentation/btrfs-mount.asciidoc b/Documentation/btrfs-mount.asciidoc
index d52d4c42..8be70e33 100644
--- a/Documentation/btrfs-mount.asciidoc
+++ b/Documentation/btrfs-mount.asciidoc
@@ -3,30 +3,42 @@ btrfs-mount(5)
NAME
----
-btrfs-mount - mount options and supported file attributes for the btrfs filesystem
+btrfs-mount - topics about the BTRFS filesystem (mount options, supported file attributes and other)
DESCRIPTION
-----------
-This document describes mount options specific to the btrfs filesystem.
-Other generic mount options are available,and are described in the
-`mount`(8) manpage.
+This document describes topics related to BTRFS that are not specific to the
+tools.
MOUNT OPTIONS
-------------
+
+This section describes mount options specific to BTRFS. For the generic mount
+options please refer to `mount`(8) manpage.
+
*alloc_start='bytes'*::
+(default: 1M, minimum: 1M)
++
Debugging option to force all block allocations above a certain
byte threshold on each block device. The value is specified in
-bytes, optionally with a K, M, or G suffix, case insensitive.
-Default is 1MB.
+bytes, optionally with a K, M, or G suffix (case insensitive).
++
+This option was used for testing and has not practial use, it's slated to be
+removed in the future.
*autodefrag*::
*noautodefrag*::
-(since: 3.0, default: off) +
-Disable/enable auto defragmentation.
-Auto defragmentation detects small random writes into files and queue
-them up for the defrag process. Works best for small files;
+(since: 3.0, default: off)
++
+Enable automatic file defragmentation.
+When enabled, small random writes into files (in a range of tens of kilobytes,
+currently it's 64K) are detected and queued up for the defragmentation process.
Not well suited for large database workloads.
+
+The read latency may increase due to reading the adjacent blocks that make up the
+range for defragmentation, successive write will merge the blocks in the new
+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
@@ -37,7 +49,8 @@ broken up ref-links.
*check_int*::
*check_int_data*::
*check_int_print_mask='value'*::
-(since: 3.0, default: off) +
+(since: 3.0, default: off)
++
These debugging options control the behavior of the integrity checking
module (the BTRFS_FS_CHECK_INTEGRITY config option required). +
+
@@ -56,7 +69,8 @@ See comments at the top of 'fs/btrfs/check-integrity.c'
for more info.
*commit='seconds'*::
-(since: 3.12, default: 30) +
+(since: 3.12, default: 30)
++
Set the interval of periodic commit. Higher
values defer data being synced to permanent storage with obvious
consequences when the system crashes. The upper bound is not forced,
@@ -66,7 +80,8 @@ but a warning is printed if it's more than 300 seconds (5 minutes).
*compress='type'*::
*compress-force*::
*compress-force='type'*::
-(default: off) +
+(default: off)
++
Control BTRFS file data compression. Type may be specified as 'zlib',
'lzo' or 'no' (for no compression, used for remounting). If no type
is specified, 'zlib' is used. If compress-force is specified,
@@ -75,37 +90,51 @@ all files will be compressed, whether or not they compress well.
NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled.
*degraded*::
-(default: off) +
-Allow mounts to continue with missing devices. A read-write mount may
-fail with too many devices missing, for example if a stripe member
-is completely missing.
+(default: off)
++
+Allow mounts with less devices than the raid profile constraints
+require. A read-write mount (or remount) may fail with too many devices
+missing, for example if a stripe member is completely missing from RAID0.
*device='devicepath'*::
-Specify a device during mount so that ioctls on the control device
-can be avoided. Especially useful when trying to mount a multi-device
-setup as root. May be specified multiple times for multiple devices.
+Specify a path to a device that will be scanned for BTRFS filesystem during
+mount. This is usually done automatically by a device manager (like udev) or
+using the *btrfs device scan* command (eg. run from the initial ramdisk). In
+cases where this is not possible the 'device' mount option can help.
++
+NOTE: booting eg. a RAID1 system may fail even if all filesystem's 'device'
+paths are provided as the actual device nodes may not be discovered by the
+system at that point.
*discard*::
*nodiscard*::
-(default: off) +
-Disable/enable discard mount option.
-Discard issues frequent commands to let the block device reclaim space
-freed by the filesystem.
-This is useful for SSD devices, thinly provisioned
-LUNs and virtual machine images, but may have a significant
-performance impact. (The fstrim command is also available to
-initiate batch trims from userspace).
+(default: off)
++
+Enable discarding of freed file blocks using 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 severly hurt performance in case the TRIM
+operation is synchronous (eg. with SATA devices up to revision 3.0).
++
+If discarding is not necessary to be done at the block freeing time, there's
+*fstrim* tool that lets the filesystem discard all free blocks in a batch,
+possibly not much interfering with other operations.
*enospc_debug*::
-(default: off) +
-Disable/enable debugging option to be more verbose in some ENOSPC conditions.
+(default: off)
++
+Enable verbose output for some ENOSPC conditions. It's safe to use but can
+be noisy if the system hits reaches near-full state.
*fatal_errors='action'*::
-(since: 3.4, default: bug) +
-Action to take when encountering a fatal error. +
+(since: 3.4, default: bug)
++
+Action to take when encountering a fatal error.
++
*bug*::::
'BUG()' on a fatal error, the system will stay in the crashed state and may be
-still partially usable, but reboot is required for full operation +
+still partially usable, but reboot is required for full operation
++
*panic*::::
'panic()' on a fatal error, depending on other system configuration, this may
be followed by a reboot. Please refer to the documentation of kernel boot
@@ -113,82 +142,144 @@ parameters, eg. 'panic', 'oops' or 'crashkernel'.
*flushoncommit*::
*noflushoncommit*::
-(default: on) +
-The `flushoncommit` mount option forces any data dirtied by a write in a
-prior transaction to commit as part of the current commit. This makes
-the committed state a fully consistent view of the file system from the
-application's perspective (i.e., it includes all completed file system
-operations). This was previously the behavior only when a snapshot is
-created.
+(default: on)
++
+This option forces any data dirtied by a write in a prior transaction to commit
+as part of the current commit. This makes the committed state a fully
+consistent view of the file system from the application's perspective (i.e., it
+includes all completed file system operations). This was previously the
+behavior only when a snapshot was created.
++
+Disabling flushing may improve performance but is not crash-safe.
*inode_cache*::
*noinode_cache*::
-(since: 3.0, default: off) +
-Enable free inode number caching. Defaults to off due to an overflow
-problem when the free space crcs don't fit inside a single page.
+(since: 3.0, default: off)
++
+Enable free inode number caching. Not recommended to use unless files on your
+filesystem get assigned inode numbers that are approaching 2^64^. Normally, new
+files in each subvolume get assigned incrementally (plus one from the last
+time) and are not reused. The mount option turns on caching of the existing
+inode numbers and reuse of inode numbers of deleted files.
++
+This option may slow down your system at first run, or after mounting without
+the option.
++
+NOTE: Defaults to off due to a potential overflow problem when the free space
+checksums don't fit inside a single page.
*max_inline='bytes'*::
(default: min(8192, page size) )
++
Specify the maximum amount of space, in bytes, that can be inlined in
a metadata B-tree leaf. The value is specified in bytes, optionally
-with a K, M, or G suffix, case insensitive. In practice, this value
-is limited by the root sector size, with some space unavailable due
-to leaf headers. For a 4k sectorsize, max inline data is ~3900 bytes.
+with a K suffix (case insensitive). In practice, this value
+is limited by the filesystem block size (named 'sectorsize' at mkfs time),
+and memory page size of the system. In case of sectorsize limit, there's
+some space unavailable due to leaf headers. For example, a 4k sectorsize, max
+inline data is ~3900 bytes.
++
+Inlining can be completely turned off specifying 0. This will increase data
+block slack if file sizes are much smaller than block size but will reduce
+metadata consumption in return.
*metadata_ratio='value'*::
-Specify that 1 metadata chunk should be allocated after every
-'value' data chunks. Off by default.
+(default: 0, internal logic)
++
+Specifies that 1 metadata chunk should be allocated after every 'value' data
+chunks. Default behaviour depends on internal logic, some percent of unused
+metadata space is attempted to be maintained but is not always possible if
+there's not space left for chunk allocation. The option could be useful to
+override the internal logic in favor of the metadata allocation if the expected
+workload is supposed to be metadata intense (snapshots, reflinks, xattrs,
+inlined files).
*acl*::
*noacl*::
-(default: on) +
+(default: on)
++
Enable/disable support for Posix Access Control Lists (ACLs). See the
`acl`(5) manual page for more information about ACLs.
*barrier*::
*nobarrier*::
-(default: on) +
-ensure that certain IOs make it through the device cache and are on
-persistent storage. If disabled on a device with a volatile
-(non-battery-backed) write-back cache, nobarrier option will lead to
-filesystem corruption on a system crash or power loss.
+(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
+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.
++
+The write flushes incur a slight hit and also prevent the IO block
+scheduler to reorder requests in more effective way. Disabling barriers gets
+rid of that penalty but will most certainly lead to a corrupted filesystem in
+case of a crash or power loss. The ordinary metadata blocks could be yet
+unwrittent at the time the new superblock is stored permanently, expecting that
+the block pointers to metadata were stored permanently before.
++
+On a device with a volatile battery-backed write-back cache, the 'nobarrier'
+option will not lead to filesystem corruption as the pending blocks are
+supposed to make it to the permanent storage.
*datacow*::
*nodatacow*::
-(default: on) +
-Enable/disable data copy-on-write for newly created files.
-Nodatacow implies nodatasum, and disables all compression.
+(default: on)
++
+Enable data copy-on-write for newly created files.
+'Nodatacow' implies 'nodatasum', and disables 'compression'. All files created
+under 'nodatacow' are also set the NOCOW file attribute (see `chattr`(1)).
*datasum*::
*nodatasum*::
-(default: on) +
-Enable/disable data checksumming for newly created files.
-Datasum implies datacow.
+(default: on)
++
+Enable data checksumming for newly created files.
+'Datasum' implies 'datacow', ie. the normal mode of operation. All files created
+under 'nodatasum' inherit the "no checksums" property, however there's no
+corresponding file attribute (see `chattr`(1)).
*treelog*::
*notreelog*::
-(default: on) +
-Enable/disable the tree logging used for fsync and O_SYNC writes.
+(default: on)
++
+Enable the tree logging used for 'fsync' and 'O_SYNC' writes. The tree log
+stores changes without the need of a full filesystem sync. The log operations
+are flushed at sync and transaction commit. If the system crashes between two
+such syncs, the pending tree log operations are replayed during mount.
++
+WARNING: currently, the tree log is replayed even with a read-only mount!
++
+The tree log could contain new files/directories, these would not exist on
+a mounted filesystm if the log is not replayed.
*recovery*::
-(since: 3.2, default: off) +
+(since: 3.2, default: off)
++
Enable autorecovery attempts if a bad tree root is found at mount time.
-Currently this scans a list of several previous tree roots and tries to
-use the first readable.
+Currently this scans a backup list of several previous tree roots and tries to
+use the first readable. This can be used with read-only mounts as well.
*rescan_uuid_tree*::
-(since: 3.12, default: off) +
+(since: 3.12, default: off)
++
Force check and rebuild procedure of the UUID tree. This should not
normally be needed.
*skip_balance*::
-(since: 3.3, default: off) +
+(since: 3.3, default: off)
++
Skip automatic resume of interrupted balance operation after mount.
-May be resumed with "btrfs balance resume."
+May be resumed with *btrfs balance resume* or the paused state can be removed
+by *btrfs balance cancel*.
*nospace_cache*::
-(since: 3.2) +
-Disable freespace cache loading without clearing the cache.
+(since: 3.2)
++
+Disable freespace cache loading without clearing the cache and the free space
+cache will not be used during the mount. This affects performance as searching
+for new free blocks could take longer. On the other hand, managing the space
+cache consumes some resources.
*clear_cache*::
Force clearing and rebuilding of the disk space cache if something
@@ -197,38 +288,47 @@ has gone wrong.
*ssd*::
*nossd*::
*ssd_spread*::
-Options to control ssd allocation schemes. By default, BTRFS will
-enable or disable ssd allocation heuristics depending on whether a
-rotational or nonrotational disk is in use. The ssd and nossd options
-can override this autodetection. +
-The ssd_spread mount option attempts to allocate into big chunks
-of unused space, and may perform better on low-end ssds. ssd_spread
-implies ssd, enabling all other ssd heuristics as well.
+(default: SSD autodetected)
++
+Options to control SSD allocation schemes. By default, BTRFS will
+enable or disable SSD allocation heuristics depending on whether a
+rotational or nonrotational disk is in use. The 'ssd' and 'nossd' options
+can override this autodetection.
++
+The 'ssd_spread' mount option attempts to allocate into bigger and aligned
+chunks of unused space, and may perform better on low-end SSDs. 'ssd_spread'
+implies 'ssd', enabling all other SSD heuristics as well.
*subvol='path'*::
-Mount subvolume at 'path' rather than the root subvolume. The
-'path' is relative to the top level subvolume.
+Mount subvolume from 'path' rather than the toplevel subvolume. The
+'path' is absolute (ie. starts at the toplevel subvolume).
+This mount option overrides the default subvolume set for the given filesystem.
-*subvolid='ID'*::
-Mount subvolume specified by an ID number rather than the root subvolume.
-This allows mounting of subvolumes which are not in the root of the mounted
-filesystem.
-You can use "btrfs subvolume list" to see subvolume ID numbers.
+*subvolid='subvolid'*::
+Mount subvolume specified by a 'subvolid' number rather than the toplevel
+subvolume. You can use *btrfs subvolume list* to see subvolume ID numbers.
+This mount option overrides the default subvolume set for the given filesystem.
*subvolrootid='objectid'*::
-(deprecated) +
-Mount subvolume specified by 'objectid' rather than the root subvolume.
-This allows mounting of subvolumes which are not in the root of the mounted
-filesystem.
-You can use "btrfs subvolume show" to see the object ID for a subvolume.
+(irrelevant since: 3.2, formally deprecated since: 3.10)
++
+A workaround option from times (pre 3.2) when it was not possible to mount a
+subvolume that did not reside directly under the toplevel subvolume.
*thread_pool='number'*::
-The number of worker threads to allocate. The default number is equal
-to the number of CPUs + 2, or 8, whichever is smaller.
+(default: min(NRCPUS + 2, 8) )
++
+The number of worker threads to allocate. NRCPUS is number of on-line CPUs
+detected at the time of mount. Small number leads to less parallelism in
+processing data and metadata, higher numbers could lead to a performance due to
+increased locking contention, cache-line bouncing or costly data transfers
+between local CPU memories.
*user_subvol_rm_allowed*::
-(default: off) +
-Allow subvolumes to be deleted by a non-root user. Use with caution.
+(default: off)
++
+Allow subvolumes to be deleted by their respective owner. Otherwise, only the
+root user can do that.
FILE ATTRIBUTES
---------------
@@ -258,7 +358,9 @@ For descriptions of these attribute flags, please refer to the
SEE ALSO
--------
+`acl`(5),
+`btrfs`(8),
`chattr`(1),
+`fstrim`(8),
`mkfs.btrfs`(8),
-`mount`(8),
-`btrfs`(8)
+`mount`(8)