summaryrefslogtreecommitdiff
path: root/Documentation/btrfs-balance.8
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/btrfs-balance.8')
-rw-r--r--Documentation/btrfs-balance.8547
1 files changed, 547 insertions, 0 deletions
diff --git a/Documentation/btrfs-balance.8 b/Documentation/btrfs-balance.8
new file mode 100644
index 00000000..c686381c
--- /dev/null
+++ b/Documentation/btrfs-balance.8
@@ -0,0 +1,547 @@
+'\" t
+.\" Title: btrfs-balance
+.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\" Date: 12/05/2018
+.\" Manual: Btrfs Manual
+.\" Source: Btrfs v4.19.1
+.\" Language: English
+.\"
+.TH "BTRFS\-BALANCE" "8" "12/05/2018" "Btrfs v4\&.19\&.1" "Btrfs Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+btrfs-balance \- balance block groups on a btrfs filesystem
+.SH "SYNOPSIS"
+.sp
+\fBbtrfs balance\fR \fI<subcommand>\fR \fI<args>\fR
+.SH "DESCRIPTION"
+.sp
+The primary purpose of the balance feature is to spread block groups across all devices so they match constraints defined by the respective profiles\&. See \fBmkfs\&.btrfs\fR(8) section \fIPROFILES\fR 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\&.
+.sp
+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 as an internal state and will be resumed upon mount, unless the mount option \fIskip_balance\fR is specified\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBWarning\fR
+.ps -1
+.br
+.sp
+running balance without filters will take a lot of time as it basically rewrites the entire filesystem and needs to update all block pointers\&.
+.sp .5v
+.RE
+.sp
+The filters can be used to perform following actions:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+convert block group profiles (filter
+\fIconvert\fR)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+make block group usage more compact (filter
+\fIusage\fR)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+perform actions only on a given device (filters
+\fIdevid\fR,
+\fIdrange\fR)
+.RE
+.sp
+The filters can be applied to a combination of block group types (data, metadata, system)\&. Note that changing \fIsystem\fR needs the force option\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+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 \fIENOSPC\fR for more details\&.
+.sp .5v
+.RE
+.SH "COMPATIBILITY"
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+The balance subcommand also exists under the \fBbtrfs filesystem\fR namespace\&. This still works for backward compatibility but is deprecated and should not be used any more\&.
+.sp .5v
+.RE
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+.sp
+A short syntax \fBbtrfs balance \fR\fB\fI<path>\fR\fR works due to backward compatibility but is deprecated and should not be used any more\&. Use \fBbtrfs balance start\fR command instead\&.
+.sp .5v
+.RE
+.SH "PERFORMANCE IMPLICATIONS"
+.sp
+Balancing operations are very IO intensive and can also be quite CPU intensive, impacting other ongoing filesystem operations\&. Typically large amounts of data are copied from one location to another, with corresponding metadata updates\&.
+.sp
+Depending upon the block group layout, it can also be seek heavy\&. Performance on rotational devices is noticeably worse compared to SSDs or fast arrays\&.
+.SH "SUBCOMMAND"
+.PP
+\fBcancel\fR \fI<path>\fR
+.RS 4
+cancels a running or paused balance, the command will block and wait until the current blockgroup being processed completes
+.RE
+.PP
+\fBpause\fR \fI<path>\fR
+.RS 4
+pause running balance operation, this will store the state of the balance progress and used filters to the filesystem
+.RE
+.PP
+\fBresume\fR \fI<path>\fR
+.RS 4
+resume interrupted balance, the balance status must be stored on the filesystem from previous run, eg\&. after it was forcibly interrupted and mounted again with
+\fIskip_balance\fR
+.RE
+.PP
+\fBstart\fR [options] \fI<path>\fR
+.RS 4
+start the balance operation according to the specified filters, no filters will rewrite the entire filesystem\&. The process runs in the foreground\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+the balance command without filters will basically rewrite everything in the filesystem\&. The run time is potentially very long, depending on the filesystem size\&. To prevent starting a full balance by accident, the user is warned and has a few seconds to cancel the operation before it starts\&. The warning and delay can be skipped with
+\fI\-\-full\-balance\fR
+option\&.
+.sp .5v
+.RE
+Please note that the filters must be written together with the
+\fI\-d\fR,
+\fI\-m\fR
+and
+\fI\-s\fR
+options, because they\(cqre optional and bare
+\fI\-d\fR
+etc also work and mean no filters\&.
+.sp
+\fBOptions\fR
+.PP
+\-d[\fI<filters>\fR]
+.RS 4
+act on data block groups, see
+\fBFILTERS\fR
+section for details about
+\fIfilters\fR
+.RE
+.PP
+\-m[\fI<filters>\fR]
+.RS 4
+act on metadata chunks, see
+\fBFILTERS\fR
+section for details about
+\fIfilters\fR
+.RE
+.PP
+\-s[\fI<filters>\fR]
+.RS 4
+act on system chunks (requires
+\fI\-f\fR), see
+\fBFILTERS\fR
+section for details about
+\fIfilters\fR\&.
+.RE
+.PP
+\-v
+.RS 4
+be verbose and print balance filter arguments
+.RE
+.PP
+\-f
+.RS 4
+force reducing of metadata integrity, eg\&. when going from
+\fIraid1\fR
+to
+\fIsingle\fR
+.RE
+.PP
+\-\-background|\-\-bg
+.RS 4
+run the balance operation asynchronously in the background, uses
+\fBfork\fR(2) to start the process that calls the kernel ioctl
+.RE
+.RE
+.PP
+\fBstatus\fR [\-v] \fI<path>\fR
+.RS 4
+Show status of running or paused balance\&.
+.sp
+If
+\fI\-v\fR
+option is given, output will be verbose\&.
+.RE
+.SH "FILTERS"
+.sp
+From kernel 3\&.3 onwards, btrfs balance can limit its action to a subset of the whole filesystem, and can be used to change the replication configuration (e\&.g\&. moving data from single to RAID1)\&. This functionality is accessed through the \fI\-d\fR, \fI\-m\fR or \fI\-s\fR options to btrfs balance start, which filter on data, metadata and system blocks respectively\&.
+.sp
+A filter has the following structure: \fItype\fR[=\fIparams\fR][,\fItype\fR=\&...]
+.sp
+The available types are:
+.PP
+\fBprofiles=\fR\fB\fI<profiles>\fR\fR
+.RS 4
+Balances only block groups with the given profiles\&. Parameters are a list of profile names separated by "\fI|\fR" (pipe)\&.
+.RE
+.PP
+\fBusage=\fR\fB\fI<percent>\fR\fR, \fBusage=\fR\fB\fI<range>\fR\fR
+.RS 4
+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
+\fIusage=0\fR
+in case balance is returning ENOSPC and your filesystem is not too full\&.
+.sp
+The argument may be a single value or a range\&. The single value
+\fIN\fR
+means
+\fIat most N percent used\fR, equivalent to
+\fI\&.\&.N\fR
+range syntax\&. Kernels prior to 4\&.4 accept only the single value format\&. The minimum range boundary is inclusive, maximum is exclusive\&.
+.RE
+.PP
+\fBdevid=\fR\fB\fI<id>\fR\fR
+.RS 4
+Balances only block groups which have at least one chunk on the given device\&. To list devices with ids use
+\fBbtrfs filesystem show\fR\&.
+.RE
+.PP
+\fBdrange=\fR\fB\fI<range>\fR\fR
+.RS 4
+Balance only block groups which overlap with the given byte range on any device\&. Use in conjunction with
+\fIdevid\fR
+to filter on a specific device\&. The parameter is a range specified as
+\fIstart\&.\&.end\fR\&.
+.RE
+.PP
+\fBvrange=\fR\fB\fI<range>\fR\fR
+.RS 4
+Balance only block groups which overlap with the given byte range in the filesystem\(cqs 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
+\fIstart\&.\&.end\fR\&.
+.RE
+.PP
+\fBconvert=\fR\fB\fI<profile>\fR\fR
+.RS 4
+Convert each selected block group to the given profile name identified by parameters\&.
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+starting with kernel 4\&.5, the
+\fIdata\fR
+chunks can be converted to/from the
+\fIDUP\fR
+profile on a single device\&.
+.sp .5v
+.RE
+.if n \{\
+.sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+starting with kernel 4\&.6, all profiles can be converted to/from
+\fIDUP\fR
+on multi\-device filesystems\&.
+.sp .5v
+.RE
+.RE
+.PP
+\fBlimit=\fR\fB\fI<number>\fR\fR, \fBlimit=\fR\fB\fI<range>\fR\fR
+.RS 4
+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 (\fIdrange\fR,
+\fIvrange\fR) or just simply limit the amount of work done by a single balance run\&.
+.sp
+The argument may be a single value or a range\&. The single value
+\fIN\fR
+means
+\fIat most N chunks\fR, equivalent to
+\fI\&.\&.N\fR
+range syntax\&. Kernels prior to 4\&.4 accept only the single value format\&. The range minimum and maximum are inclusive\&.
+.RE
+.PP
+\fBstripes=\fR\fB\fI<range>\fR\fR
+.RS 4
+Balance only block groups which have the given number of stripes\&. The parameter is a range specified as
+\fIstart\&.\&.end\fR\&. Makes sense for block group profiles that utilize striping, ie\&. RAID0/10/5/6\&. The range minimum and maximum are inclusive\&.
+.RE
+.PP
+\fBsoft\fR
+.RS 4
+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\&.
+.sp
+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\&.
+.RE
+.sp
+Profile names, used in \fIprofiles\fR and \fIconvert\fR are one of: \fIraid0\fR, \fIraid1\fR, \fIraid10\fR, \fIraid5\fR, \fIraid6\fR, \fIdup\fR, \fIsingle\fR\&. The mixed data/metadata profiles can be converted in the same way, but it\(cqs conversion between mixed and non\-mixed is not implemented\&. For the constraints of the profiles please refer to \fBmkfs\&.btrfs\fR(8), section \fIPROFILES\fR\&.
+.SH "ENOSPC"
+.sp
+The way balance operates, it usually needs to temporarily create a new block group and move the old data there, before the old block group can be removed\&. For that it needs the work space, otherwise it fails for ENOSPC reasons\&. This is not the same ENOSPC as if the free space is exhausted\&. This refers to the space on the level of block groups, which are bigger parts of the filesystem that contain many file extents\&.
+.sp
+The free work space can be calculated from the output of the \fBbtrfs filesystem show\fR command:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+ Label: \*(AqBTRFS\*(Aq 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
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+\fIsize\fR \- \fIused\fR = \fIfree work space\fR \fI53\&.90GiB\fR \- \fI51\&.90GiB\fR = \fI2\&.00GiB\fR
+.sp
+An example of a filter that does not require workspace is \fIusage=0\fR\&. This will scan through all unused block groups of a given type and will reclaim the space\&. After that it might be possible to run other filters\&.
+.sp
+\fBCONVERSIONS ON MULTIPLE DEVICES\fR
+.sp
+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 consume the work space\&.
+.SH "EXAMPLES"
+.sp
+A more comprehensive example when going from one to multiple devices, and back, can be found in section \fITYPICAL USECASES\fR of \fBbtrfs\-device\fR(8)\&.
+.SS "MAKING BLOCK GROUP LAYOUT MORE COMPACT"
+.sp
+The layout of block groups is not normally visible; most tools report only summarized numbers of free or used space, but there are still some hints provided\&.
+.sp
+Let\(cqs use the following real life example and start with the output:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ btrfs filesystem df /path
+Data, single: total=75\&.81GiB, used=64\&.44GiB
+System, RAID1: total=32\&.00MiB, used=20\&.00KiB
+Metadata, RAID1: total=15\&.87GiB, used=8\&.84GiB
+GlobalReserve, single: total=512\&.00MiB, used=0\&.00B
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Roughly calculating for data, \fI75G \- 64G = 11G\fR, the used/total ratio is about \fI85%\fR\&. How can we can interpret that:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+chunks are filled by 85% on average, ie\&. the
+\fIusage\fR
+filter with anything smaller than 85 will likely not affect anything
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+in a more realistic scenario, the space is distributed unevenly, we can assume there are completely used chunks and the remaining are partially filled
+.RE
+.sp
+Compacting the layout could be used on both\&. In the former case it would spread data of a given chunk to the others and removing it\&. Here we can estimate that roughly 850 MiB of data have to be moved (85% of a 1 GiB chunk)\&.
+.sp
+In the latter case, targeting the partially used chunks will have to move less data and thus will be faster\&. A typical filter command would look like:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# btrfs balance start \-dusage=50 /path
+Done, had to relocate 2 out of 97 chunks
+
+$ btrfs filesystem df /path
+Data, single: total=74\&.03GiB, used=64\&.43GiB
+System, RAID1: total=32\&.00MiB, used=20\&.00KiB
+Metadata, RAID1: total=15\&.87GiB, used=8\&.84GiB
+GlobalReserve, single: total=512\&.00MiB, used=0\&.00B
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+As you can see, the \fItotal\fR amount of data is decreased by just 1 GiB, which is an expected result\&. Let\(cqs see what will happen when we increase the estimated usage filter\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# btrfs balance start \-dusage=85 /path
+Done, had to relocate 13 out of 95 chunks
+
+$ btrfs filesystem df /path
+Data, single: total=68\&.03GiB, used=64\&.43GiB
+System, RAID1: total=32\&.00MiB, used=20\&.00KiB
+Metadata, RAID1: total=15\&.87GiB, used=8\&.85GiB
+GlobalReserve, single: total=512\&.00MiB, used=0\&.00B
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Now the used/total ratio is about 94% and we moved about \fI74G \- 68G = 6G\fR of data to the remaining blockgroups, ie\&. the 6GiB are now free of filesystem structures, and can be reused for new data or metadata block groups\&.
+.sp
+We can do a similar exercise with the metadata block groups, but this should not typically be necessary, unless the used/total ratio is really off\&. Here the ratio is roughly 50% but the difference as an absolute number is "a few gigabytes", which can be considered normal for a workload with snapshots or reflinks updated frequently\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# btrfs balance start \-musage=50 /path
+Done, had to relocate 4 out of 89 chunks
+
+$ btrfs filesystem df /path
+Data, single: total=68\&.03GiB, used=64\&.43GiB
+System, RAID1: total=32\&.00MiB, used=20\&.00KiB
+Metadata, RAID1: total=14\&.87GiB, used=8\&.85GiB
+GlobalReserve, single: total=512\&.00MiB, used=0\&.00B
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Just 1 GiB decrease, which possibly means there are block groups with good utilization\&. Making the metadata layout more compact would in turn require updating more metadata structures, ie\&. lots of IO\&. As running out of metadata space is a more severe problem, it\(cqs not necessary to keep the utilization ratio too high\&. For the purpose of this example, let\(cqs see the effects of further compaction:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# btrfs balance start \-musage=70 /path
+Done, had to relocate 13 out of 88 chunks
+
+$ btrfs filesystem df \&.
+Data, single: total=68\&.03GiB, used=64\&.43GiB
+System, RAID1: total=32\&.00MiB, used=20\&.00KiB
+Metadata, RAID1: total=11\&.97GiB, used=8\&.83GiB
+GlobalReserve, single: total=512\&.00MiB, used=0\&.00B
+.fi
+.if n \{\
+.RE
+.\}
+.SS "GETTING RID OF COMPLETELY UNUSED BLOCK GROUPS"
+.sp
+Normally the balance operation needs a work space, to temporarily move the data before the old block groups gets removed\&. If there\(cqs no work space, it ends with \fIno space left\fR\&.
+.sp
+There\(cqs a special case when the block groups are completely unused, possibly left after removing lots of files or deleting snapshots\&. Removing empty block groups is automatic since 3\&.18\&. The same can be achieved manually with a notable exception that this operation does not require the work space\&. Thus it can be used to reclaim unused block groups to make it available\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+# btrfs balance start \-dusage=0 /path
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+This should lead to decrease in the \fItotal\fR numbers in the \fBbtrfs filesystem df\fR output\&.
+.SH "EXIT STATUS"
+.sp
+\fBbtrfs balance\fR returns a zero exit status if it succeeds\&. Non zero is returned in case of failure\&.
+.SH "AVAILABILITY"
+.sp
+\fBbtrfs\fR is part of btrfs\-progs\&. Please refer to the btrfs wiki \m[blue]\fBhttp://btrfs\&.wiki\&.kernel\&.org\fR\m[] for further details\&.
+.SH "SEE ALSO"
+.sp
+\fBmkfs\&.btrfs\fR(8), \fBbtrfs\-device\fR(8)