188 lines
6.1 KiB
Plaintext
188 lines
6.1 KiB
Plaintext
btrfs-subvolume(8)
|
|
==================
|
|
|
|
NAME
|
|
----
|
|
btrfs-subvolume - manage btrfs subvolumes
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*btrfs subvolume* <subcommand> [<args>]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
*btrfs subvolume* is used to create/delete/list/show btrfs subvolumes and
|
|
snapshots.
|
|
|
|
SUBVOLUME AND SNAPSHOT
|
|
----------------------
|
|
|
|
A subvolume is a part of filesystem with it's own and independent
|
|
file/directory hierarchy. Subvolumes can share file extents. A snapshot is
|
|
also subvolume, but with a given initial content of the original subvolume.
|
|
|
|
NOTE: A subvolume in btrfs is not like an LVM logical volume, which is
|
|
block-level snapshot while btrfs subvolumes are file extent-based.
|
|
|
|
A subvolume looks like a normal directory, with some additional operations
|
|
described below. Subvolumes can be renamed or moved, nesting subvolumes is not
|
|
restricted but has some implications regarding snapshotting.
|
|
|
|
A subvolume in btrfs can be accessed in two ways:
|
|
|
|
* like any other directory that is accessible to the user
|
|
* like a separately mounted filesystem (options 'subvol' or 'subvolid')
|
|
|
|
In the latter case the parent directory is not visible and accessible. This is
|
|
similar to a bind mount, and in fact the subvolume mount does exactly that.
|
|
|
|
A freshly created filesystem is also a subvolume, called 'top-level',
|
|
internally has an id 5. This subvolume cannot be removed or replaced by another
|
|
subvolume. This is also the subvolume that will be mounted by default, unless
|
|
the default subvolume has been changed (see subcommand 'set-default').
|
|
|
|
A snapshot is a subvolume like any other, with given initial content. By
|
|
default, snapshots are created read-write. File modifications in a snapshot
|
|
do not affect the files in the original subvolume.
|
|
|
|
SUBCOMMAND
|
|
-----------
|
|
*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.
|
|
|
|
*delete* [options] <subvolume> [<subvolume>...]::
|
|
Delete the subvolume(s) from the filesystem.
|
|
+
|
|
If <subvolume> is not a subvolume, btrfs returns an error but continues if
|
|
there are more arguments to process.
|
|
+
|
|
The corresponding directory is removed instantly but the data blocks are
|
|
removed later. The deletion does not involve full commit by default due to
|
|
performance reasons (as a consequence, the subvolume may appear again after a
|
|
crash). Use one of the '--commit' options to wait until the operation is safely
|
|
stored on the media.
|
|
+
|
|
`Options`
|
|
+
|
|
-c|--commit-after::::
|
|
wait for transaction commit at the end of the operation
|
|
+
|
|
-C|--commit-each::::
|
|
wait for transaction commit after deleting each subvolume
|
|
|
|
*find-new* <subvolume> <last_gen>::
|
|
List the recently modified files in a subvolume, after <last_gen> ID.
|
|
|
|
*get-default* <path>::
|
|
Get the default subvolume of the filesystem <path>.
|
|
+
|
|
The output format is similar to *subvolume list* command.
|
|
|
|
*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 below specified <path>.
|
|
-u::::
|
|
print the UUID of the subvolume.
|
|
-q::::
|
|
print the parent uuid of subvolumes (and snapshots).
|
|
-R::::
|
|
print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
|
|
-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.
|
|
|
|
*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.
|
|
|
|
*show* <path>::
|
|
Show information of a given subvolume in the <path>.
|
|
|
|
*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.
|
|
|
|
*sync* <path> [subvolid...]::
|
|
Wait until given subvolume(s) are completely removed from the filesystem
|
|
after deletion. If no subvolume id is given, wait until all current deletion
|
|
requests are completed, but do not wait for subvolumes deleted meanwhile.
|
|
The status of subvolume ids is checked periodically.
|
|
+
|
|
`Options`
|
|
+
|
|
-s <N>::::
|
|
sleep N seconds between checks (default: 1)
|
|
|
|
EXIT STATUS
|
|
-----------
|
|
*btrfs subvolume* returns a zero exit status if it succeeds. A non-zero value 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),
|
|
`mount`(8),
|
|
`btrfs-quota`(8),
|
|
`btrfs-qgroup`(8),
|