| 1 |
.\" Man page generated from reStructuredText |
| 2 |
.\" by the Docutils 0.22.4 manpage writer. |
| 3 |
. |
| 4 |
. |
| 5 |
.nr rst2man-indent-level 0 |
| 6 |
. |
| 7 |
.de1 rstReportMargin |
| 8 |
\\$1 \\n[an-margin] |
| 9 |
level \\n[rst2man-indent-level] |
| 10 |
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 11 |
- |
| 12 |
\\n[rst2man-indent0] |
| 13 |
\\n[rst2man-indent1] |
| 14 |
\\n[rst2man-indent2] |
| 15 |
.. |
| 16 |
.de1 INDENT |
| 17 |
.\" .rstReportMargin pre: |
| 18 |
. RS \\$1 |
| 19 |
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
| 20 |
. nr rst2man-indent-level +1 |
| 21 |
.\" .rstReportMargin post: |
| 22 |
.. |
| 23 |
.de UNINDENT |
| 24 |
. RE |
| 25 |
.\" indent \\n[an-margin] |
| 26 |
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 27 |
.nr rst2man-indent-level -1 |
| 28 |
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
| 29 |
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
| 30 |
.. |
| 31 |
.TH "BTRFS-SUBVOLUME" "8" "May 10, 2026" "7.0" "BTRFS" |
| 32 |
.SH NAME |
| 33 |
btrfs-subvolume \- manage btrfs subvolumes |
| 34 |
.SH SYNOPSIS |
| 35 |
.sp |
| 36 |
\fBbtrfs subvolume\fP <subcommand> [<args>] |
| 37 |
.SH DESCRIPTION |
| 38 |
.sp |
| 39 |
\fBbtrfs subvolume\fP is used to create/delete/list/show btrfs subvolumes and |
| 40 |
snapshots. |
| 41 |
.sp |
| 42 |
A BTRFS subvolume is a part of filesystem with its own independent |
| 43 |
file/directory hierarchy and inode number namespace. Subvolumes can share file |
| 44 |
extents. A snapshot is also subvolume, but with a given initial content of the |
| 45 |
original subvolume. A subvolume has always inode number 256 (see more in |
| 46 |
Inode numbers (in Subvolumes) \%<Subvolumes//#\:subvolume-inode-numbers>). |
| 47 |
.sp |
| 48 |
\fBNote:\fP |
| 49 |
.INDENT 0.0 |
| 50 |
.INDENT 3.5 |
| 51 |
A subvolume in BTRFS is not like an LVM logical volume, which is block\-level |
| 52 |
snapshot while BTRFS subvolumes are file extent\-based. |
| 53 |
.UNINDENT |
| 54 |
.UNINDENT |
| 55 |
.sp |
| 56 |
A subvolume looks like a normal directory, with some additional operations |
| 57 |
described below. Subvolumes can be renamed or moved, nesting subvolumes is not |
| 58 |
restricted but has some implications regarding snapshotting. The numeric id |
| 59 |
(called \fIsubvolid\fP or \fIrootid\fP) of the subvolume is persistent and cannot be |
| 60 |
changed. |
| 61 |
.sp |
| 62 |
A subvolume in BTRFS can be accessed in two ways: |
| 63 |
.INDENT 0.0 |
| 64 |
.IP \(bu 2 |
| 65 |
like any other directory that is accessible to the user |
| 66 |
.IP \(bu 2 |
| 67 |
like a separately mounted filesystem (options \fIsubvol\fP or \fIsubvolid\fP) |
| 68 |
.UNINDENT |
| 69 |
.sp |
| 70 |
In the latter case the parent directory is not visible and accessible. This is |
| 71 |
similar to a bind mount, and in fact the subvolume mount does exactly that. |
| 72 |
.sp |
| 73 |
A freshly created filesystem is also a subvolume, called \fItop\-level\fP, |
| 74 |
internally has an id 5. This subvolume cannot be removed or replaced by another |
| 75 |
subvolume. This is also the subvolume that will be mounted by default, unless |
| 76 |
the default subvolume has been changed (see btrfs subvolume set\-default). |
| 77 |
.sp |
| 78 |
A snapshot is a subvolume like any other, with given initial content. By |
| 79 |
default, snapshots are created read\-write. File modifications in a snapshot |
| 80 |
do not affect the files in the original subvolume. |
| 81 |
.sp |
| 82 |
Subvolumes can be given capacity limits, through the qgroups/quota facility, but |
| 83 |
otherwise share the single storage pool of the whole btrfs filesystem. They may |
| 84 |
even share data between themselves (through deduplication or snapshotting). |
| 85 |
.sp |
| 86 |
\fBNote:\fP |
| 87 |
.INDENT 0.0 |
| 88 |
.INDENT 3.5 |
| 89 |
A snapshot is not a backup: snapshots work by use of BTRFS\(aq copy\-on\-write |
| 90 |
behaviour. A snapshot and the original it was taken from initially share all |
| 91 |
of the same data blocks. If that data is damaged in some way (cosmic rays, |
| 92 |
bad disk sector, accident with dd to the disk), then the snapshot and the |
| 93 |
original will both be damaged. Snapshots are useful to have local online |
| 94 |
\(dqcopies\(dq of the filesystem that can be referred back to, or to implement a |
| 95 |
form of deduplication, or to fix the state of a filesystem for making a full |
| 96 |
backup without anything changing underneath it. They do not in themselves |
| 97 |
make your data any safer. |
| 98 |
.UNINDENT |
| 99 |
.UNINDENT |
| 100 |
.SH SUBVOLUME FLAGS |
| 101 |
.sp |
| 102 |
The subvolume flag currently implemented is the \fIro\fP property (read\-only |
| 103 |
status). Read\-write subvolumes have that set to \fIfalse\fP, snapshots as \fItrue\fP\&. |
| 104 |
In addition to that, a plain snapshot will also have last change generation and |
| 105 |
creation generation equal. |
| 106 |
.sp |
| 107 |
Read\-only snapshots are building blocks of incremental send (see |
| 108 |
btrfs\-send(8) \%<>) and the whole use case relies on unmodified snapshots where |
| 109 |
the relative changes are generated from. Thus, changing the subvolume flags |
| 110 |
from read\-only to read\-write will break the assumptions and may lead to |
| 111 |
unexpected changes in the resulting incremental stream. |
| 112 |
.sp |
| 113 |
A snapshot that was created by send/receive will be read\-only, with different |
| 114 |
last change generation, and with set \fIreceived_uuid\fP which identifies |
| 115 |
the subvolume on the filesystem that produced the stream. The use case relies |
| 116 |
on matching data on both sides. Changing the subvolume to read\-write after it |
| 117 |
has been received requires to reset the \fIreceived_uuid\fP\&. As this is a notable |
| 118 |
change and could potentially break the incremental send use case, performing |
| 119 |
it by btrfs property set \%<#\:man-property-set> requires force if that is |
| 120 |
really desired by user. |
| 121 |
.sp |
| 122 |
\fBNote:\fP |
| 123 |
.INDENT 0.0 |
| 124 |
.INDENT 3.5 |
| 125 |
The safety checks have been implemented in 5.14.2, any subvolumes previously |
| 126 |
received (with a valid \fIreceived_uuid\fP) and read\-write status may exist and |
| 127 |
could still lead to problems with send/receive. You can use btrfs subvolume show |
| 128 |
to identify them. Flipping the flags to read\-only and back to |
| 129 |
read\-write will reset the \fIreceived_uuid\fP manually. There may exist a |
| 130 |
convenience tool in the future. |
| 131 |
.UNINDENT |
| 132 |
.UNINDENT |
| 133 |
.SH NESTED SUBVOLUMES |
| 134 |
.sp |
| 135 |
There are no restrictions for subvolume creation, so it\(aqs up to the user how to |
| 136 |
organize them, whether to have a flat layout (all subvolumes are direct |
| 137 |
descendants of the toplevel one), or nested. |
| 138 |
.sp |
| 139 |
What should be mentioned early is that a snapshotting is not recursive, so a |
| 140 |
subvolume or a snapshot is effectively a barrier and no files in the nested subvolumes |
| 141 |
appear in the snapshot. Instead, there\(aqs a stub subvolume, also sometimes called |
| 142 |
\fIempty subvolume\fP, with the same name as original subvolume and with inode number 2. |
| 143 |
This can be used intentionally but could be confusing in case of nested layouts. |
| 144 |
.INDENT 0.0 |
| 145 |
.INDENT 3.5 |
| 146 |
.sp |
| 147 |
.EX |
| 148 |
$ btrfs subvolume create subvol1 |
| 149 |
$ btrfs subvolume create subvol1/subvol2 |
| 150 |
$ btrfs subvolume snapshot subvol1 snap1 |
| 151 |
$ find \-ls |
| 152 |
121093 0 drwxr\-xr\-x 1 user users 24 Jul 30 12:34 . |
| 153 |
256 0 drwxr\-xr\-x 1 user users 14 Jul 30 12:34 ./subvol1 |
| 154 |
256 0 drwxr\-xr\-x 1 user users 0 Jul 30 12:34 ./subvol1/subvol2 |
| 155 |
257 0 \-rw\-r\-\-r\-\- 1 user users 0 Jul 30 12:34 ./subvol1/subvol2/file |
| 156 |
256 0 drwxr\-xr\-x 1 user users 14 Jul 30 12:34 ./snap1 |
| 157 |
2 0 drwxr\-xr\-x 1 user users 0 Jul 30 12:34 ./snap1/subvol2 |
| 158 |
.EE |
| 159 |
.UNINDENT |
| 160 |
.UNINDENT |
| 161 |
.sp |
| 162 |
The numbers in the first columns are inode numbers, 256 is for a regular |
| 163 |
subvolume (or snapshot), 2 is the \fIempty subvolume\fP\&. The snapshotted directory |
| 164 |
representing \fIsubvol2\fP does not contain the \fIfile\fP\&. |
| 165 |
.sp |
| 166 |
\fBNote:\fP |
| 167 |
.INDENT 0.0 |
| 168 |
.INDENT 3.5 |
| 169 |
The \fIempty subvolume\fP will not be sent (btrfs\-send(8) \%<>) and thus will not be created on |
| 170 |
the receive side (btrfs\-receive(8) \%<>). |
| 171 |
.UNINDENT |
| 172 |
.UNINDENT |
| 173 |
.SS Case study: system root layouts |
| 174 |
.sp |
| 175 |
There are two ways how the system root directory and subvolume layout could be |
| 176 |
organized. The interesting use case for root is to allow rollbacks to previous |
| 177 |
version, as one atomic step. If the entire filesystem hierarchy starting in \fB/\fP |
| 178 |
is in one subvolume, taking snapshot will encompass all files. This is easy for |
| 179 |
the snapshotting part but has undesirable consequences for rollback. For example, |
| 180 |
log files would get rolled back too, or any data that are stored on the root |
| 181 |
filesystem but are not meant to be rolled back either (database files, VM |
| 182 |
images, ...). |
| 183 |
.sp |
| 184 |
Here we could utilize the snapshotting barrier mentioned above, making each directory |
| 185 |
that stores data to be preserved across rollbacks its own subvolume. This |
| 186 |
could be e.g. \fB/var\fP\&. Further more fine\-grained partitioning could be done, e.g. |
| 187 |
adding separate subvolumes for \fB/var/log\fP, \fB/var/cache\fP etc. |
| 188 |
.sp |
| 189 |
The fact that there are separate subvolumes requires separate actions to take the |
| 190 |
snapshots (here, it gets disconnected from the system root snapshots). This needs |
| 191 |
to be taken care of by system tools, installers, together with selection of which |
| 192 |
directories are highly recommended to be separate subvolumes. |
| 193 |
.SH MOUNT OPTIONS |
| 194 |
.sp |
| 195 |
Mount options are of two kinds, generic (that are handled by VFS layer) and |
| 196 |
specific, handled by the filesystem. The following list shows which are |
| 197 |
applicable to individual subvolume mounts, while there are more options that |
| 198 |
always affect the whole filesystem: |
| 199 |
.INDENT 0.0 |
| 200 |
.IP \(bu 2 |
| 201 |
Generic: noatime/relatime/..., nodev, nosuid, ro, rw, dirsync |
| 202 |
.IP \(bu 2 |
| 203 |
Filesystem\-specific: compress, autodefrag, nodatacow, nodatasum |
| 204 |
.UNINDENT |
| 205 |
.sp |
| 206 |
Examples of whole filesystem options are e.g. \fIspace_cache\fP, \fIrescue\fP, \fIdevice\fP, |
| 207 |
\fIskip_balance\fP, etc. The exceptional options are \fIsubvol\fP and \fIsubvolid\fP that |
| 208 |
are actually used for mounting a given subvolume and can be specified only once |
| 209 |
for the mount. |
| 210 |
.sp |
| 211 |
Subvolumes belong to a single filesystem and, as implemented now, all share the |
| 212 |
same specific mount options. Also, changes done by remount have immediate effect. This |
| 213 |
may change in the future. |
| 214 |
.sp |
| 215 |
Mounting a read\-write snapshot as read\-only is possible and will not change the |
| 216 |
\fIro\fP property and flag of the subvolume. |
| 217 |
.sp |
| 218 |
The name of the mounted subvolume is stored in file \fB/proc/self/mountinfo\fP in |
| 219 |
the 4th column: |
| 220 |
.INDENT 0.0 |
| 221 |
.INDENT 3.5 |
| 222 |
.sp |
| 223 |
.EX |
| 224 |
27 21 0:19 /subv1 /mnt rw,relatime \- btrfs /dev/sda rw,space_cache |
| 225 |
^^^^^^ |
| 226 |
.EE |
| 227 |
.UNINDENT |
| 228 |
.UNINDENT |
| 229 |
.SH INODE NUMBERS |
| 230 |
.sp |
| 231 |
A directory representing a subvolume has always inode number 256 (sometimes |
| 232 |
also called a root of the subvolume): |
| 233 |
.INDENT 0.0 |
| 234 |
.INDENT 3.5 |
| 235 |
.sp |
| 236 |
.EX |
| 237 |
$ ls \-lis |
| 238 |
total 0 |
| 239 |
389111 0 drwxr\-xr\-x 1 user users 0 Jan 20 12:13 dir |
| 240 |
389110 0 \-rw\-r\-\-r\-\- 1 user users 0 Jan 20 12:13 file |
| 241 |
256 0 drwxr\-xr\-x 1 user users 0 Jan 20 12:13 snap1 |
| 242 |
256 0 drwxr\-xr\-x 1 user users 0 Jan 20 12:13 subv1 |
| 243 |
.EE |
| 244 |
.UNINDENT |
| 245 |
.UNINDENT |
| 246 |
.sp |
| 247 |
If a subvolume is nested and then a snapshot is taken, then the cloned |
| 248 |
directory entry representing the subvolume becomes empty and the inode has |
| 249 |
number 2. All other files and directories in the target snapshot preserve their |
| 250 |
original inode numbers. |
| 251 |
.sp |
| 252 |
\fBNote:\fP |
| 253 |
.INDENT 0.0 |
| 254 |
.INDENT 3.5 |
| 255 |
Inode number is not a filesystem\-wide unique identifier, some applications |
| 256 |
assume that. Please use the \fIsubvolumeid:inodenumber\fP pair for that purpose. |
| 257 |
The subvolume id can be read by btrfs inspect\-internal rootid \%<#\:man-inspect-rootid> |
| 258 |
or by the ioctl BTRFS_IOC_INO_LOOKUP \%<#\:btrfs-ioc-ino-lookup>\&. |
| 259 |
.UNINDENT |
| 260 |
.UNINDENT |
| 261 |
.SH PERFORMANCE |
| 262 |
.sp |
| 263 |
Subvolume creation needs to flush dirty data that belong to the subvolume and this |
| 264 |
step may take some time. Otherwise, once there\(aqs nothing else to do, the snapshot |
| 265 |
is instantaneous and only creates a new tree root copy in the metadata. |
| 266 |
.sp |
| 267 |
Snapshot deletion has two phases: first its directory is deleted and the |
| 268 |
subvolume is added to a queuing list, then the list is processed one by one and the |
| 269 |
data related to the subvolume get deleted. This is usually called \fIcleaning\fP and |
| 270 |
can take some time depending on the amount of shared blocks (can be a lot of |
| 271 |
metadata updates), and the number of currently queued deleted subvolumes. |
| 272 |
.SH SUBVOLUME AND SNAPSHOT |
| 273 |
.sp |
| 274 |
A subvolume is a part of filesystem with its own independent |
| 275 |
file/directory hierarchy. Subvolumes can share file extents. A snapshot is |
| 276 |
also subvolume, but with a given initial content of the original subvolume. |
| 277 |
.sp |
| 278 |
\fBNote:\fP |
| 279 |
.INDENT 0.0 |
| 280 |
.INDENT 3.5 |
| 281 |
A subvolume in btrfs is not like an LVM logical volume, which is block\-level |
| 282 |
snapshot while btrfs subvolumes are file extent\-based. |
| 283 |
.UNINDENT |
| 284 |
.UNINDENT |
| 285 |
.sp |
| 286 |
A subvolume looks like a normal directory, with some additional operations |
| 287 |
described below. Subvolumes can be renamed or moved, nesting subvolumes is not |
| 288 |
restricted but has some implications regarding snapshotting. |
| 289 |
.sp |
| 290 |
A subvolume in btrfs can be accessed in two ways: |
| 291 |
.INDENT 0.0 |
| 292 |
.IP \(bu 2 |
| 293 |
like any other directory that is accessible to the user |
| 294 |
.IP \(bu 2 |
| 295 |
like a separately mounted filesystem (options \fIsubvol\fP or \fIsubvolid\fP) |
| 296 |
.UNINDENT |
| 297 |
.sp |
| 298 |
In the latter case the parent directory is not visible and accessible. This is |
| 299 |
similar to a bind mount, and in fact the subvolume mount does exactly that. |
| 300 |
.sp |
| 301 |
A freshly created filesystem is also a subvolume, called \fItop\-level\fP, |
| 302 |
internally has an id 5. This subvolume cannot be removed or replaced by another |
| 303 |
subvolume. This is also the subvolume that will be mounted by default, unless |
| 304 |
the default subvolume has been changed (see subcommand set\-default). |
| 305 |
.sp |
| 306 |
A snapshot is a subvolume like any other, with given initial content. By |
| 307 |
default, snapshots are created read\-write. File modifications in a snapshot |
| 308 |
do not affect the files in the original subvolume. |
| 309 |
.SH SUBCOMMAND |
| 310 |
.INDENT 0.0 |
| 311 |
.TP |
| 312 |
.B create [options] [<dest>/]<name> [[<dest2>/]<name2> ...] |
| 313 |
Create subvolume(s) at the destination(s). |
| 314 |
.sp |
| 315 |
If \fIdest\fP part of the path is not given, subvolume \fIname\fP will be |
| 316 |
created in the current directory. |
| 317 |
.sp |
| 318 |
If multiple destinations are given, then the given options are applied to all |
| 319 |
subvolumes. |
| 320 |
.sp |
| 321 |
If failure happens for any of the destinations, the command would |
| 322 |
still retry the remaining destinations, but would return 1 to indicate |
| 323 |
the failure (similar to what \fBmkdir\fP would do. |
| 324 |
.sp |
| 325 |
\fBOptions\fP |
| 326 |
.INDENT 7.0 |
| 327 |
.TP |
| 328 |
.BI \-i \ <qgroupid> |
| 329 |
Add the newly created subvolume to a qgroup. This option can be given multiple |
| 330 |
times. |
| 331 |
.UNINDENT |
| 332 |
.INDENT 7.0 |
| 333 |
.TP |
| 334 |
.B \-p|\-\-parents |
| 335 |
Create any missing parent directories for each argument (like \fBmkdir \-p\fP). |
| 336 |
.UNINDENT |
| 337 |
.TP |
| 338 |
.B delete [options] [<subvolume> [<subvolume>...]], delete \-i|\-\-subvolid <subvolid> <path> |
| 339 |
Delete the subvolume(s) from the filesystem. |
| 340 |
.sp |
| 341 |
If \fIsubvolume\fP is not a subvolume, the command returns an error but |
| 342 |
continues if there are more arguments to process. |
| 343 |
.sp |
| 344 |
If \fI\-\-subvolid\fP is used, \fIpath\fP must point to a btrfs filesystem. See |
| 345 |
btrfs subvolume list or |
| 346 |
btrfs inspect\-internal rootid \%<#\:man-inspect-rootid> |
| 347 |
how to get the subvolume id. |
| 348 |
.sp |
| 349 |
The corresponding directory is removed instantly but the data blocks are |
| 350 |
removed later in the background. The command returns immediately. See |
| 351 |
btrfs subvolume sync how to wait until the subvolume gets completely removed. |
| 352 |
.sp |
| 353 |
The deletion does not involve a full transaction commit by default due to |
| 354 |
performance reasons. As a consequence, the subvolume may appear again after a |
| 355 |
crash. Use one of the \fI\-\-commit\fP options to wait until the operation is |
| 356 |
safely stored on the device before the command returns. |
| 357 |
.sp |
| 358 |
Deleting subvolume needs sufficient permissions, by default the owner |
| 359 |
cannot delete it unless it\(aqs enabled by a mount option |
| 360 |
\fIuser_subvol_rm_allowed\fP, or deletion is run as root. |
| 361 |
The default subvolume (see btrfs subvolume set\-default) |
| 362 |
cannot be deleted and |
| 363 |
returns error (EPERM) and this is logged to the system log. A subvolume that\(aqs |
| 364 |
currently involved in send (see btrfs\-send(8) \%<>) |
| 365 |
also cannot be deleted until the |
| 366 |
send is finished. This is also logged in the system log. |
| 367 |
.sp |
| 368 |
\fBOptions\fP |
| 369 |
.INDENT 7.0 |
| 370 |
.TP |
| 371 |
.B \-c|\-\-commit\-after |
| 372 |
wait for transaction commit at the end of the operation. |
| 373 |
.TP |
| 374 |
.B \-C|\-\-commit\-each |
| 375 |
wait for transaction commit after deleting each subvolume. |
| 376 |
.TP |
| 377 |
.B \-i|\-\-subvolid <subvolid> |
| 378 |
subvolume id to be removed instead of the <path> that should point to the |
| 379 |
filesystem with the subvolume |
| 380 |
.TP |
| 381 |
.B \-R|\-\-recursive |
| 382 |
delete subvolumes beneath each subvolume recursively |
| 383 |
.sp |
| 384 |
This requires either \fICAP_SYS_ADMIN\fP or the filesystem must be |
| 385 |
mounted with \fIuser_subvol_rm_allowed\fP mount option. |
| 386 |
In the unprivileged case, subvolumes which cannot be accessed |
| 387 |
are skipped. The deletion is not atomic. |
| 388 |
.TP |
| 389 |
.B \-v|\-\-verbose |
| 390 |
(deprecated) alias for global \fI\-v\fP option |
| 391 |
.UNINDENT |
| 392 |
.TP |
| 393 |
.B find\-new <subvolume> <last_gen> |
| 394 |
List the recently modified files in a subvolume, after \fIlast_gen\fP generation. |
| 395 |
.TP |
| 396 |
.B get\-default <path> |
| 397 |
Get the default subvolume of the filesystem \fIpath\fP\&. |
| 398 |
.sp |
| 399 |
The output format is similar to \fBsubvolume list\fP command. |
| 400 |
.UNINDENT |
| 401 |
.INDENT 0.0 |
| 402 |
.TP |
| 403 |
.B list [options] [\-G [+|\-]<value>] [\-C [+|\-]<value>] [\-\-sort=rootid,gen,ogen,path] <path> |
| 404 |
List the subvolumes present in the filesystem \fIpath\fP\&. |
| 405 |
.sp |
| 406 |
For every subvolume the following information is shown by default: |
| 407 |
.sp |
| 408 |
ID \fIID\fP gen \fIgeneration\fP top level \fIparent_ID\fP path \fIpath\fP |
| 409 |
.sp |
| 410 |
where \fIID\fP is subvolume\(aqs (root)id, \fIgeneration\fP is an internal counter which is |
| 411 |
updated every transaction, \fIparent_ID\fP is the same as the parent subvolume\(aqs id, |
| 412 |
and \fIpath\fP is the relative path of the subvolume to the top level subvolume. |
| 413 |
The subvolume\(aqs ID may be used by the subvolume set\-default command, |
| 414 |
or at mount time via the \fIsubvolid=\fP option. |
| 415 |
.sp |
| 416 |
\fBOptions\fP |
| 417 |
.sp |
| 418 |
Path filtering: |
| 419 |
.INDENT 7.0 |
| 420 |
.TP |
| 421 |
.B \-o |
| 422 |
Print only subvolumes below specified <path>. Note that this is not a |
| 423 |
recursive command, and won\(aqt show nested subvolumes under <path>. |
| 424 |
.TP |
| 425 |
.B \-a |
| 426 |
print all the subvolumes in the filesystem and distinguish between |
| 427 |
absolute and relative path with respect to the given \fIpath\fP\&. |
| 428 |
.UNINDENT |
| 429 |
.sp |
| 430 |
Field selection: |
| 431 |
.INDENT 7.0 |
| 432 |
.TP |
| 433 |
.B \-p |
| 434 |
print the parent ID |
| 435 |
(\fIparent\fP here means the subvolume which contains this subvolume). |
| 436 |
.TP |
| 437 |
.B \-c |
| 438 |
print the ogeneration of the subvolume, aliases: ogen or origin generation. |
| 439 |
.TP |
| 440 |
.B \-g |
| 441 |
print the generation of the subvolume (default). |
| 442 |
.TP |
| 443 |
.B \-u |
| 444 |
print the UUID of the subvolume. |
| 445 |
.TP |
| 446 |
.B \-q |
| 447 |
print the parent UUID of the subvolume |
| 448 |
(\fIparent\fP here means subvolume of which this subvolume is a snapshot). |
| 449 |
.TP |
| 450 |
.B \-R |
| 451 |
print the UUID of the sent subvolume, where the subvolume is the result of a receive operation. |
| 452 |
.UNINDENT |
| 453 |
.sp |
| 454 |
Type filtering: |
| 455 |
.INDENT 7.0 |
| 456 |
.TP |
| 457 |
.B \-s |
| 458 |
only snapshot subvolumes in the filesystem will be listed. |
| 459 |
.TP |
| 460 |
.B \-r |
| 461 |
only readonly subvolumes in the filesystem will be listed. |
| 462 |
.TP |
| 463 |
.B \-d |
| 464 |
list deleted subvolumes that are not yet cleaned. |
| 465 |
.UNINDENT |
| 466 |
.sp |
| 467 |
Other: |
| 468 |
.INDENT 7.0 |
| 469 |
.TP |
| 470 |
.B \-t |
| 471 |
print the result as a table. |
| 472 |
.UNINDENT |
| 473 |
.sp |
| 474 |
Sorting: |
| 475 |
.sp |
| 476 |
By default the subvolumes will be sorted by subvolume ID ascending. |
| 477 |
.INDENT 7.0 |
| 478 |
.TP |
| 479 |
.B \-G [+|\-]<value> |
| 480 |
list subvolumes in the filesystem that its generation is |
| 481 |
>=, <= or = value. \(aq+\(aq means >= value, \(aq\-\(aq means <= value, If there is |
| 482 |
neither \(aq+\(aq nor \(aq\-\(aq, it means = value. |
| 483 |
.TP |
| 484 |
.B \-C [+|\-]<value> |
| 485 |
list subvolumes in the filesystem that its ogeneration is |
| 486 |
>=, <= or = value. The usage is the same to \fI\-G\fP option. |
| 487 |
.TP |
| 488 |
.B \-\-sort=rootid,gen,ogen,path |
| 489 |
list subvolumes in order by specified items. |
| 490 |
you can add \fI+\fP or \fI\-\fP in front of each items, \fI+\fP means ascending, |
| 491 |
\fI\-\fP means descending. The default is ascending. |
| 492 |
.sp |
| 493 |
for \fI\-\-sort\fP you can combine some items together by \fI,\fP, just like |
| 494 |
\fI\-\-sort=+ogen,\-gen,path,rootid\fP\&. |
| 495 |
.UNINDENT |
| 496 |
.UNINDENT |
| 497 |
.INDENT 0.0 |
| 498 |
.TP |
| 499 |
.B set\-default [<subvolume>|<id> <path>] |
| 500 |
Set the default subvolume for the (mounted) filesystem. |
| 501 |
.sp |
| 502 |
Set the default subvolume for the (mounted) filesystem at \fIpath\fP\&. This will hide |
| 503 |
the top\-level subvolume (i.e. the one mounted with \fIsubvol=/\fP or \fIsubvolid=5\fP). |
| 504 |
Takes action on next mount. |
| 505 |
.sp |
| 506 |
There are two ways how to specify the subvolume, by \fIid\fP or by the \fIsubvolume\fP |
| 507 |
path. |
| 508 |
The id can be obtained from btrfs subvolume list |
| 509 |
btrfs subvolume show or |
| 510 |
btrfs inspect\-internal rootid \%<#\:man-inspect-rootid>\&. |
| 511 |
.UNINDENT |
| 512 |
.INDENT 0.0 |
| 513 |
.TP |
| 514 |
.B show [options] <path> |
| 515 |
Show more information about a subvolume (UUIDs, generations, times, flags, |
| 516 |
related snapshots). |
| 517 |
.INDENT 7.0 |
| 518 |
.INDENT 3.5 |
| 519 |
.sp |
| 520 |
.EX |
| 521 |
/mnt/btrfs/subvolume |
| 522 |
Name: subvolume |
| 523 |
UUID: 5e076a14\-4e42\-254d\-ac8e\-55bebea982d1 |
| 524 |
Parent UUID: \- |
| 525 |
Received UUID: \- |
| 526 |
Creation time: 2018\-01\-01 12:34:56 +0000 |
| 527 |
Subvolume ID: 79 |
| 528 |
Generation: 2844 |
| 529 |
Gen at creation: 2844 |
| 530 |
Parent ID: 5 |
| 531 |
Top level ID: 5 |
| 532 |
Flags: \- |
| 533 |
Snapshot(s): |
| 534 |
.EE |
| 535 |
.UNINDENT |
| 536 |
.UNINDENT |
| 537 |
.sp |
| 538 |
\fBOptions\fP |
| 539 |
.INDENT 7.0 |
| 540 |
.TP |
| 541 |
.B \-r|\-\-rootid <ID> |
| 542 |
show details about subvolume with root \fIID\fP, looked up in \fIpath\fP |
| 543 |
.TP |
| 544 |
.B \-u|\-\-uuid UUID |
| 545 |
show details about subvolume with the given \fIUUID\fP, looked up in \fIpath\fP |
| 546 |
.UNINDENT |
| 547 |
.TP |
| 548 |
.B snapshot [\-r] [\-i <qgroupid>] <source> <dest>|[<dest>/]<name> |
| 549 |
Create a snapshot of the subvolume \fIsource\fP with the |
| 550 |
name \fIname\fP in the \fIdest\fP directory. |
| 551 |
.sp |
| 552 |
If only \fIdest\fP is given, the subvolume will be named the basename of \fIsource\fP\&. |
| 553 |
If \fIsource\fP is not a subvolume, btrfs returns an error. |
| 554 |
.sp |
| 555 |
\fBOptions\fP |
| 556 |
.INDENT 7.0 |
| 557 |
.TP |
| 558 |
.B \-r |
| 559 |
Make the new snapshot read only. |
| 560 |
.TP |
| 561 |
.BI \-i \ <qgroupid> |
| 562 |
Add the newly created subvolume to a qgroup. This option can be given multiple |
| 563 |
times. |
| 564 |
.UNINDENT |
| 565 |
.UNINDENT |
| 566 |
.INDENT 0.0 |
| 567 |
.TP |
| 568 |
.B sync <path> [subvolid...] |
| 569 |
Wait until given subvolume(s) are completely removed from the filesystem after |
| 570 |
deletion. If no subvolume id is given, wait until all current deletion requests |
| 571 |
are completed, but do not wait for subvolumes deleted in the meantime. |
| 572 |
.sp |
| 573 |
If the filesystem status changes to read\-only then the waiting is interrupted. |
| 574 |
.sp |
| 575 |
\fBOptions\fP |
| 576 |
.INDENT 7.0 |
| 577 |
.TP |
| 578 |
.BI \-s \ <N> |
| 579 |
sleep N seconds between checks (default: 1) |
| 580 |
.UNINDENT |
| 581 |
.UNINDENT |
| 582 |
.SH EXAMPLES |
| 583 |
.SS Deleting a subvolume |
| 584 |
.sp |
| 585 |
If we want to delete a subvolume called \fIfoo\fP from a btrfs volume mounted at |
| 586 |
\fB/mnt/bar\fP we could run the following: |
| 587 |
.INDENT 0.0 |
| 588 |
.INDENT 3.5 |
| 589 |
.sp |
| 590 |
.EX |
| 591 |
btrfs subvolume delete /mnt/bar/foo |
| 592 |
.EE |
| 593 |
.UNINDENT |
| 594 |
.UNINDENT |
| 595 |
.SH EXIT STATUS |
| 596 |
.sp |
| 597 |
\fBbtrfs subvolume\fP returns a zero exit status if it succeeds. A non\-zero value is |
| 598 |
returned in case of failure. |
| 599 |
.SH AVAILABILITY |
| 600 |
.sp |
| 601 |
\fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at |
| 602 |
\%<https://\:btrfs\:.readthedocs\:.io>\&. |
| 603 |
.SH SEE ALSO |
| 604 |
.sp |
| 605 |
btrfs\-qgroup(8) \%<>, |
| 606 |
btrfs\-quota(8) \%<>, |
| 607 |
btrfs\-send(8) \%<>, |
| 608 |
mkfs.btrfs(8) \%<>, |
| 609 |
mount(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:mount\:.8\:.html> |
| 610 |
.\" End of generated man page. |