|
|
| (One intermediate revision by one user not shown) |
| Line 1: |
Line 1: |
| − | =btrfs-subvolume(8) manual page=
| |
| | {{GeneratedManpage | | {{GeneratedManpage |
| | |name=btrfs-subvolume}} | | |name=btrfs-subvolume}} |
| − |
| |
| − | ==NAME==
| |
| − | btrfs-subvolume - manage btrfs subvolumes
| |
| − |
| |
| − | ==SYNOPSIS==
| |
| − |
| |
| − | <p><b>btrfs subvolume</b> <em><subcommand></em> [<em><args></em>]</p>
| |
| − | ==DESCRIPTION==
| |
| − |
| |
| − | <p><b>btrfs subvolume</b> is used to create/delete/list/show btrfs subvolumes and
| |
| − | snapshots.</p>
| |
| − | ==SUBVOLUME AND SNAPSHOT==
| |
| − |
| |
| − | <p>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.</p>
| |
| − | <blockquote><b>Note:</b>
| |
| − | A subvolume in btrfs is not like an LVM logical volume, which is
| |
| − | block-level snapshot while btrfs subvolumes are file extent-based.</blockquote>
| |
| − | <p>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.</p>
| |
| − | <p>A subvolume in btrfs can be accessed in two ways:</p>
| |
| − | <ul>
| |
| − | <li>
| |
| − | <p>
| |
| − | like any other directory that is accessible to the user
| |
| − | </p>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>
| |
| − | like a separately mounted filesystem (options <em>subvol</em> or <em>subvolid</em>)
| |
| − | </p>
| |
| − | </li>
| |
| − | </ul>
| |
| − | <p>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.</p>
| |
| − | <p>A freshly created filesystem is also a subvolume, called <em>top-level</em>,
| |
| − | 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 <em>set-default</em>).</p>
| |
| − | <p>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.</p>
| |
| − | ==SUBCOMMAND==
| |
| − |
| |
| − | <dl>
| |
| − | <dt>
| |
| − | <b>create</b> [-i <em><qgroupid></em>] [<dest>/]<em><name></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Create a subvolume <em><name></em> in <em><dest></em>.
| |
| − | </p>
| |
| − | <p>If <em><dest></em> is not given, subvolume <em><name></em> will be created in the current
| |
| − | directory.</p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -i <em><qgroupid></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Add the newly created subvolume to a qgroup. This option can be given multiple
| |
| − | times.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | <b>delete</b> [options] <em><subvolume></em> [<em><subvolume></em>…]
| |
| − | <dd>
| |
| − | <p>
| |
| − | Delete the subvolume(s) from the filesystem.
| |
| − | </p>
| |
| − | <p>If <em><subvolume></em> is not a subvolume, btrfs returns an error but continues if
| |
| − | there are more arguments to process.</p>
| |
| − | <p>The corresponding directory is removed instantly but the data blocks are
| |
| − | 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>
| |
| − | <p>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 <em>--commit</em> options to wait until the operation is
| |
| − | safely stored on the device.</p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -c|--commit-after
| |
| − | <dd>
| |
| − | <p>
| |
| − | wait for transaction commit at the end of the operation.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -C|--commit-each
| |
| − | <dd>
| |
| − | <p>
| |
| − | wait for transaction commit after deleting each subvolume.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -v|--verbose
| |
| − | <dd>
| |
| − | <p>
| |
| − | verbose output of operations.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | <b>find-new</b> <em><subvolume></em> <em><last_gen></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | List the recently modified files in a subvolume, after <em><last_gen></em> generation.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>get-default</b> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Get the default subvolume of the filesystem <em><path></em>.
| |
| − | </p>
| |
| − | <p>The output format is similar to <b>subvolume list</b> command.</p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>list</b> [options] [-G [+|-]<em><value></em>] [-C [+|-]<em><value></em>] [--sort=rootid,gen,ogen,path] <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | List the subvolumes present in the filesystem <em><path></em>.
| |
| − | </p>
| |
| − | <p>For every subvolume the following information is shown by default:</p>
| |
| − | <p>ID <em><ID></em> gen <em><generation></em> top level <em><ID></em> path <em><path></em></p>
| |
| − | <p>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.</p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | Path filtering
| |
| − | <dd>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -o
| |
| − | <dd>
| |
| − | <p>
| |
| − | print only subvolumes below specified <em><path></em>.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -a
| |
| − | <dd>
| |
| − | <p>
| |
| − | print all the subvolumes in the filesystem and distinguish between
| |
| − | absolute and relative path with respect to the given <em><path></em>.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | Field selection
| |
| − | <dd>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -p
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the parent ID
| |
| − | (<em>parent</em> here means the subvolume which contains this subvolume).
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -c
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the ogeneration of the subvolume, aliases: ogen or origin generation.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -g
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the generation of the subvolume (default).
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -u
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the UUID of the subvolume.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -q
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the parent UUID of the subvolume
| |
| − | (<em>parent</em> here means subvolume of which this subvolume is a snapshot).
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -R
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the UUID of the sent subvolume, where the subvolume is the result of a receive operation.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | Type filtering
| |
| − | <dd>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -s
| |
| − | <dd>
| |
| − | <p>
| |
| − | only snapshot subvolumes in the filesystem will be listed.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -r
| |
| − | <dd>
| |
| − | <p>
| |
| − | only readonly subvolumes in the filesystem will be listed.
| |
| − | </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>
| |
| − | -G [+|-]<em><value></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | list subvolumes in the filesystem that its generation is
| |
| − | >=, ⇐ or = value. '+' means >= value, '-' means <= value, If there is
| |
| − | neither '+' nor '-', it means = value.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -C [+|-]<em><value></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | list subvolumes in the filesystem that its ogeneration is
| |
| − | >=, <= or = value. The usage is the same to <em>-G</em> option.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | --sort=rootid,gen,ogen,path
| |
| − | <dd>
| |
| − | <p>
| |
| − | list subvolumes in order by specified items.
| |
| − | you can add '+' or '-' in front of each items, '+' means ascending,
| |
| − | '-' means descending. The default is ascending.
| |
| − | </p>
| |
| − | <p>for --sort you can combine some items together by ',', just like
| |
| − | --sort=+ogen,-gen,path,rootid.</p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | <b>set-default</b> [<em><subvolume></em>|<em><id></em> <em><path></em>]
| |
| − | <dd>
| |
| − | <p>
| |
| − | Set the default subvolume for the (mounted) filesystem.
| |
| − | </p>
| |
| − | <p>Set the default subvolume for the (mounted) filesystem at <em><path></em>. This will hide
| |
| − | 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><id></em> or by the <em><subvolume></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>
| |
| − | <b>show</b> [options] <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Show more information about subvolume <em><path></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>
| |
| − |
| |
| − | <dt>
| |
| − | -u|--uuid
| |
| − | <dd>
| |
| − | <p>
| |
| − | UUID of the subvolume.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | <b>snapshot</b> [-r|-i <em><qgroupid></em>] <em><source></em> <em><dest></em>|[<dest>/]<em><name></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Create a snapshot of the subvolume <em><source></em> with the
| |
| − | name <em><name></em> in the <em><dest></em> directory.
| |
| − | </p>
| |
| − | <p>If only <em><dest></em> is given, the subvolume will be named the basename of <em><source></em>.
| |
| − | If <em><source></em> is not a subvolume, btrfs returns an error.</p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -r
| |
| − | <dd>
| |
| − | <p>
| |
| − | Make the new snapshot read only.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -i <em><qgroupid></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Add the newly created subvolume to a qgroup. This option can be given multiple
| |
| − | times.
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | <dt>
| |
| − | <b>sync</b> <em><path></em> [subvolid…]
| |
| − | <dd>
| |
| − | <p>
| |
| − | 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.
| |
| − | </p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -s <em><N></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | sleep N seconds between checks (default: 1)
| |
| − | </p>
| |
| − |
| |
| − | </dl>
| |
| − |
| |
| − | </dl>
| |
| − | ==EXIT STATUS==
| |
| − |
| |
| − | <p><b>btrfs subvolume</b> returns a zero exit status if it succeeds. A non-zero value is
| |
| − | returned in case of failure.</p>
| |
| − | ==AVAILABILITY==
| |
| − |
| |
| − | <p><b>btrfs</b> is part of btrfs-progs.
| |
| − | Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
| |
| − | further details.</p>
| |
| − | ==SEE ALSO==
| |
| − |
| |
| − | <p>[[Manpage/mkfs.btrfs|mkfs.btrfs(8)]],
| |
| − | [http://man7.org/linux/man-pages/man8/mount.8.html mount(8)],
| |
| − | [[Manpage/btrfs-quota|btrfs-quota(8)]],
| |
| − | [[Manpage/btrfs-qgroup|btrfs-qgroup(8)]],</p>
| |
| − | [[Category:Manpage]]
| |
