From d78d642bffff6ea49d62c19f26052ed6d3dcc467 Mon Sep 17 00:00:00 2001 From: Dimitri John Ledkov Date: Thu, 11 Jan 2018 15:44:55 +0000 Subject: New upstream release. --- Documentation/btrfs-balance.8.gz | Bin 6045 -> 6128 bytes Documentation/btrfs-balance.asciidoc | 17 +-- Documentation/btrfs-check.8.gz | Bin 2692 -> 2742 bytes Documentation/btrfs-check.asciidoc | 17 ++- Documentation/btrfs-convert.8.gz | Bin 2711 -> 2755 bytes Documentation/btrfs-convert.asciidoc | 21 ++-- Documentation/btrfs-device.8.gz | Bin 4494 -> 4852 bytes Documentation/btrfs-device.asciidoc | 35 +++++- Documentation/btrfs-filesystem.8.gz | Bin 5853 -> 5909 bytes Documentation/btrfs-filesystem.asciidoc | 19 +-- Documentation/btrfs-find-root.8.gz | Bin 850 -> 869 bytes Documentation/btrfs-find-root.asciidoc | 2 +- Documentation/btrfs-image.8.gz | Bin 1454 -> 1473 bytes Documentation/btrfs-inspect-internal.8.gz | Bin 3034 -> 3062 bytes Documentation/btrfs-inspect-internal.asciidoc | 8 +- Documentation/btrfs-man5.asciidoc | 173 +++++++++++++++++++------- Documentation/btrfs-map-logical.8.gz | Bin 867 -> 883 bytes Documentation/btrfs-map-logical.asciidoc | 2 +- Documentation/btrfs-property.8.gz | Bin 1423 -> 1527 bytes Documentation/btrfs-property.asciidoc | 19 +-- Documentation/btrfs-qgroup.8.gz | Bin 2368 -> 2388 bytes Documentation/btrfs-qgroup.asciidoc | 8 +- Documentation/btrfs-quota.8.gz | Bin 4887 -> 4908 bytes Documentation/btrfs-quota.asciidoc | 16 +-- Documentation/btrfs-receive.8.gz | Bin 2017 -> 2033 bytes Documentation/btrfs-receive.asciidoc | 2 +- Documentation/btrfs-replace.8.gz | Bin 1624 -> 1646 bytes Documentation/btrfs-replace.asciidoc | 6 +- Documentation/btrfs-rescue.8.gz | Bin 1710 -> 2059 bytes Documentation/btrfs-rescue.asciidoc | 24 +++- Documentation/btrfs-restore.8.gz | Bin 1972 -> 1991 bytes Documentation/btrfs-scrub.8.gz | Bin 2148 -> 2168 bytes Documentation/btrfs-scrub.asciidoc | 4 +- Documentation/btrfs-select-super.8.gz | Bin 1258 -> 1275 bytes Documentation/btrfs-send.8.gz | Bin 1708 -> 1734 bytes Documentation/btrfs-send.asciidoc | 11 +- Documentation/btrfs-subvolume.8.gz | Bin 3121 -> 3242 bytes Documentation/btrfs-subvolume.asciidoc | 34 +++-- Documentation/btrfs.5.gz | Bin 9228 -> 10993 bytes Documentation/btrfs.8.gz | Bin 2205 -> 2234 bytes Documentation/btrfs.asciidoc | 14 +-- Documentation/btrfstune.8.gz | Bin 1997 -> 2050 bytes Documentation/btrfstune.asciidoc | 13 +- Documentation/fsck.btrfs.8.gz | Bin 1119 -> 1123 bytes Documentation/fsck.btrfs.asciidoc | 7 +- Documentation/mkfs.btrfs.8.gz | Bin 6254 -> 6298 bytes Documentation/mkfs.btrfs.asciidoc | 21 ++-- 47 files changed, 308 insertions(+), 165 deletions(-) (limited to 'Documentation') diff --git a/Documentation/btrfs-balance.8.gz b/Documentation/btrfs-balance.8.gz index 1d553317..e2344c16 100644 Binary files a/Documentation/btrfs-balance.8.gz and b/Documentation/btrfs-balance.8.gz differ diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc index cc81de91..7017bed7 100644 --- a/Documentation/btrfs-balance.asciidoc +++ b/Documentation/btrfs-balance.asciidoc @@ -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. diff --git a/Documentation/btrfs-check.8.gz b/Documentation/btrfs-check.8.gz index 9f5c4bca..475ea594 100644 Binary files a/Documentation/btrfs-check.8.gz and b/Documentation/btrfs-check.8.gz differ diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc index fbf48847..cc76d846 100644 --- a/Documentation/btrfs-check.asciidoc +++ b/Documentation/btrfs-check.asciidoc @@ -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 :: 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. diff --git a/Documentation/btrfs-convert.8.gz b/Documentation/btrfs-convert.8.gz index 9758a080..f361a835 100644 Binary files a/Documentation/btrfs-convert.8.gz and b/Documentation/btrfs-convert.8.gz differ diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc index 07ff608a..41f23d61 100644 --- a/Documentation/btrfs-convert.asciidoc +++ b/Documentation/btrfs-convert.asciidoc @@ -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 [,...]:: -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). diff --git a/Documentation/btrfs-device.8.gz b/Documentation/btrfs-device.8.gz index a457c952..785a0046 100644 Binary files a/Documentation/btrfs-device.8.gz and b/Documentation/btrfs-device.8.gz differ diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc index 88822ece..223ade5c 100644 --- a/Documentation/btrfs-device.asciidoc +++ b/Documentation/btrfs-device.asciidoc @@ -68,13 +68,23 @@ Remove device(s) from a filesystem identified by Device removal must satisfy the profile constraints, otherwise the command fails. The filesystem must be converted to profile(s) that would allow the removal. This can typically happen when going down from 2 devices to 1 and -using the RAID1 profile. See the example section below. +using the RAID1 profile. See the *TYPICAL USECASES* section below. + The operation can take long as it needs to move all data from the device. + It is possible to delete the device that was used to mount the filesystem. The -device entry in mount table will be replaced by another device name with the -lowest device id. +device entry in the mount table will be replaced by another device name with +the lowest device id. ++ +If the filesystem is mounted in degraded mode (-o degraded), special term +'missing' can be used for 'device'. In that case, the first device that is +described by the filesystem metadata, but not present at the mount time will be +removed. ++ +NOTE: In most cases, there is only one missing device in degraded mode, +otherwise mount fails. If there are two or more devices missing (e.g. possible +in RAID6), you need specify 'missing' as many times as the number of missing +devices to remove all of them. *delete* | [|...] :: Alias of remove kept for backward compatibility @@ -114,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. @@ -180,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 @@ -206,6 +216,19 @@ data or the block groups occupy the whole first device. The device size of '/dev/sdb' as seen by the filesystem remains unchanged, but the logical space from 50-100GiB will be unused. +==== REMOVE DEVICE ==== + +Device removal must satisfy the profile constraints, otherwise the command +fails. For example: + + $ btrfs device remove /dev/sda /mnt + ERROR: error removing device '/dev/sda': unable to go below two devices on raid1 + +In order to remove a device, you need to convert the profile in this case: + + $ btrfs balance start -mconvert=dup -dconvert=single /mnt + $ btrfs device remove /dev/sda /mnt + DEVICE STATS ------------ diff --git a/Documentation/btrfs-filesystem.8.gz b/Documentation/btrfs-filesystem.8.gz index b1628e4c..727f2421 100644 Binary files a/Documentation/btrfs-filesystem.8.gz and b/Documentation/btrfs-filesystem.8.gz differ diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc index 41b30320..961405ba 100644 --- a/Documentation/btrfs-filesystem.asciidoc +++ b/Documentation/btrfs-filesystem.asciidoc @@ -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. diff --git a/Documentation/btrfs-find-root.8.gz b/Documentation/btrfs-find-root.8.gz index bbe8ad41..c90e2244 100644 Binary files a/Documentation/btrfs-find-root.8.gz and b/Documentation/btrfs-find-root.8.gz differ diff --git a/Documentation/btrfs-find-root.asciidoc b/Documentation/btrfs-find-root.asciidoc index 3d6af2df..652796c8 100644 --- a/Documentation/btrfs-find-root.asciidoc +++ b/Documentation/btrfs-find-root.asciidoc @@ -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 :: Filter root tree by it's original transaction id, tree root's generation in default. -o :: diff --git a/Documentation/btrfs-image.8.gz b/Documentation/btrfs-image.8.gz index cc7fc7ba..e5591ab1 100644 Binary files a/Documentation/btrfs-image.8.gz and b/Documentation/btrfs-image.8.gz differ diff --git a/Documentation/btrfs-inspect-internal.8.gz b/Documentation/btrfs-inspect-internal.8.gz index 145bbb3d..b8147ecf 100644 Binary files a/Documentation/btrfs-inspect-internal.8.gz and b/Documentation/btrfs-inspect-internal.8.gz differ diff --git a/Documentation/btrfs-inspect-internal.asciidoc b/Documentation/btrfs-inspect-internal.asciidoc index 62b10294..e072a943 100644 --- a/Documentation/btrfs-inspect-internal.asciidoc +++ b/Documentation/btrfs-inspect-internal.asciidoc @@ -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* :: -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* :: (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] :: (needs root privileges) diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc index 3981435e..1f444d73 100644 --- a/Documentation/btrfs-man5.asciidoc +++ b/Documentation/btrfs-man5.asciidoc @@ -26,6 +26,13 @@ This section describes mount options specific to BTRFS. For the generic mount options please refer to `mount`(8) manpage. The options are sorted alphabetically (discarding the 'no' prefix). +NOTE: most mount options apply to the whole filesystem and only options in the +first mounted subvolume will take effect. This is due to lack of implementation +and may change in the future. This means that (for example) you can't set +per-subvolume 'nodatacow', 'nodatasum', or 'compress' using mount options. This +should eventually be fixed, but it has proved to be difficult to implement +correctly within the Linux VFS framework. + *acl*:: *noacl*:: (default: on) @@ -51,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. @@ -83,21 +90,22 @@ supposed to make it to the permanent storage. (since: 3.0, default: off) + These debugging options control the behavior of the integrity checking -module (the BTRFS_FS_CHECK_INTEGRITY config option required). + +module (the BTRFS_FS_CHECK_INTEGRITY config option required). The main goal is +to verify that all blocks from a given transaction period are properly linked. + -`check_int` enables the integrity checker module, which examines all +'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. + +memory and CPU cost. + -`check_int_data` includes extent data in the integrity checks, and -implies the check_int option. + +'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 +'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. + +checker module behavior. + See comments at the top of 'fs/btrfs/check-integrity.c' -for more info. +for more information. *clear_cache*:: Force clearing and rebuilding of the disk space cache if something @@ -106,10 +114,11 @@ has gone wrong. See also: 'space_cache'. *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). +Set the interval of periodic transaction commit when data are synchronized +to permanent storage. Higher interval values lead to larger amount of unwritten +data, which has 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). Use with care. *compress*:: *compress='type'*:: @@ -120,7 +129,7 @@ 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', '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 allways 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. @@ -141,6 +150,10 @@ Enable data copy-on-write for newly created files. under 'nodatacow' are also set the NOCOW file attribute (see `chattr`(1)). + NOTE: If 'nodatacow' or 'nodatasum' are enabled, compression is disabled. ++ +Updates in-place improve performance for workloads that do frequent overwrites, +at the cost of potential partial writes, in case the write is interruted +(system crash, device failure). *datasum*:: *nodatasum*:: @@ -152,13 +165,31 @@ under 'nodatasum' inherit the "no checksums" property, however there's no corresponding file attribute (see `chattr`(1)). + NOTE: If 'nodatacow' or 'nodatasum' are enabled, compression is disabled. ++ +There is a slight performance gain when checksums are turned off, the +correspoinding metadata blocks holding the checksums do not need to updated. +The cost of checksumming of the blocks in memory is much lower than the IO, +modern CPUs feature hardware support of the checksumming algorithm. *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 +Allow mounts with less devices than the RAID profile constraints +require. A read-write mount (or remount) may fail when there are too many devices missing, for example if a stripe member is completely missing from RAID0. ++ +Since 4.14, the constraint checks have been improved and are verified on the +chunk level, not an the device level. This allows degraded mounts of +filesystems with mixed RAID profiles for data and metadata, even if the +device number constraints would not be satisfied for some of the prifles. ++ +Example: metadata -- raid1, data -- single, devices -- /dev/sda, /dev/sdb ++ +Suppose the data are completely stored on 'sda', then missing 'sdb' will not +prevent the mount, even if 1 missing device would normally prevent (any) +'single' profile to mount. In case some of the data chunks are stored on 'sdb', +then the constraint of single/data is not satisfied and the filesystem +cannot be mounted. *device='devicepath'*:: Specify a path to a device that will be scanned for BTRFS filesystem during @@ -174,14 +205,22 @@ system at that point. *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 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` tool that lets the filesystem discard all free blocks in a batch, +`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 ignore the TRIM command if the range is too small, so running the batch discard can actually discard the blocks. @@ -215,7 +254,7 @@ This option forces any data dirtied by a write in a prior transaction to commit as part of the current commit, effectively a full filesystem sync. + 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 +the application's perspective (i.e. it includes all completed file system operations). This was previously the behavior only when a snapshot was created. + @@ -245,6 +284,14 @@ the option. + NOTE: Defaults to off due to a potential overflow problem when the free space checksums don't fit inside a single page. ++ +Don't use this option unless you really need it. The inode number limit +on 64bit system is 2^64^, which is practically enough for the whole filesystem +lifetime. Due to implemention of linux VFS layer, the inode numbers on 32bit +systems are only 32 bits wide. This lowers the limit significantly and makes +it possible to reach it. In such case, this mount option will help. +Alternatively, files with high inode numbers can be copied to a new subvolume +which will effectively start the inode numbers from the beginning again. *logreplay*:: *nologreplay*:: @@ -258,7 +305,7 @@ disable that behaviour, mount also with 'nologreplay'. *max_inline='bytes'*:: (default: min(2048, page size) ) + -Specify the maximum amount of space, in bytes, that can be inlined in +Specify the maximum amount of space, 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), @@ -319,8 +366,8 @@ the space cache consumes some resources, including a small amount of disk space. + There are two implementations of the free space cache. The original -implementation, 'v1', is the safe default. The 'v1' space cache can be disabled -at mount time with 'nospace_cache' without clearing. +one, referred to as 'v1', is the safe default. The 'v1' space cache can be +disabled at mount time with 'nospace_cache' without clearing. + On very large filesystems (many terabytes) and certain workloads, the performance of the 'v1' space cache may degrade drastically. The 'v2' @@ -329,12 +376,12 @@ this issue. Once enabled, the 'v2' space cache will always be used and cannot be disabled unless it is cleared. Use 'clear_cache,space_cache=v1' or 'clear_cache,nospace_cache' to do so. If 'v2' is enabled, kernels without 'v2' support will only be able to mount the filesystem in read-only mode. The -`btrfs(8)` command currently only has read-only support for 'v2'. A read-write +`btrfs`(8) command currently only has read-only support for 'v2'. A read-write command may be run on a 'v2' filesystem by clearing the cache, running the command, and then remounting with 'space_cache=v2'. + If a version is not explicitly specified, the default implementation will be -chosen, which is 'v1' as of 4.9. +chosen, which is 'v1'. *ssd*:: *ssd_spread*:: @@ -342,10 +389,22 @@ chosen, which is 'v1' as of 4.9. (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 non-rotational device is in use (contents of -'/sys/block/DEV/queue/rotational'). If it is, the 'ssd' option is turned on. -The option 'nossd' will disable the autodetection. +enable or disable SSD optimizations depending on status of a device with +respect to rotational or non-rotational type. This is determined by the +contents of '/sys/block/DEV/queue/rotational'). If it is 1, the 'ssd' option is +turned on. The option 'nossd' will disable the autodetection. ++ +The optimizations make use of the absence of the seek penalty that's inherent +for the rotational devices. The blocks can be typically written faster and +are not offloaded to separate threads. ++ +NOTE: Since 4.14, the block layout optimizations have been dropped. This used +to help with first generations of SSD devices. Their FTL (flash translation +layer) was not effective and the optimization was supposed to improve the wear +by better aligning blocks. This is no longer true with modern SSD devices and +the optimization had no real benefit. Furthermore it caused increased +fragmentation. The layout tuning has been kept intact for the option +'ssd_spread'. + 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' @@ -354,25 +413,26 @@ will disable all SSD options. *subvol='path'*:: Mount subvolume from 'path' rather than the toplevel subvolume. The -'path' is absolute (ie. starts at the toplevel subvolume). +'path' is always treated as relative to the 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. +subvolume. You can use *btrfs subvolume list* of *btrfs subvolume show* 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. +same subvolume, otherwise the mount will fail. *thread_pool='number'*:: (default: min(NRCPUS + 2, 8) ) + -The number of worker threads to allocate. NRCPUS is number of on-line CPUs +The number of worker threads to start. 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 hit -due to increased locking contention, cache-line bouncing or costly data -transfers between local CPU memories. +due to increased locking contention, process scheduling, cache-line bouncing or +costly data transfers between local CPU memories. *treelog*:: *notreelog*:: @@ -384,13 +444,14 @@ 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! To -disable that behaviour, mount also with 'nologreplay'. +disable that behaviour, also mount 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*:: +(since: 4.6, 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 @@ -403,6 +464,11 @@ NOTE: This option has replaced 'recovery'. + Allow subvolumes to be deleted by their respective owner. Otherwise, only the root user can do that. ++ +NOTE: historically, any user could create a snapshot even if he was not owner +of the source subvolume, the subvolume deletion has been restricted for that +reason. The subvolume creation has been restricted but this mount option is +still required. This is a usability issue and will be addressed in the future. DEPRECATED MOUNT OPTIONS ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -428,6 +494,25 @@ but will work on 4.5+ kernels. 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. +NOTES ON GENERIC MOUNT OPTIONS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the general mount options from `mount`(8) that affect BTRFS and are +worth mentioning. + +*noatime*:: +under read intensive work-loads, specifying 'noatime' significantly improves +performance because no new access time information needs to be written. Without +this option, the default is 'relatime', which only reduces the number of +inode atime updates in comparison to the traditional 'strictatime'. The worst +case for atime updates under 'relatime' occurs when many files are read whose +atime is older than 24 h and which are freshly snapshotted. In that case the +atime is updated 'and' COW happens - for each file - in bulk. See also +https://lwn.net/Articles/499293/ - 'Atime and btrfs: a bad combination? (LWN, 2012-05-31)'. ++ +Note that 'noatime' may break applications that rely on atime uptimes like +the venerable Mutt (unless you use maildir mailboxes). + FILESYSTEM FEATURES ------------------- @@ -566,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. diff --git a/Documentation/btrfs-map-logical.8.gz b/Documentation/btrfs-map-logical.8.gz index ce04a33a..a1ae0432 100644 Binary files a/Documentation/btrfs-map-logical.8.gz and b/Documentation/btrfs-map-logical.8.gz differ diff --git a/Documentation/btrfs-map-logical.asciidoc b/Documentation/btrfs-map-logical.asciidoc index a3d110cb..34b22c0d 100644 --- a/Documentation/btrfs-map-logical.asciidoc +++ b/Documentation/btrfs-map-logical.asciidoc @@ -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. diff --git a/Documentation/btrfs-property.8.gz b/Documentation/btrfs-property.8.gz index e8a46fc9..d8ecdf79 100644 Binary files a/Documentation/btrfs-property.8.gz and b/Documentation/btrfs-property.8.gz differ diff --git a/Documentation/btrfs-property.asciidoc b/Documentation/btrfs-property.asciidoc index 7ed6a7df..b562717b 100644 --- a/Documentation/btrfs-property.asciidoc +++ b/Documentation/btrfs-property.asciidoc @@ -3,7 +3,7 @@ btrfs-property(8) NAME ---- -btrfs-property - get/set/list properties for given btrfs object. +btrfs-property - get/set/list properties for given filesystem object SYNOPSIS -------- @@ -11,8 +11,9 @@ SYNOPSIS DESCRIPTION ----------- -*btrfs property* is used to get/set/list property for given btrfs object. -See the description of *get* subcommand for more information about +*btrfs property* is used to get/set/list property for given filesystem object. +The object can be an inode (file or directory), subvolume or the whole +filesystem. See the description of *get* subcommand for more information about both btrfs object and property. *btrfs property* provides an unified and user-friendly method to tune different @@ -22,28 +23,30 @@ btrfs properties instead of using the traditional method like `chattr`(1) or SUBCOMMAND ---------- *get* [-t ] []:: -Gets a property from a btrfs object. +get property from a btrfs of given + A btrfs object, which is set by , can be a btrfs filesystem -itself, a btrfs subvolume, an inode(file or directory) inside btrfs, +itself, a btrfs subvolume, an inode (file or directory) inside btrfs, or a device on which a btrfs exists. + The option '-t' can be used to explicitly specify what type of object you meant. This is only needed when a property could be set for more then one object type. + -Possible types are 's[ubvol]', 'f[ilesystem]', 'i[node]' and 'd[evice]'. +Possible types are 's[ubvol]', 'f[ilesystem]', 'i[node]' and 'd[evice]', where +the first lettes is a shortcut. + Set the name of property by 'name'. If no 'name' is specified, all properties for the given object are printed. 'name' is one of -the followings. +the following: ro:::: read-only flag of subvolume: true or false label:::: label of device compression:::: -compression setting for an inode: lzo, zlib, zstd, or "" (empty string) +compression algorithm set for an inode, possible values: 'lzo', 'zlib', 'zstd'. +To disable compression use "" (empty string), 'no' or 'none'. *list* [-t ] :: Lists available properties with their descriptions for the given object. diff --git a/Documentation/btrfs-qgroup.8.gz b/Documentation/btrfs-qgroup.8.gz index 8201a6e9..a493240d 100644 Binary files a/Documentation/btrfs-qgroup.8.gz and b/Documentation/btrfs-qgroup.8.gz differ diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc index 3053f2e6..3108457c 100644 --- a/Documentation/btrfs-qgroup.asciidoc +++ b/Documentation/btrfs-qgroup.asciidoc @@ -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/' qgroup, a qgroup can be created even before the -subvolume created. +subvolume is created. *destroy* :: 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] |none [] :: Limit the size of a qgroup to or no limit in the btrfs filesystem diff --git a/Documentation/btrfs-quota.8.gz b/Documentation/btrfs-quota.8.gz index 7c6c3001..5a94e29f 100644 Binary files a/Documentation/btrfs-quota.8.gz and b/Documentation/btrfs-quota.8.gz differ diff --git a/Documentation/btrfs-quota.asciidoc b/Documentation/btrfs-quota.asciidoc index f882647d..85ebf729 100644 --- a/Documentation/btrfs-quota.asciidoc +++ b/Documentation/btrfs-quota.asciidoc @@ -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. diff --git a/Documentation/btrfs-receive.8.gz b/Documentation/btrfs-receive.8.gz index 4b53e360..c842f36e 100644 Binary files a/Documentation/btrfs-receive.8.gz and b/Documentation/btrfs-receive.8.gz differ diff --git a/Documentation/btrfs-receive.asciidoc b/Documentation/btrfs-receive.asciidoc index 1f6847a9..cbd88e6a 100644 --- a/Documentation/btrfs-receive.asciidoc +++ b/Documentation/btrfs-receive.asciidoc @@ -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 diff --git a/Documentation/btrfs-replace.8.gz b/Documentation/btrfs-replace.8.gz index 75fce06e..c5d3d449 100644 Binary files a/Documentation/btrfs-replace.8.gz and b/Documentation/btrfs-replace.8.gz differ diff --git a/Documentation/btrfs-replace.asciidoc b/Documentation/btrfs-replace.asciidoc index 9a8a9ea1..35ecb1f8 100644 --- a/Documentation/btrfs-replace.asciidoc +++ b/Documentation/btrfs-replace.asciidoc @@ -34,7 +34,7 @@ from the system, you have to use the devid parameter format. The needs to be same size or larger than the . + 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 :max /path` + `Options` @@ -45,10 +45,10 @@ only read from if no other zero-defect mirror exists. slow) -f:::: force using and overwriting 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 . + -B:::: diff --git a/Documentation/btrfs-rescue.8.gz b/Documentation/btrfs-rescue.8.gz index cbf07923..11ea6215 100644 Binary files a/Documentation/btrfs-rescue.8.gz and b/Documentation/btrfs-rescue.8.gz differ diff --git a/Documentation/btrfs-rescue.asciidoc b/Documentation/btrfs-rescue.asciidoc index 24b619c6..743a23a6 100644 --- a/Documentation/btrfs-rescue.asciidoc +++ b/Documentation/btrfs-rescue.asciidoc @@ -15,6 +15,7 @@ DESCRIPTION SUBCOMMAND ---------- + *chunk-recover* [options] :: Recover the chunk tree by scanning the devices + @@ -30,6 +31,25 @@ help. NOTE: Since *chunk-recover* will scan the whole device, it will be *VERY* slow especially executed on a large device. +*fix-device-size* :: +fix device size and super block total bytes values that are do not match ++ +Kernel 4.11 starts to check the device size more strictly and this might +mismatch the stored value of total bytes. See the exact error message below. +Newer kernel will refuse to mount the filesystem where the values do not match. +This error is not fatal and can be fixed. This command will fix the device +size values if possible. ++ +---- +BTRFS error (device sdb): super_total_bytes 92017859088384 mismatch with fs_devices total_rw_bytes 92017859094528 +---- ++ +The mismatch may also exhibit as a kernel warning: ++ +---- +WARNING: CPU: 3 PID: 439 at fs/btrfs/ctree.h:1559 btrfs_update_device+0x1c5/0x1d0 [btrfs] +---- + *super-recover* [options] :: Recover bad superblocks from good copies. + @@ -47,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 diff --git a/Documentation/btrfs-restore.8.gz b/Documentation/btrfs-restore.8.gz index 2fa149f6..c4c2b201 100644 Binary files a/Documentation/btrfs-restore.8.gz and b/Documentation/btrfs-restore.8.gz differ diff --git a/Documentation/btrfs-scrub.8.gz b/Documentation/btrfs-scrub.8.gz index edfc4390..56b3a58f 100644 Binary files a/Documentation/btrfs-scrub.8.gz and b/Documentation/btrfs-scrub.8.gz differ diff --git a/Documentation/btrfs-scrub.asciidoc b/Documentation/btrfs-scrub.asciidoc index eb90a1c4..d2d20627 100644 --- a/Documentation/btrfs-scrub.asciidoc +++ b/Documentation/btrfs-scrub.asciidoc @@ -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 diff --git a/Documentation/btrfs-select-super.8.gz b/Documentation/btrfs-select-super.8.gz index 2cf064db..e19b070f 100644 Binary files a/Documentation/btrfs-select-super.8.gz and b/Documentation/btrfs-select-super.8.gz differ diff --git a/Documentation/btrfs-send.8.gz b/Documentation/btrfs-send.8.gz index 06002bd1..e7afb09a 100644 Binary files a/Documentation/btrfs-send.8.gz and b/Documentation/btrfs-send.8.gz differ diff --git a/Documentation/btrfs-send.asciidoc b/Documentation/btrfs-send.asciidoc index ef345f68..cd7ada76 100644 --- a/Documentation/btrfs-send.asciidoc +++ b/Documentation/btrfs-send.asciidoc @@ -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 ' option when '-c ' options -are given, in which case *btrfs send* will determine a suitable parent among the -clone sources itself. +The '-p ' option can be omitted when '-c ' 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 diff --git a/Documentation/btrfs-subvolume.8.gz b/Documentation/btrfs-subvolume.8.gz index 3d8519a5..9ae7d367 100644 Binary files a/Documentation/btrfs-subvolume.8.gz and b/Documentation/btrfs-subvolume.8.gz differ diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc index 5cfe8856..a8c4af4b 100644 --- a/Documentation/btrfs-subvolume.asciidoc +++ b/Documentation/btrfs-subvolume.asciidoc @@ -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 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 @@ -142,29 +142,37 @@ you can add \'\+' or \'-' in front of each items, \'+' means ascending, for --sort you can combine some items together by \',', just like --sort=+ogen,-gen,path,rootid. -*set-default* :: -Set the subvolume of the filesystem which is mounted as -default. +*set-default* [| ]:: +Set the default subvolume for the (mounted) filesystem. + +Set the default subvolume for the (mounted) filesystem at . This will hide +the top-level subvolume (ie. the one mounted with 'subvol=/' or 'subvolid=5'). +Takes action on next mount. + -The subvolume is identified by , which is returned by the *subvolume list* -command. +There are two ways how to specify the subvolume, by or by the +path. +The id can be obtained from *btrfs subvolume list*, *btrfs subvolume show* or +*btrfs inspect-internal rootid*. *show* :: Show information of a given subvolume in the . *snapshot* [-r] |[/]:: -Create a writable/readonly snapshot of the subvolume with the +Create a snapshot of the subvolume with the name in the directory. + If only is given, the subvolume will be named the basename of . If is not a subvolume, btrfs returns an error. -If '-r' is given, the snapshot will be readonly. ++ +`Options` ++ +-r:::: +Make the new snapshot read only. *sync* [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` + diff --git a/Documentation/btrfs.5.gz b/Documentation/btrfs.5.gz index b72078a8..f0dbd468 100644 Binary files a/Documentation/btrfs.5.gz and b/Documentation/btrfs.5.gz differ diff --git a/Documentation/btrfs.8.gz b/Documentation/btrfs.8.gz index 0330e855..13d14727 100644 Binary files a/Documentation/btrfs.8.gz and b/Documentation/btrfs.8.gz differ diff --git a/Documentation/btrfs.asciidoc b/Documentation/btrfs.asciidoc index 100a6adf..82530234 100644 --- a/Documentation/btrfs.asciidoc +++ b/Documentation/btrfs.asciidoc @@ -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-*. +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-*. 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*: diff --git a/Documentation/btrfstune.8.gz b/Documentation/btrfstune.8.gz index 30a81a82..9de752e8 100644 Binary files a/Documentation/btrfstune.8.gz and b/Documentation/btrfstune.8.gz differ diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc index cd7bb532..27100964 100644 --- a/Documentation/btrfstune.asciidoc +++ b/Documentation/btrfstune.asciidoc @@ -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 -------- diff --git a/Documentation/fsck.btrfs.8.gz b/Documentation/fsck.btrfs.8.gz index 86c8bfc6..1275946e 100644 Binary files a/Documentation/fsck.btrfs.8.gz and b/Documentation/fsck.btrfs.8.gz differ diff --git a/Documentation/fsck.btrfs.asciidoc b/Documentation/fsck.btrfs.asciidoc index 0bad075b..9a174a60 100644 --- a/Documentation/fsck.btrfs.asciidoc +++ b/Documentation/fsck.btrfs.asciidoc @@ -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 ------- diff --git a/Documentation/mkfs.btrfs.8.gz b/Documentation/mkfs.btrfs.8.gz index 11956269..c455e9ea 100644 Binary files a/Documentation/mkfs.btrfs.8.gz and b/Documentation/mkfs.btrfs.8.gz differ diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc index d53d9e26..f69c529d 100644 --- a/Documentation/mkfs.btrfs.asciidoc +++ b/Documentation/mkfs.btrfs.asciidoc @@ -21,13 +21,8 @@ mount option. See section *MULTIPLE DEVICES* for more details. OPTIONS ------- -*-A|--alloc-start *:: -(An option to help debugging chunk allocator.) -Specify the (physical) offset from the start of the device at which allocations -start. The default value is zero. - *-b|--byte-count *:: -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 *:: @@ -79,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 lead 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. @@ -135,6 +130,12 @@ Print the *mkfs.btrfs* version and exit. *--help*:: Print help. +*-A|--alloc-start *:: +*deprecated, will be removed* +(An option to help debugging chunk allocator.) +Specify the (physical) offset from the start of the device at which allocations +start. The default value is zero. + SIZE UNITS ---------- The default unit is 'byte'. All size parameters accept suffixes in the 1024 @@ -166,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 @@ -281,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 -- cgit v1.2.3