|
|
| (6 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 - control btrfs subvolume(s)
| |
| − |
| |
| − | ==SYNOPSIS==
| |
| − |
| |
| − | <p><b>btrfs subvolume</b> <em><subcommand></em> [<em><args></em>]</p>
| |
| − | ==DESCRIPTION==
| |
| − |
| |
| − | <p><b>btrfs subvolume</b> is used to control the filesystem to create/delete/list/show
| |
| − | subvolumes and snapshots.</p>
| |
| − | ==SUBVOLUME AND SNAPSHOT==
| |
| − |
| |
| − | <p>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.</p>
| |
| − | <p>A subvolume in btrfs can be accessed in two ways.</p>
| |
| − | <ol>
| |
| − | <li>
| |
| − | <p>
| |
| − | From the parent subvolume<br/>
| |
| − | 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.
| |
| − | </p>
| |
| − | </li>
| |
| − | <li>
| |
| − | <p>
| |
| − | Separate mounted filesystem<br/>
| |
| − | When [http://man7.org/linux/man-pages/man8/mount.8.html mount(8)] using <em>subvol</em> or <em>subvolid</em> mount option, one can access
| |
| − | files/directories/subvolumes inside it, but nothing in parent subvolumes.
| |
| − | </p>
| |
| − | </li>
| |
| − | </ol>
| |
| − | <p>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.)</p>
| |
| − | <p>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.</p>
| |
| − | <p>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.</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 currently
| |
| − | 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. 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 <em>--commit</em> options to wait until the operation is safely
| |
| − | stored on the media.</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)]],
| |
| − | [[Manpage/btrfs-quota|btrfs-quota(8)]],
| |
| − | [[Manpage/btrfs-qgroup|btrfs-qgroup(8)]],</p>
| |
| − | [[Category:Manpage]]
| |
