diff options
Diffstat (limited to 'upstream/fedora-40/man8/btrfs-subvolume.8')
| -rw-r--r-- | upstream/fedora-40/man8/btrfs-subvolume.8 | 573 |
1 files changed, 573 insertions, 0 deletions
diff --git a/upstream/fedora-40/man8/btrfs-subvolume.8 b/upstream/fedora-40/man8/btrfs-subvolume.8 new file mode 100644 index 00000000..1ac17e3e --- /dev/null +++ b/upstream/fedora-40/man8/btrfs-subvolume.8 @@ -0,0 +1,573 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BTRFS-SUBVOLUME" "8" "Feb 14, 2024" "6.7.1" "BTRFS" +.SH NAME +btrfs-subvolume \- manage btrfs subvolumes +.SH SYNOPSIS +.sp +\fBbtrfs subvolume\fP <subcommand> [<args>] +.SH DESCRIPTION +.sp +\fBbtrfs subvolume\fP is used to create/delete/list/show btrfs subvolumes and +snapshots. +.sp +A BTRFS subvolume is a part of filesystem with its own independent +file/directory hierarchy and inode number namespace. Subvolumes can share file +extents. A snapshot is also subvolume, but with a given initial content of the +original subvolume. A subvolume has always inode number 256. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A subvolume in BTRFS is not like an LVM logical volume, which is block\-level +snapshot while BTRFS subvolumes are file extent\-based. +.UNINDENT +.UNINDENT +.sp +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. The numeric id +(called \fIsubvolid\fP or \fIrootid\fP) of the subvolume is persistent and cannot be +changed. +.sp +A subvolume in BTRFS can be accessed in two ways: +.INDENT 0.0 +.IP \(bu 2 +like any other directory that is accessible to the user +.IP \(bu 2 +like a separately mounted filesystem (options \fIsubvol\fP or \fIsubvolid\fP) +.UNINDENT +.sp +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. +.sp +A freshly created filesystem is also a subvolume, called \fItop\-level\fP, +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 \fI\%btrfs subvolume set\-default\fP). +.sp +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. +.sp +Subvolumes can be given capacity limits, through the qgroups/quota facility, but +otherwise share the single storage pool of the whole btrfs filesystem. They may +even share data between themselves (through deduplication or snapshotting). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A snapshot is not a backup: snapshots work by use of BTRFS\(aq copy\-on\-write +behaviour. A snapshot and the original it was taken from initially share all +of the same data blocks. If that data is damaged in some way (cosmic rays, +bad disk sector, accident with dd to the disk), then the snapshot and the +original will both be damaged. Snapshots are useful to have local online +\(dqcopies\(dq of the filesystem that can be referred back to, or to implement a +form of deduplication, or to fix the state of a filesystem for making a full +backup without anything changing underneath it. They do not in themselves +make your data any safer. +.UNINDENT +.UNINDENT +.SH SUBVOLUME FLAGS +.sp +The subvolume flag currently implemented is the \fIro\fP property (read\-only +status). Read\-write subvolumes have that set to \fIfalse\fP, snapshots as \fItrue\fP\&. +In addition to that, a plain snapshot will also have last change generation and +creation generation equal. +.sp +Read\-only snapshots are building blocks of incremental send (see +\fI\%btrfs\-send(8)\fP) 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. +.sp +A snapshot that was created by send/receive will be read\-only, with different +last change generation, read\-only and with set \fIreceived_uuid\fP which identifies +the subvolume on the filesystem that produced the stream. The use case relies +on matching data on both sides. Changing the subvolume to read\-write after it +has been received requires to reset the \fIreceived_uuid\fP\&. As this is a notable +change and could potentially break the incremental send use case, performing +it by \fI\%btrfs property set\fP requires force if that is +really desired by user. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The safety checks have been implemented in 5.14.2, any subvolumes previously +received (with a valid \fIreceived_uuid\fP) and read\-write status may exist and +could still lead to problems with send/receive. You can use \fI\%btrfs subvolume show\fP +to identify them. Flipping the flags to read\-only and back to +read\-write will reset the \fIreceived_uuid\fP manually. There may exist a +convenience tool in the future. +.UNINDENT +.UNINDENT +.SH NESTED SUBVOLUMES +.sp +There are no restrictions for subvolume creation, so it\(aqs up to the user how to +organize them, whether to have a flat layout (all subvolumes are direct +descendants of the toplevel one), or nested. +.sp +What should be mentioned early is that a snapshotting is not recursive, so a +subvolume or a snapshot is effectively a barrier and no files in the nested +appear in the snapshot. Instead there\(aqs a stub subvolume (also sometimes +\fIempty subvolume\fP with the same name as original subvolume, with inode number +2). This can be used intentionally but could be confusing in case of nested +layouts. +.SS Case study: system root layouts +.sp +There are two ways how the system root directory and subvolume layout could be +organized. The interesting use case for root is to allow rollbacks to previous +version, as one atomic step. If the entire filesystem hierarchy starting in \fB/\fP +is in one subvolume, taking snapshot will encompass all files. This is easy for +the snapshotting part but has undesirable consequences for rollback. For example, +log files would get rolled back too, or any data that are stored on the root +filesystem but are not meant to be rolled back either (database files, VM +images, ...). +.sp +Here we could utilize the snapshotting barrier mentioned above, each directory +that stores data to be preserved across rollbacks is it\(aqs own subvolume. This +could be e.g. \fB/var\fP\&. Further more\-fine grained partitioning could be done, e.g. +adding separate subvolumes for \fB/var/log\fP, \fB/var/cache\fP etc. +.sp +That there are separate subvolumes requires separate actions to take the +snapshots (here it gets disconnected from the system root snapshots). This needs +to be taken care of by system tools, installers together with selection of which +directories are highly recommended to be separate subvolumes. +.SH MOUNT OPTIONS +.sp +Mount options are of two kinds, generic (that are handled by VFS layer) and +specific, handled by the filesystem. The following list shows which are +applicable to individual subvolume mounts, while there are more options that +always affect the whole filesystem: +.INDENT 0.0 +.IP \(bu 2 +generic: noatime/relatime/..., nodev, nosuid, ro, rw, dirsync +.IP \(bu 2 +fs\-specific: compress, autodefrag, nodatacow, nodatasum +.UNINDENT +.sp +An example of whole filesystem options is e.g. \fIspace_cache\fP, \fIrescue\fP, \fIdevice\fP, +\fIskip_balance\fP, etc. The exceptional options are \fIsubvol\fP and \fIsubvolid\fP that +are actually used for mounting a given subvolume and can be specified only once +for the mount. +.sp +Subvolumes belong to a single filesystem and as implemented now all share the +same specific mount options, changes done by remount have immediate effect. This +may change in the future. +.sp +Mounting a read\-write snapshot as read\-only is possible and will not change the +\fIro\fP property and flag of the subvolume. +.sp +The name of the mounted subvolume is stored in file \fB/proc/self/mountinfo\fP in +the 4th column: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +27 21 0:19 /subv1 /mnt rw,relatime \- btrfs /dev/sda rw,space_cache + ^^^^^^ +.ft P +.fi +.UNINDENT +.UNINDENT +.SH INODE NUMBERS +.sp +A proper subvolume has always inode number 256. If a subvolume is nested and +then a snapshot is taken, then the cloned directory entry representing the +subvolume becomes empty and the inode has number 2. All other files and +directories in the target snapshot preserve their original inode numbers. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Inode number is not a filesystem\-wide unique identifier, some applications +assume that. Please use pair \fIsubvolumeid:inodenumber\fP for that purpose. +The subvolume id can be read by \fI\%btrfs inspect\-internal rootid\fP +or by the ioctl \fI\%BTRFS_IOC_INO_LOOKUP\fP\&. +.UNINDENT +.UNINDENT +.SH PERFORMANCE +.sp +Subvolume creation needs to flush dirty data that belong to the subvolume, this +step may take some time, otherwise once there\(aqs nothing else to do, the snapshot +is instant and in the metadata it only creates a new tree root copy. +.sp +Snapshot deletion has two phases: first its directory is deleted and the +subvolume is added to a list, then the list is processed one by one and the +data related to the subvolume get deleted. This is usually called \fIcleaning\fP and +can take some time depending on the amount of shared blocks (can be a lot of +metadata updates), and the number of currently queued deleted subvolumes. +.SH SUBVOLUME AND SNAPSHOT +.sp +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. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A subvolume in btrfs is not like an LVM logical volume, which is block\-level +snapshot while btrfs subvolumes are file extent\-based. +.UNINDENT +.UNINDENT +.sp +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. +.sp +A subvolume in btrfs can be accessed in two ways: +.INDENT 0.0 +.IP \(bu 2 +like any other directory that is accessible to the user +.IP \(bu 2 +like a separately mounted filesystem (options \fIsubvol\fP or \fIsubvolid\fP) +.UNINDENT +.sp +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. +.sp +A freshly created filesystem is also a subvolume, called \fItop\-level\fP, +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 \fI\%set\-default\fP). +.sp +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. +.SH SUBCOMMAND +.INDENT 0.0 +.TP +.B create [options] [<dest>/]<name> [[<dest2>/]<name2> ...] +Create subvolume(s) at the destination(s). +.sp +If \fIdest\fP part of the path is not given, subvolume \fIname\fP will be +created in the current directory. +.sp +If multiple destinations are given, then the given options are applied to all +subvolumes. +.sp +If failure happens for any of the destinations, the command would +still retry the remaining destinations, but would return 1 to indicate +the failure (similar to what \fBmkdir\fP would do. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.BI \-i \ <qgroupid> +Add the newly created subvolume to a qgroup. This option can be given multiple +times. +.UNINDENT +.INDENT 7.0 +.TP +.B \-p|\-\-parents +Create any missing parent directories for each argument (like \fBmkdir \-p\fP). +.UNINDENT +.TP +.B delete [options] [<subvolume> [<subvolume>...]], delete \-i|\-\-subvolid <subvolid> <path> +Delete the subvolume(s) from the filesystem. +.sp +If \fIsubvolume\fP is not a subvolume, btrfs returns an error but continues if +there are more arguments to process. +.sp +If \fI\-\-subvolid\fP is used, \fIpath\fP must point to a btrfs filesystem. See +\fI\%btrfs subvolume list\fP or +\fI\%btrfs inspect\-internal rootid\fP +how to get the subvolume id. +.sp +The corresponding directory is removed instantly but the data blocks are +removed later in the background. The command returns immediately. See +\fI\%btrfs subvolume sync\fP how to wait until the subvolume gets completely removed. +.sp +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 \fI\-\-commit\fP options to wait until the operation is +safely stored on the device. +.sp +Deleting subvolume needs sufficient permissions, by default the owner +cannot delete it unless it\(aqs enabled by a mount option +\fIuser_subvol_rm_allowed\fP, or deletion is run as root. +The default subvolume (see \fI\%btrfs subvolume set\-default\fP) +cannot be deleted and +returns error (EPERM) and this is logged to the system log. A subvolume that\(aqs +currently involved in send (see \fI\%btrfs\-send(8)\fP) +also cannot be deleted until the +send is finished. This is also logged in the system log. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-c|\-\-commit\-after +wait for transaction commit at the end of the operation. +.TP +.B \-C|\-\-commit\-each +wait for transaction commit after deleting each subvolume. +.TP +.B \-i|\-\-subvolid <subvolid> +subvolume id to be removed instead of the <path> that should point to the +filesystem with the subvolume +.UNINDENT +.INDENT 7.0 +.TP +.B \-\-delete\-qgroup +also delete the qgroup 0/subvolid if it exists +.TP +.B \-\-no\-delete\-qgroup +do not delete the 0/subvolid qgroup (default) +.UNINDENT +.INDENT 7.0 +.TP +.B \-v|\-\-verbose +(deprecated) alias for global \fI\-v\fP option +.UNINDENT +.TP +.B find\-new <subvolume> <last_gen> +List the recently modified files in a subvolume, after \fIlast_gen\fP generation. +.TP +.B get\-default <path> +Get the default subvolume of the filesystem \fIpath\fP\&. +.sp +The output format is similar to \fBsubvolume list\fP command. +.UNINDENT +.INDENT 0.0 +.TP +.B list [options] [\-G [+|\-]<value>] [\-C [+|\-]<value>] [\-\-sort=rootid,gen,ogen,path] <path> +List the subvolumes present in the filesystem \fIpath\fP\&. +.sp +For every subvolume the following information is shown by default: +.sp +ID \fIID\fP gen \fIgeneration\fP top level \fIparent_ID\fP path \fIpath\fP +.sp +where \fIID\fP is subvolume\(aqs (root)id, \fIgeneration\fP is an internal counter which is +updated every transaction, \fIparent_ID\fP is the same as the parent subvolume\(aqs id, +and \fIpath\fP is the relative path of the subvolume to the top level subvolume. +The subvolume\(aqs ID may be used by the subvolume set\-default command, +or at mount time via the \fIsubvolid=\fP option. +.sp +\fBOptions\fP +.sp +Path filtering: +.INDENT 7.0 +.TP +.B \-o +Print only subvolumes below specified <path>. Note that this is not a +recursive command, and won\(aqt show nested subvolumes under <path>. +.TP +.B \-a +print all the subvolumes in the filesystem and distinguish between +absolute and relative path with respect to the given \fIpath\fP\&. +.UNINDENT +.sp +Field selection: +.INDENT 7.0 +.TP +.B \-p +print the parent ID +(\fIparent\fP here means the subvolume which contains this subvolume). +.TP +.B \-c +print the ogeneration of the subvolume, aliases: ogen or origin generation. +.TP +.B \-g +print the generation of the subvolume (default). +.TP +.B \-u +print the UUID of the subvolume. +.TP +.B \-q +print the parent UUID of the subvolume +(\fIparent\fP here means subvolume of which this subvolume is a snapshot). +.TP +.B \-R +print the UUID of the sent subvolume, where the subvolume is the result of a receive operation. +.UNINDENT +.sp +Type filtering: +.INDENT 7.0 +.TP +.B \-s +only snapshot subvolumes in the filesystem will be listed. +.TP +.B \-r +only readonly subvolumes in the filesystem will be listed. +.TP +.B \-d +list deleted subvolumes that are not yet cleaned. +.UNINDENT +.sp +Other: +.INDENT 7.0 +.TP +.B \-t +print the result as a table. +.UNINDENT +.sp +Sorting: +.sp +By default the subvolumes will be sorted by subvolume ID ascending. +.INDENT 7.0 +.TP +.B \-G [+|\-]<value> +list subvolumes in the filesystem that its generation is +>=, <= or = value. \(aq+\(aq means >= value, \(aq\-\(aq means <= value, If there is +neither \(aq+\(aq nor \(aq\-\(aq, it means = value. +.TP +.B \-C [+|\-]<value> +list subvolumes in the filesystem that its ogeneration is +>=, <= or = value. The usage is the same to \fI\-G\fP option. +.TP +.B \-\-sort=rootid,gen,ogen,path +list subvolumes in order by specified items. +you can add \fI+\fP or \fI\-\fP in front of each items, \fI+\fP means ascending, +\fI\-\fP means descending. The default is ascending. +.sp +for \fI\-\-sort\fP you can combine some items together by \fI,\fP, just like +\fI\-\-sort=+ogen,\-gen,path,rootid\fP\&. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B set\-default [<subvolume>|<id> <path>] +Set the default subvolume for the (mounted) filesystem. +.sp +Set the default subvolume for the (mounted) filesystem at \fIpath\fP\&. This will hide +the top\-level subvolume (i.e. the one mounted with \fIsubvol=/\fP or \fIsubvolid=5\fP). +Takes action on next mount. +.sp +There are two ways how to specify the subvolume, by \fIid\fP or by the \fIsubvolume\fP +path. +The id can be obtained from \fI\%btrfs subvolume list\fP +\fI\%btrfs subvolume show\fP or +\fI\%btrfs inspect\-internal rootid\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B show [options] <path> +Show more information about a subvolume (UUIDs, generations, times, flags, +related snapshots). +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +/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): +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-r|\-\-rootid <ID> +show details about subvolume with root \fIID\fP, looked up in \fIpath\fP +.TP +.B \-u|\-\-uuid UUID +show details about subvolume with the given \fIUUID\fP, looked up in \fIpath\fP +.UNINDENT +.TP +.B snapshot [\-r] [\-i <qgroupid>] <source> <dest>|[<dest>/]<name> +Create a snapshot of the subvolume \fIsource\fP with the +name \fIname\fP in the \fIdest\fP directory. +.sp +If only \fIdest\fP is given, the subvolume will be named the basename of \fIsource\fP\&. +If \fIsource\fP is not a subvolume, btrfs returns an error. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.B \-r +Make the new snapshot read only. +.TP +.BI \-i \ <qgroupid> +Add the newly created subvolume to a qgroup. This option can be given multiple +times. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B 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. +.sp +If the filesystem status changes to read\-only then the waiting is interrupted. +.sp +\fBOptions\fP +.INDENT 7.0 +.TP +.BI \-s \ <N> +sleep N seconds between checks (default: 1) +.UNINDENT +.UNINDENT +.SH EXAMPLES +.SS Deleting a subvolume +.sp +If we want to delete a subvolume called \fIfoo\fP from a btrfs volume mounted at +\fB/mnt/bar\fP we could run the following: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +btrfs subvolume delete /mnt/bar/foo +.ft P +.fi +.UNINDENT +.UNINDENT +.SH EXIT STATUS +.sp +\fBbtrfs subvolume\fP returns a zero exit status if it succeeds. A non\-zero value is +returned in case of failure. +.SH AVAILABILITY +.sp +\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at +\fI\%https://btrfs.readthedocs.io\fP\&. +.SH SEE ALSO +.sp +\fI\%btrfs\-qgroup(8)\fP, +\fI\%btrfs\-quota(8)\fP, +\fI\%btrfs\-send(8)\fP, +\fI\%mkfs.btrfs(8)\fP, +\fBmount(8)\fP +.\" Generated by docutils manpage writer. +. |