diff options
Diffstat (limited to 'man/btrfs.8.in')
| -rw-r--r-- | man/btrfs.8.in | 258 |
1 files changed, 221 insertions, 37 deletions
diff --git a/man/btrfs.8.in b/man/btrfs.8.in index be478e0..af7df4d 100644 --- a/man/btrfs.8.in +++ b/man/btrfs.8.in @@ -7,52 +7,74 @@ btrfs \- control a btrfs filesystem .SH SYNOPSIS \fBbtrfs\fP \fBsubvolume snapshot\fP\fI [-r] <source> [<dest>/]<name>\fP .PP -\fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume>\fP +\fBbtrfs\fP \fBsubvolume delete\fP\fI <subvolume> [<subvolume>...]\fP .PP \fBbtrfs\fP \fBsubvolume create\fP\fI [<dest>/]<name>\fP .PP -\fBbtrfs\fP \fBsubvolume list\fP\fI [-p] <path>\fP +\fBbtrfs\fP \fBsubvolume list\fP\fI [-acgoprts] [-G [+|-]value] [-C [+|-]value] [--sort=rootid,gen,ogen,path] <path>\fP .PP \fBbtrfs\fP \fBsubvolume set-default\fP\fI <id> <path>\fP .PP \fBbtrfs\fP \fBsubvolume get-default\fP\fI <path>\fP .PP -\fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP +\fBbtrfs\fP \fBsubvolume find-new\fP\fI <subvolume> <last_gen>\fP .PP -\fBbtrfs\fP \fBfilesystem resize\fP\fI [+/\-]<size>[gkm]|max <filesystem>\fP +\fBbtrfs\fP \fBsubvolume show\fP\fI <path>\fP .PP -\fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP +\fBbtrfs\fP \fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] \ +[-s \fIstart\fR] [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> \ +[<\fIfile\fR>|<\fIdir\fR>...] .PP -\fBbtrfs\fP \fBfilesystem defrag\fP\fI [options] <file>|<dir> [<file>|<dir>...]\fP +\fBbtrfs\fP \fBfilesystem sync\fP\fI <path> \fP .PP -\fBbtrfs\fP \fBsubvolume find-new\fP\fI <subvolume> <last_gen>\fP +\fBbtrfs\fP \fBfilesystem resize\fP\fI [devid:][+/\-]<size>[gkm]|[devid:]max <filesystem>\fP .PP -\fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP +\fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP .PP -\fBbtrfs\fP \fBfilesystem defragment\fP\fI <file>|<dir> [<file>|<dir>...]\fP +\fBbtrfs\fP \fBfilesystem balance\fP\fI <path> \fP .PP \fBbtrfs\fP \fBdevice scan\fP\fI [--all-devices|<device> [<device>...]]\fP .PP -\fBbtrfs\fP \fBdevice show\fP\fI [--all-devices|<uuid>|<label>]\fP +\fBbtrfs\fP \fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP} .PP \fBbtrfs\fP \fBdevice add\fP\fI <device> [<device>...] <path> \fP .PP \fBbtrfs\fP \fBdevice delete\fP\fI <device> [<device>...] <path> \fP .PP -\fBbtrfs\fP \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP} +\fBbtrfs\fP \fBreplace start\fP \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fP +.PP +\fBbtrfs\fP \fBreplace status\fP \fI[-1] <path>\fP +.PP +\fBbtrfs\fP \fBreplace cancel\fP \fI<path>\fP +.PP +\fBbtrfs\fP \fBscrub start\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP} .PP \fBbtrfs\fP \fBscrub cancel\fP {\fI<path>\fP|\fI<device>\fP} .PP -\fBbtrfs\fP \fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP} +\fBbtrfs\fP \fBscrub resume\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP} .PP \fBbtrfs\fP \fBscrub status\fP [-d] {\fI<path>\fP|\fI<device>\fP} .PP \fBbtrfs\fP \fBinspect-internal inode-resolve\fP [-v] \fI<inode>\fP \fI<path>\fP .PP \fBbtrfs\fP \fBinspect-internal logical-resolve\fP -[-Pv] \fI<logical>\fP \fI<path>\fP +[-Pv] [-s size] \fI<logical>\fP \fI<path>\fP .PP -\fBbtrfs\fP \fBhelp|\-\-help|\-h \fP\fI\fP +\fBbtrfs\fP \fBinspect-internal subvolid-resolve\fP \fI<subvolid>\fP \fI<path>\fP +.PP +\fBbtrfs\fP \fBqgroup assign\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP +.PP +\fBbtrfs\fP \fBqgroup remove\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP +.PP +\fBbtrfs\fP \fBqgroup create\fP \fI<qgroupid>\fP \fI<path>\fP +.PP +\fBbtrfs\fP \fBqgroup destroy\fP \fI<qgroupid>\fP \fI<path>\fP +.PP +\fBbtrfs\fP \fBqgroup show\fP \fI<path>\fP +.PP +\fBbtrfs\fP \fBqgroup limit\fP [options] \fI<size>\fP|\fBnone\fP [\fI<qgroupid>\fP] \fI<path>\fP +.PP +\fBbtrfs\fP \fBhelp|\-\-help \fP\fI\fP .PP \fBbtrfs\fP \fB<command> \-\-help \fP\fI\fP .PP @@ -78,7 +100,7 @@ and as .I filesystem sync. In this case .I btrfs -returnsfilesystem sync +returns filesystem sync If a command is terminated by .I --help , the detailed help is showed. If the passed command matches more commands, @@ -98,7 +120,7 @@ subvolume, \fBbtrfs\fR returns an error. If \fI-r\fR is given, the snapshot will be readonly. .TP -\fBsubvolume delete\fR\fI <subvolume>\fR +\fBsubvolume delete\fR\fI <subvolume> [<subvolume>...]\fR Delete the subvolume \fI<subvolume>\fR. If \fI<subvolume>\fR is not a subvolume, \fBbtrfs\fR returns an error. .TP @@ -108,17 +130,54 @@ Create a subvolume in \fI<dest>\fR (or in the current directory if \fI<dest>\fR is omitted). .TP -\fBsubvolume list\fR\fI [-p] <path>\fR +\fBsubvolume list\fR\fI [-acgoprts] [-G [+|-]value] [-C [+|-]value] [--sort=rootid,gen,ogen,path] <path>\fR +.RS List the subvolumes present in the filesystem \fI<path>\fR. 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 \fItop level\fR subvolume. + The subvolume's ID may be used by the \fBsubvolume set-default\fR command, or -at mount time via the \fIsubvol=\fR option. +at mount time via the \fIsubvolid=\fR option. If \fI-p\fR is given, then \fIparent <ID>\fR is added to the output between ID and top level. The parent's ID may be used at mount time via the \fIsubvolrootid=\fR option. + +\fB-t\fP print the result as a table. + +\fB-a\fP print all the subvolumes in the filesystem and distinguish between +absolute and relative path with respect to the given <path>. + +\fB-c\fP print the ogeneration of the subvolume, aliases: ogen or origin generation + +\fB-g\fP print the generation of the subvolume + +\fB-u\fP print the UUID of the subvolume + +\fB-o\fP print only subvolumes bellow specified <path>. + +\fB-r\fP only readonly subvolumes in the filesystem will be listed. + +\fB-s\fP only snapshot subvolumes in the filesystem will be listed. + +\fB-G [+|-]value\fP +list subvolumes in the filesystem that its generation is +>=, <= or = value. '+' means >= value, '-' means <= value, If there is +neither '+' nor '-', it means = value. + +\fB-C [+|-]value\fP +list subvolumes in the filesystem that its ogeneration is +>=, <= or = value. The usage is the same to '-g' option. + +\fB--sort=rootid,gen,ogen,path\fP +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 \fB--sort\fP you can combine some items together by ',', just like +\f--sort=+ogen,-gen,path,rootid\fR. +.RE .TP \fBsubvolume set-default\fR\fI <id> <path>\fR @@ -132,12 +191,25 @@ Get the default subvolume of the filesystem \fI<path>\fR. The output format is similar to \fBsubvolume list\fR command. .TP -\fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] [-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...] +\fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR +List the recently modified files in a subvolume, after \fI<last_gen>\fR ID. +.TP + +\fBsubvolume show\fR\fI <path>\fR +Show information of a given subvolume in the \fI<path>\fR. +.TP + +\fBfilesystem defragment\fP -c[zlib|lzo] [-l \fIlen\fR] [-s \fIstart\fR] \ +[-t \fIsize\fR] -[vf] <\fIfile\fR>|<\fIdir\fR> [<\fIfile\fR>|<\fIdir\fR>...] Defragment file data and/or directory metadata. To defragment all files in a directory you have to specify each one on its own or use your shell wildcards. -The start position and the number of bytes to deframention can be specified by \fIstart\fR and \fIlen\fR. Any extent bigger than \fIthresh\fR will be considered already defragged. Use 0 to take the kernel default, and use 1 to say eveery single extent must be rewritten. You can also turn on compression in defragment operations. +The start position and the number of bytes to defragment can be specified by +\fIstart\fR and \fIlen\fR. Any extent bigger than threshold will be +considered already defragged. Use 0 to take the kernel default, and use 1 to +say every single extent must be rewritten. You can also turn on compression in +defragment operations. \fB-v\fP be verbose @@ -151,11 +223,12 @@ The start position and the number of bytes to deframention can be specified by \ \fB-t size\fP defragment only files at least \fIsize\fR bytes big -NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data, don't -use it if you use snapshots, have de-duplicated your data or made copies with -\fBcp --reflink\fP. -\fBsubvolume find-new\fR\fI <subvolume> <last_gen>\fR -List the recently modified files in a subvolume, after \fI<last_gen>\fR ID. +For \fBstart\fP, \fBlen\fP, \fBsize\fP it is possible to append a suffix +like \fBk\fP for 1 KBytes, \fBm\fP for 1 MBytes... + +NOTE: defragmenting with kernels up to 2.6.37 will unlink COW-ed copies of data, +don't use it if you use snapshots, have de-duplicated your data or made +copies with \fBcp --reflink\fP. .TP \fBfilesystem sync\fR\fI <path> \fR @@ -166,32 +239,37 @@ Force a sync for the filesystem identified by \fI<path>\fR. .\" Some wording are extracted by the resize2fs man page .\" -\fBfilesystem resize\fR\fI [+/\-]<size>[gkm]|max <path>\fR -Resize a filesystem identified by \fI<path>\fR. +\fBfilesystem resize\fR\fI [devid:][+/\-]<size>[gkm]|[devid:]max <path>\fR +Resize a filesystem identified by \fI<path>\fR for the underlying device +\fIdevid\fR. The \fIdevid\fR can be found with \fBbtrfs filesystem show\fR and +defaults to 1 if not specified. The \fI<size>\fR parameter specifies the new size of the filesystem. If the prefix \fI+\fR or \fI\-\fR is present the size is increased or decreased by the quantity \fI<size>\fR. If no units are specified, the unit of the \fI<size>\fR parameter defaults to bytes. Optionally, the size parameter may be suffixed by one of the following -the units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes, +units designators: 'K', 'M', or 'G', kilobytes, megabytes, or gigabytes, respectively. If 'max' is passed, the filesystem will occupy all available space on the -volume(s). +device \fIdevid\fR. The \fBresize\fR command \fBdoes not\fR 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. +partition after reducing the size of the filesystem. This can done using +\fBfdisk(8)\fR or \fBparted(8)\fR 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. .TP -\fBbtrfs\fP \fBfilesystem label\fP\fI <dev> [newlabel]\fP +\fBfilesystem label\fP\fI <dev> [newlabel]\fP Show or update the label of a filesystem. \fI<dev>\fR is used to identify the filesystem. If a \fInewlabel\fR optional argument is passed, the label is changed. The -following costraints exist for a label: +following constraints exist for a label: .IP -- the maximum allowable lenght shall be less or equal than 256 chars +- the maximum allowable length shall be less or equal than 256 chars .IP - the label shall not contain the '/' or '\\' characters. @@ -209,11 +287,23 @@ If \fB--all-devices\fP is passed, all the devices under /dev are scanned; otherwise the devices list is extracted from the /proc/partitions file. .TP -\fBdevice balance\fR \fI<path>\fR +\fBfilesystem balance\fR \fI<path>\fR Balance the chunks of the filesystem identified by \fI<path>\fR across the devices. .TP +\fBdevice stats\fP [-z] {\fI<path>\fP|\fI<device>\fP} +Read and print the device IO stats for all devices of the filesystem +identified by \fI<path>\fR or for a single \fI<device>\fR. + +.RS +\fIOptions\fR +.TP +.B -z +Reset stats to zero after reading them. +.RE +.TP + \fBdevice add\fR\fI <dev> [<dev>..] <path>\fR Add device(s) to the filesystem identified by \fI<path>\fR. .TP @@ -230,12 +320,65 @@ Finally, if \fB--all-devices\fP is passed, all the devices under /dev are scanned. .TP +\fBreplace start\fR \fI[-Bfr] <srcdev>|<devid> <targetdev> <path>\fR +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 \fB-r\fR 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 \fIsrcdev\fR is a numerical value, it is assumed to be the device id +of the filesystem which is mounted at mount_point, otherwise is is +the path to the source device. If the source device is disconnected, +from the system, you have to use the \fIdevid\fR parameter format. +The targetdev needs to be same size or larger than the \fIsrcdev\fR. + +.RS +\fIOptions\fR +.TP +.B -r +only read from \fIsrcdev\fR if no other zero-defect mirror exists (enable +this if your drive has lots of read errors, the access would be very slow) +.TP +.B -f +force using and overwriting \fItargetdev\fR 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 \fItargetdev\fR +.TP +.B -B +do not background +.RE +.TP + +\fBreplace status\fR \fI[-1] <path>\fR +Print status and progress information of a running device replace operation. + +.RS +\fIOptions\fR +.TP +.B -1 +print once instead of print continously until the replace +operation finishes (or is canceled) +.RE +.TP + +\fBreplace cancel\fR \fI<path>\fR +Cancel a running device replace operation. +.TP + \fBscrub start\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP} +\fBscrub start\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP} Start a scrub on all devices of the filesystem identified by \fI<path>\fR or on a single \fI<device>\fR. Without options, scrub is started as a background process. Progress can be obtained with the \fBscrub status\fR command. Scrubbing involves reading all data from all disks and verifying checksums. Errors are corrected along the way if possible. +.IP +The default IO priority of scrub is the idle class. The priority can be configured similar to the +.BR ionice (1) +syntax. .RS \fIOptions\fR @@ -249,6 +392,14 @@ Quiet. Omit error messages and statistics. Read only mode. Do not attempt to correct anything. .IP -u 5 Scrub unused space as well. (NOT IMPLEMENTED) +.IP -c 5 +Set IO priority class (see +.BR ionice (1) +manpage). +.IP -n 5 +Set IO priority classdata (see +.BR ionice (1) +manpage). .RE .TP @@ -260,7 +411,7 @@ If a \fI<device>\fR is given, the corresponding filesystem is found and \fBscrub cancel\fP behaves as if it was called on that filesystem. .TP -\fBscrub resume\fP [-Bdqru] {\fI<path>\fP|\fI<device>\fP} +\fBscrub resume\fP [-Bdqru] [-c ioprio_class -n ioprio_classdata] {\fI<path>\fP|\fI<device>\fP} Resume a canceled or interrupted scrub cycle on the filesystem identified by \fI<path>\fR or on a given \fI<device>\fR. Does not start a new scrub if the last scrub finished successfully. @@ -295,7 +446,7 @@ verbose mode. print count of returned paths and ioctl() return value .RE .TP -\fBinspect-internal logical-resolve\fP [-Pv] \fI<logical>\fP \fI<path>\fP +\fBinspect-internal logical-resolve\fP [-Pv] [-s bufsize] \fI<logical>\fP \fI<path>\fP Resolves a <logical> address in the filesystem mounted at <path> to all inodes. By default, each inode is then resolved to a file system path (similar to the \fBinode-resolve\fP subcommand). @@ -306,6 +457,38 @@ By default, each inode is then resolved to a file system path (similar to the skip the path resolving and print the inodes instead .IP -v 5 verbose mode. print count of returned paths and all ioctl() return values +.IP -s bufsize 5 +set inode container's size. This is used to increase inode container's size in case it is +not enough to read all the resolved results. The max value one can set is 64k. +.RE +.TP + +\fBinspect-internal subvolid-resolve\fP \fI<subvolid>\fP \fI<path>\fP +Get file system paths for the given subvolume ID. +.TP + +\fBbtrfs qgroup assign\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP +Enable subvolume qgroup support for a filesystem. +.TP + +\fBbtrfs qgroup remove\fP \fI<src>\fP \fI<dst>\fP \fI<path>\fP +Remove a subvol from a quota group. +.TP + +\fBbtrfs qgroup create\fP \fI<qgroupid>\fP \fI<path>\fP +Create a subvolume quota group. +.TP + +\fBbtrfs qgroup destroy\fP \fI<qgroupid>\fP \fI<path>\fP +Destroy a subvolume quota group. +.TP + +\fBbtrfs qgroup show\fP \fI<path>\fP +Show all subvolume quota groups. +.TP + +\fBbtrfs\fP \fBqgroup limit\fP [options] \fI<size>\fP|\fBnone\fP [\fI<qgroupid>\fP] \fI<path>\fP +Limit the size of a subvolume quota group. .RE .SH EXIT STATUS @@ -319,4 +502,5 @@ and not suitable for any uses other than benchmarking and review. Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for further details. .SH SEE ALSO -.BR mkfs.btrfs (8) +.BR mkfs.btrfs (8), +.BR ionice (1) |