|
|
| (3 intermediate revisions 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 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.</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 immediatelly. 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>
| |
| − |
| |
| − | </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> ID.
| |
| − | </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.<br/>
| |
| − | ID <em><ID></em> top level <em><ID></em> path <em><path></em><br/>
| |
| − | 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 <tt>-p</tt> is given, then parent <em><ID></em> is added to the output between ID
| |
| − | and top level. The parent’s ID may be used at mount time via the
| |
| − | <tt>subvolrootid=</tt> option.</p>
| |
| − | <p><tt>Options</tt></p>
| |
| − | <dl>
| |
| − | <dt>
| |
| − | -p
| |
| − | <dd>
| |
| − | <p>
| |
| − | print parent ID.
| |
| − | </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>
| |
| − |
| |
| − | <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.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -o
| |
| − | <dd>
| |
| − | <p>
| |
| − | print only subvolumes below specified <em><path></em>.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -u
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the UUID of the subvolume.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -q
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the parent uuid of subvolumes (and snapshots).
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -R
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | -t
| |
| − | <dd>
| |
| − | <p>
| |
| − | print the result as a table.
| |
| − | </p>
| |
| − |
| |
| − | <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>
| |
| − | -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>
| |
| − |
| |
| − | <dt>
| |
| − | <b>set-default</b> <em><id></em> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Set the subvolume of the filesystem <em><path></em> which is mounted as
| |
| − | default.
| |
| − | </p>
| |
| − | <p>The subvolume is identified by <em><id></em>, which is returned by the <b>subvolume list</b>
| |
| − | command.</p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>show</b> <em><path></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Show information of a given subvolume in the <em><path></em>.
| |
| − | </p>
| |
| − |
| |
| − | <dt>
| |
| − | <b>snapshot</b> [-r] <em><source></em> <em><dest></em>|[<dest>/]<em><name></em>
| |
| − | <dd>
| |
| − | <p>
| |
| − | Create a writable/readonly 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.
| |
| − | If <em>-r</em> is given, the snapshot will be readonly.</p>
| |
| − |
| |
| − | <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 meanwhile.
| |
| − | The status of subvolume ids is checked periodically.
| |
| − | </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]]
| |
