From f03df4f256e97e9f0e59ef0767770a107c512185 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Wed, 27 Oct 2021 00:45:24 +0200 Subject: [PATCH] btrfs-progs: docs: convert btrfs-subvolume to rst Signed-off-by: David Sterba --- Documentation/btrfs-subvolume.rst | 307 ++++++++++++++++++++++++++++++ Documentation/conf.py | 1 + Documentation/man-index.rst | 1 + 3 files changed, 309 insertions(+) create mode 100644 Documentation/btrfs-subvolume.rst diff --git a/Documentation/btrfs-subvolume.rst b/Documentation/btrfs-subvolume.rst new file mode 100644 index 00000000..3e381bca --- /dev/null +++ b/Documentation/btrfs-subvolume.rst @@ -0,0 +1,307 @@ +btrfs-subvolume(8) +================== + +SYNOPSIS +-------- + +**btrfs subvolume** [] + +DESCRIPTION +----------- + +**btrfs subvolume** is used to create/delete/list/show btrfs subvolumes and +snapshots. + +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. + +SUBCOMMAND +----------- + +create [-i ] [/] + Create a subvolume *name* in *dest*. + + If *dest* is not given, subvolume *name* will be created in the current + directory. + + ``Options`` + + -i + Add the newly created subvolume to a qgroup. This option can be given multiple + times. + +delete [options] [ [...]], delete -i|--subvolid + 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. + + If *--subvolid* is used, *path* must point to a btrfs filesystem. See ``btrfs + subvolume list`` or ``btrfs inspect-internal rootid`` how to get the subvolume id. + + 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. + + The default subvolume (see ``btrfs subvolume set-default``) cannot be deleted and + returns error (EPERM) and this is logged to the system log. A subvolume that's + currently involved in send (see ``btrfs send``) also cannot be deleted until the + send is finished. This is also logged in the system log. + + ``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. + + -i|--subvolid + subvolume id to be removed instead of the that should point to the + filesystem with the subvolume + -v|--verbose + (deprecated) alias for global *-v* option + +find-new + List the recently modified files in a subvolume, after *last_gen* generation. + +get-default + Get the default subvolume of the filesystem *path*. + + The output format is similar to **subvolume list** command. + +list [options] [-G [\+|-]] [-C [+|-]] [--sort=rootid,gen,ogen,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 . + -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 [+|-] + list subvolumes in the filesystem that its generation is + >=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is + neither \'+' nor \'-', it means = value. + -C [+|-] + 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 [| ] + 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] + Show more information about a subvolume (UUIDs, generations, times, flags, + related snapshots). + + .. code-block:: none + + /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 + show details about subvolume with root *ID*, looked up in *path* + -u|--uuid UUID + show details about subvolume with the given *UUID*, looked up in *path* + +snapshot [-r] [-i ] |[/] + 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 + Add the newly created subvolume to a qgroup. This option can be given multiple + times. + +sync [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 + sleep N seconds between checks (default: 1) + +SUBVOLUME FLAGS +--------------- + +The subvolume flag currently implemented is the *ro* property. Read-write +subvolumes have that set to *false*, snapshots as *true*. In addition to that, +a plain snapshot will also have last change generation and creation generation +equal. + +Read-only snapshots are building blocks fo incremental send (see +``btrfs-send(8)``) and the whole use case relies on unmodified snapshots where the +relative changes are generated from. Thus, changing the subvolume flags from +read-only to read-write will break the assumptions and may lead to unexpected changes +in the resulting incremental stream. + +A snapshot that was created by send/receive will be read-only, with different +last change generation, read-only and with set *received_uuid* which identifies +the subvolume on the filesystem that produced the stream. The usecase relies +on matching data on both sides. Changing the subvolume to read-write after it +has been received requires to reset the *received_uuid*. As this is a notable +change and could potentially break the incremental send use case, performing +it by **btrfs property set** requires force if that is really desired by user. + +.. note:: + The safety checks have been implemented in 5.14.2, any subvolumes previously + received (with a valid *received_uuid*) and read-write status may exist and + could still lead to problems with send/receive. You can use **btrfs subvolume + show** to identify them. Flipping the flags to read-only and back to + read-write will reset the *received_uuid* manually. There may exist a + convenience tool in the future. + +EXAMPLES +-------- + +Deleting a subvolume +^^^^^^^^^^^^^^^^^^^^ + +If we want to delete a subvolume called *foo* from a btrfs volume mounted at +*/mnt/bar* we could run the following: + +.. code-block:: bash + + btrfs subvolume delete /mnt/bar/foo + +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)``, +``mount(8)``, +``btrfs-quota(8)``, +``btrfs-qgroup(8)``, +``btrfs-send(8)`` diff --git a/Documentation/conf.py b/Documentation/conf.py index 7dcc234a..4d7b8383 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -60,4 +60,5 @@ man_pages = [ ('btrfs-convert', 'btrfs-convert', 'convert from ext2/3/4 or reiserfs filesystem to btrfs in-place', '', 8), ('btrfs-check', 'btrfs-check', 'check or repair a btrfs filesystem', '', 8), ('btrfs-balance', 'btrfs-balance', 'balance block groups on a btrfs filesystem', '', 8), + ('btrfs-subvolume', 'btrfs-subvolume', 'manage btrfs subvolumes', '', 8), ] diff --git a/Documentation/man-index.rst b/Documentation/man-index.rst index 04edc8ff..cb5ec63a 100644 --- a/Documentation/man-index.rst +++ b/Documentation/man-index.rst @@ -24,6 +24,7 @@ Manual pages btrfs-scrub btrfs-select-super btrfs-send + btrfs-subvolume btrfstune fsck.btrfs