Manpage/btrfs-subvolume

From btrfs Wiki
(Difference between revisions)
Jump to: navigation, search
m (Protected "Manpage/btrfs-subvolume": Counter-productive edit warring (‎[edit=sysop] (indefinite) ‎[move=sysop] (indefinite)))
(git 5.4)
 
Line 15: Line 15:
 
==SUBVOLUME AND SNAPSHOT==
 
==SUBVOLUME AND SNAPSHOT==
  
<p>A subvolume is a part of filesystem with its own and independent
+
<p>A subvolume is a part of filesystem with its own independent
 
file/directory hierarchy. Subvolumes can share file extents. A snapshot is
 
file/directory hierarchy. Subvolumes can share file extents. A snapshot is
 
also subvolume, but with a given initial content of the original subvolume.</p>
 
also subvolume, but with a given initial content of the original subvolume.</p>
Line 78: Line 78:
 
there are more arguments to process.</p>
 
there are more arguments to process.</p>
 
<p>The corresponding directory is removed instantly but the data blocks are
 
<p>The corresponding directory is removed instantly but the data blocks are
removed later in the background. The command returns immediatelly. See <tt>btrfs
+
removed later in the background. The command returns immediately. See <tt>btrfs
 
subvolume sync</tt> how to wait until the subvolume gets completely removed.</p>
 
subvolume sync</tt> how to wait until the subvolume gets completely removed.</p>
 
<p>The deletion does not involve full transaction commit by default due to
 
<p>The deletion does not involve full transaction commit by default due to
Line 90: Line 90:
 
<dd>
 
<dd>
 
<p>
 
<p>
wait for transaction commit at the end of the operation
+
wait for transaction commit at the end of the operation.
 
</p>
 
</p>
  
Line 97: Line 97:
 
<dd>
 
<dd>
 
<p>
 
<p>
wait for transaction commit after deleting each subvolume
+
wait for transaction commit after deleting each subvolume.
 +
</p>
 +
 
 +
<dt>
 +
-v|--verbose
 +
<dd>
 +
<p>
 +
verbose output of operations.
 
</p>
 
</p>
  
Line 106: Line 113:
 
<dd>
 
<dd>
 
<p>
 
<p>
List the recently modified files in a subvolume, after <em>&lt;last_gen&gt;</em> ID.
+
List the recently modified files in a subvolume, after <em>&lt;last_gen&gt;</em> generation.
 
</p>
 
</p>
  
Line 123: Line 130:
 
List the subvolumes present in the filesystem <em>&lt;path&gt;</em>.
 
List the subvolumes present in the filesystem <em>&lt;path&gt;</em>.
 
</p>
 
</p>
<p>For every subvolume the following information is shown by default.<br/>
+
<p>For every subvolume the following information is shown by default:</p>
ID <em>&lt;ID&gt;</em> top level <em>&lt;ID&gt;</em> path <em>&lt;path&gt;</em><br/>
+
<p>ID <em>&lt;ID&gt;</em> gen <em>&lt;generation&gt;</em> top level <em>&lt;ID&gt;</em> path <em>&lt;path&gt;</em></p>
where path is the relative path of the subvolume to the top level subvolume.
+
<p>where ID is subvolume&#8217;s id, gen is an internal counter which is updated
 +
every transaction, top level is the same as parent subvolume&#8217;s id, and
 +
path is the relative path of the subvolume to the top level subvolume.
 
The subvolume&#8217;s ID may be used by the subvolume set-default command,
 
The subvolume&#8217;s ID may be used by the subvolume set-default command,
or at mount time via the subvolid= option.
+
or at mount time via the subvolid= option.</p>
If <tt>-p</tt> is given, then parent <em>&lt;ID&gt;</em> is added to the output between ID
+
and top level. The parent&#8217;s ID may be used at mount time via the
+
<tt>subvolrootid=</tt> option.</p>
+
 
<p><tt>Options</tt></p>
 
<p><tt>Options</tt></p>
 
<dl>
 
<dl>
 
<dt>
 
<dt>
-p
+
Path filtering
 +
<dd>
 +
<dl>
 +
<dt>
 +
-o
 
<dd>
 
