mirror of
https://github.com/kdave/btrfs-progs
synced 2025-03-25 04:16:32 +00:00
btrfs-progs: docs: enhance btrfs-filesystem manual page
Wording, formatting, explanations, examples. Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
parent
ac45d64c04
commit
ecd4bb607f
@ -3,7 +3,7 @@ btrfs-filesystem(8)
|
||||
|
||||
NAME
|
||||
----
|
||||
btrfs-filesystem - control btrfs filesystem
|
||||
btrfs-filesystem - command group of btrfs that usually work on the whole filesystem
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
@ -11,14 +11,49 @@ SYNOPSIS
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
*btrfs filesystem* is used to do the filesystem level control jobs, including
|
||||
all the regular filesystem operations like setting/getting label,
|
||||
resizing, defragment.
|
||||
*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 space usage information for a mount point.
|
||||
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`
|
||||
+
|
||||
@ -44,7 +79,7 @@ show sizes in TiB, or TB with --si
|
||||
If conflicting options are passed, the last one takes precedence.
|
||||
|
||||
*defragment* [options] <file>|<dir> [<file>|<dir>...]::
|
||||
Defragment file data and/or directory metadata *online*.
|
||||
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
|
||||
@ -57,7 +92,7 @@ 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`,
|
||||
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.
|
||||
@ -65,11 +100,11 @@ ref-links.
|
||||
`Options`
|
||||
+
|
||||
-v::::
|
||||
be verbose
|
||||
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.
|
||||
compression. See also section 'EXAMPLES'.
|
||||
-r::::
|
||||
defragment files recursively in given directories
|
||||
-f::::
|
||||
@ -77,45 +112,51 @@ flush data for each file before going to the next file. This will limit the amou
|
||||
of dirty data to current file, otherwise the amount cumulates from several files
|
||||
and may increase system load.
|
||||
-s <start>[kKmMgGtTpPeE]::::
|
||||
defragment only from byte <start> onward
|
||||
defragmentation will start from the given offset, default is beginning of a file
|
||||
-l <len>[kKmMgGtTpPeE]::::
|
||||
defragment only up to <len> bytes
|
||||
defragment only up to 'len' bytes, default is the file size
|
||||
-t <size>[kKmMgGtTpPeE]::::
|
||||
target extent size, do not touch extents bigger than <size>
|
||||
target extent size, do not touch extents bigger than 'size'
|
||||
+
|
||||
For <start>, <len>, <size> it is possible to append
|
||||
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.
|
||||
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.
|
||||
Show or update the label of a filesystem. This works on a mounted filesystem or
|
||||
a filesystem image.
|
||||
+
|
||||
[<device>|<mountpoint>] is used to identify the filesystem.
|
||||
If a newlabel optional argument is passed, the label is changed.
|
||||
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
|
||||
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 directory <path>. A particular device
|
||||
can be resized by specifying a <devid>.
|
||||
Resize a mounted filesystem identified by 'path'. A particular device
|
||||
can be resized by specifying a 'devid'.
|
||||
+
|
||||
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
|
||||
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 with *btrfs filesystem show* and
|
||||
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, the unit of the <size> parameter defaults to
|
||||
bytes. Optionally, the size parameter may be suffixed by one of the following
|
||||
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.
|
||||
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 devid.
|
||||
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
|
||||
@ -123,21 +164,29 @@ 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 disk cylinder as before.
|
||||
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.
|
||||
Show the btrfs filesystem with some additional info about devices and space
|
||||
allocation.
|
||||
+
|
||||
If no option nor <path>|<uuid>|<device>|<label> is passed, btrfs shows
|
||||
information of all the btrfs filesystem both mounted and unmounted.
|
||||
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 btrfs kernel to list mounted btrfs filesystems(s)
|
||||
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.
|
||||
/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::::
|
||||
@ -156,10 +205,48 @@ show sizes in GiB, or GB with --si
|
||||
show sizes in TiB, or TB with --si
|
||||
|
||||
*sync* <path>::
|
||||
Force a sync for the filesystem identified by <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.
|
||||
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`
|
||||
+
|
||||
@ -186,6 +273,55 @@ 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
|
||||
|
Loading…
Reference in New Issue
Block a user