184 lines
5.9 KiB
Plaintext
184 lines
5.9 KiB
Plaintext
btrfs-subvolume(8)
|
|
==================
|
|
|
|
NAME
|
|
----
|
|
btrfs-subvolume - control btrfs subvolume(s)
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*btrfs subvolume* <subcommand> [<args>]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
*btrfs subvolume* is used to control the filesystem to create/delete/list/show
|
|
subvolumes and snapshots.
|
|
|
|
SUBVOLUME AND SNAPSHOT
|
|
----------------------
|
|
A subvolume in btrfs is not like an LVM logical volume, which is quite
|
|
independent from each other, a btrfs subvolume has its hierarchy and relations
|
|
between other subvolumes.
|
|
|
|
A subvolume in btrfs can be accessed in two ways.
|
|
|
|
1. From the parent subvolume +
|
|
When accessing from the parent subvolume, the subvolume can be used just
|
|
like a directory. It can have child subvolumes and its own files/directories.
|
|
|
|
2. Separate mounted filesystem +
|
|
When `mount`(8) using 'subvol' or 'subvolid' mount option, one can access
|
|
files/directories/subvolumes inside it, but nothing in parent subvolumes.
|
|
|
|
Also every btrfs filesystem has a default subvolume as its initially top-level
|
|
subvolume, whose subvolume id is 5. (0 is also acceptable as an alias.)
|
|
|
|
A btrfs snapshot is much like a subvolume, but shares its data(and metadata)
|
|
with other subvolume/snapshot. Due to the capabilities of COW, modifications
|
|
inside a snapshot will only show in a snapshot but not in its source subvolume.
|
|
|
|
Although in btrfs, subvolumes/snapshots are treated as directories, only
|
|
subvolume/snapshot can be the source of a snapshot, snapshot can not be made
|
|
from normal directories.
|
|
|
|
SUBCOMMAND
|
|
-----------
|
|
*create* [-i <qgroupid>] [<dest>]<name>::
|
|
Create a subvolume <name> in <dest>.
|
|
+
|
|
If <dest> is not given, subvolume <name> will be created in the currently
|
|
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 delet 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),
|
|
`btrfs-subvolume`(8),
|
|
`btrfs-quota`(8),
|
|
`btrfs-qgroup`(8),
|