diff options
Diffstat (limited to 'Documentation')
32 files changed, 3384 insertions, 0 deletions
diff --git a/Documentation/Makefile.in b/Documentation/Makefile.in new file mode 100644 index 00000000..f046abd5 --- /dev/null +++ b/Documentation/Makefile.in @@ -0,0 +1,133 @@ +# Guard against environment variables +MAN8_TXT = + +# Top level commands +MAN8_TXT += btrfs.asciidoc +MAN8_TXT += btrfs-convert.asciidoc +MAN8_TXT += btrfs-debug-tree.asciidoc +MAN8_TXT += btrfs-find-root.asciidoc +MAN8_TXT += btrfs-image.asciidoc +MAN8_TXT += btrfs-map-logical.asciidoc +MAN8_TXT += btrfs-show-super.asciidoc +MAN8_TXT += btrfs-select-super.asciidoc +MAN8_TXT += btrfstune.asciidoc +MAN8_TXT += fsck.btrfs.asciidoc +MAN8_TXT += mkfs.btrfs.asciidoc + +# Sub commands for btrfs +MAN8_TXT += btrfs-subvolume.asciidoc +MAN8_TXT += btrfs-filesystem.asciidoc +MAN8_TXT += btrfs-balance.asciidoc +MAN8_TXT += btrfs-device.asciidoc +MAN8_TXT += btrfs-scrub.asciidoc +MAN8_TXT += btrfs-check.asciidoc +MAN8_TXT += btrfs-rescue.asciidoc +MAN8_TXT += btrfs-inspect-internal.asciidoc +MAN8_TXT += btrfs-send.asciidoc +MAN8_TXT += btrfs-receive.asciidoc +MAN8_TXT += btrfs-quota.asciidoc +MAN8_TXT += btrfs-qgroup.asciidoc +MAN8_TXT += btrfs-replace.asciidoc +MAN8_TXT += btrfs-restore.asciidoc +MAN8_TXT += btrfs-property.asciidoc + +# Category 5 manual page +MAN5_TXT += btrfs-man5.asciidoc + +MAN_TXT = $(MAN8_TXT) $(MAN5_TXT) +MAN_XML = $(patsubst %.asciidoc,%.xml,$(MAN_TXT)) +MAN_HTML = $(patsubst %.asciidoc,%.html,$(MAN_TXT)) + +DOC_MAN5 = $(patsubst %.asciidoc,%.5,$(MAN5_TXT)) +GZ_MAN5 = $(patsubst %.asciidoc,%.5.gz,$(MAN5_TXT)) + +DOC_MAN8 = $(patsubst %.asciidoc,%.8,$(MAN8_TXT)) +GZ_MAN8 = $(patsubst %.asciidoc,%.8.gz,$(MAN8_TXT)) + +mandir ?= $(prefix)/share/man +man8dir = $(mandir)/man8 +man5dir = $(mandir)/man5 + +ASCIIDOC = @ASCIIDOC@ +ASCIIDOC_EXTRA = +MANPAGE_XSL = manpage-normal.xsl +XMLTO = @XMLTO@ +XMLTO_EXTRA = +XMLTO_EXTRA = -m manpage-bold-literal.xsl +GZIPCMD = @GZIP@ +INSTALL = @INSTALL@ +RM = @RM@ +RMDIR = @RMDIR@ +LN_S = @LN_S@ +MV = @MV@ +SED = @SED@ +BTRFS_VERSION = $(shell $(SED) -n 's/.*PACKAGE_VERSION "\(.*\)"/\1/p'\ + ../config.h) + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifndef V + QUIET_RM = @ + QUIET_ASCIIDOC = @echo " [ASCII] $@"; + QUIET_XMLTO = @echo " [XMLTO] $@"; + QUIET_GZIP = @echo " [GZ] $@"; + QUIET_STDERR = 2> /dev/null + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + +all: man +man: man5 man8 +man5: $(GZ_MAN5) +man8: $(GZ_MAN8) +html: $(MAN_HTML) + +install: install-man + +install-man: man + $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir) + $(INSTALL) -d -m 755 $(DESTDIR)$(man8dir) + $(INSTALL) -m 644 $(GZ_MAN5) $(DESTDIR)$(man5dir) + # the source file name of btrfs.5 clashes with section 8 page, but we + # want to keep the code generic + $(MV) $(DESTDIR)$(man5dir)/btrfs-man5.5.gz $(DESTDIR)$(man5dir)/btrfs.5.gz + $(INSTALL) -m 644 $(GZ_MAN8) $(DESTDIR)$(man8dir) + $(LN_S) -f btrfs-check.8.gz $(DESTDIR)$(man8dir)/btrfsck.8.gz + $(LN_S) -f btrfs-rescue.8.gz $(DESTDIR)$(man8dir)/btrfs-zero-log.8.gz + +uninstall: + cd $(DESTDIR)$(man8dir); rm -f btrfs-check.8.gz $(GZ_MAN8) + $(RMDIR) -p --ignore-fail-on-non-empty $(DESTDIR)$(man8dir) + +clean: + $(QUIET_RM)$(RM) -f *.xml *.xml+ *.5 *.5.gz *.8 *.8.gz *.html + +%.5.gz : %.5 + $(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@ + +%.8.gz : %.8 + $(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@ + +%.5 : %.xml + $(QUIET_XMLTO)$(RM) -f $@ && \ + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +%.8 : %.xml + $(QUIET_XMLTO)$(RM) -f $@ && \ + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +%.xml : %.asciidoc asciidoc.conf + $(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ + $(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \ + -o $@+ $< && \ + $(MV) $@+ $@ + +%.html : %.asciidoc asciidoc.conf + $(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \ + $(ASCIIDOC) -b html -d article -f asciidoc.conf \ + $(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \ + -o $@+ $< && \ + $(MV) $@+ $@ diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 00000000..1ea74591 --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,48 @@ +## linkbtrfs: macro +# +# Usage: linkbtrfs:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show Btrfslink as: <command>(<section>); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?P<name>linkbtrfs):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= + +[tags] +bracket-emphasis={1?[{1}]}<emphasis><|></emphasis> + +[quotes] +<|>=#bracket-emphasis + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +backslash=\ +tilde=~ +apostrophe=' +backtick=` +litdd=-- + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] +<refentry> +<refmeta> +<refentrytitle>{mantitle}</refentrytitle> +<manvolnum>{manvolnum}</manvolnum> +<refmiscinfo class="source">Btrfs</refmiscinfo> +<refmiscinfo class="version">{btrfs_version}</refmiscinfo> +<refmiscinfo class="manual">Btrfs Manual</refmiscinfo> +</refmeta> +<refnamediv> + <refname>{manname}</refname> + <refpurpose>{manpurpose}</refpurpose> +</refnamediv> +endif::backend-docbook[] +endif::doctype-manpage[] diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc new file mode 100644 index 00000000..c8407419 --- /dev/null +++ b/Documentation/btrfs-balance.asciidoc @@ -0,0 +1,217 @@ +btrfs-balance(8) +================ + +NAME +---- +btrfs-balance - balance block groups on a btrfs filesystem + +SYNOPSIS +-------- +*btrfs balance* <subcommand> <args> + +DESCRIPTION +----------- +The primary purpose of the balance feature is to spread block groups accross +all devices so they match constraints defined by the respective profiles. See +`mkfs.btrfs`(8) section 'PROFILES' for more details. +The scope of the balancing process can be further tuned by use of filters that +can select the block groups to process. Balance works only on a mounted +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. + +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. + +The filters can be used to perform following actions: + +- convert block group profiles (filter 'convert') +- make block group usage more compact (filter 'usage') +- perform actions only on a given device (filters 'devid', 'drange') + +The filters can be applied to a combination of block group types (data, +metadata, system). Note that changing 'system' needs the force option. + +NOTE: the balance operation needs enough work space, ie. space that is +completely unused in the filesystem, otherwise this may lead to ENOSPC reports. +See the section 'ENOSPC' for more details. + +COMPATIBILITY +------------- + +NOTE: The balance subcommand also exists under the *btrfs filesystem* +namespace. This still works for backward compatibility but is deprecated and +should not be used anymore. + +NOTE: A short syntax *btrfs balance <path>* works due to backward compatibility +but is deprecated and should not be used anymore. Use *btrfs balance start* +command instead. + +SUBCOMMAND +---------- +*cancel* <path>:: +cancel running or paused balance + +*pause* <path>:: +pause running balance operation, this will store the state of the balance +progress and used filters to the filesystem + +*resume* <path>:: +resume interrupted balance + +*start* [options] <path>:: +start the balance operation according to the specified filters, no filters +will rewrite the entire filesystem. The process runs in the foreground. ++ +`Options` ++ +-d[<filters>]:::: +act on data block groups, see `FILTERS` section for details about 'filters' +-m[<filters>]:::: +act on metadata chunks, see `FILTERS` section for details about 'filters' +-s[<filters>]:::: +act on system chunks (requires '-f'), see `FILTERS` section for details about 'filters'. +-v:::: +be verbose and print balance filter arguments +-f:::: +force reducing of metadata integrity, eg. when going from 'raid1' to 'single' + +*status* [-v] <path>:: +Show status of running or paused balance. ++ +If '-v' option is given, output will be verbose. + +FILTERS +------- +From kernel 3.3 onwards, btrfs balance can limit its action to a subset of the +full filesystem, and can be used to change the replication configuration (e.g. +moving data from single to RAID1). This functionality is accessed through the +'-d', '-m' or '-s' options to btrfs balance start, which filter on data, +metadata and system blocks respectively. + +A filter has the following stucture: 'type'[='params'][,'type'=...] + +The available types are: + +*profiles=<profiles>*:: +Balances only block groups with the given profiles. Parameters +are a list of profile names separated by "'|'" (pipe). + +*usage=<percent>*:: +*usage=<range>*:: +Balances only block groups with usage under the given percentage. The +value of 0 is allowed and will clean up completely unused block groups, this +should not require any new work space allocated. You may want to use 'usage=0' +in case balance is returnin ENOSPC and your filesystem is not too full. ++ +The argument may be a single value or a range. The single value 'N' means 'at +most N percent used', equivalent to '..N' range syntax. Kernels prior to 4.4 +accept only the single value format. +The minimum range boundary is inclusive, maximum is exclusive. + +*devid=<id>*:: +Balances only block groups which have at least one chunk on the given +device. To list devices with ids use *btrfs fi show*. + +*drange=<range>*:: +Balance only block groups which overlap with the given byte range on any +device. Use in conjunction with 'devid' to filter on a specific device. The +parameter is a range specified as 'start..end'. + +*vrange=<range>*:: +Balance only block groups which overlap with the given byte range in the +filesystem's internal virtual address space. This is the address space that +most reports from btrfs in the kernel log use. The parameter is a range +specified as 'start..end'. + +*convert=<profile>*:: +Convert each selected block group to the given profile name identified by +parameters. ++ +NOTE: starting with kernel 4.5, the 'data' chunks can be converted to/from the +'DUP' profile on a single device. + +*limit=<number>*:: +*limit=<range>*:: +Process only given number of chunks, after all filters are applied. This can be +used to specifically target a chunk in connection with other filters ('drange', +'vrange') or just simply limit the amount of work done by a single balance run. ++ +The argument may be a single value or a range. The single value 'N' means 'at +most N chunks', equivalent to '..N' range syntax. Kernels prior to 4.4 accept +only the single value format. The range minimum and maximum are inclusive. + +*stripes=<range>*:: +Balance only block groups which have the given number of stripes. The parameter +is a range specified as 'start..end'. Makes sense fo block group profiles that +utilize striping, ie. RAID0/10/5/6. The range minimum and maximum are +inclusive. + +*soft*:: +Takes no parameters. Only has meaning when converting between profiles. +When doing convert from one profile to another and soft mode is on, +chunks that already have the target profile are left untouched. +This is useful e.g. when half of the filesystem was converted earlier but got +cancelled. ++ +The soft mode switch is (like every other filter) per-type. +For example, this means that we can convert metadata chunks the "hard" way +while converting data chunks selectively with soft switch. + +Profile names, used in 'profiles' and 'convert' are one of: 'raid0', 'raid1', +'raid10', 'raid5', 'raid6', 'dup', 'single'. The mixed data/metadata profiles +can be converted in the same way, but it's conversion between mixed and non-mixed +is not implemented. For the constraints of the profiles please refer to `mkfs.btrfs`(8), +section 'PROFILES'. + +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. +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 free work space can be calculated from the output of the *btrfs filesystem show* +command: + +------------------------------ + Label: 'BTRFS' uuid: 8a9d72cd-ead3-469d-b371-9c7203276265 + Total devices 2 FS bytes used 77.03GiB + devid 1 size 53.90GiB used 51.90GiB path /dev/sdc2 + devid 2 size 53.90GiB used 51.90GiB path /dev/sde1 +------------------------------ + +'size' - 'used' = 'free work space' + +'53.90GiB' - '51.90GiB' = '2.00GiB' + +An example of a filter that does not require workspace is 'usage=0'. This will +scan through all unused block groups of a given type and will reclaim the +space. Ater that it might be possible to run other filters. + +**CONVERSIONS ON MULTIPLE DEVICES** + +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. + +EXIT STATUS +----------- +*btrfs balance* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-device`(8) diff --git a/Documentation/btrfs-check.asciidoc b/Documentation/btrfs-check.asciidoc new file mode 100644 index 00000000..327a45d6 --- /dev/null +++ b/Documentation/btrfs-check.asciidoc @@ -0,0 +1,60 @@ +btrfs-check(8) +============== + +NAME +---- +btrfs-check - check or repair an unmounted btrfs filesystem + +SYNOPSIS +-------- +*btrfs check* [options] <device> + +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 + +*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 +--repair:: +try to repair the filesystem +--init-csum-tree:: +create a new CRC tree and recalculate all checksums +--init-extent-tree:: +create a new extent tree +--check-data-csum:: +verify checksums of data blocks +-p|--progress:: +indicate progress at various checking phases +--qgroup-report:: +verify qgroup accounting and compare against filesystem accounting +--subvol-extents <subvolid>:: +show extent state for a subvolume +--tree-root <bytenr>:: +use the given bytenr for the tree root + +EXIT STATUS +----------- +*btrfs check* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-scrub`(8), +`btrfs-rescue`(8) diff --git a/Documentation/btrfs-convert.asciidoc b/Documentation/btrfs-convert.asciidoc new file mode 100644 index 00000000..ca3417f4 --- /dev/null +++ b/Documentation/btrfs-convert.asciidoc @@ -0,0 +1,98 @@ +btrfs-convert(8) +================ + +NAME +---- +btrfs-convert - convert from ext2/3/4 filesystem to btrfs + +SYNOPSIS +-------- +*btrfs-convert* [options] <device> + +DESCRIPTION +----------- +*btrfs-convert* is used to convert existing ext2/3/4 filesystem image to a +btrfs filesystem in-place. The original filesystem image is accessible +subvolume named 'ext2_saved' as file 'image'. + +WARNING: If you are going to perform rollback to ext2/3/4, you should not +execute *btrfs balance* command on the converted filesystem. This will change +the extent layout and make *btrfs-convert* unable to rollback. + +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. + +**REMOVE THE ORIGINAL FILESYSTEM METADATA** + +By removing the 'ext2_saved' subvolume, all 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. + +**MAKE FILE DATA MORE CONTIGUOUS** + +An optional but recommended step is to run defragmentation on the entire +filesystem. This will attempt to make file extents more contiguous. + + # btrfs filesystem defrag -v -r -f -t 32M /mnt/btrfs + +Verbose recursive defragmentation ('-v', '-r'), flush data per-file ('-f') with target +extent size 32M ('-t'). + +**ATTEMPT TO MAKE BTRFS METADATA MORE COMPACT** + +Optional but recommended step. + +The metadata block groups after conversion may be smaller than the default size +(256MiB or 1GiB). Running a balance will attempt to merge the block groups. +This depends on the free space layout (and fragmentation) and may fail. This is +a soft error leaving the filesystem usable but the block group layout may +remain unchanged. + +Note that balance operation takes a lot of time. + + # btrfs balance start -m /mnt/btrfs + +OPTIONS +------- +-d|--no-datasum:: +disable data checksum calculations and set NODATASUM file flag, this can speed +up the conversion +-i|--no-xattr:: +ignore xattrs and ACLs of files +-n|--no-inline:: +disable inlining of small files to metadata blocks, this will decrease the metadata +consumption and may help to convert a filesystem with low free space +-N|--nodesize <SIZE>:: +set filesystem nodesize, the tree block size in which btrfs stores its metadata. +The default value is 16KB (16384) or the page size, whichever is bigger. +Must be a multiple of the sectorsize, but not larger than 65536. Se +`mkfs.btrfs`(8) for more details. +-r|--rollback:: +rollback to the original ext2/3/4 filesystem if possible +-l|--label <LABEL>:: +set filesystem label during conversion +-L|--copy-label:: +use label from the converted filesystem +-p|--progress:: +show progress of conversion, on by default +--no-progress:: +disable detailed progress and show only the main phases of conversion + +EXIT STATUS +----------- +*btrfs-convert* will return 0 if no error happened. +If any problems happened, 1 will be returned. + +SEE ALSO +-------- +`mkfs.btrfs`(8) diff --git a/Documentation/btrfs-debug-tree.asciidoc b/Documentation/btrfs-debug-tree.asciidoc new file mode 100644 index 00000000..23fc1156 --- /dev/null +++ b/Documentation/btrfs-debug-tree.asciidoc @@ -0,0 +1,38 @@ +btrfs-debug-tree(8) +=================== + +NAME +---- +btrfs-debug-tree - dump btrfs filesystem metadata into stdout + +SYNOPSIS +-------- +*btrfs-debug-tree* [options] <device> + +DESCRIPTION +----------- +*btrfs-debug-tree* is used to dump the whole tree of the given device. + +This is maybe useful for analyzing filesystem state or inconsistence and has +a positive educational effect on understanding the internal structure. +<device> is the device file where the filesystem is stored. + +OPTIONS +------- +-e:: +Print detailed extents info. +-d:: +Print info of btrfs device and root tree dirs only. +-r:: +Print info of roots only. +-b <block_num>:: +Print info of the specified block only. + +EXIT STATUS +----------- +*btrfs-debug-tree* will return 0 if no error happened. +If any problems happened, 1 will be returned. + +SEE ALSO +-------- +`mkfs.btrfs`(8) diff --git a/Documentation/btrfs-device.asciidoc b/Documentation/btrfs-device.asciidoc new file mode 100644 index 00000000..2827598a --- /dev/null +++ b/Documentation/btrfs-device.asciidoc @@ -0,0 +1,145 @@ +btrfs-device(8) +=============== + +NAME +---- +btrfs-device - control btrfs devices + +SYNOPSIS +-------- +*btrfs device* <subcommand> <args> + +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. + +DEVICE MANAGEMENT +----------------- +Btrfs filesystem is capable to manage multiple devices. + +Btrfs filesystem uses different profiles to manage different RAID level, and +use balance to rebuild chunks, also devices can be added/removed/replace +online. + +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. + +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. + +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. + +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. ++ +`Options` ++ +-K|--nodiscard:::: +do not perform discard by default +-f|--force:::: +force overwrite of existing filesystem on the given disk(s) + +*remove* <dev> [<dev>...] <path>:: +Remove device(s) from a filesystem identified by <path>. + +*delete* <dev> [<dev>...] <path>:: +Alias of remove kept for backwards compatability + +*ready* <device>:: +Check device to see if it has all of it's devices in cache for mounting. + +*scan* [(--all-devices|-d)|<device> [<device>...]]:: +Scan devices for a btrfs filesystem. ++ +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, if '--all-devices' or '-d' is passed, all the devices under /dev are +scanned. + +*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>. ++ +`Options` ++ +-z:::: +Reset stats to zero after reading them. + +*usage* [options] <path> [<path>...]:: +Show detailed information about internal allocations in devices. ++ +`Options` ++ +-b|--raw:::: +raw numbers in bytes, without the 'B' suffix +-h|--human-readable:::: +print human friendly numbers, base 1024, this is the default +-H:::: +print human friendly numbers, base 1000 +--iec:::: +select the 1024 base for the following options, according to the IEC standard +--si:::: +select the 1000 base for the following options, according to the SI standard +-k|--kbytes:::: +show sizes in KiB, or kB with --si +-m|--mbytes:::: +show sizes in MiB, or MB with --si +-g|--gbytes:::: +show sizes in GiB, or GB with --si +-t|--tbytes:::: +show sizes in TiB, or TB with --si + +If conflicting options are passed, the last one takes precedence. + +EXIT STATUS +----------- +*btrfs device* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-replace`(8), +`btrfs-balance`(8) diff --git a/Documentation/btrfs-filesystem.asciidoc b/Documentation/btrfs-filesystem.asciidoc new file mode 100644 index 00000000..26126175 --- /dev/null +++ b/Documentation/btrfs-filesystem.asciidoc @@ -0,0 +1,338 @@ +btrfs-filesystem(8) +=================== + +NAME +---- +btrfs-filesystem - command group of btrfs that usually work on the whole filesystem + +SYNOPSIS +-------- +*btrfs filesystem* <subcommand> <args> + +DESCRIPTION +----------- +*btrfs filesystem* is used to do the whole filesystem level tasks, including +all the regular filesystem operations like resizing, space stats, label +setting/getting, and defragmentation. + +SUBCOMMAND +---------- +*df* [options] <path>:: +Show a terse summary information about allocation of block group types of a given +mount point. The original purpose of this command was a debugging helper. The +output needs to be further interpreted and is not suitable for quick overview. ++ +-- +An example with description: + +* device size: '1.9TiB', one device, no RAID +* filesystem size: '1.9TiB' +* created with: 'mkfs.btrfs -d single -m single' +-- ++ +------------------------------ +$ btrfs filesystem df /path +Data, single: total=1.15TiB, used=1.13TiB +System, single: total=32.00MiB, used=144.00KiB +Metadata, single: total=12.00GiB, used=6.45GiB +GlobalReserve, single: total=512.00MiB, used=0.00B +------------------------------ ++ +-- +* 'Data', 'System' and 'Metadata' are separeate block group types. +'GlobalReserve' is an artificial and internal emergency space, see below. +* 'single' -- the allocation profile, defined at mkfs time +* 'total' -- sum of space reserved for +all allocation profiles of the given type, ie. all Data/single. Note that it's +not total size of filesystem. +* 'used' -- sum of used space of the above, ie. file extents, metadata blocks +-- ++ +'GlobalReserve' is an artificial and internal emergency space. It is used eg. +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'. ++ +`Options` ++ +-b|--raw:::: +raw numbers in bytes, without the 'B' suffix +-h|--human-readable:::: +print human friendly numbers, base 1024, this is the default +-H:::: +print human friendly numbers, base 1000 +--iec:::: +select the 1024 base for the following options, according to the IEC standard +--si:::: +select the 1000 base for the following options, according to the SI standard +-k|--kbytes:::: +show sizes in KiB, or kB with --si +-m|--mbytes:::: +show sizes in MiB, or MB with --si +-g|--gbytes:::: +show sizes in GiB, or GB with --si +-t|--tbytes:::: +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 filesytem. ++ +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 +start and len using '-s' and '-l' options below. +Extents bigger than value given by '-t' will be skipped, otherwise this value +is used as a target extent size, but is only advisory and may not be reached +if the free space is too fragmented. +Use 0 to take the kernel default, which is 256kB but may change in the future. +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`, +snapshots or de-duplicated data). +This may cause considerable increase of space usage depending on the broken up +ref-links. ++ +`Options` ++ +-v:::: +be verbose, print file names as they're submitted for defragmentation +-c[<algo>]:::: +compress file contents while defragmenting. Optional argument selects the compression +algorithm, 'zlib' (default) or 'lzo'. Currently it's not possible to select no +compression. See also section 'EXAMPLES'. +-r:::: +defragment files recursively in given directories +-f:::: +flush data for each file before going to the next file. This will limit the amount +of dirty data to current file, otherwise the amount cumulates from several files +and may increase system load. +-s <start>[kKmMgGtTpPeE]:::: +defragmentation will start from the given offset, default is beginning of a file +-l <len>[kKmMgGtTpPeE]:::: +defragment only up to 'len' bytes, default is the file size +-t <size>[kKmMgGtTpPeE]:::: +target extent size, do not touch extents bigger than 'size' ++ +For 'start', 'len', 'size' it is possible to append +units designator: \'K', \'M', \'G', \'T', \'P', or \'E', which represent +KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). ++ +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 +confusing and could be removed in the future. + +*label* [<dev>|<mountpoint>] [<newlabel>]:: +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 +is omitted. ++ +NOTE: the maximum allowable length shall be less than 256 chars and must not contain +a newline. The trailing newline is stripped automatically. + +// Some wording are extracted by the resize2fs man page +*resize* [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>:: +Resize a mounted filesystem identified by 'path'. A particular device +can be resized by specifying a 'devid'. ++ +WARNING: If 'path' is a file containing a BTRFS image then resize does not work +as expected and does not resize the image. This would resize the underlying +filesystem instead. ++ +The 'devid' can be found in the output of *btrfs filesystem show* and +defaults to 1 if not specified. +The 'size' parameter specifies the new size of the filesystem. +If the prefix '+' or '-' is present the size is increased or decreased +by the quantity 'size'. +If no units are specified, bytes are assumed for 'size'. +Optionally, the size parameter may be suffixed by one of the following +units designators: \'K', \'M', \'G', \'T', \'P', or \'E', which represent +KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter). ++ +If 'max' is passed, the filesystem will occupy all available space on the +device respecting 'devid' (remember, devid 1 by default). ++ +The resize command does not manipulate the size of underlying +partition. If you wish to enlarge/reduce a filesystem, you must make sure you +can expand the partition before enlarging the filesystem and shrink the +partition after reducing the size of the filesystem. This can done using +`fdisk`(8) or `parted`(8) to delete the existing partition and recreate +it with the new desired size. When recreating the partition make sure to use +the same starting partition offset as before. ++ +Growing is usually instant as it only updates the size. However, shrinking could +take a long time if there are data in the device area that's beyond the new +end. Relocation of the data takes time. ++ +See also section 'EXAMPLES'. + +*show* [options] [<path>|<uuid>|<device>|<label>]:: +Show the btrfs filesystem with some additional info about devices and space +allocation. ++ +If no option none of 'path'/'uuid'/'device'/'label' is passed, information +about all the BTRFS filesystems is shown, both mounted and unmounted. ++ +`Options` ++ +-m|--mounted:::: +probe kernel for mounted BTRFS filesystems +-d|--all-devices:::: +scan all devices under /dev, otherwise the devices list is extracted from the +/proc/partitions file. This is a fallback option if there's no device node +manager (like udev) available in the system. +--raw:::: +raw numbers in bytes, without the 'B' suffix +--human-readable:::: +print human friendly numbers, base 1024, this is the default +--iec:::: +select the 1024 base for the following options, according to the IEC standard +--si:::: +select the 1000 base for the following options, according to the SI standard +--kbytes:::: +show sizes in KiB, or kB with --si +--mbytes:::: +show sizes in MiB, or MB with --si +--gbytes:::: +show sizes in GiB, or GB with --si +--tbytes:::: +show sizes in TiB, or TB with --si + +*sync* <path>:: +Force a sync of the filesystem at 'path'. This is done via a special ioctl and +will also trigger cleaning of deleted subvolumes. Besides that it's equivalent +to the `sync`(1) command. + +*usage* [options] <path> [<path>...]:: +Show detailed information about internal filesystem usage. This is supposed to +replace the *btrfs filesystem df* command in the long run. ++ +The level of detail can differ if the command is run under a regular or the +root user (due to use of restricted ioctl). For both there's a summary section +with information about space usage: ++ +------------------------- +$ btrfs fi usage /path +WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root +Overall: + Device size: 1.82TiB + Device allocated: 1.17TiB + Device unallocated: 669.99GiB + Device missing: 0.00B + Used: 1.14TiB + Free (estimated): 692.57GiB (min: 692.57GiB) + Data ratio: 1.00 + Metadata ratio: 1.00 + Global reserve: 512.00MiB (used: 0.00B) +------------------------- ++ +The root user will also see stats broken down by block group types: ++ +------------------------- +Data,single: Size:1.15TiB, Used:1.13TiB + /dev/sdb 1.15TiB + +Metadata,single: Size:12.00GiB, Used:6.45GiB + /dev/sdb 12.00GiB + +System,single: Size:32.00MiB, Used:144.00KiB + /dev/sdb 32.00MiB + +Unallocated: + /dev/sdb 669.99GiB +------------------------- ++ +`Options` ++ +-b|--raw:::: +raw numbers in bytes, without the 'B' suffix +-h|--human-readable:::: +print human friendly numbers, base 1024, this is the default +-H:::: +print human friendly numbers, base 1000 +--iec:::: +select the 1024 base for the following options, according to the IEC standard +--si:::: +select the 1000 base for the following options, according to the SI standard +-k|--kbytes:::: +show sizes in KiB, or kB with --si +-m|--mbytes:::: +show sizes in MiB, or MB with --si +-g|--gbytes:::: +show sizes in GiB, or GB with --si +-t|--tbytes:::: +show sizes in TiB, or TB with --si +-T:::: +show data in tabular format ++ +If conflicting options are passed, the last one takes precedence. + +EXAMPLES +-------- + +*$ btrfs filesystem defrag -v -r dir/* + +Recursively defragment files under 'dir/', print files as they are processed. +The file names will be printed in batches, similarly the amount of data triggered +by defragmentation will be proportional to last N printed files. The system dirty +memory throttling will slow down the defragmentation but there can still be a lot +of IO load and the system may stall for a moment. + +*$ btrfs filesystem defrag -v -r -f dir/* + +Recusively defragment files under 'dir/', be verbose and wait until all blocks +are flushed before processing next file. You can note slower progress of the +output and lower IO load (proportional to currently defragmented file). + +*$ btrfs filesystem defrag -v -r -f -clzo dir/* + +Recusively defragment files under 'dir/', be verbose, wait until all blocks are +flushed and force file compression. + +*$ btrfs filesystem defrag -v -r -t 64M dir/* + +Recusively defragment files under 'dir/', be verbose and try to merge extents +to be about 64MiB. As stated above, the success rate depends on actual free +space fragmentation and the final result is not guaranteed to meet the target +even if run repeatedly. + +*$ btrfs filesystem resize -1G /path* + +*$ btrfs filesystem resize 1:-1G /path* + +Shrink size of the filesystem's device id 1 by 1GiB. The first syntax expects a +device with id 1 to exist, otherwise fails. The second is equivalent and more +explicit. For a single-device filesystem it's typically not necessary to +specify the devid though. + +*$ btrfs filesystem resize max /path* + +*$ 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. + +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. + +EXIT STATUS +----------- +*btrfs filesystem* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), diff --git a/Documentation/btrfs-find-root.asciidoc b/Documentation/btrfs-find-root.asciidoc new file mode 100644 index 00000000..e04cd3e8 --- /dev/null +++ b/Documentation/btrfs-find-root.asciidoc @@ -0,0 +1,35 @@ +btrfs-find-root(8) +================== + +NAME +---- +btrfs-find-root - filter to find btrfs root + +SYNOPSIS +-------- +*btrfs-find-root* [options] <dev> + +DESCRIPTION +----------- +*btrfs-find-root* is used to find the satisfied root, you can filter by +root tree's objectid, generation, level. + +OPTIONS +------- +-a:: +Search through all the metadata extents, even the root is already found. +-g <generation>:: +Filter root tree by it's original transaction id, tree root's generation in default. +-o <objectid>:: +Filter root tree by it's objectid,tree root's objectid in default. +-l <level>:: +Filter root tree by B-+ tree's level, level 0 in default. + +EXIT STATUS +----------- +*btrfs-find-root* will return 0 if no error happened. +If any problems happened, 1 will be returned. + +SEE ALSO +-------- +`mkfs.btrfs`(8) diff --git a/Documentation/btrfs-image.asciidoc b/Documentation/btrfs-image.asciidoc new file mode 100644 index 00000000..38265171 --- /dev/null +++ b/Documentation/btrfs-image.asciidoc @@ -0,0 +1,66 @@ +btrfs-image(8) +============== + +NAME +---- +btrfs-image - create/restore an image of the filesystem + +SYNOPSIS +-------- +*btrfs-image* [options] <source> <target> + +DESCRIPTION +----------- +*btrfs-image* is used to create an image of a btrfs filesystem. +All data will be zeroed, but metadata and the like is preserved. +Mainly used for debugging purposes. + +In the dump mode, source is the btrfs device/file and target is the output +file (use '-' for stdout). + +In the restore mode (option -r), source is the dumped image and target is the btrfs device/file. + + +OPTIONS +------- +-r:: +Restore metadump image. By default, this fixes super's chunk tree, by +using 1 stripe pointing to primary device, so that file system can be +restored by running tree log reply if possible. To restore without +changing number of stripes in chunk tree check -o option. + +-c <value>:: +Compression level (0 ~ 9). + +-t <value>:: +Number of threads (1 ~ 32) to be used to process the image dump or restore. + +-o:: +Use the old restore method, this does not fixup the chunk tree so the restored +file system will not be able to be mounted. + +-s:: +Sanitize the file names when generating the image. One -s means just +generate random garbage, which means that the directory indexes won't match up +since the hashes won't match with the garbage filenames. Using -ss will +calculate a collision for the filename so that the hashes match, and if it +can't calculate a collision then it will just generate garbage. The collision +calculator is very time and CPU intensive so only use it if you are having +problems with your file system tree and need to have it mostly working. + +-w:: +Walk all the trees manually and copy any blocks that are referenced. Use this +option if your extent tree is corrupted to make sure that all of the metadata is +captured. + +-m:: +Restore for multiple devices, more than 1 device should be provided. + +EXIT STATUS +----------- +*btrfs-image* will return 0 if no error happened. +If any problems happened, 1 will be returned. + +SEE ALSO +-------- +`mkfs.btrfs`(8) diff --git a/Documentation/btrfs-inspect-internal.asciidoc b/Documentation/btrfs-inspect-internal.asciidoc new file mode 100644 index 00000000..1c7c3611 --- /dev/null +++ b/Documentation/btrfs-inspect-internal.asciidoc @@ -0,0 +1,84 @@ +btrfs-inspect-internal(8) +========================= + +NAME +---- +btrfs-inspect-internal - query various internal information + +SYNOPSIS +-------- +*btrfs inspect-internal* <subcommand> <args> + +DESCRIPTION +----------- + +This command group provides an interface to query internal information. The +functionality ranges from a simple UI to an ioctl or a more complex query that +assembles the result from several internal structures. The latter usually +requires calls to privileged ioctls. + +SUBCOMMAND +---------- +*inode-resolve* [-v] <ino> <path>:: +(needs root privileges) ++ +resolve paths to all files with given inode number 'ino' in a given subvolume +at 'path', ie. all hardlinks ++ +`Options` ++ +-v:::: +verbose mode, print count of returned paths and ioctl() return value + +*logical-resolve* [-Pv] [-s <bufsize>] <logical> <path>:: +(needs root privileges) ++ +resolve paths to all files at given 'logical' address in the linear filesystem space ++ +`Options` ++ +-P:::: +skip the path resolving and print the inodes instead +-v:::: +verbose mode, print count of returned paths and all ioctl() return values +-s <bufsize>:::: +set internal buffer for storing the file names to 'bufsize', default is 4096, maximum 64k + +*min-dev-size* [options] <path>:: +(needs root privileges) ++ +return the minimum size the device can be shrunk to, without performing any +resize operation, this may be useful before executing the actual resize operation ++ +`Options` ++ +--id <id>:::: +specify the device 'id' to query, default is 1 if this option is not used + +*rootid* <path>:: +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) ++ +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 + +*subvolid-resolve* <subvolid> <path>:: +(needs root privileges) ++ +resolve the absolute path of a the subvolume id 'subvolid' + +EXIT STATUS +----------- +*btrfs inspect-internal* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-debug-tree`(8) diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc new file mode 100644 index 00000000..d4323917 --- /dev/null +++ b/Documentation/btrfs-man5.asciidoc @@ -0,0 +1,406 @@ +btrfs-man5(5) +============== + +NAME +---- +btrfs-man5 - topics about the BTRFS filesystem (mount options, supported file attributes and other) + +DESCRIPTION +----------- +This document describes topics related to BTRFS that are not specific to the +tools. Currently covers: + +1. mount options + +2. file attributes + +MOUNT OPTIONS +------------- + +This section describes mount options specific to BTRFS. For the generic mount +options please refer to `mount`(8) manpage. The options are sorted alphabetically +(discarding the 'no' prefix). + +*acl*:: +*noacl*:: +(default: on) ++ +Enable/disable support for Posix Access Control Lists (ACLs). See the +`acl`(5) manual page for more information about ACLs. + +*alloc_start='bytes'*:: +(default: 1M, minimum: 1M) ++ +Debugging option to force all block allocations above a certain +byte threshold on each block device. The value is specified in +bytes, optionally with a K, M, or G suffix (case insensitive). ++ +This option was used for testing and has not practial use, it's slated to be +removed in the future. + +*autodefrag*:: +*noautodefrag*:: +(since: 3.0, default: off) ++ +Enable automatic file defragmentation. +When enabled, small random writes into files (in a range of tens of kilobytes, +currently it's 64K) are detected and queued up for the defragmentation process. +Not well suited for large database workloads. ++ +The read latency may increase due to reading the adjacent blocks that make up the +range for defragmentation, successive write will merge the blocks in the new +location. ++ +WARNING: Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14-rc2 as +well as with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or +≥ 3.13.4 will break up the ref-links of CoW data (for example files +copied with `cp --reflink`, snapshots or de-duplicated data). +This may cause considerable increase of space usage depending on the +broken up ref-links. + +*barrier*:: +*nobarrier*:: +(default: on) ++ +Ensure that all IO write operations make it through the device cache and are stored +permanently when the filesystem is at it's consistency checkpoint. This +typically means that a flush command is sent to the device that will +synchronize all pending data and ordinary metadata blocks, then writes the +superblock and issues another flush. ++ +The write flushes incur a slight hit and also prevent the IO block +scheduler to reorder requests in more effective way. Disabling barriers gets +rid of that penalty but will most certainly lead to a corrupted filesystem in +case of a crash or power loss. The ordinary metadata blocks could be yet +unwrittent at the time the new superblock is stored permanently, expecting that +the block pointers to metadata were stored permanently before. ++ +On a device with a volatile battery-backed write-back cache, the 'nobarrier' +option will not lead to filesystem corruption as the pending blocks are +supposed to make it to the permanent storage. + +*check_int*:: +*check_int_data*:: +*check_int_print_mask='value'*:: +(since: 3.0, default: off) ++ +These debugging options control the behavior of the integrity checking +module (the BTRFS_FS_CHECK_INTEGRITY config option required). + ++ +`check_int` enables the integrity checker module, which examines all +block write requests to ensure on-disk consistency, at a large +memory and CPU cost. + ++ +`check_int_data` includes extent data in the integrity checks, and +implies the check_int option. + ++ +`check_int_print_mask` takes a bitmask of BTRFSIC_PRINT_MASK_* values +as defined in 'fs/btrfs/check-integrity.c', to control the integrity +checker module behavior. + ++ +See comments at the top of 'fs/btrfs/check-integrity.c' +for more info. + +*clear_cache*:: +Force clearing and rebuilding of the disk space cache if something +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). + +*compress*:: +*compress='type'*:: +*compress-force*:: +*compress-force='type'*:: +(default: off) ++ +Control BTRFS file data compression. Type may be specified as 'zlib', +'lzo' or 'no' (for no compression, used for remounting). If no type +is specified, 'zlib' is used. If compress-force is specified, +all files will be compressed, whether or not they compress well. ++ +NOTE: If compression is enabled, 'nodatacow' and 'nodatasum' are disabled. + +*datacow*:: +*nodatacow*:: +(default: on) ++ +Enable data copy-on-write for newly created files. +'Nodatacow' implies 'nodatasum', and disables 'compression'. All files created +under 'nodatacow' are also set the NOCOW file attribute (see `chattr`(1)). + +*datasum*:: +*nodatasum*:: +(default: on) ++ +Enable data checksumming for newly created files. +'Datasum' implies 'datacow', ie. the normal mode of operation. All files created +under 'nodatasum' inherit the "no checksums" property, however there's no +corresponding file attribute (see `chattr`(1)). + +*degraded*:: +(default: off) ++ +Allow mounts with less devices than the raid profile constraints +require. A read-write mount (or remount) may fail with too many devices +missing, for example if a stripe member is completely missing from RAID0. + +*device='devicepath'*:: +Specify a path to a device that will be scanned for BTRFS filesystem during +mount. This is usually done automatically by a device manager (like udev) or +using the *btrfs device scan* command (eg. run from the initial ramdisk). In +cases where this is not possible the 'device' mount option can help. ++ +NOTE: booting eg. a RAID1 system may fail even if all filesystem's 'device' +paths are provided as the actual device nodes may not be discovered by the +system at that point. + +*discard*:: +*nodiscard*:: +(default: off) ++ +Enable discarding of freed file blocks using TRIM operation. This is useful +for SSD devices, thinly provisioned LUNs or virtual machine images where the +backing device understands the operation. Depending on support of the +underlying device, the operation may severly hurt performance in case the TRIM +operation is synchronous (eg. with SATA devices up to revision 3.0). ++ +If discarding is not necessary to be done at the block freeing time, there's +*fstrim* tool that lets the filesystem discard all free blocks in a batch, +possibly not much interfering with other operations. + +*enospc_debug*:: +*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. + +*fatal_errors='action'*:: +(since: 3.4, default: bug) ++ +Action to take when encountering a fatal error. ++ +*bug*:::: +'BUG()' on a fatal error, the system will stay in the crashed state and may be +still partially usable, but reboot is required for full operation ++ +*panic*:::: +'panic()' on a fatal error, depending on other system configuration, this may +be followed by a reboot. Please refer to the documentation of kernel boot +parameters, eg. 'panic', 'oops' or 'crashkernel'. + +*flushoncommit*:: +*noflushoncommit*:: +(default: on) ++ +This option forces any data dirtied by a write in a prior transaction to commit +as part of the current commit. This makes the committed state a fully +consistent view of the file system from the application's perspective (i.e., it +includes all completed file system operations). This was previously the +behavior only when a snapshot was created. ++ +Disabling flushing may improve performance but is not crash-safe. + +*fragment='type'*:: +(depends on compile-time option BTRFS_DEBUG, since: 4.4, default: off) ++ +A debugging helper to intentionally fragment given 'type' of block groups. The +type can be 'data', 'metadata' or 'all'. This mount option should not be used +outside of debugging environments and is not recognized if the kernel config +option 'BTRFS_DEBUG' is not enabled. + +*inode_cache*:: +*noinode_cache*:: +(since: 3.0, default: off) ++ +Enable free inode number caching. Not recommended to use unless files on your +filesystem get assigned inode numbers that are approaching 2^64^. Normally, new +files in each subvolume get assigned incrementally (plus one from the last +time) and are not reused. The mount option turns on caching of the existing +inode numbers and reuse of inode numbers of deleted files. ++ +This option may slow down your system at first run, or after mounting without +the option. ++ +NOTE: Defaults to off due to a potential overflow problem when the free space +checksums don't fit inside a single page. + +*max_inline='bytes'*:: +(default: min(8192, page size) ) ++ +Specify the maximum amount of space, in bytes, that can be inlined in +a metadata B-tree leaf. The value is specified in bytes, optionally +with a K suffix (case insensitive). In practice, this value +is limited by the filesystem block size (named 'sectorsize' at mkfs time), +and memory page size of the system. In case of sectorsize limit, there's +some space unavailable due to leaf headers. For example, a 4k sectorsize, max +inline data is ~3900 bytes. ++ +Inlining can be completely turned off specifying 0. This will increase data +block slack if file sizes are much smaller than block size but will reduce +metadata consumption in return. + +*metadata_ratio='value'*:: +(default: 0, internal logic) ++ +Specifies that 1 metadata chunk should be allocated after every 'value' data +chunks. Default behaviour depends on internal logic, some percent of unused +metadata space is attempted to be maintained but is not always possible if +there's not space left for chunk allocation. The option could be useful to +override the internal logic in favor of the metadata allocation if the expected +workload is supposed to be metadata intense (snapshots, reflinks, xattrs, +inlined files). + +*recovery*:: +(since: 3.2, default: off) ++ +Enable autorecovery attempts if a bad tree root is found at mount time. +Currently this scans a backup list of several previous tree roots and tries to +use the first readable. This can be used with read-only mounts as well. + +*rescan_uuid_tree*:: +(since: 3.12, default: off) ++ +Force check and rebuild procedure of the UUID tree. This should not +normally be needed. + +*skip_balance*:: +(since: 3.3, default: off) ++ +Skip automatic resume of interrupted balance operation after mount. +May be resumed with *btrfs balance resume* or the paused state can be removed +by *btrfs balance cancel*. + +*space_cache*:: +*nospace_cache*:: +('nospace_cache' since: 3.2, default: on) ++ +Disable freespace cache loading without clearing the cache and the free space +cache will not be used during the mount. This affects performance as searching +for new free blocks could take longer. On the other hand, managing the space +cache consumes some resources. + +*ssd*:: +*nossd*:: +*ssd_spread*:: +(default: SSD autodetected) ++ +Options to control SSD allocation schemes. By default, BTRFS will +enable or disable SSD allocation heuristics depending on whether a +rotational or nonrotational disk is in use. The 'ssd' and 'nossd' options +can override this autodetection. ++ +The 'ssd_spread' mount option attempts to allocate into bigger and aligned +chunks of unused space, and may perform better on low-end SSDs. 'ssd_spread' +implies 'ssd', enabling all other SSD heuristics as well. + +*subvol='path'*:: +Mount subvolume from 'path' rather than the toplevel subvolume. The +'path' is absolute (ie. starts at the toplevel subvolume). +This mount option overrides the default subvolume set for the given filesystem. + +*subvolid='subvolid'*:: +Mount subvolume specified by a 'subvolid' number rather than the toplevel +subvolume. You can use *btrfs subvolume list* to see subvolume ID numbers. +This mount option overrides the default subvolume set for the given filesystem. + +*subvolrootid='objectid'*:: +(irrelevant since: 3.2, formally deprecated since: 3.10) ++ +A workaround option from times (pre 3.2) when it was not possible to mount a +subvolume that did not reside directly under the toplevel subvolume. + +*thread_pool='number'*:: +(default: min(NRCPUS + 2, 8) ) ++ +The number of worker threads to allocate. NRCPUS is number of on-line CPUs +detected at the time of mount. Small number leads to less parallelism in +processing data and metadata, higher numbers could lead to a performance due to +increased locking contention, cache-line bouncing or costly data transfers +between local CPU memories. + +*treelog*:: +*notreelog*:: +(default: on) ++ +Enable the tree logging used for 'fsync' and 'O_SYNC' writes. The tree log +stores changes without the need of a full filesystem sync. The log operations +are flushed at sync and transaction commit. If the system crashes between two +such syncs, the pending tree log operations are replayed during mount. ++ +WARNING: currently, the tree log is replayed even with a read-only mount! ++ +The tree log could contain new files/directories, these would not exist on +a mounted filesystm if the log is not replayed. + +*user_subvol_rm_allowed*:: +(default: off) ++ +Allow subvolumes to be deleted by their respective owner. Otherwise, only the +root user can do that. + +FILE ATTRIBUTES +--------------- +The btrfs filesystem supports setting the following file attributes using the +`chattr`(1) utility: + +*a*:: +'append only', new writes are always written at the end of the file + +*A*:: +'no atime updates' + +*c*:: +'compress data', all data written after this attribute is set will be compressed. +Please note that compression is also affected by the mount options or the parent +directory attributes. ++ +When set on a directory, all newly created files will inherit this attribute. + +*C*:: +'no copy-on-write', file modifications are done in-place ++ +When set on a directory, all newly created files will inherit this attribute. ++ +NOTE: due to implementation limitations, this flag can be set/unset only on +empty files. + +*d*:: +'no dump', makes sense with 3rd party tools like `dump`(8), on BTRFS the +attribute can be set/unset on no other special handling is done + +*D*:: +'synchronous directory updates', for more details search `open`(2) for 'O_SYNC' +and 'O_DSYNC' + +*i*:: +'immutable', no file data and metadata changes allowed even to the root user as +long as this attribute is set (obviously the exception is unsetting the attribute) + +*S*:: +'synchronous updates', for more details search `open`(2) for 'O_SYNC' and +'O_DSYNC' + +*X*:: +'no compression', permanently turn off compression on the given file, other +compression mount options will not affect that ++ +When set on a directory, all newly created files will inherit this attribute. + +No other attributes are supported. For the complete list please refer to the +`chattr`(1) manual page. + +SEE ALSO +-------- +`acl`(5), +`btrfs`(8), +`chattr`(1), +`fstrim`(8), +`mkfs.btrfs`(8), +`mount`(8) diff --git a/Documentation/btrfs-map-logical.asciidoc b/Documentation/btrfs-map-logical.asciidoc new file mode 100644 index 00000000..a3d110cb --- /dev/null +++ b/Documentation/btrfs-map-logical.asciidoc @@ -0,0 +1,37 @@ +btrfs-map-logical(8) +==================== + +NAME +---- +btrfs-map-logical - map btrfs logical extent to physical extent + +SYNOPSIS +-------- +*btrfs-map-logical* <options> <device> + +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. + +Mainly used for debug purpose. + +OPTIONS +------- +-l|--logical <logical_num>:: +Logical extent to map. +-c|--copy <copy>:: +Copy of the extent to read(usually 1 or 2). +-o|--output <filename>:: +Output file to hold the extent. +-b|--bytes <bytes>:: +Number of bytes to read. + +EXIT STATUS +----------- +*btrfs-map-logical* will return 0 if no error happened. +If any problems happened, 1 will be returned. + +SEE ALSO +-------- +`mkfs.btrfs`(8) diff --git a/Documentation/btrfs-property.asciidoc b/Documentation/btrfs-property.asciidoc new file mode 100644 index 00000000..8b9b7f03 --- /dev/null +++ b/Documentation/btrfs-property.asciidoc @@ -0,0 +1,73 @@ +btrfs-property(8) +================= + +NAME +---- +btrfs-property - get/set/list properties for given btrfs object. + +SYNOPSIS +-------- +*btrfs property* <subcommand> <args> + +DESCRIPTION +----------- +*btrfs property* is used to get/set/list property for given btrfs object. +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 +btrfs properties instead of using the traditional method like `chattr`(1) or +`lsattr`(1). + +SUBCOMMAND +---------- +*get* [-t <type>] <object> [<name>]:: +Gets a property from a btrfs object. ++ +A btrfs object, which is set by <object>, can be a btrfs filesystem +itself, a btrfs subvolume, an inode(file or directory) inside btrfs, +or a device on which a btrfs exists. ++ +The '-t <type>' option 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]'. ++ +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. + +ro:::: +read-only flag of subvolume: true or false +label:::: +label of device +compression:::: +compression setting for an inode: lzo, zlib, or "" (empty string) + +*list* [-t <type>] <object>:: +Lists available properties with their descriptions for the given object. ++ +See the description of *get* subcommand for the meaning of each option. + +*set* [-t <type>] <object> <name> <value>:: +Sets a property on a btrfs object. ++ +See the description of *get* subcommand for the meaning of each option. + +EXIT STATUS +----------- +*btrfs property* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`lsattr`(1), +`chattr`(1) diff --git a/Documentation/btrfs-qgroup.asciidoc b/Documentation/btrfs-qgroup.asciidoc new file mode 100644 index 00000000..57cf012d --- /dev/null +++ b/Documentation/btrfs-qgroup.asciidoc @@ -0,0 +1,145 @@ +btrfs-qgroup(8) +=============== + +NAME +---- +btrfs-qgroup - control the quota group of a btrfs filesystem + +SYNOPSIS +-------- +*btrfs qgroup* <subcommand> <args> + +DESCRIPTION +----------- +*btrfs qgroup* is used to control quota group (qgroup) of a btrfs filesystem. + +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). + +QGROUP +------ +Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are +attached to subvolumes. The size limits are set per qgroup and apply when any +limit is reached in tree that contains a given subvolume. + +The limit sare separated between shared and exclusive and reflect the extent +ownership. For example a fresh snapshot shares almost all the blocks with the +original subvolume, new writes to either subvolume will raise towards the +exclusive limit. + +The qgroup identifiers conform to 'level/id' where level 0 is reserved to the +qgroups associated with subvolumes. Such qgroups are created automatically. + +The qgroup hierarchy is built by commands *create* and *assign*. + +NOTE: If the qgroup of a subvolume is destroyed, quota about the subvolume +will not be functional until qgroup '0/<subvolume id>' is created again. + +SUBCOMMAND +---------- +*assign* [options] <src> <dst> <path>:: +Assign qgroup <src> as the child qgroup of <dst> in the btrfs filesystem +identified by <path>. ++ +`Options` ++ +--rescan:::: +Automatically schedule quota rescan if the new qgroup assignment leads to +quota inconsistency. +--no-rescan:::: +Explicitly ask not to do a rescan. + +*create* <qgroupid> <path>:: +Create a subvolume quota group. ++ +For the '0/<subvolume id>' qgroup, a qgroup can be created even before the +subvolume created. + +*destroy* <qgroupid> <path>:: +Destroy a qgroup. ++ +If a qgroup is no isolated,which means it is a parent or child qgroup, it +can't be destroyed. + +*limit* [options] <size>|none [<qgroupid>] <path>:: +Limit the size of a qgroup to <size> or no limit in the btrfs filesystem +identified by <path>. ++ +If <qgroupid> is not given, qgroup of the subvolume identified by <path> +is used if possible. ++ +`Options` ++ +-c:::: +limit amount of data after compression. This is the default, it is currently not +possible to turn off this option. ++ +-e:::: +limit space exclusively assigned to this qgroup. + +*remove* <src> <dst> <path>:: +Remove the relationship between child qgroup <src> and parent qgroup <dst> in +the btrfs filesystem identified by <path>. + +*show* [options] <path>:: +Show all qgroups in the btrfs filesystem identified by <path>. ++ +`Options` ++ +-p:::: +print parent qgroup id. +-c:::: +print child qgroup id. +-r:::: +print limit of referenced size of qgroup. +-e:::: +print limit of exclusive size of qgroup. +-F:::: +list all qgroups which impact the given path(include ancestral qgroups) +-f:::: +list all qgroups which impact the given path(exclude ancestral qgroups) +--raw:::: +raw numbers in bytes, without the 'B' suffix. +--human-readable:::: +print human friendly numbers, base 1024, this is the default +--iec:::: +select the 1024 base for the following options, according to the IEC standard. +--si:::: +select the 1000 base for the following options, according to the SI standard. +--kbytes:::: +show sizes in KiB, or kB with --si. +--mbytes:::: +show sizes in MiB, or MB with --si. +--gbytes:::: +show sizes in GiB, or GB with --si. +--tbytes:::: +show sizes in TiB, or TB with --si. +--sort=[\+/-]<attr>[,[+/-]<attr>]...:::: +list qgroups in order of <attr>. ++ +<attr> can be one or more of qgroupid,rfer,excl,max_rfer,max_excl. ++ +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. + +EXIT STATUS +----------- +*btrfs qgroup* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-subvolume`(8), +`btrfs-quota`(8), diff --git a/Documentation/btrfs-quota.asciidoc b/Documentation/btrfs-quota.asciidoc new file mode 100644 index 00000000..00e09c61 --- /dev/null +++ b/Documentation/btrfs-quota.asciidoc @@ -0,0 +1,56 @@ +btrfs-quota(8) +============== + +NAME +---- +btrfs-quota - control the quota of a btrfs filesystem + +SYNOPSIS +-------- +*btrfs quota* <subcommand> <args> + +DESCRIPTION +----------- +*btrfs quota* is used to enable/disable or rescan subvolume quota of a btrfs +filesystem. + +For setting quota or other quota operations on a btrfs filesystem, please see +`btrfs-qgroup`(8) for details. + +WARNING: Quota and qgroup in btrfs filesystem is not stable and impacts +performance in mainline kernel yet(v3.14 so far). + +SUBCOMMAND +---------- +*disable* <path>:: +Disable subvolume quota support for a filesystem. + +*enable* <path>:: +Enable subvolume quota support for a filesystem. + +*rescan* [-s] <path>:: +Trash all qgroup numbers and scan the metadata again with the current config. ++ +`Options` ++ +-s:::: +show status of a running rescan operation. +-w:::: +wait for rescan operation to finish(can be already in progress). + +EXIT STATUS +----------- +*btrfs quota* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-subvolume`(8), +`btrfs-qgroup`(8) diff --git a/Documentation/btrfs-receive.asciidoc b/Documentation/btrfs-receive.asciidoc new file mode 100644 index 00000000..84b85c1c --- /dev/null +++ b/Documentation/btrfs-receive.asciidoc @@ -0,0 +1,67 @@ +btrfs-receive(8) +================ + +NAME +---- +btrfs-receive - receive subvolumes from stdin/file. + +SYNOPSIS +-------- +*btrfs receive* [options] <mount> + +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: + +1. a receiving subvolume already exists. + +2. a previously received subvolume was changed after it was received. + +3. default subvolume is changed or you don't mount btrfs filesystem with +fs tree. + +After receiving a subvolume, it is immediately set to read only. + +`Options` + +-v:: +Enable verbose debug output. Each occurrence of this option increases the +verbose level more. +-f <infile>:: +By default, btrfs receive uses stdin to receive the subvolumes. +Use this option to specify a file to use instead. +-C|--chroot:: +Confine the process to <mount> using chroot. +-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. +--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. +-m:: +The root mount point of the destination fs. ++ +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 +----------- +*btrfs receive* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-send`(8) diff --git a/Documentation/btrfs-replace.asciidoc b/Documentation/btrfs-replace.asciidoc new file mode 100644 index 00000000..5a14a40a --- /dev/null +++ b/Documentation/btrfs-replace.asciidoc @@ -0,0 +1,76 @@ +btrfs-replace(8) +=============== + +NAME +---- +btrfs-replace - replace devices managed by btrfs with other device. + +SYNOPSIS +-------- +*btrfs replace* <subcommand> <args> + +DESCRIPTION +----------- +*btrfs replace* is used to replace btrfs managed devices with other device. + +SUBCOMMAND +---------- +*cancel* <mount_point>:: +Cancel a running device replace operation. + +*start* [-Bfr] <srcdev>|<devid> <targetdev> <path>:: +Replace device of a btrfs filesystem. ++ +On a live filesystem, duplicate the data to the target device which +is currently stored on the source device. +If the source device is not available anymore, or if the -r option is set, +the data is built only using the RAID redundancy mechanisms. +After completion of the operation, the source device is removed from the +filesystem. +If the <srcdev> is a numerical value, it is assumed to be the device id +of the filesystem which is mounted at <path>, otherwise is is +the path to the source device. If the source device is disconnected, +from the system, you have to use the devid parameter format. +The <targetdev> needs to be same size or larger than the <srcdev>. ++ +`Options` ++ +-r:::: +only read from <srcdev> if no other zero-defect mirror exists. +(enable this if your drive has lots of read errors, the access would be very +slow) +-f:::: +force using and overwriting <targetdev> even if it looks like +containing 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 +never allowed to be used as the <targetdev>. ++ +-B:::: +no background replace. + +*status* [-1] <mount_point>:: +Print status and progress information of a running device replace operation. ++ +`Options` ++ +-1:::: +print once instead of print continuously until the replace +operation finishes (or is canceled) + +EXIT STATUS +----------- +*btrfs replace* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-device`(8), diff --git a/Documentation/btrfs-rescue.asciidoc b/Documentation/btrfs-rescue.asciidoc new file mode 100644 index 00000000..42aca645 --- /dev/null +++ b/Documentation/btrfs-rescue.asciidoc @@ -0,0 +1,90 @@ +btrfs-rescue(8) +============== + +NAME +---- +btrfs-rescue - Recover a damaged btrfs filesystem + +SYNOPSIS +-------- +*btrfs rescue* <subcommand> <args> + +DESCRIPTION +----------- +*btrfs rescue* is used to try to recover a damaged btrfs filesystem. + +SUBCOMMAND +---------- +*chunk-recover* [options] <device>:: +Recover the chunk tree by scanning the devices ++ +`Options` ++ +-y:::: +assume an answer of 'yes' to all questions. +-v:::: +verbose mode. +-h:::: +help. + +NOTE: Since *chunk-recover* will scan the whole device, it will be *VERY* slow +especially executed on a large device. + +*super-recover* [options] <device>:: +Recover bad superblocks from good copies. ++ +`Options` ++ +-y:::: +assume an answer of 'yes' to all questions. +-v:::: +verbose mode. + +*zero-log* <device>:: +clear the filesystem log tree + +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 +kept around. + +NOTE: clearing the log may lead to loss of changes that were made since the +last transaction commit. This may be up to 30 seconds (default commit period) +or less if the commit was implied by other filesystem activity. + +One can determine whether *zero-log* is needed according to the kernel +backtrace: +---- +? replay_one_dir_item+0xb5/0xb5 [btrfs] +? walk_log_tree+0x9c/0x19d [btrfs] +? btrfs_read_fs_root_no_radix+0x169/0x1a1 [btrfs] +? btrfs_recover_log_trees+0x195/0x29c [btrfs] +? replay_one_dir_item+0xb5/0xb5 [btrfs] +? btree_read_extent_buffer_pages+0x76/0xbc [btrfs] +? open_ctree+0xff6/0x132c [btrfs] +---- + +If the errors are like above, then *zero-log* should be used to clear +the log and the filesystem may be mounted normally again. The keywords to look +for are 'open_ctree' which says that it's during mount and function names +that contain 'replay', 'recover' or 'log_tree'. + +EXIT STATUS +----------- +*btrfs rescue* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-scrub`(8), +`btrfs-check`(8) diff --git a/Documentation/btrfs-restore.asciidoc b/Documentation/btrfs-restore.asciidoc new file mode 100644 index 00000000..ec3a08bc --- /dev/null +++ b/Documentation/btrfs-restore.asciidoc @@ -0,0 +1,91 @@ +btrfs-restore(8) +================ + +NAME +---- +btrfs-restore - try to restore files from a damaged btrfs filesystem image + +SYNOPSIS +-------- +*btrfs restore* [options] <device> <path> | -l <device> + +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. + +Since current `btrfs-check`(8) or `btrfs-rescue`(8) only has very limited usage, +*btrfs restore* is normally a better choice. + +NOTE: It is recommended to read the following btrfs wiki page if your data is +not salvaged with default option: + +https://btrfs.wiki.kernel.org/index.php/Restore + +OPTIONS +------- +-s|--snapshots:: +get snapshots, btrfs restore skips snapshots in default. + +-x|--xattr:: +get extended attributes. + +-m|--metadata:: +restore owner, mode and times. + +-S|--symlinks:: +restore symbolic links as well as normal files. + +-v|--verbose:: +verbose. + +-i|--ignore-errors:: +ignore errors. + +-o|--overwrite:: +overwrite directories/files in <path>. + +-t <bytenr>:: +use <bytenr> to read root tree. + +-f <bytenr>:: +only restore files that are under specified root whose root bytenr is <bytenr>. + +-u|--super <mirror>:: +use given superblock mirror identified by <mirror>, it can be 0,1,2. + +-r|--root <rootid>:: +only restore files that are under specified root whose objectid is <rootid>. + +-d:: +find dir. + +-l|--list-roots:: +list tree roots. + +-D|--dry-run:: +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): ++ ++^/(|home(|/username(|/Desktop(|/.*))))$+ + +-c:: +ignore case (--path-regex only). + +EXIT STATUS +----------- +*btrfs restore* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-rescue`(8), +`btrfs-check`(8) diff --git a/Documentation/btrfs-scrub.asciidoc b/Documentation/btrfs-scrub.asciidoc new file mode 100644 index 00000000..7750868d --- /dev/null +++ b/Documentation/btrfs-scrub.asciidoc @@ -0,0 +1,94 @@ +btrfs-scrub(8) +============== + +NAME +---- +btrfs-scrub - scrub btrfs filesystem + +SYNOPSIS +-------- +*btrfs scrub* <subcommand> <args> + +DESCRIPTION +----------- +*btrfs scrub* is used to scrub a btrfs filesystem, which will read all data +from all disks and verify checksums. + +SUBCOMMAND +---------- +*cancel* <path>|<device>:: +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. + +*resume* [-BdqrR] [-c <ioprio_class> -n <ioprio_classdata>] <path>|<device>:: +Resume a canceled or interrupted scrub cycle on the filesystem identified by +<path> or on a given <device>. ++ +Does not start a new scrub if the last scrub finished successfully. ++ +`Options` ++ +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. ++ +Without options, scrub is started as a background process. +Progress can be obtained with the *scrub status* command. Scrubbing +involves reading all data from all disks and verifying checksums. Errors are +corrected along the way if possible. ++ +The default IO priority of scrub is the idle class. The priority can be +configured similar to the `ionice`(1) syntax using '-c' and '-n' options. ++ +`Options` ++ +-B:::: +Do not background and print scrub statistics when finished. +-d:::: +Print separate statistics for each device of the filesystem (-B only). +-q:::: +Quiet. Omit error messages and statistics. +-r:::: +Read only mode. Do not attempt to correct anything. +-R:::: +Raw print mode. Print full data instead of summary. +-c <ioprio_class>:::: +Set IO priority class (see `ionice`(1) manpage). +-n <ioprio_classdata>:::: +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 stat record file is damaged. + +*status* [-d] <path>|<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 canceled scrub +for that filesystem or device. ++ +`Options` ++ +-d:::: +Print separate statistics for each device of the filesystem. + +EXIT STATUS +----------- +*btrfs scrub* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), diff --git a/Documentation/btrfs-select-super.asciidoc b/Documentation/btrfs-select-super.asciidoc new file mode 100644 index 00000000..a8d7ef00 --- /dev/null +++ b/Documentation/btrfs-select-super.asciidoc @@ -0,0 +1,29 @@ +btrfs-select-super(8) +===================== + +NAME +---- +btrfs-select-super - overwrite superblock with a backup + +SYNOPSIS +-------- +*btrfs-select-super* -s number dev + +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*. + +The filesystem specified by `dev` must not be mounted. + +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 + +SEE ALSO +-------- +`btrfsck check`(8) diff --git a/Documentation/btrfs-send.asciidoc b/Documentation/btrfs-send.asciidoc new file mode 100644 index 00000000..e05342ff --- /dev/null +++ b/Documentation/btrfs-send.asciidoc @@ -0,0 +1,63 @@ +btrfs-send(8) +============= + +NAME +---- +btrfs-send - send data of subvolume(s) to stdout/file. + +SYNOPSIS +-------- +*btrfs send* [-ve] [-p <parent>] [-c <clone-src>] [-f <outfile>] <subvol> [<subvol>...] + +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>'. + +If you want to allow btrfs to clone from any additional local snapshots, +use '-c <clone-src>' (multiple times where applicable). + +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. + +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. + +`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. +-p <parent>:: +Send an incremental stream from <parent> to <subvol>. +-c <clone-src>:: +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. +--no-data:: +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. + +EXIT STATUS +----------- +*btrfs send* returns a zero exit status if it succeeds. Non zero is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-receive`(8) diff --git a/Documentation/btrfs-show-super.asciidoc b/Documentation/btrfs-show-super.asciidoc new file mode 100644 index 00000000..8866c940 --- /dev/null +++ b/Documentation/btrfs-show-super.asciidoc @@ -0,0 +1,54 @@ +btrfs-show-super(8) +==================== + +NAME +---- +btrfs-show-super - show btrfs superblock information stored in devices + +SYNOPSIS +-------- +*btrfs-show-super* [options] <dev> [<dev>...] + +DESCRIPTION +----------- +*btrfs-show-super* is used to print the information of superblock, +you can specify which mirror to print out. + +By default, every device's first superblock will be printed out. + +Mainly used for debug purpose. + +OPTIONS +------- +-f:: +Print full superblock information. ++ +Including the system chunk array and backup roots. + +-a:: +Print information of all superblocks. ++ +If this option is given, '-i' option will be ignored. + +-i <super_mirror>:: +Specify which mirror to print out. ++ +<super_mirror> is between 0 and 2. +If several '-i <super_mirror>' are given, only the last one is valid. + +-F:: +Attempt to print the superblock even if no superblock magic is found. May end +badly. + +-s <bytenr>:: +specifiy offset to a superblock in a non-standard location at 'bytenr', useful +for debugging (disables the '-f' option) + +EXIT STATUS +----------- +*btrfs-show-super* will return 0 if no error happened. +If any problems happened, 1 will be returned. + +SEE ALSO +-------- +`mkfs.btrfs`(8) diff --git a/Documentation/btrfs-subvolume.asciidoc b/Documentation/btrfs-subvolume.asciidoc new file mode 100644 index 00000000..96cfe4ac --- /dev/null +++ b/Documentation/btrfs-subvolume.asciidoc @@ -0,0 +1,182 @@ +btrfs-subvolume(8) +================== + +NAME +---- +btrfs-subvolume - control btrfs subvolume(s) + +SYNOPSIS +-------- +*btrfs subvolume* <subcommand> [<args>] + +DESCRIPTION +----------- +*btrfs subvolume* is used to control the filesystem to create/delete/list/show +subvolumes and snapshots. + +SUBVOLUME AND SNAPSHOT +---------------------- +A subvolume in btrfs is not like an LVM logical volume, which is quite +independent from each other, a btrfs subvolume has its hierarchy and relations +between other subvolumes. + +A subvolume in btrfs can be accessed in two ways. + +1. From the parent subvolume + +When accessing from the parent subvolume, the subvolume can be used just +like a directory. It can have child subvolumes and its own files/directories. + +2. Separate mounted filesystem + +When `mount`(8) using 'subvol' or 'subvolid' mount option, one can access +files/directories/subvolumes inside it, but nothing in parent subvolumes. + +Also every btrfs filesystem has a default subvolume as its initially top-level +subvolume, whose subvolume id is 5. (0 is also acceptable as an alias.) + +A btrfs snapshot is much like a subvolume, but shares its data(and metadata) +with other subvolume/snapshot. Due to the capabilities of COW, modifications +inside a snapshot will only show in a snapshot but not in its source subvolume. + +Although in btrfs, subvolumes/snapshots are treated as directories, only +subvolume/snapshot can be the source of a snapshot, snapshot can not be made +from normal directories. + +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 +directory. ++ +`Options` ++ +-i <qgroupid>:::: +Add the newly created subvolume to a qgroup. This option can be given multiple +times. + +*delete* [options] <subvolume> [<subvolume>...]:: +Delete the subvolume(s) from the filesystem. ++ +If <subvolume> 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. The deletion does not involve full commit by default due to +performance reasons (as a consequence, the subvolume may appear again after a +crash). Use one of the '--commit' options to wait until the operation is safely +stored on the media. ++ +`Options` ++ +-c|--commit-after:::: +wait for transaction commit at the end of the operation ++ +-C|--commit-each:::: +wait for transaction commit after delet each subvolume + +*find-new* <subvolume> <last_gen>:: +List the recently modified files in a subvolume, after <last_gen> ID. + +*get-default* <path>:: +Get the default subvolume of the filesystem <path>. ++ +The output format is similar to *subvolume list* command. + +*list* [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>:: +List the subvolumes present in the filesystem <path>. ++ +For every subvolume the following information is shown by default. + +ID <ID> top level <ID> path <path> + +where path is the relative path of the subvolume to the top level subvolume. +The subvolume's ID may be used by the subvolume set-default command, +or at mount time via the subvolid= option. +If `-p` is given, then parent <ID> is added to the output between ID +and top level. The parent's ID may be used at mount time via the +`subvolrootid=` option. ++ +`Options` ++ +-p:::: +print parent ID. +-a:::: +print all the subvolumes in the filesystem and distinguish between +absolute and relative path with respect to the given <path>. +-c:::: +print the ogeneration of the subvolume, aliases: ogen or origin generation. +-g:::: +print the generation of the subvolume. +-o:::: +print only subvolumes below specified <path>. +-u:::: +print the UUID of the subvolume. +-q:::: +print the parent uuid of subvolumes (and snapshots). +-R:::: +print the UUID of the sent subvolume, where the subvolume is the result of a receive operation +-t:::: +print the result as a table. +-s:::: +only snapshot subvolumes in the filesystem will be listed. +-r:::: +only readonly subvolumes in the filesystem will be listed. +-G [+|-]<value>:::: +list subvolumes in the filesystem that its generation is +>=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is +neither \'+' nor \'-', it means = value. +-C [+|-]<value>:::: +list subvolumes in the filesystem that its ogeneration is +>=, \<= or = value. The usage is the same to '-g' option. +--sort=rootid,gen,ogen,path:::: +list subvolumes in order by specified items. +you can add \'\+' or \'-' in front of each items, \'+' means ascending, +\'-' means descending. The default is ascending. ++ +for --sort you can combine some items together by \',', just like +-sort=+ogen,-gen,path,rootid. + +*set-default* <id> <path>:: +Set the subvolume of the filesystem <path> which is mounted as +default. ++ +The subvolume is identified by <id>, which is returned by the *subvolume list* +command. + +*show* <path>:: +Show information of a given subvolume in the <path>. + +*snapshot* [-r] <source> <dest>|[<dest>/]<name>:: +Create a writable/readonly snapshot of the subvolume <source> with the +name <name> in the <dest> directory. ++ +If only <dest> is given, the subvolume will be named the basename of <source>. +If <source> is not a subvolume, btrfs returns an error. +If '-r' is given, the snapshot will be readonly. + +*sync* <path> [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. ++ +`Options` ++ +-s <N>:::: +sleep N seconds between checks (default: 1) + +EXIT STATUS +----------- +*btrfs subvolume* returns a zero exit status if it succeeds. A non-zero value is +returned in case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), +`btrfs-quota`(8), +`btrfs-qgroup`(8), diff --git a/Documentation/btrfs.asciidoc b/Documentation/btrfs.asciidoc new file mode 100644 index 00000000..abf1ff89 --- /dev/null +++ b/Documentation/btrfs.asciidoc @@ -0,0 +1,127 @@ +btrfs(8) +======== + +NAME +---- +btrfs - control a btrfs filesystem + +SYNOPSIS +-------- +*btrfs* <command> [<args>] + +DESCRIPTION +----------- +The *btrfs* utility is a toolbox for managing btrfs filesystems. There are +command groups to work with subvolumes, devices, for whole filesystem or other +specific actions. See section *COMMANDS*. + +COMMAND SYTNAX +-------------- + +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-<group>*. + +For example: it is possible to run *btrfs sub snaps* instead of +*btrfs subvolume snapshot*. +But *btrfs file s* is not allowed, because *file s* may be interpreted +both as *filesystem show* and as *filesystem sync*. + +If the command name is ambiguous, the list of conflicting options is +printed. + +For an overview of a given command use 'btrfs command --help' +or 'btrfs [command...] --help --full' to print all available options. + +COMMANDS +-------- +*balance*:: + Balance btrfs filesystem chunks across single or several devices. + + See `btrfs-balance`(8) for details. + +*check*:: + Do off-line check on a btrfs filesystem. + + See `btrfs-check`(8) for details. + +*device*:: + Manage devices managed by btrfs, including add/delete/scan and so + on. + + See `btrfs-device`(8) for details. + +*filesystem*:: + Manage a btrfs filesystem, including label setting/sync and so on. + + See `btrfs-filesystem`(8) for details. + +*inspect-internal*:: + Debug tools for developers/hackers. + + See `btrfs-inspect-internal`(8) for details. + +*property*:: + Get/set a property from/to a btrfs object. + + See `btrfs-property`(8) for details. + +*qgroup*:: + Manage quota group(qgroup) for btrfs filesystem. + + See `btrfs-qgroup`(8) for details. + +*quota*:: + Manage quota on btrfs filesystem like enabling/rescan and etc. + + See `btrfs-quota`(8) and `btrfs-qgroup`(8) for details. + +*receive*:: + Receive subvolume data from stdin/file for restore and etc. + + See `btrfs-receive`(8) for details. + +*replace*:: + Replace btrfs devices. + + See `btrfs-replace`(8) for details. + +*rescue*:: + Try to rescue damaged btrfs filesystem. + + See `btrfs-rescue`(8) for details. + +*restore*:: + Try to restore files from a damaged btrfs filesystem. + + See `btrfs-restore`(8) for details. + +*scrub*:: + Scrub a btrfs filesystem. + + See `btrfs-scrub`(8) for details. + +*send*:: + Send subvolume data to stdout/file for backup and etc. + + See `btrfs-send`(8) for details. + +*subvolume*:: + Create/delete/list/manage btrfs subvolume. + + See `btrfs-subvolume`(8) for details. + +EXIT STATUS +----------- +*btrfs* returns a zero exit status if it succeeds. Non zero is returned in +case of failure. + +AVAILABILITY +------------ +*btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`mkfs.btrfs`(8), `ionice`(1), +`btrfs-balance`(8), +`btrfs-check`(8), +`btrfs-device`(8), +`btrfs-filesystem`(8), +`btrfs-inspect-internal`(8), +`btrfs-property`(8), +`btrfs-qgroup`(8), +`btrfs-quota`(8), +`btrfs-receive`(8), +`btrfs-replace`(8), +`btrfs-rescue`(8), +`btrfs-restore`(8), +`btrfs-scrub`(8), +`btrfs-send`(8), +`btrfs-subvolume`(8), diff --git a/Documentation/btrfstune.asciidoc b/Documentation/btrfstune.asciidoc new file mode 100644 index 00000000..f5cf15e7 --- /dev/null +++ b/Documentation/btrfstune.asciidoc @@ -0,0 +1,75 @@ +btrfstune(8) +============ + +NAME +---- +btrfstune - tune various filesystem parameters + +SYNOPSIS +-------- +*btrfstune* [options] <dev> [<dev>...] + +DESCRIPTION +----------- +*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. +Please make sure that you have kernel support for the features. You can find a +complete list of features and kernel version of their introduction at +https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature . + +OPTIONS +------- +-S <0|1>:: +Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. + +A seeding filesystem is forced to be mounted read-only. A new device can be added +to the filesystem and will capture all writes keeping the seeding device intact. +-r:: +Enable extended inode refs (hardlink limit per file in a directory is 65536), +enabled by mkfs feature 'extref'. Since kernel 3.7. +-x:: +Enable skinny metadata extent refs (more efficient representation of extents), +enabled by mkfs feature 'skinny-metadata'. Since kernel 3.10. +-n:: +Enable no-holes feature (more efficient representation of file holes), enabled +by mkfs feature 'no-holes'. Since kernel 3.14. +-f:: +Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure +that you are aware of the dangers. +-u:: +Change fsid to a randomly generated UUID or continue previous fsid change +operation in case it was interrupted. +-U <UUID>:: +Change fsid to 'UUID'. ++ +The 'UUID' should be a 36 bytes string in `printf`(3) format +'"%08x-%04x-%04x-%04x-%012x"'. +If there is a previous unfinished fsid change, it will continue only if the +'UUID' matches the unfinished one or if you use the option '-u'. + +WARNING: Cancelling or interrupting a UUID change operation will make the +filesystem temporarily unmountable. To fix it, rerun 'btrfstune -u' to restore +the UUID and let it complete. + +WARNING: Clearing the seeding flag on a device may be dangerous. +If a previously-seeding device is changed, all filesystems that used that +device will become unmountable. Setting the seeding flag back will not fix +that. + +A valid usecase is 'seeding device as a base image'. Clear the seeding +flag, update the filesystem and make it seeding again, provided that it's ok +to throw away all filesystems built on top of the previous base. + +EXIT STATUS +----------- +*btrfstune* returns 0 if no error happened, 1 otherwise. + +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. + +SEE ALSO +-------- +`mkfs.btrfs`(8) diff --git a/Documentation/fsck.btrfs.asciidoc b/Documentation/fsck.btrfs.asciidoc new file mode 100644 index 00000000..0bad075b --- /dev/null +++ b/Documentation/fsck.btrfs.asciidoc @@ -0,0 +1,51 @@ +fsck.btrfs(8) +============= + +NAME +---- +fsck.btrfs - do nothing, successfully + +SYNOPSIS +-------- +*fsck.btrfs* [-aApy] [<device>...] + +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. + +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!). + +OPTIONS +------- +The options are all the same and detect if *fsck.btrfs* is executed in +non-interactive mode and exits with success, +otherwise prints a message about btrfs check. + +EXIT STATUS +----------- +There are two possible exit code returned: + +0:: +No error + +8:: +Operational error, eg. device does not exist + +FILES +----- +`/etc/fstab` + +SEE ALSO +-------- +`btrfs`(8), +`fsck`(8), +`fstab`(5), diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl new file mode 100644 index 00000000..a264fa61 --- /dev/null +++ b/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ +<!-- manpage-base.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- these params silence some output from xmlto --> +<xsl:param name="man.output.quietly" select="1"/> +<xsl:param name="refentry.meta.get.quietly" select="1"/> + +<!-- convert asciidoc callouts to man page format; + git.docbook.backslash and git.docbook.dot params + must be supplied by another XSL file or other means --> +<xsl:template match="co"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB(', + substring-after(@id,'-'),')', + $git.docbook.backslash,'fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB', + substring-after(@arearefs,'-'), + '. ',$git.docbook.backslash,'fR')"/> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>br </xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl new file mode 100644 index 00000000..608eb5df --- /dev/null +++ b/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,17 @@ +<!-- manpage-bold-literal.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- render literal text as bold (instead of plain or monospace); + this makes literal text easier to distinguish in manpages + viewed on a tty --> +<xsl:template match="literal"> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fB</xsl:text> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fR</xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 00000000..a48f5b11 --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ +<!-- manpage-normal.xsl: + special settings for manpages rendered from asciidoc+docbook + handles anything we want to keep away from docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the normal values for the roff control characters --> +<xsl:param name="git.docbook.backslash">\</xsl:param> +<xsl:param name="git.docbook.dot" >.</xsl:param> + +</xsl:stylesheet> diff --git a/Documentation/mkfs.btrfs.asciidoc b/Documentation/mkfs.btrfs.asciidoc new file mode 100644 index 00000000..6a492658 --- /dev/null +++ b/Documentation/mkfs.btrfs.asciidoc @@ -0,0 +1,341 @@ +mkfs.btrfs(8) +============= + +NAME +---- +mkfs.btrfs - create a btrfs filesystem + +SYNOPSIS +-------- +*mkfs.btrfs* +$$[-A|--alloc-start <alloc-start>]$$ +$$[-b|--byte-count <byte-count>]$$ +$$[-d|--data <data-profile>]$$ +$$[-m|--metadata <metadata profile>]$$ +$$[-M|--mixed]$$ +$$[-l|--leafsize <leafsize>]$$ +$$[-n|--nodesize <nodesize>]$$ +$$[-s|--sectorsize <sectorsize>]$$ +$$[-L|--label <label>]$$ +$$[-K|--nodiscard]$$ +$$[-r|--rootdir <rootdir>]$$ +$$[-O|--features <feature1>[,<feature2>...]]$$ +$$[-U|--uuid <UUID>]$$ +$$[-f|--force]$$ +$$[-q|--quiet]$$ +$$[--help]$$ +$$[-V|--version]$$ +$$<device> [<device>...]$$ + +DESCRIPTION +----------- +*mkfs.btrfs* is used to create the btrfs filesystem on a single or multiple +devices. <device> is typically a block device but can be a file-backed image +as well. Multiple devices are grouped by UUID of the filesystem. + +Before mounting such filesystem, the kernel module must know all the devices +either via preceding execution of *btrfs device scan* or using the *device* +mount option. See section *MULTIPLE DEVICES* for more details. + +OPTIONS +------- +*-A|--alloc-start <offset>*:: +(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 <size>*:: +Specify the size of the filesystem. If this option is not used, +mkfs.btrfs uses the entire device space for the filesystem. + +*-d|--data <profile>*:: +Specify the profile for the data block groups. Valid values are 'raid0', +'raid1', 'raid5', 'raid6', 'raid10' or 'single' or dup (case does not matter). ++ +See 'DUP PROFILES ON A SINGLE DEVICE' for more. + +*-m|--metadata <profile>*:: +Specify the profile for the metadata block groups. +Valid values are 'raid0', 'raid1', 'raid5', 'raid6', 'raid10', 'single' or +'dup', (case does not matter). ++ +A single device filesystem will default to 'DUP', unless a SSD is detected. Then +it will default to 'single'. The detection is based on the value of +`/sys/block/DEV/queue/rotational`, where 'DEV' is the short name of the device. ++ +Note that the rotational status can be arbitrarily set by the underlying block +device driver and may not reflect the true status (network block device, memory-backed +SCSI devices etc). Use the options '--data/--metadata' to avoid confusion. ++ +See 'DUP PROFILES ON A SINGLE DEVICE' for more details. + +*-M|--mixed*:: +Normally the data and metadata block groups are isolated. The 'mixed' mode +will remove the isolation and store both types in the same block group type. +This helps to utilize the free space regardless of the purpose and is suitable +for small devices. The separate allocation of block groups leads to a situation +where the space is reserved for the other block group type, is not available for +allocation and can lead to ENOSPC state. ++ +The recommended size for the mixed mode is for filesystems less than 1GiB. The +soft recommendation is to use it for filesystems smaller than 5GiB. The mixed +mode may lead to degraded performance on larger filesystems, but is otherwise +usable, even on multiple devices. ++ +The 'nodesize' and 'sectorsize' must be equal, and the block group types must +match. ++ +NOTE: versions up to 4.2.x forced the mixed mode for devices smaller than 1GiB. +This has been removed in 4.3+ as it caused some usability issues. + +*-l|--leafsize <size>*:: +Alias for --nodesize. Deprecated. + +*-n|--nodesize <size>*:: +Specify the nodesize, the tree block size in which btrfs stores metadata. The +default value is 16KiB (16384) or the page size, whichever is bigger. Must be a +multiple of the sectorsize, 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 +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. ++ +NOTE: versions up to 3.11 set the nodesize to 4k. + +*-s|--sectorsize <size>*:: +Specify the sectorsize, the minimum data block allocation unit. ++ +The default value is the page size and is autodetected. If the sectorsize +differs from the page size, the created filesystem may not be mountable by the +kernel. Therefore it is not recommended to use this option unless you are going +to mount it on a system with the appropriate page size. + +*-L|--label <string>*:: +Specify a label for the filesystem. The 'string' should be less than 256 +bytes and must not contain newline characters. + +*-K|--nodiscard*:: +Do not perform whole device TRIM operation on devices that are capable of that. + +*-r|--rootdir <rootdir>*:: +Populate the toplevel subvolume with files from 'rootdir'. This does not +require root permissions and does not mount the filesystem. + +*-O|--features <feature1>[,<feature2>...]*:: +A list of filesystem features turned on at mkfs time. Not all features are +supported by old kernels. To disable a feature, prefix it with '^'. ++ +See section *FILESYSTEM FEATURES* for more details. To see all available +features that mkfs.btrfs supports run: ++ ++mkfs.btrfs -O list-all+ + +*-f|--force*:: +Forcibly overwrite the block devices when an existing filesystem is detected. +By default, mkfs.btrfs will utilize 'libblkid' to check for any known +filesystem on the devices. Alternatively you can use the `wipefs` utility +to clear the devices. + +*-q|--quiet*:: +Print only error or warning messages. Options --features or --help are unaffected. + +*-U|--uuid <UUID>*:: +Create the filesystem with the given 'UUID'. The UUID must not exist on any +filesystem currently present. + +*-V|--version*:: +Print the *mkfs.btrfs* version and exit. + +*--help*:: +Print help. + +SIZE UNITS +---------- +The default unit is 'byte'. All size parameters accept suffixes in the 1024 +base. The recognized suffixes are: 'k', 'm', 'g', 't', 'p', 'e', both uppercase +and lowercase. + +MULTIPLE DEVICES +---------------- + +Before mounting a multiple device filesystem, the kernel module must know the +association of the block devices that are attached to the filesystem UUID. + +There is typically no action needed from the user. On a system that utilizes a +udev-like daemon, any new block device is automatically registered. The rules +call *btrfs device scan*. + +The same command can be used to trigger the device scanning if the btrfs kernel +module is reloaded (naturally all previous information about the device +registration is lost). + +Another possibility is to use the mount options *device* to specify the list of +devices to scan at the time of mount. + + # mount -o device=/dev/sdb,device=/dev/sdc /dev/sda /mnt + +NOTE: that this means only scanning, if the devices do not exist in the system, +mount will fail anyway. This can happen on systems without initramfs/initrd and +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. + +FILESYSTEM FEATURES +------------------- + +*mixed-bg*:: +mixed data and metadata block groups, also set by option '--mixed' + +*extref*:: +(default since btrfs-progs 3.12, kernel support since 3.7) ++ +increased hardlink limit per file in a directory to 65536, older kernels +supported a varying number of hardlinks depending on the sum of all file name +sizes that can be stored into one metadata block + +*raid56*:: +extended format for RAID5/6, also enabled if raid5 or raid6 block groups +are selected + +*skinny-metadata*:: +(default since btrfs-progs 3.18, kernel support since 3.10) ++ +reduced-size metadata for extent references, saves a few percent of metadata + +*no-holes*:: +improved representation of file extents where holes are not explicitly +stored as an extent, saves a few percent of metadata if sparse files are used + +BLOCK GROUPS, CHUNKS, RAID +-------------------------- + +The highlevel organizational units of a filesystem are block groups of three types: +data, metadata and system. + +*DATA*:: +store data blocks and nothing else + +*METADATA*:: +store internal metadata in b-trees, can store file data if they fit into the +inline limit + +*SYSTEM*:: +store structures that describe the mapping between the physical devices and the +linear logical space representing the filesystem + +Other terms commonly used: + +*block group*:: +*chunk*:: +a logical range of space of a given profile, stores data, metadata or both; +sometimes the terms are used interchangably ++ +A typical size of metadata block group is 256MiB (filesystem smaller than +50GiB) and 1GiB (larger than 50GiB), for data it's 1GiB. The system block group +size is a few megabytes. + +*RAID*:: +a block group profile type that utilizes RAID-like features on multiple +devices: striping, mirroring, parity + +*profile*:: +when used in connection with block groups refers to the allocation strategy +and constraints, see the section 'PROFILES' for more details + +PROFILES +-------- + +There are the following block group types available: + +[ cols="^,^,^,^,^",width="60%" ] +|============================================================= +.2+^.<h| Profile 3+^.^h| Redundancy .2+^.<h| Min/max devices + ^.^h| Copies ^.^h| Parity ^.<h| Striping +| single | 1 | | | 1/any +| DUP | 2 / 1 device | | | 1/1 ^(see note)^ +| RAID0 | | | 1 to N | 2/any +| RAID1 | 2 | | | 2/any +| RAID10 | 2 | | 1 to N | 4/any +| RAID5 | 1 | 1 | 2 to N - 1 | 2/any +| RAID6 | 1 | 2 | 3 to N - 2 | 3/any +|============================================================= + +'Note:' DUP may exist on more than 1 device if it starts on a single device and +another one is added, but *mkfs.btrfs* will not let you create DUP on multiple +devices. + +DUP PROFILES ON A SINGLE DEVICE +------------------------------- + +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 +deduplicating them. This negates the purpose of increased redunancy and just +wastes space. + +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. + +The traditional rotational hard drives usually fail at the sector level. + +In any case, a device that starts to misbehave and repairs from the DUP copy +should be replaced! *DUP is not backup*. + +KNOWN ISSUES +------------ + +**SMALL FILESYSTEMS AND LARGE NODESIZE** + +The combination of small filesystem size and large nodesize is not recommended +in general and can lead to various ENOSPC-related issues during mount time or runtime. + +Since mixed block group creation is optional, we allow small +filesystem instances with differing values for 'sectorsize' and 'nodesize' +to be created and could end up in the following situation: + + # mkfs.btrfs -f -n 65536 /dev/loop0 + btrfs-progs v3.19-rc2-405-g976307c + See http://btrfs.wiki.kernel.org for more information. + + Performing full device TRIM (512.00MiB) ... + Label: (null) + UUID: 49fab72e-0c8b-466b-a3ca-d1bfe56475f0 + Node size: 65536 + Sector size: 4096 + Filesystem size: 512.00MiB + Block group profiles: + Data: single 8.00MiB + Metadata: DUP 40.00MiB + System: DUP 12.00MiB + SSD detected: no + Incompat features: extref, skinny-metadata + Number of devices: 1 + Devices: + ID SIZE PATH + 1 512.00MiB /dev/loop0 + + # mount /dev/loop0 /mnt/ + mount: mount /dev/loop0 on /mnt failed: No space left on device + +The ENOSPC occurs during the creation of the UUID tree. This is caused +by large metadata blocks and space reservation strategy that allocates more +than can fit into the filesystem. + + +AVAILABILITY +------------ +*mkfs.btrfs* is part of btrfs-progs. +Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for +further details. + +SEE ALSO +-------- +`btrfs`(8), `wipefs`(8) |