<dd>
 
<p>
 
<p>
print parent ID.
+
print only subvolumes below specified <em>&lt;path&gt;</em>.
 
</p>
 
</p>
  
Line 147: Line 157:
 
absolute and relative path with respect to the given <em>&lt;path&gt;</em>.
 
absolute and relative path with respect to the given <em>&lt;path&gt;</em>.
 
</p>
 
</p>
 +
 +
</dl>
  
 
<dt>
 
<dt>
-c
+
Field selection
 +
<dd>
 +
<dl>
 +
<dt>
 +
-p
 
<dd>
 
<dd>
 
<p>
 
<p>
print the ogeneration of the subvolume, aliases: ogen or origin generation.
+
print the parent ID
 +
(<em>parent</em> here means the subvolume which contains this subvolume).
 
</p>
 
</p>
  
 
<dt>
 
<dt>
-g
+
-c
 
<dd>
 
<dd>
 
<p>
 
<p>
print the generation of the subvolume.
+
print the ogeneration of the subvolume, aliases: ogen or origin generation.
 
</p>
 
</p>
  
 
<dt>
 
<dt>
-o
+
-g
 
<dd>
 
<dd>
 
<p>
 
<p>
print only subvolumes below specified <em>&lt;path&gt;</em>.
+
print the generation of the subvolume (default).
 
</p>
 
</p>
  
Line 180: Line 197:
 
<dd>
 
<dd>
 
<p>
 
<p>
print the parent uuid of subvolumes (and snapshots).
+
print the parent UUID of the subvolume
 +
(<em>parent</em> here means subvolume of which this subvolume is a snapshot).
 
</p>
 
</p>
  
Line 187: Line 205:
 
<dd>
 
<dd>
 
<p>
 
<p>
print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
+
print the UUID of the sent subvolume, where the subvolume is the result of a receive operation.
 
</p>
 
</p>
 +
 +
</dl>
  
 
<dt>
 
<dt>
-t
+
Type filtering
 
<dd>
 
<dd>
<p>
+
<dl>
print the result as a table.
+
</p>
+
 
+
 
<dt>
 
<dt>
 
-s
 
-s
Line 211: Line 228:
 
</p>
 
</p>
  
 +
<dt>
 +
-d
 +
<dd>
 +
<p>
 +
list deleted subvolumes that are not yet cleaned.
 +
</p>
 +
 +
</dl>
 +
 +
<dt>
 +
Other
 +
<dd>
 +
<dl>
 +
<dt>
 +
-t
 +
<dd>
 +
<p>
 +
print the result as a table.
 +
</p>
 +
 +
</dl>
 +
 +
<dt>
 +
Sorting
 +
<dd>
 +
<p>
 +
By default the subvolumes will be sorted by subvolume ID ascending.
 +
</p>
 +
<dl>
 
<dt>
 
<dt>
 
-G [+|-]<em>&lt;value&gt;</em>
 
-G [+|-]<em>&lt;value&gt;</em>
Line 238: Line 284:
 
<p>for --sort you can combine some items together by ',', just like
 
<p>for --sort you can combine some items together by ',', just like
 
--sort=+ogen,-gen,path,rootid.</p>
 
--sort=+ogen,-gen,path,rootid.</p>
 +
 +
</dl>
  
 
</dl>
 
</dl>
  
 
<dt>
 
<dt>
<b>set-default</b> <em>&lt;id&gt;</em> <em>&lt;path&gt;</em>
+
<b>set-default</b> [<em>&lt;subvolume&gt;</em>|<em>&lt;id&gt;</em> <em>&lt;path&gt;</em>]
 
<dd>
 
<dd>
 
<p>
 
<p>
Set the subvolume of the filesystem <em>&lt;path&gt;</em> which is mounted as
+
Set the default subvolume for the (mounted) filesystem.
default.
+
 
</p>
 
</p>
<p>The subvolume is identified by <em>&lt;id&gt;</em>, which is returned by the <b>subvolume list</b>
+
<p>Set the default subvolume for the (mounted) filesystem at <em>&lt;path&gt;</em>. This will hide
command.</p>
+
the top-level subvolume (i.e. the one mounted with <em>subvol=/</em> or <em>subvolid=5</em>).
 +
