BTRFS(8)							       btrfs								  BTRFS(8)

NAME

       btrfs - control a btrfs filesystem

SYNOPSIS

       btrfs subvolume create [-i <qgroupid>] [<dest>/]<name>

       btrfs subvolume delete <subvolume> [<subvolume>...]

       btrfs subvolume list [options] [-G [+|-]value] [-C [+|-]value] [--sort=rootid,gen,ogen,path] <path>

       btrfs subvolume snapshot [-r] <source> <dest>|[<dest>/]<name>

       btrfs subvolume get-default <path>

       btrfs subvolume set-default <id> <path>

       btrfs subvolume find-new <subvolume> <lastgen>

       btrfs subvolume show <path>

       btrfs filesystem df <path>

       btrfs filesystem show [--mounted|--all-devices|<uuid>]

       btrfs filesystem sync <path>

       btrfs filesystem defragment [options] <file>|<dir> [<file>|<dir>...]

       btrfs filesystem resize [devid:][+/-]<size>[gkm]|[devid:]max <path>

       btrfs filesystem label [<device>|<mount_point>] [<newlabel>]

       btrfs [filesystem] balance start [options] <path>

       btrfs [filesystem] balance pause <path>

       btrfs [filesystem] balance cancel <path>

       btrfs [filesystem] balance resume <path>

       btrfs [filesystem] balance status [-v] <path>

       btrfs device add [-Kf] <device> [<device>...] <path>

       btrfs device delete <device> [<device>...] <path>

       btrfs device scan [--all-devices|<device> P[<device>...]

       btrfs device ready <device>

       btrfs device stats [-z] {<path>|<device>}

       btrfs scrub start [-BdqrR] [-c ioprio_class -n ioprio_classdata] {<path>|<device>}

       btrfs scrub cancel {<path>|<device>}

       btrfs scrub resume [-BdqrR] [-c ioprio_class -n ioprio_classdata] {<path>|<device>}

       btrfs scrub status [-d] {<path>|<device>}

       btrfs check [options] <device>

       btrfs rescue chunk-recover [options] <path>

       btrfs rescue super-recover [options] <path>

       btrfs restore [options] <device>

       btrfs inspect-internal inode-resolve [-v] <inode> <path>

       btrfs inspect-internal logical-resolve [-Pv] [-s <size>] <logical> <path>

       btrfs inspect-internal subvolid-resolve <subvolid> <path>

       btrfs inspect-internal rootid <path>

       btrfs send [-v] [-p <parent>] [-c <clone-src>] [-f <outfile>] <subvol>

       btrfs receive [-ve] [-f <infile>] <mount>

       btrfs quota enable <path>

       btrfs quota disable <path>

       btrfs quota rescan [-s] <path>

       btrfs qgroup assign <src> <dst> <path>

       btrfs qgroup remove <src> <dst> <path>

       btrfs qgroup create <qgroupid> <path>

       btrfs qgroup destroy <qgroupid> <path>

       btrfs qgroup show <path>

       btrfs qgroup limit [options] <size>|none [<qgroupid>] <path>

       btrfs replace start [-Bfr] <srcdev>|<devid> <targetdev> <mount_point>

       btrfs replace status [-1] <mount_point>

       btrfs replace cancel <mount_point>

       btrfs help|--help

       btrfs <command> --help

DESCRIPTION

       btrfs is used to control the filesystem and the files and directories stored. It is the tool to create or destroy a snapshot or a subvolume
       for the filesystem, to defrag a file or a directory, flush the data to the disk, to resize the filesystem, to scan the device.

       It is possible to abbreviate the commands unless the commands are ambiguous.  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.  In this case btrfs returns filesystem sync If a command is terminated by --help , the detailed help is showed. If the passed command
       matches more commands, detailed help of all the matched commands is showed. For example btrfs dev --help shows the help of all device* com-
       mands.

COMMANDS

       subvolume create [-i <qgroupid>] [<dest>/]<name>
	      Create a subvolume <name> in <dest>.  If <dest> is not given subvolume <name> will be created in the current directory.

	      Options

	      -i <qgroupid>
		   Add the newly created subvolume to a qgroup. This option can be given multiple times.

       subvolume delete <subvolume> [<subvolume>...]
	      Delete the subvolume <subvolume>. If <subvolume> is not a subvolume, btrfs returns an error.

       subvolume 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 bellow specified <path>.

	      -u   print the UUID of the subvolume.

	      -q   print the parent uuid of subvolumes (and snapshots).

	      -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.

       subvolume 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.

       subvolume get-default <path>
	      Get the default subvolume of the filesystem <path>. The output format is similar to subvolume list command.

       subvolume 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.

       subvolume find-new <subvolume> <last_gen>
	      List the recently modified files in a subvolume, after <last_gen> ID.

       subvolume show <path>
	      Show information of a given subvolume in the <path>.

       filesystem df <path>
	      Show space usage information for a mount point.

       filesystem show [--mounted|--all-devices|<uuid>]
	      Show the btrfs filesystem with some additional info. If no option or UUID is passed,  btrfs  shows  information  of  all	the  btrfs
	      filesystem  both mounted and unmounted.  If --mounted is passed, it would probe btrfs kernel to list mounted btrfs filesystem(s); If
	      --all-devices is passed, all the devices under /dev are scanned; otherwise the devices list is extracted from  the  /proc/partitions
	      file.

       filesystem sync <path>
	      Force a sync for the filesystem identified by <path>.

       filesystem defragment [options] <file>|<dir> [<file>|<dir>...]
	      Defragment file data and/or directory metadata. 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. 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.

	      Options

	      -v   be verbose

	      -c   compress file contents while defragmenting

	      -r   defragment files recursively

	      -f   flush filesystem after defragmenting

	      -s start
		   defragment only from byte start onward

	      -l len
		   defragment only up to len bytes

	      -t size
		   defragment only files at least size bytes big

		   For start, len, size it is possible to append a suffix like k for 1 KBytes, m 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 cp --reflink.

       filesystem resize [devid:][+/-]<size>[gkm]|[devid:]max <path>
	      Resize a filesystem identified by <path> for the underlying device devid.  The devid can be found with  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 units designators: 'K', 'M', or 'G', kilobytes,
	      megabytes, or gigabytes, respectively.

	      If 'max' is passed, the filesystem will occupy all available space on the device devid.

	      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 filesys-
	      tem.  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.

       filesystem label [<dev>|<mount_point>] [newlabel]
	      Show  or update the label of a filesystem. [<device>|<mountpoint>] is used to identify the filesystem.  If a newlabel optional argu-
	      ment is passed, the label is changed. The following constraints exist for a label:

	      - the maximum allowable length shall be less than 256 chars

       [filesystem] balance start [options] <path>
	      Balance chunks across the devices 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[filters]
		   act on data chunks

	      -m[filters]
		   act on metadata chunks

	      -s[filters]
		   act on system chunks (only under -f)

	      -v   be verbose

	      -f   force reducing of metadata integrity

       [filesystem] balance pause <path>
	      Pause running balance.

       [filesystem] balance cancel <path>
	      Cancel running or paused balance.

       [filesystem] balance resume <path>
	      Resume interrupted balance.

       [filesystem] balance status [-v] <path>
	      Show status of running or paused balance.

	      Options

	      -v   be verbose

       device 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)

       device delete <dev> [<dev>...] <path>
	      Remove device(s) from a filesystem identified by <path>.

       device scan [--all-devices|<device> [<device>...]
	      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 is passed, all the devices under /dev are scanned.

       device ready <device>
	      Check device to see if it has all of it's devices in cache for mounting.

       device stats [-z] {<path>|<device>}
	      Read and print the device IO stats for all devices of the filesystem identified by <path> or for a single <device>.

	      Options

	      -z   Reset stats to zero after reading them.

       scrub start [-BdqrR] [-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>. 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.

	      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).

       scrub 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.

       scrub 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.

       scrub 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.

       check [options] <device>
	      Check an unmounted btrfs filesystem.

	      Options

	      -s|--support <superblock>
		   use this superblock copy.

	      --repair
		   try to repair the filesystem.

	      --init-csum-tree
		   create a new CRC tree.

	      --init-extent-tree
		   create a new extent tree.

       rescue chunk-recover [options] <device>
	      Recover the chunk tree by scanning the devices one by one.

	      Options

	      -y   assume an answer of 'yes' to all questions.

	      -v   verbose mode.

	      -h   help.

       rescue super-recover [options] <device>
	      Recover bad superblocks from good copies.

	      Options

	      -y   assume an answer of 'yes' to all questions.

	      -v   verbose mode.

       restore [options] <device>
	      Try to restore files from a damaged filesystem(unmounted).

	      Options

	      -s   get snapshots.

	      -x   get extended attributes.

	      -v   verbose.

	      -i   ignore errors.

	      -o   overwrite.

	      -t <location>
		   tree location.

	      -f <offset>
		   filesystem location.

	      -u <block>
		   super mirror.

	      -r <rootid>
		   root objectid.

	      -d   find dir.

	      -l   list tree roots.

       inspect-internal inode-resolve [-v] <inode> <path>
	      Resolves an <inode> in subvolume <path> to all filesystem paths.

	      Options

	      -v   verbose mode. print count of returned paths and ioctl() return value

       inspect-internal logical-resolve [-Pv] [-s bufsize] <logical> <path>
	      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 inode-resolve subcommand).

	      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 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.

       inspect-internal subvolid-resolve <subvolid> <path>
	      Get file system paths for the given subvolume ID.

       inspect-internal rootid <path>
	      For a given file or directory, return the containing tree root id. For a subvolume return it's own tree id.

	      The result is undefined for the so-called empty subvolumes (identified by inode number 2).

       send [-v] [-p <parent>] [-c <clone-src>] [-f <outfile>] <subvol>
	      Send the subvolume to stdout.  Sends the subvolume specified by <subvol> to stdout.  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 which case 'btrfs send' will  deter-
	      mine a suitable parent among the clone sources itself.

	      Options

	      -v   Enable verbose debug output. Each occurrence of this option increases the verbose level more.

	      -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.

       receive [-ve] [-f <infile>] <mount>
	      Receive  subvolumes  from stdin.	Receives one or more subvolumes that were previously sent with btrfs send. The received subvolumes
	      are stored into <mount>.	btrfs receive will fail in case a receiving subvolume already exists. It will also fail in case  a  previ-
	      ously received subvolume was changed after it was received.  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.

	      -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.

       quota enable <path>
	      Enable subvolume quota support for a filesystem.

       quota disable <path>
	      Disable subvolume quota support for a filesystem.

       quota 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.

       qgroup assign <src> <dst> <path>
	      Enable subvolume qgroup support for a filesystem.

       qgroup remove <src> <dst> <path>
	      Remove a subvol from a quota group.

       qgroup create <qgroupid> <path>
	      Create a subvolume quota group.

       qgroup destroy <qgroupid> <path>
	      Destroy a subvolume quota group.

       qgroup show <path>
	      Show all subvolume quota groups.

       qgroup limit [options] <size>|none [<qgroupid>] <path>
	      Limit the size of a subvolume quota group.

       replace 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 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 devid parameter format.  The  <target-
	      dev> 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   do not 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)

       replace cancel <mount_point>
	      Cancel a running device replace operation.

EXIT STATUS

       btrfs returns a zero exist status if it succeeds. Non zero is returned in case of failure.

AVAILABILITY

       btrfs is part of btrfs-progs. Btrfs filesystem is currently under heavy development, 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.

SEE ALSO

       mkfs.btrfs(8), ionice(1)

btrfs																	  BTRFS(8)