path: root/Documentation
diff options
authorDimitri John Ledkov <>2017-02-13 11:24:33 +0000
committerDimitri John Ledkov <>2017-02-13 11:24:33 +0000
commit4305d024938113df5d73021a09eb2a991f54ca2f (patch)
treed9e7ecc9db14bcc1394607a9e6c644a8b93e9bea /Documentation
parente693f0e4ffb1776a05b78264ee3d93d5f07efede (diff)
New upstream release Closes: #849353, #817806, #854915, #845473
Diffstat (limited to 'Documentation')
13 files changed, 152 insertions, 72 deletions
diff --git a/Documentation/ReleaseChecklist b/Documentation/ReleaseChecklist
new file mode 100644
index 00000000..d8bf50c1
--- /dev/null
+++ b/Documentation/ReleaseChecklist
@@ -0,0 +1,37 @@
+Release checklist
+Last code touches:
+* make the code ready, collect patches queued for the release
+* look to mailinglist for any relevant last-minute fixes
+* update package in OBS, (multi arch build checks)
+* submit sources to coverity
+* run all internal functional tests
+ * defaults
+ * D=asan
+ * D=ubsan
+* run all build tests
+* run with fstests
+* write CHANGES entry
+* tag release, sign
+* make tar
+* build check of unpacked tar
+* upload tar to
+* refresh git branches, push tags
+* write and send announcement mail to mailinglist
+* update wiki://Main_page#News
+* update wiki://Changelog#btrfs-progs
+* update title on IRC
diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc
index abc9f0dc..633cbbf6 100644
--- a/Documentation/btrfs-check.asciidoc
+++ b/Documentation/btrfs-check.asciidoc
@@ -20,7 +20,7 @@ by the option '--readonly'.
*btrfsck* is an alias of *btrfs check* command and is now deprecated.
-WARNING: Do not use '--repair' unless you are adviced to by a developer, an
+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
@@ -78,6 +78,20 @@ respective superblock offset is within the device size
This can be used to use a different starting point if some of the primary
superblock is damaged.
+--clear-space-cache v1|v2::
+completely wipe all free space cache of given type
+For free space cache 'v1', the 'clear_cache' kernel mount option only rebuilds
+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
+method of clearing the free space cache that doesn't require mounting the
diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc
index ecc157cd..cbc1c730 100644
--- a/Documentation/btrfs-convert.asciidoc
+++ b/Documentation/btrfs-convert.asciidoc
@@ -33,6 +33,9 @@ have 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
+NOTE: The source filesystem should be clean, you are encouraged to run the
+'fsck' tool if you're not sure.
By removing the 'ext2_saved' subvolume, all metadata of the original filesystem
diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc
index d05fc457..eedcac85 100644
--- a/Documentation/btrfs-device.asciidoc
+++ b/Documentation/btrfs-device.asciidoc
@@ -27,7 +27,7 @@ The device management works on a mounted filesystem. Devices can be added,
removed or replaced, by commands profided by *btrfs device* and *btrfs replace*.
The profiles can be also changed, provided there's enough workspace to do the
-conversion, using the *btrfs balance* comand and namely the filter 'convert'.
+conversion, using the *btrfs balance* command and namely the filter 'convert'.
A profile describes an allocation policy based on the redundancy/replication
@@ -98,16 +98,22 @@ remain as such. Reloading the kernel module will drop this information. There's
an alternative way of mounting multiple-device filesystem without the need for
prior scanning. See the mount option 'device'.
-*stats* [-z] <path>|<device>::
+*stats* [options] <path>|<device>::
Read and print the device IO error statistics for all devices of the given
-filesystem identified by <path> or for a single <device>. See section *DEVICE
-STATS* for more information.
+filesystem identified by <path> or for a single <device>. The filesystem must
+be mounted. See section *DEVICE STATS* for more information about the reported
+statistics and the meaning.
Print the stats and reset the values to zero afterwards.
+Check if the stats are all zeros and return 0 it it 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.
*usage* [options] <path> [<path>...]::
Show detailed information about internal allocations in devices.
@@ -180,7 +186,7 @@ logial mappings).
What changed:
-* available data space decreased by 3GiB, usable rougly (50 - 3) + (100 - 3) = 144 GiB
+* available data space decreased by 3GiB, usable roughly (50 - 3) + (100 - 3) = 144 GiB
* metadata redundancy increased
IOW, the unequal device sizes allow for combined space for data yet improved
@@ -231,6 +237,9 @@ EXIT STATUS
*btrfs device* returns a zero exit status if it succeeds. Non zero is
returned in case of failure.
+If the '-s' option is used, *btrfs device stats* will add 64 to the
+exit status if any of the error counters is non-zero.
*btrfs* is part of btrfs-progs.
diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc
index 9782af9b..0f7ea495 100644
--- a/Documentation/btrfs-filesystem.asciidoc
+++ b/Documentation/btrfs-filesystem.asciidoc
@@ -80,7 +80,7 @@ show sizes in TiB, or TB with --si
If conflicting options are passed, the last one takes precedence.
*defragment* [options] <file>|<dir> [<file>|<dir>...]::
-Defragment file data on a mounted filesystem.
+Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer.
If '-r' is passed, files in dir will be defragmented recursively.
The start position and the number of bytes to defragment can be specified by
diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc
index caa9390b..acc4e429 100644
--- a/Documentation/btrfs-man5.asciidoc
+++ b/Documentation/btrfs-man5.asciidoc
@@ -319,25 +319,32 @@ May be resumed with *btrfs balance resume* or the paused state can be removed
by *btrfs balance cancel*. The default behaviour is to start interrutpd balance.
-('nospace_cache' since: 3.2, 'space_cache=v2' since 4.5, default: on)
-Options to control the free space cache. This affects performance as searching
-for new free blocks could take longer if the space cache is not enabled. On the
-other hand, managing the space cache consumes some resources. It can be
-disabled without clearing at mount time.
-There are two implementations of how the space is tracked. The safe default is
-'v1'. On large filesystems (many-terabytes) and certain workloads the 'v1'
-performance may degrade. This problem is addressed by 'v2', that is based on
-b-trees, sometimes referred to as 'free-space-tree'.
-'Compatibility notes:'
-* the 'v2' has to be enabled manually at mount time, once
-* kernel without 'v2' support will be able to mount the filesystem in read-only mode
-* 'v2' can be removed by mounting with 'clear_cache'
+('nospace_cache' since: 3.2, 'space_cache=v1' and 'space_cache=v2' since 4.5, default: 'space_cache=v1')
+Options to control the free space cache. The free space cache greatly improves
+performance when reading block group free space into memory. However, managing
+the space cache consumes some resources, including a small amount of disk
+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.
+On very large filesystems (many terabytes) and certain workloads, the
+performance of the 'v1' space cache may degrade drastically. The 'v2'
+implementation, which adds a new B-tree called the free space tree, addresses
+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
+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.
@@ -434,7 +441,7 @@ dump-super device* will dump a superblock, you can map the value of
after mkfs, on a mounted filesystem::
The features of a filesystem (with a given UUID) are listed in
`/sys/fs/btrfs/UUID/features/`, one file per feature. The status of is stored
-insid the file. The value '1' is for enabled, '0' means the feature was had
+insid the file. The value '1' is for enabled, '0' means the feature had
been enabled at the mount time and turned off afterwards.
Whether a particular feature can be turned on a mounted filesystem can be found
@@ -562,7 +569,7 @@ crw------- 1 root root 10, 234 Jan 1 12:00 /dev/btrfs-control
The device accepts some ioctl calls that can perform following actions on the
filesyste module:
-* scan devices for btrfs filesytem (ie. to let multi-device filesystems mount
+* scan devices for btrfs filesystem (ie. to let multi-device filesystems mount
automatically) and register them with the kernel module
* similar to scan, but also wait until the device scanning process is finished
for a given filesystem
diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc
index 438dbc7d..3053f2e6 100644
--- a/Documentation/btrfs-qgroup.asciidoc
+++ b/Documentation/btrfs-qgroup.asciidoc
@@ -126,6 +126,10 @@ Prefix \'+' means ascending order and \'-' means descending order of <attr>.
If no prefix is given, use ascending order by default.
If multiple <attr>s is given, use comma to separate.
+To retrieve information after updating the state of qgroups,
+force sync of the filesystem identified by <path> before getting information.
diff --git a/Documentation/btrfs-quota.asciidoc b/Documentation/btrfs-quota.asciidoc
index 33c3bfd7..77d4c685 100644
--- a/Documentation/btrfs-quota.asciidoc
+++ b/Documentation/btrfs-quota.asciidoc
@@ -16,7 +16,7 @@ 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
-to track shared and exlusive data per-subvolume. Plese refer to the section
+to track shared and exclusive data per-subvolume. Please refer to the section
'HIERARCHICAL QUOTA GROUP CONCEPTS' for a detailed description.
@@ -91,7 +91,7 @@ Qgroups of level 0 get created automatically when a subvolume/snapshot gets
created. The ID of the qgroup corresponds to the ID of the subvolume, so 0/5
is the qgroup for the root subvolume.
For the *btrfs qgroup* command, the path to the subvolume can also be used
-instead of '0/ID'. For all higher levels, the ID can be choosen freely.
+instead of '0/ID'. For all higher levels, the ID can be chosen freely.
Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy
of qgroups. Figure 1 shows an example qgroup tree.
diff --git a/Documentation/btrfs-receive.asciidoc b/Documentation/btrfs-receive.asciidoc
index e246603c..a6838e5e 100644
--- a/Documentation/btrfs-receive.asciidoc
+++ b/Documentation/btrfs-receive.asciidoc
@@ -9,32 +9,37 @@ SYNOPSIS
*btrfs receive* [options] <path>
+*btrfs receive* --dump [options]
Receive a stream of changes and replicate one or more subvolumes that were
-previously used with *btrfs send* The received subvolumes are stored to
+previously generated by *btrfs send*. The received subvolumes are stored to
+'path', unless '--dump' option is given.
+If '--dump' option is specified, *btrfs receive* will only do the validation of
+the stream, and print the stream metadata, one operation per line.
*btrfs receive* will fail int the following cases:
1. receiving subvolume already exists
-2. previously received subvolume was changed after it was received
+2. previously received subvolume has been changed after it was received
-3. default subvolume has changed or you didn't mount BTRFS filesystem at the toplevel subvolume
+3. default subvolume has changed or you didn't mount the filesystem at the toplevel subvolume
A subvolume is made read-only after the receiving process finishes succesfully.
-enable verbose debug output, print each operation (each occurrence of this
-option increases the verbosity level)
+increase verbosity about performed actions, print details about each operation
--f <infile>::
-by default, btrfs receive uses standard input to receive the stream,
-use this option to read from a file instead
+-f <FILE>::
+read the stream from <FILE> instead of stdin,
confine the process to 'path' using `chroot`(1)
@@ -42,19 +47,26 @@ confine the process to 'path' using `chroot`(1)
terminate after receiving an 'end cmd' marker in the stream.
-Without this option, the receiver terminates only if an error is encountered
-or at end of file
+Without this option the receiver side terminates only in case
+of an error on end of file.
---max-errors <N>::
-terminate as soon as N errors happened while processing commands from the send
-stream, default value is 1, 0 means no limit
+-E|--max-errors <NERR>::
+terminate as soon as NERR errors occur while stream processing commands from
+the stream
+Default value is 1. A value of 0 means no limit.
--m <mountpoint>::
the root mount point of the destination filesystem
By default the mountpoint is searched in '/proc/self/mounts'.
-If you do not have '/proc', eg. in a chroot environment, use this option to tell
-us where this filesystem is mounted.
+If '/proc' is not accessible, eg. in a chroot environment, use this option to
+tell us where this filesystem is mounted.
+dump the stream metadata, one line per operation
+Does not require the 'path' parameter. The filesystem chanded.
diff --git a/Documentation/btrfs-scrub.asciidoc b/Documentation/btrfs-scrub.asciidoc
index 40e793c2..f579c39e 100644
--- a/Documentation/btrfs-scrub.asciidoc
+++ b/Documentation/btrfs-scrub.asciidoc
@@ -20,7 +20,7 @@ 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 filesytem. The IO priority class is by
+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.
@@ -34,7 +34,7 @@ saved position.
*cancel* <path>|<device>::
-If a scrub is running on the filesystem identified by 'path>' cancel it.
+If a scrub is running on the filesystem identified by 'path' cancel it.
If a 'device' is specified, the corresponding filesystem is found and
*btrfs scrub cancel* behaves as if it was called on that filesystem.
@@ -95,7 +95,14 @@ print separate statistics for each device of the filesystem
*btrfs scrub* returns a zero exit status if it succeeds. Non zero is
-returned in case of failure.
+returned in case of failure:
+scrub couldn't be performed
+there is nothing to resume
+scrub found uncorrectable errors
diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc
index 0a1ca003..3419b138 100644
--- a/Documentation/btrfs-subvolume.asciidoc
+++ b/Documentation/btrfs-subvolume.asciidoc
@@ -17,7 +17,7 @@ snapshots.
-A subvolume is a part of filesystem with it's own and independent
+A subvolume is a part of filesystem with its own and independent
file/directory hierarchy. Subvolumes can share file extents. A snapshot is
also subvolume, but with a given initial content of the original subvolume.
diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc
index 1e9aa703..04295ee3 100644
--- a/Documentation/btrfstune.asciidoc
+++ b/Documentation/btrfstune.asciidoc
@@ -20,7 +20,7 @@ complete list of features and kernel version of their introduction at . Also, the
manual page `mkfs.btrfs`(8) contains more details about the features.
-Some of the features could be enabled on a mounted filesytem. Please refer to
+Some of the features could be enabled on a mounted filesystem. Please refer to
the respective section in `btrfs`(5).
diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc
index 6515e145..46a4d2d5 100644
--- a/Documentation/mkfs.btrfs.asciidoc
+++ b/Documentation/mkfs.btrfs.asciidoc
@@ -7,25 +7,7 @@ mkfs.btrfs - create a btrfs filesystem
-$$[-A|--alloc-start <alloc-start>]$$
-$$[-b|--byte-count <byte-count>]$$
-$$[-d|--data <data-profile>]$$
-$$[-m|--metadata <metadata profile>]$$
-$$[-l|--leafsize <leafsize>]$$
-$$[-n|--nodesize <nodesize>]$$
-$$[-s|--sectorsize <sectorsize>]$$
-$$[-L|--label <label>]$$
-$$[-r|--rootdir <rootdir>]$$
-$$[-O|--features <feature1>[,<feature2>...]]$$
-$$[-U|--uuid <UUID>]$$
-$$<device> [<device>...]$$
+*mkfs.btrfs* [options] <device> [<device>...]
@@ -118,6 +100,8 @@ bytes and must not contain newline characters.
Do not perform whole device TRIM operation on devices that are capable of that.
+This does not affect discard/trim operation when the filesystem is mounted.
+Please see the mount option 'discard' for that in `btrfs`(5).
*-r|--rootdir <rootdir>*::
Populate the toplevel subvolume with files from 'rootdir'. This does not
@@ -182,6 +166,9 @@ 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
+employed for production use.
@@ -271,7 +258,7 @@ There are the following block group types available:
| RAID6 | 1 | 2 | 3 to N - 2 | 3/any ^(see note 3)^
-WARNING: It's not recommended to build btrfs with RAID0/1/10/5/6 prfiles on
+WARNING: It's not recommended to build btrfs with RAID0/1/10/5/6 profiles on
partitions from the same device. Neither redundancy nor performance will be