Takes action on next mount.</p>
 +
<p>There are two ways how to specify the subvolume, by <em>&lt;id&gt;</em> or by the <em>&lt;subvolume&gt;</em>
 +
path.
 +
The id can be obtained from <b>btrfs subvolume list</b>, <b>btrfs subvolume show</b> or
 +
<b>btrfs inspect-internal rootid</b>.</p>
  
 
<dt>
 
<dt>
<b>show</b> <em>&lt;path&gt;</em>
+
<b>show</b> [options] <em>&lt;path&gt;</em>
 
<dd>
 
<dd>
 
<p>
 
<p>
Show information of a given subvolume in the <em>&lt;path&gt;</em>.
+
Show more information about subvolume <em>&lt;path&gt;</em> regarding UUIDs, times,
 +
generations, flags and related snapshots.
 +
</p>
 +
<pre>/mnt/btrfs/subvolume
 +
        Name:                  subvolume
 +
        UUID:                  5e076a14-4e42-254d-ac8e-55bebea982d1
 +
        Parent UUID:            -
 +
        Received UUID:          -
 +
        Creation time:          2018-01-01 12:34:56 +0000
 +
        Subvolume ID:          79
 +
        Generation:            2844
 +
        Gen at creation:        2844
 +
        Parent ID:              5
 +
        Top level ID:          5
 +
        Flags:                  -
 +
        Snapshot(s):</pre>
 +
<p><tt>Options</tt></p>
 +
<dl>
 +
<dt>
 +
-r|--rootid
 +
<dd>
 +
<p>
 +
rootid of the subvolume.
 
</p>
 
</p>
  
 
<dt>
 
<dt>
<b>snapshot</b> [-r] <em>&lt;source&gt;</em> <em>&lt;dest&gt;</em>|[&lt;dest&gt;/]<em>&lt;name&gt;</em>
+
-u|--uuid
 
<dd>
 
<dd>
 
<p>
 
<p>
Create a writable/readonly snapshot of the subvolume <em>&lt;source&gt;</em> with the
+
UUID of the subvolume.
 +
</p>
 +
 
 +
</dl>
 +
 
 +
<dt>
 +
<b>snapshot</b> [-r|-i <em>&lt;qgroupid&gt;</em>] <em>&lt;source&gt;</em> <em>&lt;dest&gt;</em>|[&lt;dest&gt;/]<em>&lt;name&gt;</em>
 +
<dd>
 +
<p>
 +
Create a snapshot of the subvolume <em>&lt;source&gt;</em> with the
 
name <em>&lt;name&gt;</em> in the <em>&lt;dest&gt;</em> directory.
 
name <em>&lt;name&gt;</em> in the <em>&lt;dest&gt;</em> directory.
 
</p>
 
</p>
 
<p>If only <em>&lt;dest&gt;</em> is given, the subvolume will be named the basename of <em>&lt;source&gt;</em>.
 
<p>If only <em>&lt;dest&gt;</em> is given, the subvolume will be named the basename of <em>&lt;source&gt;</em>.
If <em>&lt;source&gt;</em> is not a subvolume, btrfs returns an error.
+
If <em>&lt;source&gt;</em> is not a subvolume, btrfs returns an error.</p>
If <em>-r</em> is given, the snapshot will be readonly.</p>
+
<p><tt>Options</tt></p>
 +
<dl>
 +
<dt>
 +
-r
 +
<dd>
 +
<p>
 +
Make the new snapshot read only.
 +
</p>
 +
 
 +
<dt>
 +
-i <em>&lt;qgroupid&gt;</em>
 +
<dd>
 +
<p>
 +
Add the newly created subvolume to a qgroup. This option can be given multiple
 +
times.
 +
</p>
 +
 
 +
</dl>
  
 
<dt>
 
<dt>
Line 273: Line 373:
 
<dd>
 
<dd>
 
<p>
 
