summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Sterba <dsterba@suse.com>2016-05-06 12:27:31 +0200
committerDavid Sterba <dsterba@suse.com>2016-05-11 16:37:12 +0200
commitb3751c131a312b12517b6f2674d9613fb6a0d2dd (patch)
tree1f82741dd6699791238e085f3ea6894e96049300 /Documentation
parent00fd55385312d0cc2c340dc31d06806167c7dcb4 (diff)
btrfs-progs: docs: update btrfs-man5
Wording, added new options. Signed-off-by: David Sterba <dsterba@suse.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/btrfs-man5.asciidoc85
1 files changed, 64 insertions, 21 deletions
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index e2eea263..6ce4c440 100644
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -27,6 +27,9 @@ options please refer to `mount`(8) manpage. The options are sorted alphabeticall
+
Enable/disable support for Posix Access Control Lists (ACLs). See the
`acl`(5) manual page for more information about ACLs.
++
+The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL) and
+mount fails if 'acl' is requested but the feature is not compiled in.
*alloc_start='bytes'*::
(default: 1M, minimum: 1M)
@@ -69,7 +72,7 @@ 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
+scheduler to reorder requests in a 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
unwritten at the time the new superblock is stored permanently, expecting that
@@ -121,8 +124,11 @@ but a warning is printed if it's more than 300 seconds (5 minutes).
+
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,
-all files will be compressed, whether or not they compress well.
+is specified, 'zlib' is used. If 'compress-force' is specified,
+all files will be compressed, whether or not they compress well. Otherwise
+some simple heuristics are applied to detect an incompressible file. If the
+first blocks written to a file are not compressible, the whole file is
+permanently marked to skip compression.
+
NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled.
@@ -171,15 +177,17 @@ underlying device, the operation may severely 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.
+`fstrim` tool that lets the filesystem discard all free blocks in a batch,
+possibly not much interfering with other operations. Also, the the device may
+ignore the TRIM command if the range is too small, so running the batch discard
+can actually discard the blocks.
*enospc_debug*::
*noenospc_debug*::
(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.
+be noisy if the system reaches near-full state.
*fatal_errors='action'*::
(since: 3.4, default: bug)
@@ -231,20 +239,31 @@ the option.
NOTE: Defaults to off due to a potential overflow problem when the free space
checksums don't fit inside a single page.
+*logreplay*::
+*nologreplay*::
+(default: on, even read-only)
++
+Enable/disable log replay at mount time. See also 'treelog'.
++
+WARNING: currently, the tree log is replayed even with a read-only mount! To
+disable that behaviour, mount also with 'nologreplay'.
+
*max_inline='bytes'*::
-(default: min(8192, page size) )
+(default: min(2048, 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 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.
+some space unavailable due to leaf headers. For example, a 4k sectorsize,
+maximum size of inline data is about 3900 bytes.
+
-Inlining can be completely turned off specifying 0. This will increase data
+Inlining can be completely turned off by specifying 0. This will increase data
block slack if file sizes are much smaller than block size but will reduce
metadata consumption in return.
++
+NOTE: the default value has changed to 2048 in kernel 4.6.
*metadata_ratio='value'*::
(default: 0, internal logic)
@@ -252,17 +271,27 @@ metadata consumption in return.
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
+there's not enough 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).
*recovery*::
-(since: 3.2, default: off)
+(since: 3.2, default: off, deprecated since: 4.5)
+
-Enable autorecovery attempts if a bad tree root is found at mount time.
-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.
+NOTE: this option has been replaced by 'usebackuproot' and should not be used
+but will work on 4.5+ kernels.
+
+*norecovery*::
+(since: 4.5, default: off)
++
+Do not attempt any data recovery at mount time. This will disable 'logreplay'
+and avoids other write operations.
++
+NOTE: The opposite option 'recovery' used to have different meaning but was
+changed for consistency with other filesystems, where 'norecovery' is used for
+skipping log replay. BTRFS does the same and in general will try to avoid any
+write operations.
*rescan_uuid_tree*::
(since: 3.12, default: off)
@@ -275,7 +304,7 @@ normally be needed.
+
Skip automatic resume of interrupted balance operation after mount.
May be resumed with *btrfs balance resume* or the paused state can be removed
-by *btrfs balance cancel*.
+by *btrfs balance cancel*. The default behaviour is to start interrutpd balance.
*space_cache*::
*space_cache=v2*::
@@ -305,7 +334,8 @@ b-trees, sometimes referred to as 'free-space-tree'.
+
Options to control SSD allocation schemes. By default, BTRFS will
enable or disable SSD allocation heuristics depending on whether a
-rotational or non-rotational disk is in use. The 'ssd' and 'nossd' options
+rotational or non-rotational disk is in use (contents of
+'/sys/block/DEV/queue/rotational'). The 'ssd' and 'nossd' options
can override this autodetection.
+
The 'ssd_spread' mount option attempts to allocate into bigger and aligned
@@ -321,6 +351,9 @@ This mount option overrides the default subvolume set for the given filesystem.
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.
++
+NOTE: if both 'subvolid' and 'subvol' are specified, they must point at the
+same subvolume, otherwise mount will fail.
*subvolrootid='objectid'*::
(irrelevant since: 3.2, formally deprecated since: 3.10)
@@ -333,9 +366,9 @@ subvolume that did not reside directly under the toplevel subvolume.
+
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.
+processing data and metadata, higher numbers could lead to a performance hit
+due to increased locking contention, cache-line bouncing or costly data
+transfers between local CPU memories.
*treelog*::
*notreelog*::
@@ -346,11 +379,21 @@ 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!
+WARNING: currently, the tree log is replayed even with a read-only mount! To
+disable that behaviour, mount also with 'nologreplay'.
+
The tree log could contain new files/directories, these would not exist on
a mounted filesystem if the log is not replayed.
+*usebackuproot*::
+*nousebackuproot*::
++
+Enable autorecovery attempts if a bad tree root is found at mount time.
+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.
++
+NOTE: This option has replaced 'recovery'.
+
*user_subvol_rm_allowed*::
(default: off)
+