diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/btrfs-check.asciidoc | 93 | ||||
| -rw-r--r-- | Documentation/btrfs-convert.asciidoc | 1 | ||||
| -rw-r--r-- | Documentation/btrfs-device.asciidoc | 205 | ||||
| -rw-r--r-- | Documentation/btrfs-man5.asciidoc | 89 | ||||
| -rw-r--r-- | Documentation/btrfs-receive.asciidoc | 54 | ||||
| -rw-r--r-- | Documentation/btrfs-restore.asciidoc | 55 | ||||
| -rw-r--r-- | Documentation/btrfs-scrub.asciidoc | 51 | ||||
| -rw-r--r-- | Documentation/btrfs-select-super.asciidoc | 36 | ||||
| -rw-r--r-- | Documentation/btrfs-send.asciidoc | 49 | ||||
| -rw-r--r-- | Documentation/btrfs-subvolume.asciidoc | 2 | ||||
| -rw-r--r-- | Documentation/mkfs.btrfs.asciidoc | 23 |
11 files changed, 460 insertions, 198 deletions
diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc index 7371a23c..74a2ad21 100644 --- a/Documentation/btrfs-check.asciidoc +++ b/Documentation/btrfs-check.asciidoc @@ -11,42 +11,87 @@ SYNOPSIS DESCRIPTION ----------- -*btrfs check* is used to check or repair an unmounted btrfs filesystem. -NOTE: Since btrfs is under development, the *btrfs check* capabilities are -continuously enhanced. It's highly recommended to read the following btrfs -wiki before executing *btrfs check* with '--repair' option: + -https://btrfs.wiki.kernel.org/index.php/Btrfsck +The filesystem checker is used to verify structural integrity of a filesystem +and attempt to repair it if requested. The filesystem must be unmounted. + +By default, *btrfs check* will not modify the device but you can reaffirm that +by the option '--readonly'. *btrfsck* is an alias of *btrfs check* command and is now deprecated. -OPTIONS -------- --s|--super <superblock>:: -use <superblock>th superblock copy, valid values are 0 up to 2 if the -respective superblock offset is within the filesystem +WARNING: Do not use '--repair' unless you are adviced 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. + +The structural integrity check verifies if internal filesystem objects or +data structures satisfy the constraints, point to the right objects or are +correctly connected together. + +There are several cross checks that can detect wrong reference counts of shared +extents, backrefrences, missing extents of inodes, directory and inode +connectivity etc. + +The amount of memory required can be high, depending on the size of the +filesystem, smililarly the run time. + +SAFE OR ADVISORY OPTIONS +------------------------ + -b|--backup:: -use the first backup roots stored in the superblock that is valid ---repair:: -try to repair the filesystem ---readonly:: -run in read-only mode (default) ---init-csum-tree:: -create a new CRC tree and recalculate all checksums ---init-extent-tree:: -create a new extent tree +use the first valid set of backup roots stored in the superblock ++ +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 coipes. + +--chunk-root <bytenr>:: +use the given offset 'bytenr' for the chunk tree root + +-E|--subvol-extents <subvolid>:: +show extent state for the given subvolume + -p|--progress:: indicate progress at various checking phases + --qgroup-report:: verify qgroup accounting and compare against filesystem accounting --E|--subvol-extents <subvolid>:: -show extent state for the given subvolume + -r|--tree-root <bytenr>:: -use the given bytenr for the tree root ---chunk-root <bytenr>:: -use the given bytenr for the chunk tree root +use the given offset 'bytenr' for the tree root + +--readonly:: +(default) +run in read-only mode, this option exists to calm potential panic when users +are going to run the checker + +-s|--super <superblock>:: +use 'superblock'th superblock copy, valid values are 0, 1 or 2 if the +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. + +DANGEROUS OPTIONS +----------------- + +--repair:: +enable the repair mode and attempt to fix problems where possible +--init-csum-tree:: +create a new checksum tree and recalculate checksums in all files ++ +NOTE: Do not blindly use this option to fix checksum mismatch problems. + +--init-extent-tree:: +build the extent tree from scratch ++ +NOTE: Do not use unless you know what you're doing. EXIT STATUS ----------- diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc index 28f9a394..ab3577db 100644 --- a/Documentation/btrfs-convert.asciidoc +++ b/Documentation/btrfs-convert.asciidoc @@ -90,6 +90,7 @@ are supported by old kernels. To disable a feature, prefix it with '^'. To see all available features that btrfs-convert supports run: + +btrfs-convert -O list-all+ ++ -p|--progress:: show progress of conversion, on by default --no-progress:: diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc index edd9b98e..d05fc457 100644 --- a/Documentation/btrfs-device.asciidoc +++ b/Documentation/btrfs-device.asciidoc @@ -3,7 +3,7 @@ btrfs-device(8) NAME ---- -btrfs-device - control btrfs devices +btrfs-device - manage devices of btrfs filesystems SYNOPSIS -------- @@ -11,95 +11,102 @@ SYNOPSIS DESCRIPTION ----------- -*btrfs device* is used to control the btrfs devices, since btrfs can be used -across several devices, *btrfs device* is used for multiple device management. +The *btrfs device* command group is used to manage devices of the btrfs filesystems. DEVICE MANAGEMENT ----------------- -Btrfs filesystem is capable to manage multiple devices. +Btrfs filesystem can be created on top of single or multiple block devices. +Data and metadata are organized in allocation profiles with various redundancy +policies. There's some similarity with traditional RAID levels, but this could +be confusing to users familiar with the traditional meaning. Due to the +similarity, the RAID terminology is widely used in the documentation. See +`mkfs.btrfs`(9) for more details and the exact profile capabilities and +constraints. -Btrfs filesystem uses different profiles to manage different RAID level, and -use balance to rebuild chunks, also devices can be added/removed/replace -online. +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'. Profile:: -Btrfs filesystem uses data/metadata profiles to manage allocation/duplication -mechanism. + -Profiles like RAID level can be assigned to data and metadata separately. -+ -See `mkfs.btrfs`(8) for more details. +A profile describes an allocation policy based on the redundancy/replication +constrants in connection with the number of devices. The profile applies to +data and metadata block groups separately. RAID level:: -Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10. + -RAID levels can be assigned at mkfs time or online. -+ -See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for -online RAID level assign. -+ -NOTE: Since btrfs is under heavy development especially the RAID5/6 support, -it is *highly* recommended to read the follow btrfs wiki page to get more -updated details on RAID5/6: + -https://btrfs.wiki.kernel.org/index.php/RAID56 - -Balance:: -`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the -desired profile. -+ -Due to the fact that balance can rebuild/recovery chunks according to its RAID -duplication if possible, so when using RAID1/5/6/10 with some devices failed -and you just added a new device to btrfs using `btrfs-device`(8), you should -run `btrfs-balance`(8) to rebuild the chunks. -+ -See `btrfs-balance`(8) for more details. +Where applicable, the level refers to a profile that matches constraints of the +standard RAID levels. At the moment the supported ones are: RAID0, RAID1, +RAID10, RAID5 and RAID6. -Device add/remove/replace:: -Device can be added/removed using `btrfs-device`(8) subcommand and replaced -using `btrfs-replace`(8). -+ -When device is removed or replaced, btrfs will do the chunk rebuild if needed. -+ -See `btrfs-replace`(8) man page for more details on device replace. +See the section *TYPICAL USECASES* for some examples. SUBCOMMAND ---------- *add* [-Kf] <dev> [<dev>...] <path>:: Add device(s) to the filesystem identified by <path>. + -If applicable, a whole device discard (TRIM) operation is performed. +If applicable, a whole device discard (TRIM) operation is performed prior to +adding the device. A device with existing filesystem detected by `blkid`(8) +will prevent device addition and has to be forced. Alternatively the filesystem +can be wiped from the device using eg. the `wipefs`(8) tool. ++ +The operation is instant and does not affect existing data. The operation merely +adds the device to the filesystem structures and creates some block groups +headers. + `Options` + -K|--nodiscard:::: -do not perform discard by default +do not perform discard (TRIM) by default -f|--force:::: force overwrite of existing filesystem on the given disk(s) *remove* <dev>|<devid> [<dev>|<devid>...] <path>:: -Remove device(s) from a filesystem identified by <path>. +Remove device(s) from a filesystem identified by <path> ++ +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. ++ +The operation can take long as it needs to move all data from the device. ++ +NOTE: It is not possible to delete the device that was used to mount the +filesystem. This is a limitation given by the VFS. *delete* <dev>|<devid> [<dev>|<devid>...] <path>:: Alias of remove kept for backward compatibility *ready* <device>:: -Check device to see if it has all of it's devices in cache for mounting. +Wait until all devices of a multiple-device filesystem are scanned and registered +within the kernel module. *scan* [(--all-devices|-d)|<device> [<device>...]]:: -Scan devices for a btrfs filesystem. +Scan devices for a btrfs filesystem and register them with the kernel module. +This allows mounting multiple-device filesystem by specifying just one from the +whole group. ++ +If no devices are passed, all block devices that blkid reports to contain btrfs +are scanned. + -If one or more devices are passed, these are scanned for a btrfs filesystem. -If no devices are passed, btrfs uses block devices containing btrfs -filesystem as listed by blkid. -Finally, '--all-devices' or '-d' is the deprecated option. If it is passed, -its behavior is the same as if no devices are passed. +The options '--all-devices' or '-d' are deprecated and kept for backward compatibility. +If used, behavior is the same as if no devices are passed. ++ +The command can be run repeatedly. Devices that have been already registered +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>:: -Read and print the device IO stats for all mounted devices of the filesystem -identified by <path> or for a single <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. + `Options` + -z:::: -Reset stats to zero after reading them. +Print the stats and reset the values to zero afterwards. *usage* [options] <path> [<path>...]:: Show detailed information about internal allocations in devices. @@ -127,6 +134,98 @@ show sizes in TiB, or TB with --si If conflicting options are passed, the last one takes precedence. +TYPICAL USECASES +---------------- + +STARTING WITH A SINGLE-DEVICE FILESYSTEM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assume we've created a filesystem on a block device '/dev/sda' with profile +'single/single' (data/metadata), the device size is 50GiB and we've used the +whole device for the filesystem. The mount point is '/mnt'. + +The amount of data stored is 16GiB, metadata have allocated 2GiB. + +==== ADD NEW DEVICE ==== + +We want to increase the total size of the filesystem and keep the profiles. The +size of the new device '/dev/sdb' is 100GiB. + + $ btrfs device add /dev/sdb /mnt + +The amount of free data space increases by less than 100GiB, some space is +allocated for metadata. + +==== CONVERT TO RAID1 ==== + +Now we want to increase the redundancy level of both data and metadata, but +we'll do that in steps. Note, that the device sizes are not equal and we'll use +that to show the capabilities of split data/metadata and independent profiles. + +The constraint for RAID1 gives us at most 50GiB of usable space and exactly 2 +copies will be stored on the devices. + +First we'll convert the metadata. As the metadata occupy less than 50GiB and +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 +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 +normally happens as the system block group also holds metadata (the physical to +logial mappings). + +What changed: + +* available data space decreased by 3GiB, usable rougly (50 - 3) + (100 - 3) = 144 GiB +* metadata redundancy increased + +IOW, the unequal device sizes allow for combined space for data yet improved +redundancy for metadata. If we decide to increase redundancy of data as well, +we're going to lose 50GiB of the second device for obvious reasons. + + $ btrfs balance start -dconvert=raid1 /mnt + +The balance process needs some workspace (ie. a free device space without any +data or metadata block groups) so the command could fail if there's too much +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. + +DEVICE STATS +------------ + +The device stats keep persistent record of several error classes related to +doing IO. The current values are printed at mount time and updated during +filesystem lifetime or from a scrub run. + + $ btrfs device stats /dev/sda3 + [/dev/sda3].write_io_errs 0 + [/dev/sda3].read_io_errs 0 + [/dev/sda3].flush_io_errs 0 + [/dev/sda3].corruption_errs 0 + [/dev/sda3].generation_errs 0 + +write_io_errs:: +Failed writes to the block devices, means that the layers beneath the +filesystem were not able to satisfy the write request. +read_io_errors:: +Read request analogy to write_io_errs. +flush_io_errs:: +Number of failed writes with the 'FLUSH' flag set. The flushing is a method of +forcing a particular order between write requests and is crucial for +implementing crash consistency. In case of btrfs, all the metadata blocks must +be permanently stored on the block device before the superblock is written. +corruption_errs:: +A block checksum mismatched or a corrupted metadata header was found. +generation_errs:: +The block generation does not match the expected value (eg. stored in the +parent node). + EXIT STATUS ----------- *btrfs device* returns a zero exit status if it succeeds. Non zero is diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc index e2eea263..7dd323fa 100644 --- a/Documentation/btrfs-man5.asciidoc +++ b/Documentation/btrfs-man5.asciidoc @@ -27,6 +27,9 @@ options please refer to `mount`(8) manpage. The options are sorted alphabeticall + Enable/disable support for Posix Access Control Lists (ACLs). See the `acl`(5) manual page for more information about ACLs. ++ +The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL) and +mount fails if 'acl' is requested but the feature is not compiled in. *alloc_start='bytes'*:: (default: 1M, minimum: 1M) @@ -69,7 +72,7 @@ synchronize all pending data and ordinary metadata blocks, then writes the superblock and issues another flush. + The write flushes incur a slight hit and also prevent the IO block -scheduler to reorder requests in more effective way. Disabling barriers gets +scheduler to reorder requests in a more effective way. Disabling barriers gets rid of that penalty but will most certainly lead to a corrupted filesystem in case of a crash or power loss. The ordinary metadata blocks could be yet unwritten at the time the new superblock is stored permanently, expecting that @@ -121,8 +124,11 @@ but a warning is printed if it's more than 300 seconds (5 minutes). + Control BTRFS file data compression. Type may be specified as 'zlib', 'lzo' or 'no' (for no compression, used for remounting). If no type -is specified, 'zlib' is used. If compress-force is specified, -all files will be compressed, whether or not they compress well. +is specified, 'zlib' is used. If 'compress-force' is specified, +all files will be compressed, whether or not they compress well. Otherwise +some simple heuristics are applied to detect an incompressible file. If the +first blocks written to a file are not compressible, the whole file is +permanently marked to skip compression. + NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled. @@ -133,6 +139,8 @@ NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled. 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)). ++ +NOTE: If 'nodatacow' or 'nodatasum' are enabled, compression is disabled. *datasum*:: *nodatasum*:: @@ -142,6 +150,8 @@ 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)). ++ +NOTE: If 'nodatacow' or 'nodatasum' are enabled, compression is disabled. *degraded*:: (default: off) @@ -171,15 +181,17 @@ underlying device, the operation may severely hurt performance in case the TRIM operation is synchronous (eg. with SATA devices up to revision 3.0). + If discarding is not necessary to be done at the block freeing time, there's -*fstrim* tool that lets the filesystem discard all free blocks in a batch, -possibly not much interfering with other operations. +`fstrim` tool that lets the filesystem discard all free blocks in a batch, +possibly not much interfering with other operations. Also, the the device may +ignore the TRIM command if the range is too small, so running the batch discard +can actually discard the blocks. *enospc_debug*:: *noenospc_debug*:: (default: off) + Enable verbose output for some ENOSPC conditions. It's safe to use but can -be noisy if the system hits reaches near-full state. +be noisy if the system reaches near-full state. *fatal_errors='action'*:: (since: 3.4, default: bug) @@ -231,20 +243,31 @@ the option. NOTE: Defaults to off due to a potential overflow problem when the free space checksums don't fit inside a single page. +*logreplay*:: +*nologreplay*:: +(default: on, even read-only) ++ +Enable/disable log replay at mount time. See also 'treelog'. ++ +WARNING: currently, the tree log is replayed even with a read-only mount! To +disable that behaviour, mount also with 'nologreplay'. + *max_inline='bytes'*:: -(default: min(8192, page size) ) +(default: min(2048, page size) ) + Specify the maximum amount of space, in bytes, that can be inlined in a metadata B-tree leaf. The value is specified in bytes, optionally with a K suffix (case insensitive). In practice, this value is limited by the filesystem block size (named 'sectorsize' at mkfs time), and memory page size of the system. In case of sectorsize limit, there's -some space unavailable due to leaf headers. For example, a 4k sectorsize, max -inline data is ~3900 bytes. +some space unavailable due to leaf headers. For example, a 4k sectorsize, +maximum size of inline data is about 3900 bytes. + -Inlining can be completely turned off specifying 0. This will increase data +Inlining can be completely turned off by specifying 0. This will increase data block slack if file sizes are much smaller than block size but will reduce metadata consumption in return. ++ +NOTE: the default value has changed to 2048 in kernel 4.6. *metadata_ratio='value'*:: (default: 0, internal logic) @@ -252,17 +275,27 @@ metadata consumption in return. Specifies that 1 metadata chunk should be allocated after every 'value' data chunks. Default behaviour depends on internal logic, some percent of unused metadata space is attempted to be maintained but is not always possible if -there's not space left for chunk allocation. The option could be useful to +there's not enough space left for chunk allocation. The option could be useful to override the internal logic in favor of the metadata allocation if the expected workload is supposed to be metadata intense (snapshots, reflinks, xattrs, inlined files). *recovery*:: -(since: 3.2, default: off) +(since: 3.2, default: off, deprecated since: 4.5) + -Enable autorecovery attempts if a bad tree root is found at mount time. -Currently this scans a backup list of several previous tree roots and tries to -use the first readable. This can be used with read-only mounts as well. +NOTE: this option has been replaced by 'usebackuproot' and should not be used +but will work on 4.5+ kernels. + +*norecovery*:: +(since: 4.5, default: off) ++ +Do not attempt any data recovery at mount time. This will disable 'logreplay' +and avoids other write operations. ++ +NOTE: The opposite option 'recovery' used to have different meaning but was +changed for consistency with other filesystems, where 'norecovery' is used for +skipping log replay. BTRFS does the same and in general will try to avoid any +write operations. *rescan_uuid_tree*:: (since: 3.12, default: off) @@ -275,7 +308,7 @@ normally be needed. + Skip automatic resume of interrupted balance operation after mount. May be resumed with *btrfs balance resume* or the paused state can be removed -by *btrfs balance cancel*. +by *btrfs balance cancel*. The default behaviour is to start interrutpd balance. *space_cache*:: *space_cache=v2*:: @@ -305,7 +338,8 @@ b-trees, sometimes referred to as 'free-space-tree'. + Options to control SSD allocation schemes. By default, BTRFS will enable or disable SSD allocation heuristics depending on whether a -rotational or non-rotational disk is in use. The 'ssd' and 'nossd' options +rotational or non-rotational disk is in use (contents of +'/sys/block/DEV/queue/rotational'). The 'ssd' and 'nossd' options can override this autodetection. + The 'ssd_spread' mount option attempts to allocate into bigger and aligned @@ -321,6 +355,9 @@ This mount option overrides the default subvolume set for the given filesystem. Mount subvolume specified by a 'subvolid' number rather than the toplevel subvolume. You can use *btrfs subvolume list* to see subvolume ID numbers. This mount option overrides the default subvolume set for the given filesystem. ++ +NOTE: if both 'subvolid' and 'subvol' are specified, they must point at the +same subvolume, otherwise mount will fail. *subvolrootid='objectid'*:: (irrelevant since: 3.2, formally deprecated since: 3.10) @@ -333,9 +370,9 @@ subvolume that did not reside directly under the toplevel subvolume. + The number of worker threads to allocate. NRCPUS is number of on-line CPUs detected at the time of mount. Small number leads to less parallelism in -processing data and metadata, higher numbers could lead to a performance due to -increased locking contention, cache-line bouncing or costly data transfers -between local CPU memories. +processing data and metadata, higher numbers could lead to a performance hit +due to increased locking contention, cache-line bouncing or costly data +transfers between local CPU memories. *treelog*:: *notreelog*:: @@ -346,11 +383,21 @@ stores changes without the need of a full filesystem sync. The log operations are flushed at sync and transaction commit. If the system crashes between two such syncs, the pending tree log operations are replayed during mount. + -WARNING: currently, the tree log is replayed even with a read-only mount! +WARNING: currently, the tree log is replayed even with a read-only mount! To +disable that behaviour, mount also with 'nologreplay'. + The tree log could contain new files/directories, these would not exist on a mounted filesystem if the log is not replayed. +*usebackuproot*:: +*nousebackuproot*:: ++ +Enable autorecovery attempts if a bad tree root is found at mount time. +Currently this scans a backup list of several previous tree roots and tries to +use the first readable. This can be used with read-only mounts as well. ++ +NOTE: This option has replaced 'recovery'. + *user_subvol_rm_allowed*:: (default: off) + diff --git a/Documentation/btrfs-receive.asciidoc b/Documentation/btrfs-receive.asciidoc index 758eebe3..e246603c 100644 --- a/Documentation/btrfs-receive.asciidoc +++ b/Documentation/btrfs-receive.asciidoc @@ -3,51 +3,57 @@ btrfs-receive(8) NAME ---- -btrfs-receive - receive subvolumes from stdin/file. +btrfs-receive - receive subvolumes from send stream SYNOPSIS -------- -*btrfs receive* [options] <mount> +*btrfs receive* [options] <path> DESCRIPTION ----------- -Receives one or more subvolumes that were previously -sent with *btrfs send*. The received subvolumes are stored -into <mount>. -*btrfs receive* will fail with the following case: +Receive a stream of changes and replicate one or more subvolumes that were +previously used with *btrfs send* The received subvolumes are stored to +'path'. -1. a receiving subvolume already exists. +*btrfs receive* will fail int the following cases: -2. a previously received subvolume was changed after it was received. +1. receiving subvolume already exists -3. default subvolume is changed or you don't mount btrfs filesystem with -fs tree. +2. previously received subvolume was changed after it was received -After receiving a subvolume, it is immediately set to read only. +3. default subvolume has changed or you didn't mount BTRFS filesystem at the toplevel subvolume + +A subvolume is made read-only after the receiving process finishes succesfully. `Options` -v:: -Enable verbose debug output. Each occurrence of this option increases the -verbose level more. +enable verbose debug output, print each operation (each occurrence of this +option increases the verbosity level) + -f <infile>:: -By default, btrfs receive uses stdin to receive the subvolumes. -Use this option to specify a file to use instead. +by default, btrfs receive uses standard input to receive the stream, +use this option to read from a file instead + -C|--chroot:: -Confine the process to <mount> using chroot. +confine the process to 'path' using `chroot`(1) + -e:: -Terminate after receiving an <end cmd> in the data stream. -Without this option, the receiver terminates only if an error is recognized -or on EOF. +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 + --max-errors <N>:: -Terminate as soon as N errors happened while processing commands from the send -stream. Default value is 1. A value of 0 means no limit. +terminate as soon as N errors happened while processing commands from the send +stream, default value is 1, 0 means no limit + -m <mountpoint>:: -The root mount point of the destination fs. +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 +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. EXIT STATUS diff --git a/Documentation/btrfs-restore.asciidoc b/Documentation/btrfs-restore.asciidoc index ec3a08bc..41e90e2f 100644 --- a/Documentation/btrfs-restore.asciidoc +++ b/Documentation/btrfs-restore.asciidoc @@ -12,10 +12,22 @@ SYNOPSIS DESCRIPTION ----------- *btrfs restore* is used to try to salvage files from a damaged filesystem and -restore them into <path> or just list the tree roots. +restore them into <path> or just list the subvolume tree roots. The filesystem +image is not modified. -Since current `btrfs-check`(8) or `btrfs-rescue`(8) only has very limited usage, -*btrfs restore* is normally a better choice. +If the filesystem is damaged and cannot be repaired by the other tools +(`btrfs-check`(8) or `btrfs-rescue`(8)), *btrfs restore* could be used to +retrieve file data, as far as the metadata are readable. The checks done by +restore are less strict and the process is usually able to get far enough to +retrieve data from the whole filesystem. This comes at a cost that some data +might be incomplete or from older versions if they're available. + +There are several options to attempt restoration of various file metadata type. +You can try a dry run first to see how well the process goes and use further +options to extend the set of restored metadata. + +For images with damaged tree structures, there are several options to point the +process to some spare copy. NOTE: It is recommended to read the following btrfs wiki page if your data is not salvaged with default option: + @@ -24,54 +36,59 @@ https://btrfs.wiki.kernel.org/index.php/Restore OPTIONS ------- -s|--snapshots:: -get snapshots, btrfs restore skips snapshots in default. +get also snapshots that are skippped by default -x|--xattr:: -get extended attributes. +get extended attributes -m|--metadata:: -restore owner, mode and times. +restore owner, mode and times for files and directories -S|--symlinks:: -restore symbolic links as well as normal files. +restore symbolic links as well as normal files -v|--verbose:: -verbose. +be verbose and print what is being restored -i|--ignore-errors:: -ignore errors. +ignore errors during restoration and continue -o|--overwrite:: -overwrite directories/files in <path>. +overwrite directories/files in <path>, eg. for repeated runs -t <bytenr>:: -use <bytenr> to read root tree. +use <bytenr> to read the root tree -f <bytenr>:: -only restore files that are under specified root whose root bytenr is <bytenr>. +only restore files that are under specified subvolume root pointed by <bytenr> -u|--super <mirror>:: -use given superblock mirror identified by <mirror>, it can be 0,1,2. +use given superblock mirror identified by <mirror>, it can be 0,1 or 2 -r|--root <rootid>:: -only restore files that are under specified root whose objectid is <rootid>. +only restore files that are under a specified subvolume whose objectid is <rootid> -d:: -find dir. +find directory -l|--list-roots:: -list tree roots. +list subvolume tree roots, can be used as argument for '-r' -D|--dry-run:: -dry run (only list files that would be recovered). +dry run (only list files that would be recovered) --path-regex <regex>:: -restore only filenames matching regex, you have to use following syntax (possibly quoted): +restore only filenames matching a regular expression (`regex`(7)) with a +mandatory format + +^/(|home(|/username(|/Desktop(|/.*))))$+ ++ +The format is not very comfortable and restores all files in the directories +in the whole path, so this is not useful for restoring single file in a deep +hierarchy. -c:: -ignore case (--path-regex only). +ignore case (--path-regex only) EXIT STATUS ----------- diff --git a/Documentation/btrfs-scrub.asciidoc b/Documentation/btrfs-scrub.asciidoc index 2335aba2..83ddcaa7 100644 --- a/Documentation/btrfs-scrub.asciidoc +++ b/Documentation/btrfs-scrub.asciidoc @@ -3,7 +3,7 @@ btrfs-scrub(8) NAME ---- -btrfs-scrub - scrub btrfs filesystem +btrfs-scrub - scrub btrfs filesystem, verify block checksums SYNOPSIS -------- @@ -12,21 +12,22 @@ SYNOPSIS DESCRIPTION ----------- *btrfs scrub* is used to scrub a btrfs filesystem, which will read all data -from all disks and verify checksums. +and metadata blocks from all disks and verify checksums. Automatically repair +corrupted blocks if there's a correct copy available. SUBCOMMAND ---------- *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. + -Progress is saved in the scrub progress file and scrubbing can be resumed later -using the scrub resume command. -If a <device> is given, the corresponding filesystem is found and -scrub cancel behaves as if it was called on that filesystem. +Progress is saved in the scrub progress file ('/var/lib/btrfs/scrub.status.UUID') +and scrubbing can be resumed later using the *btrfs scrub resume* command. +If a 'device' is specified, the corresponding filesystem is found and +*btrfs scrub cancel* behaves as if it was called on that filesystem. *resume* [-BdqrR] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>:: -Resume a cancelled or interrupted scrub cycle on the filesystem identified by -<path> or on a given <device>. +Resume a cancelled or interrupted scrub on the filesystem identified by +'path' or on a given 'device'. + Does not start a new scrub if the last scrub finished successfully. + @@ -35,11 +36,11 @@ Does not start a new scrub if the last scrub finished successfully. see *scrub start*. *start* [-BdqrRf] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>:: -Start a scrub on all devices of the filesystem identified by <path> or on -a single <device>. If a scrub is already running, the new one fails. +Start a scrub on all devices of the filesystem identified by 'path' or on +a single 'device'. If a scrub is already running, the new one fails. + Without options, scrub is started as a background process. -Progress can be obtained with the *scrub status* command. Scrubbing +Progress can be obtained with the *btrfs scrub status* command. Scrubbing involves reading all data from all disks and verifying checksums. Errors are corrected along the way if possible. + @@ -49,26 +50,28 @@ configured similar to the `ionice`(1) syntax using '-c' and '-n' options. `Options` + -B:::: -Do not background and print scrub statistics when finished. +do not background and print scrub statistics when finished -d:::: -Print separate statistics for each device of the filesystem (-B only). +print separate statistics for each device of the filesystem ('-B' only) -q:::: -Quiet. Omit error messages and statistics. +be quiet, omit error messages and statistics -r:::: -Read only mode. Do not attempt to correct anything. +read only mode, do not attempt to correct anything, can be run on a read-only +filesystem -R:::: -Raw print mode. Print full data instead of summary. +print raw statistics per-device instead of a summary -c <ioprio_class>:::: -Set IO priority class (see `ionice`(1) manpage). +set IO priority class (see `ionice`(1) manpage) -n <ioprio_classdata>:::: -Set IO priority classdata (see `ionice`(1) manpage). +set IO priority classdata (see `ionice`(1) manpage) -f:::: -Force starting new scrub even if a scrub is already running. -This is useful when scrub status record file is damaged. +force starting new scrub even if a scrub is already running, +this is useful when scrub status file is damaged and reports a running +scrub although it is not *status* [-d] <path>|<device>:: -Show status of a running scrub for the filesystem identified by <path> or -for the specified <device>. +Show status of a running scrub for the filesystem identified by 'path' or +for the specified 'device'. + If no scrub is running, show statistics of the last finished or cancelled scrub for that filesystem or device. @@ -76,7 +79,7 @@ for that filesystem or device. `Options` + -d:::: -Print separate statistics for each device of the filesystem. +print separate statistics for each device of the filesystem EXIT STATUS ----------- diff --git a/Documentation/btrfs-select-super.asciidoc b/Documentation/btrfs-select-super.asciidoc index a8d7ef00..6e94a034 100644 --- a/Documentation/btrfs-select-super.asciidoc +++ b/Documentation/btrfs-select-super.asciidoc @@ -3,27 +3,45 @@ btrfs-select-super(8) NAME ---- -btrfs-select-super - overwrite superblock with a backup +btrfs-select-super - overwrite primary superblock with a backup copy SYNOPSIS -------- -*btrfs-select-super* -s number dev +*btrfs-select-super* -s number <device> DESCRIPTION ----------- -*btrfs-select-super* destructively overwrites all copies of the superblock -with a specified copy. This helps with certain cases of damage, especially -when barriers were disabled during a power failure. You can find a valid -copy of the superblock with *btrfs check -s*. +Destructively overwrite all copies of the superblock +with a specified copy. This helps in certain cases, for example when write +barriers were disabled during a power failure and not all superblocks were +written, or if the primary superblock is damaged, eg. accidentally overwritten. -The filesystem specified by `dev` must not be mounted. +The filesystem specified by 'device' must not be mounted. + +NOTE: *Prior to overwriting the primary superblock, please make sure that the backup +copies are valid!* + +To dump a superblock use the *btrfs inspect-internal +dump-super* command, or the obsolete command *btrfs-show-super*. + +Then run the check (in the non-repair mode) using the command *btrfs check -s* +where '-s' specifies the superblock copy to use. + +Superblock copies exist in the following offsets on the device: + +- primary: '64KiB' (65536) +- 1st copy: '64MiB' (67108864) +- 2nd copy: '256GiB' (274877906944) + +A superblock size is '4KiB' (4096). OPTIONS ------- -s|--super <superblock>:: -use <superblock>th superblock copy, valid values are 0 up to 2 if the -respective superblock offset is within the filesystem +use 'superblock'th superblock copy, valid values are 0 1 or 2 if the +respective superblock offset is within the device size SEE ALSO -------- +`btrfs-inspect-internal`(8), `btrfsck check`(8) diff --git a/Documentation/btrfs-send.asciidoc b/Documentation/btrfs-send.asciidoc index e05342ff..47b0b047 100644 --- a/Documentation/btrfs-send.asciidoc +++ b/Documentation/btrfs-send.asciidoc @@ -3,7 +3,7 @@ btrfs-send(8) NAME ---- -btrfs-send - send data of subvolume(s) to stdout/file. +btrfs-send - generate a stream of changes between two subvolumes SYNOPSIS -------- @@ -11,40 +11,53 @@ SYNOPSIS DESCRIPTION ----------- -Sends the subvolume(s) specified by <subvol> to stdout. -<subvol> should be read-only here. -By default, this will send the whole subvolume. To do an incremental -send, use '-p <parent>'. +This command will generate a stream of instructions that describe changes +between two subvolumes. The stream can be consumed by the *btrfs receive* +command to replicate the sent subvolume on a different filesystem. +The command operates in two modes: full and incremental. -If you want to allow btrfs to clone from any additional local snapshots, -use '-c <clone-src>' (multiple times where applicable). +All subvolumes involved in one send command must be read-only (ie. the +read-only snapshots and this status cannot be changed if there's a running send +operation that uses the subvolume). -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. +In the full mode, the entire subvolume data and metadata will end up in the +stream. + +In the incremental mode (options '-p' and '-c'), there can be one or more +parent subvolumes that will establish the base for determining the changes. +The final stream will be smaller compared to the full mode. It is allowed to omit the '-p <parent>' option when '-c <clone-src>' options are given, in which case *btrfs send* will determine a suitable parent among the clone sources itself. +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. + `Options` --v:: -Enable verbose debug output. Each occurrence of this option increases the -verbose level more. -e:: -If sending multiple subvols at once, use the new format and omit the <end cmd> between the subvols. +if sending multiple subvolumes at once, use the new format and omit the +'end cmd' marker in the stream separating the subvolumes -p <parent>:: -Send an incremental stream from <parent> to <subvol>. +send an incremental stream from 'parent' to 'subvol' -c <clone-src>:: -Use this snapshot as a clone source for an incremental send (multiple allowed). +use this snapshot as a clone source for an incremental send (multiple allowed) -f <outfile>:: -Output is normally written to stdout. To write to a file, use this option. -An alternative would be to use pipes. +output is normally written to standard outout so it can be eg. piped to +receive, use this option to write it to a file --no-data:: -Send in NO_FILE_DATA mode. The output stream does not contain any file +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. +-v|--verbose:: +enable verbose output, print generated commands in a readable form, (each +occurrence of this option increases the verbosity level) +-q|--quiet:: +suppress all messagese except errors EXIT STATUS ----------- diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc index 5497c57a..fb64aa4a 100644 --- a/Documentation/btrfs-subvolume.asciidoc +++ b/Documentation/btrfs-subvolume.asciidoc @@ -46,7 +46,7 @@ SUBCOMMAND *create* [-i <qgroupid>] [<dest>]<name>:: Create a subvolume <name> in <dest>. + -If <dest> is not given, subvolume <name> will be created in the currently +If <dest> is not given, subvolume <name> will be created in the current directory. + `Options` diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc index e4321de9..5d79e24f 100644 --- a/Documentation/mkfs.btrfs.asciidoc +++ b/Documentation/mkfs.btrfs.asciidoc @@ -275,14 +275,27 @@ physical copies highly depends on the underlying device type. 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 space. +wastes filesystem space without 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 -details are not usually disclosed by vendors. As another example, the widely -used USB flash or SD cards use a translation layer. The data lifetime may -be affected by frequent plugging. The memory cells could get damaged, hopefully -not destroying both copies of particular data. +details are not usually disclosed by vendors. For example we could expect that +not all blocks get deduplicated. This will provide a non-zero probability of +recovery compared to a zero chance if the single profile is used. The user +should make the tradeoff decision. The deduplication in SSDs is thought to be +widely available so the reason behind the mkfs default is to not give a false +sense of redundancy. + +As another example, the widely used USB flash or SD cards use a translation +layer between the logical and physical view of the device. The data lifetime +may be affected by frequent plugging. The memory cells could get damaged, +hopefully not destroying both copies of particular data in case of DUP. + +The wear levelling techniques can also lead to reduced redundancy, even if the +device does not do any deduplication. The controllers may put data written in +a short timespan into the same physical storage unit (cell, block etc). In case +this unit dies, both copies are lost. BTRFS does not add any artificial delay +between metadata writes. The traditional rotational hard drives usually fail at the sector level. |