<p>
Wait until given subvolume(s) are completely removed from the filesystem
+
Wait until given subvolume(s) are completely removed from the filesystem after
after deletion. If no subvolume id is given, wait until all current deletion
+
deletion. If no subvolume id is given, wait until all current deletion requests
requests are completed, but do not wait for subvolumes deleted meanwhile.
+
are completed, but do not wait for subvolumes deleted in the meantime.
The status of subvolume ids is checked periodically.
+
 
</p>
 
</p>
 
<p><tt>Options</tt></p>
 
<p><tt>Options</tt></p>

Latest revision as of 17:49, 16 January 2020

Contents

[edit] btrfs-subvolume(8) manual page

Warning: this page is automatically generated from git, all edits will be lost. Current git version.


[edit] NAME

btrfs-subvolume - manage btrfs subvolumes

[edit] SYNOPSIS

btrfs subvolume <subcommand> [<args>]

[edit] DESCRIPTION

btrfs subvolume is used to create/delete/list/show btrfs subvolumes and snapshots.

[edit] SUBVOLUME AND SNAPSHOT

A subvolume is a part of filesystem with its own 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.

[edit] 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 in the background. The command returns immediately. See btrfs subvolume sync how to wait until the subvolume gets completely removed.

The deletion does not involve full transaction 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 device.

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.

-v|--verbose

verbose output of operations.

find-new <subvolume> <last_gen>

List the recently modified files in a subvolume, after <last_gen> generation.

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> gen <generation> top level <ID> path <path>

where ID is subvolume’s id, gen is an internal counter which is updated every transaction, top level is the same as parent subvolume’s id, and 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.

Options

Path filtering
-o

print only subvolumes below specified <path>.

-a

print all the subvolumes in the filesystem and distinguish between absolute and relative path with respect to the given <path>.

Field selection
-p

print the parent ID (parent here means the subvolume which contains this subvolume).

-c

print the ogeneration of the subvolume, aliases: ogen or origin generation.

-g

print the generation of the subvolume (default).

-u

print the UUID of the subvolume.

-q

print the parent UUID of the subvolume (parent here means subvolume of which this subvolume is a snapshot).

-R

print the UUID of the sent subvolume, where the subvolume is the result of a receive operation.

Type filtering
-s

only snapshot subvolumes in the filesystem will be listed.

-r

only readonly subvolumes in the filesystem will be listed.

-d

list deleted subvolumes that are not yet cleaned.

Other
-t

print the result as a table.

Sorting

By default the subvolumes will be sorted by subvolume ID ascending.

-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 [<subvolume>|<id> <path>]

Set the default subvolume for the (mounted) filesystem.

Set the default subvolume for the (mounted) filesystem at <path>. This will hide the top-level subvolume (i.e. the one mounted with subvol=/ or subvolid=5). Takes action on next mount.

There are two ways how to specify the subvolume, by <id> or by the <subvolume> path. The id can be obtained from btrfs subvolume list, btrfs subvolume show or btrfs inspect-internal rootid.

show [options] <path>

Show more information about subvolume <path> regarding UUIDs, times, generations, flags and related snapshots.

/mnt/btrfs/subvolume
        Name:                   subvolume
        UUID:                   5e076a14-4e42-254d-ac8e-55bebea982d1
        Parent UUID:            -
        Received UUID:          -
        Creation time:          2018-01-01 12:34:56 +0000
        Subvolume ID:           79
        Generation:             2844
        Gen at creation:        2844
        Parent ID:              5
        Top level ID:           5
        Flags:                  -
        Snapshot(s):

Options

-r|--rootid

rootid of the subvolume.

-u|--uuid

UUID of the subvolume.

snapshot [-r|-i <qgroupid>] <source> <dest>|[<dest>/]<name>

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

Options

-r

Make the new snapshot read only.

-i <qgroupid>

Add the newly created subvolume to a qgroup. This option can be given multiple times.

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 in the meantime.

Options

-s <N>

sleep N seconds between checks (default: 1)

[edit] EXIT STATUS

btrfs subvolume returns a zero exit status if it succeeds. A non-zero value is returned in case of failure.

[edit] AVAILABILITY

btrfs is part of btrfs-progs. Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for further details.

[edit] SEE ALSO

mkfs.btrfs(8), mount(8), btrfs-quota(8), btrfs-qgroup(8),

Personal tools