From 7ffccaf0c3b4d4979d7d74bab3d79d9541a6e665 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Tue, 14 Apr 2015 17:37:23 +0200 Subject: btrfs-progs: Documentaion: rename to .asciidoc A few minor benefits: * editors set highliting according to the extensions * web access to the git repository (github) renders the .asciidoc files: * we can link to them from the wiki * the files are editable via browser and such editations can be submitted for merge easily Signed-off-by: David Sterba --- Documentation/btrfs-balance.asciidoc | 140 +++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 Documentation/btrfs-balance.asciidoc (limited to 'Documentation/btrfs-balance.asciidoc') diff --git a/Documentation/btrfs-balance.asciidoc b/Documentation/btrfs-balance.asciidoc new file mode 100644 index 00000000..6d2fd0c3 --- /dev/null +++ b/Documentation/btrfs-balance.asciidoc @@ -0,0 +1,140 @@ +btrfs-balance(8) +================ + +NAME +---- +btrfs-balance - balance btrfs filesystem + +SYNOPSIS +-------- +*btrfs balance* + +DESCRIPTION +----------- +*btrfs balance* is used to balance chunks in a btrfs filesystem across +multiple or even single device. + +See `btrfs-device`(8) for more details about the effect on device management. + +NOTE: The balance subcommand also exists under the *filesystem* namespace. This +still works for backward compatibility but is deprecated and should not be +used anymore. + +NOTE: A short syntax *btrfs balance * works due to backward compatibility +but is deprecated and should not be used anymore. Use *btrfs balance start* +command instead. + +SUBCOMMAND +---------- +*cancel* :: +Cancel running or paused balance. + +*pause* :: +Pause running balance. + +*resume* :: +Resume interrupted balance. + +*start* [options] :: +Balance chunks across the devices *online*. ++ +Balance and/or convert (change allocation profile of) chunks that +passed all filters in a comma-separated list of filters for a +particular chunk type. +If filter list is not given balance all chunks of that type. +In case none of the -d, -m or -s options is +given balance all chunks in a filesystem. ++ +`Options` ++ +-d[]:::: +act on data chunks. See `FILTERS` section for details about . +-m[]:::: +act on metadata chunks. See `FILTERS` section for details about . +-s[]:::: +act on system chunks (only under -f). See `FILTERS` section for details about . +-v:::: +be verbose +-f:::: +force reducing of metadata integrity + +*status* [-v] :: +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 RAID-1). 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*:: +Balances only block groups with the given replication profiles. Parameters +are a list of profile names separated by |. + +*usage*:: +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 space allocated. You may want to use usage=0 in +case balance is returnin ENOSPC and your filesystem is not too full. + +*devid*:: +Balances only block groups which have at least one chunk on the given +device (by btrfs device ID -- use btrfs fi show to list device IDs) + +*drange*:: +Balances 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 . + +*vrange*:: +Balances 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 . + +*convert*:: +Convert each selected block group to the given profile name identified by +parameters. + +*limit*:: +Process only given number of chunks, after all filters apply. 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. + +*soft*:: +Takes no parameters. Only has meaning when converting between profiles. +When doing convert from one profile to another and soft mode is on, +restriper won't touch chunks that already have the target profile. This is +useful if e.g. half of the FS was converted earlier. ++ +The soft mode switch is (like every other filter) per-type. This means +that we can convert for example meta 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'. + +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) -- cgit v1.2.3