From 32c063ccb73dc11e880a575f30e921ca64b8c520 Mon Sep 17 00:00:00 2001
From: David Sterba <dsterba@suse.com>
Date: Mon, 11 Jan 2016 15:32:38 +0100
Subject: btrfs-progs: docs: rename btrfs-mount to btrfs-man5

The page does will not contain only mount options but other stuff.

Signed-off-by: David Sterba <dsterba@suse.com>
---
 Documentation/btrfs-man5.asciidoc | 395 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 395 insertions(+)
 create mode 100644 Documentation/btrfs-man5.asciidoc

(limited to 'Documentation/btrfs-man5.asciidoc')

diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
new file mode 100644
index 00000000..2bb6ae09
--- /dev/null
+++ b/Documentation/btrfs-man5.asciidoc
@@ -0,0 +1,395 @@
+btrfs-man5(5)
+==============
+
+NAME
+----
+btrfs-man5 - topics about the BTRFS filesystem (mount options, supported file attributes and other)
+
+DESCRIPTION
+-----------
+This document describes topics related to BTRFS that are not specific to the
+tools.  Currently covers:
+
+1. mount options
+
+2. file attributes
+
+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).
++
+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)
++
+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
+copied with `cp --reflink`, snapshots or de-duplicated data).
+This may cause considerable increase of space usage depending on the
+broken up ref-links.
+
+*check_int*::
+*check_int_data*::
+*check_int_print_mask='value'*::
+(since: 3.0, default: off)
++
+These debugging options control the behavior of the integrity checking
+module (the BTRFS_FS_CHECK_INTEGRITY config option required). +
++
+`check_int` enables the integrity checker module, which examines all
+block write requests to ensure on-disk consistency, at a large
+memory and CPU cost. +
++
+`check_int_data` includes extent data in the integrity checks, and
+implies the check_int option. +
++
+`check_int_print_mask` takes a bitmask of BTRFSIC_PRINT_MASK_* values
+as defined in 'fs/btrfs/check-integrity.c', to control the integrity
+checker module behavior. +
++
+See comments at the top of 'fs/btrfs/check-integrity.c'
+for more info.
+
+*commit='seconds'*::
+(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,
+but a warning is printed if it's more than 300 seconds (5 minutes).
+
+*compress*::
+*compress='type'*::
+*compress-force*::
+*compress-force='type'*::
+(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,
+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 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 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)
++
+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)
++
+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.
++
+*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
++
+*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
+parameters, eg. 'panic', 'oops' or 'crashkernel'.
+
+*flushoncommit*::
+*noflushoncommit*::
+(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. 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 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'*::
+(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)
++
+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 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 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 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 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)
++
+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.
+
+*rescan_uuid_tree*::
+(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)
++
+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*.
+
+*nospace_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
+has gone wrong.
+
+*ssd*::
+*nossd*::
+*ssd_spread*::
+(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 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='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'*::
+(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'*::
+(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 their respective owner. Otherwise, only the
+root user can do that.
+
+FILE ATTRIBUTES
+---------------
+The btrfs filesystem supports setting the following file attributes using the
+`chattr`(1) utility:
+
+*a*::
+'append only', new writes are always written at the end of the file
+
+*A*::
+'no atime updates'
+
+*c*::
+'compress data', all data written after this attribute is set will be compressed.
+Please note that compression is also affected by the mount options or the parent
+directory attributes.
++
+When set on a directory, all newly created files will inherit this attribute.
+
+*C*::
+'no copy-on-write', file modifications are done in-place
++
+When set on a directory, all newly created files will inherit this attribute.
++
+NOTE: due to implementation limitations, this flag can be set/unset only on
+empty files.
+
+*d*::
+'no dump', makes sense with 3rd party tools like `dump`(8), on BTRFS the
+attribute can be set/unset on no other special handling is done
+
+*D*::
+'synchronous directory updates', for more details search `open`(2) for 'O_SYNC'
+and 'O_DSYNC'
+
+*i*::
+'immutable', no file data and metadata changes allowed even to the root user as
+long as this attribute is set (obviously the exception is unsetting the attribute)
+
+*S*::
+'synchronous updates', for more details search `open`(2) for 'O_SYNC' and
+'O_DSYNC'
+
+*X*::
+'no compression', permanently turn off compression on the given file, other
+compression mount options will not affect that
++
+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.
+
+SEE ALSO
+--------
+`acl`(5),
+`btrfs`(8),
+`chattr`(1),
+`fstrim`(8),
+`mkfs.btrfs`(8),
+`mount`(8)
-- 
cgit v1.2.3

