From 32c063ccb73dc11e880a575f30e921ca64b8c520 Mon Sep 17 00:00:00 2001 From: David Sterba 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 --- Documentation/Makefile.in | 6 +- Documentation/btrfs-man5.asciidoc | 395 +++++++++++++++++++++++++++++++++++++ Documentation/btrfs-mount.asciidoc | 395 ------------------------------------- 3 files changed, 398 insertions(+), 398 deletions(-) create mode 100644 Documentation/btrfs-man5.asciidoc delete mode 100644 Documentation/btrfs-mount.asciidoc (limited to 'Documentation') diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in index 4711ad1f..f046abd5 100644 --- a/Documentation/Makefile.in +++ b/Documentation/Makefile.in @@ -31,8 +31,8 @@ MAN8_TXT += btrfs-replace.asciidoc MAN8_TXT += btrfs-restore.asciidoc MAN8_TXT += btrfs-property.asciidoc -# Mount manpage -MAN5_TXT += btrfs-mount.asciidoc +# Category 5 manual page +MAN5_TXT += btrfs-man5.asciidoc MAN_TXT = $(MAN8_TXT) $(MAN5_TXT) MAN_XML = $(patsubst %.asciidoc,%.xml,$(MAN_TXT)) @@ -92,7 +92,7 @@ install-man: man $(INSTALL) -m 644 $(GZ_MAN5) $(DESTDIR)$(man5dir) # the source file name of btrfs.5 clashes with section 8 page, but we # want to keep the code generic - $(MV) $(DESTDIR)$(man5dir)/btrfs-mount.5.gz $(DESTDIR)$(man5dir)/btrfs.5.gz + $(MV) $(DESTDIR)$(man5dir)/btrfs-man5.5.gz $(DESTDIR)$(man5dir)/btrfs.5.gz $(INSTALL) -m 644 $(GZ_MAN8) $(DESTDIR)$(man8dir) $(LN_S) -f btrfs-check.8.gz $(DESTDIR)$(man8dir)/btrfsck.8.gz $(LN_S) -f btrfs-rescue.8.gz $(DESTDIR)$(man8dir)/btrfs-zero-log.8.gz 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) diff --git a/Documentation/btrfs-mount.asciidoc b/Documentation/btrfs-mount.asciidoc deleted file mode 100644 index aa253824..00000000 --- a/Documentation/btrfs-mount.asciidoc +++ /dev/null @@ -1,395 +0,0 @@ -btrfs-mount(5) -============== - -NAME ----- -btrfs-mount - 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