1BTRFS-SUBVOLUME(8) BTRFS BTRFS-SUBVOLUME(8)
2
6 btrfs-subvolume - manage btrfs subvolumes
7
9 btrfs subvolume <subcommand> [<args>]
10
12 btrfs subvolume is used to create/delete/list/show btrfs subvolumes and
13 snapshots.
14 A BTRFS subvolume is a part of filesystem with its own independent
16 file/directory hierarchy and inode number namespace. Subvolumes can
17 share file extents. A snapshot is also subvolume, but with a given ini‐
18 tial content of the original subvolume. A subvolume has always inode
19 number 256.
20 NOTE:
22 A subvolume in BTRFS is not like an LVM logical volume, which is
23 block-level snapshot while BTRFS subvolumes are file extent-based.
24 A subvolume looks like a normal directory, with some additional opera‐
26 tions described below. Subvolumes can be renamed or moved, nesting sub‐
27 volumes is not restricted but has some implications regarding snapshot‐
28 ting. The numeric id (called subvolid or rootid) of the subvolume is
29 persistent and cannot be changed.
30 A subvolume in BTRFS can be accessed in two ways:
32 • like any other directory that is accessible to the user
34 • like a separately mounted filesystem (options subvol or subvolid)
36 In the latter case the parent directory is not visible and accessible.
38 This is similar to a bind mount, and in fact the subvolume mount does
39 exactly that.
40 A freshly created filesystem is also a subvolume, called top-level, in‐
42 ternally has an id 5. This subvolume cannot be removed or replaced by
43 another subvolume. This is also the subvolume that will be mounted by
44 default, unless the default subvolume has been changed (see btrfs sub‐
45 volume set-default).
46 A snapshot is a subvolume like any other, with given initial content.
48 By default, snapshots are created read-write. File modifications in a
49 snapshot do not affect the files in the original subvolume.
50 Subvolumes can be given capacity limits, through the qgroups/quota fa‐
52 cility, but otherwise share the single storage pool of the whole btrfs
53 filesystem. They may even share data between themselves (through dedu‐
54 plication or snapshotting).
55 NOTE:
57 A snapshot is not a backup: snapshots work by use of BTRFS'
58 copy-on-write behaviour. A snapshot and the original it was taken
59 from initially share all of the same data blocks. If that data is
60 damaged in some way (cosmic rays, bad disk sector, accident with dd
61 to the disk), then the snapshot and the original will both be dam‐
62 aged. Snapshots are useful to have local online "copies" of the
63 filesystem that can be referred back to, or to implement a form of
64 deduplication, or to fix the state of a filesystem for making a full
65 backup without anything changing underneath it. They do not in them‐
66 selves make your data any safer.
67
69 The subvolume flag currently implemented is the ro property (read-only
70 status). Read-write subvolumes have that set to false, snapshots as
71 true. In addition to that, a plain snapshot will also have last change
72 generation and creation generation equal.
73 Read-only snapshots are building blocks of incremental send (see
75 btrfs-send(8)) and the whole use case relies on unmodified snapshots
76 where the relative changes are generated from. Thus, changing the sub‐
77 volume flags from read-only to read-write will break the assumptions
78 and may lead to unexpected changes in the resulting incremental stream.
79 A snapshot that was created by send/receive will be read-only, with
81 different last change generation, read-only and with set received_uuid
82 which identifies the subvolume on the filesystem that produced the
83 stream. The use case relies on matching data on both sides. Changing
84 the subvolume to read-write after it has been received requires to re‐
85 set the received_uuid. As this is a notable change and could poten‐
86 tially break the incremental send use case, performing it by btrfs
87 property set requires force if that is really desired by user.
88 NOTE:
90 The safety checks have been implemented in 5.14.2, any subvolumes
91 previously received (with a valid received_uuid) and read-write sta‐
92 tus may exist and could still lead to problems with send/receive.
93 You can use btrfs subvolume show to identify them. Flipping the
94 flags to read-only and back to read-write will reset the re‐
95 ceived_uuid manually. There may exist a convenience tool in the fu‐
96 ture.
97
99 There are no restrictions for subvolume creation, so it's up to the
100 user how to organize them, whether to have a flat layout (all subvol‐
101 umes are direct descendants of the toplevel one), or nested.
102 What should be mentioned early is that a snapshotting is not recursive,
104 so a subvolume or a snapshot is effectively a barrier and no files in
105 the nested appear in the snapshot. Instead there's a stub subvolume
106 (also sometimes empty subvolume with the same name as original subvol‐
107 ume, with inode number 2). This can be used intentionally but could be
108 confusing in case of nested layouts.
109 Case study: system root layouts
111 There are two ways how the system root directory and subvolume layout
112 could be organized. The interesting usecase for root is to allow roll‐
113 backs to previous version, as one atomic step. If the entire filesystem
114 hierarchy starting in "/" is in one subvolume, taking snapshot will en‐
115 compass all files. This is easy for the snapshotting part but has unde‐
116 sirable consequences for rollback. For example, log files would get
117 rolled back too, or any data that are stored on the root filesystem but
118 are not meant to be rolled back either (database files, VM images,
119 ...).
120 Here we could utilize the snapshotting barrier mentioned above, each
122 directory that stores data to be preserved accross rollbacks is it's
123 own subvolume. This could be eg. /var. Further more-fine grained parti‐
124 tioning could be done, eg. adding separate subvolumes for /var/log,
125 /var/cache etc.
126 That there are separate subvolumes requrires separate actions to take
128 the snapshots (here it gets disconnected from the system root snap‐
129 shots). This needs to be taken care of by system tools, installers to‐
130 gether with selection of which directories are highly recommended to be
131 separate subvolumes.
132
134 Mount options are of two kinds, generic (that are handled by VFS layer)
135 and specific, handled by the filesystem. The following list shows which
136 are applicable to individual subvolume mounts, while there are more op‐
137 tions that always affect the whole filesystem:
138 • generic: noatime/relatime/..., nodev, nosuid, ro, rw, dirsync
140 • fs-specific: compress, autodefrag, nodatacow, nodatasum
142 An example of whole filesystem options is eg. space_cache, rescue, de‐
144 vice, skip_balance, etc. The exceptional options are subvol and sub‐
145 volid that are actually used for mounting a given subvolume and can be
146 specified only once for the mount.
147 Subvolumes belong to a single filesystem and as implemented now all
149 share the same specific mount options, changes done by remount have im‐
150 mediate effect. This may change in the future.
151 Mounting a read-write snapshot as read-only is possible and will not
153 chnange the ro property and flag of the subvolume.
154 The name of the mounted subvolume is stored in file /proc/self/mounts
156 in the 4th column:
157 27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache
159 ^^^^^^
160
162 A proper subvolume has always inode number 256. If a subvolume is
163 nested and then a snapshot is taken, then the cloned directory entry
164 representing the subvolume becomes empty and the inode has number 2.
165 All other files and directories in the target snapshot preserve their
166 original inode numbers.
167 NOTE:
169 Inode number is not a filesystem-wide unique identifier, some appli‐
170 cations assume that. Please user pair subvolumeid:inodenumber for
171 that purpose.
172
174 Subvolume creation needs to flush dirty data that belong to the subvol‐
175 ume, this step may take some time, otherwise once there's nothing else
176 to do, the snapshot is instant and in the metadata it only creates a
177 new tree root copy.
178 Snapshot deletion has two phases: first its directory is deleted and
180 the subvolume is added to a list, then the list is processed one by one
181 and the data related to the subvolume get deleted. This is usually
182 called cleaning and can take some time depending on the amount of
183 shared blocks (can be a lot of metadata updates), and the number of
184 currently queued deleted subvolumes.
185
187 A subvolume is a part of filesystem with its own independent file/di‐
188 rectory hierarchy. Subvolumes can share file extents. A snapshot is
189 also subvolume, but with a given initial content of the original sub‐
190 volume.
191 NOTE:
193 A subvolume in btrfs is not like an LVM logical volume, which is
194 block-level snapshot while btrfs subvolumes are file extent-based.
195 A subvolume looks like a normal directory, with some additional opera‐
197 tions described below. Subvolumes can be renamed or moved, nesting sub‐
198 volumes is not restricted but has some implications regarding snapshot‐
199 ting.
200 A subvolume in btrfs can be accessed in two ways:
202 • like any other directory that is accessible to the user
204 • like a separately mounted filesystem (options subvol or subvolid)
206 In the latter case the parent directory is not visible and accessible.
208 This is similar to a bind mount, and in fact the subvolume mount does
209 exactly that.
210 A freshly created filesystem is also a subvolume, called top-level, in‐
212 ternally has an id 5. This subvolume cannot be removed or replaced by
213 another subvolume. This is also the subvolume that will be mounted by
214 default, unless the default subvolume has been changed (see subcommand
215 set-default).
216 A snapshot is a subvolume like any other, with given initial content.
218 By default, snapshots are created read-write. File modifications in a
219 snapshot do not affect the files in the original subvolume.
220
222 create [-i <qgroupid>] [<dest>/]<name>
223 Create a subvolume name in dest.
224 If dest is not given, subvolume name will be created in the cur‐
226 rent directory.
227 Options
229 -i <qgroupid>
231 Add the newly created subvolume to a qgroup. This option
232 can be given multiple times.
233 delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid
235 <subvolid> <path>
236 Delete the subvolume(s) from the filesystem.
237 If subvolume is not a subvolume, btrfs returns an error but con‐
239 tinues if there are more arguments to process.
240 If --subvolid is used, path must point to a btrfs filesystem.
242 See btrfs subvolume list or btrfs inspect-internal rootid how to
243 get the subvolume id.
244 The corresponding directory is removed instantly but the data
246 blocks are removed later in the background. The command returns
247 immediately. See btrfs subvolume sync how to wait until the sub‐
248 volume gets completely removed.
249 The deletion does not involve full transaction commit by default
251 due to performance reasons. As a consequence, the subvolume may
252 appear again after a crash. Use one of the --commit options to
253 wait until the operation is safely stored on the device.
254 The default subvolume (see btrfs subvolume set-default) cannot
256 be deleted and returns error (EPERM) and this is logged to the
257 system log. A subvolume that's currently involved in send (see
258 btrfs send) also cannot be deleted until the send is finished.
259 This is also logged in the system log.
260 Options
262 -c|--commit-after
264 wait for transaction commit at the end of the operation.
265 -C|--commit-each
267 wait for transaction commit after deleting each subvol‐
268 ume.
269 -i|--subvolid <subvolid>
271 subvolume id to be removed instead of the <path> that
272 should point to the filesystem with the subvolume
273 -v|--verbose
275 (deprecated) alias for global -v option
276 find-new <subvolume> <last_gen>
278 List the recently modified files in a subvolume, after last_gen
279 generation.
280 get-default <path>
282 Get the default subvolume of the filesystem path.
283 The output format is similar to subvolume list command.
285 list [options] [-G [+|-]<value>] [-C [+|-]<value>]
287 [--sort=rootid,gen,ogen,path] <path>
288 List the subvolumes present in the filesystem path.
289 For every subvolume the following information is shown by de‐
291 fault:
292 ID ID gen generation top level ID path path
294 where ID is subvolume's id, gen is an internal counter which is
296 updated every transaction, top level is the same as parent sub‐
297 volume's id, and path is the relative path of the subvolume to
298 the top level subvolume. The subvolume's ID may be used by the
299 subvolume set-default command, or at mount time via the sub‐
300 volid= option.
301 Options
303 Path filtering:
305 -o print only subvolumes below specified <path>.
307 -a print all the subvolumes in the filesystem and distin‐
309 guish between absolute and relative path with respect to
310 the given path.
311 Field selection:
313 -p print the parent ID (parent here means the subvolume
315 which contains this subvolume).
316 -c print the ogeneration of the subvolume, aliases: ogen or
318 origin generation.
319 -g print the generation of the subvolume (default).
321 -u print the UUID of the subvolume.
323 -q print the parent UUID of the subvolume (parent here means
325 subvolume of which this subvolume is a snapshot).
326 -R print the UUID of the sent subvolume, where the subvolume
328 is the result of a receive operation.
329 Type filtering:
331 -s only snapshot subvolumes in the filesystem will be
333 listed.
334 -r only readonly subvolumes in the filesystem will be
336 listed.
337 -d list deleted subvolumes that are not yet cleaned.
339 Other:
341 -t print the result as a table.
343 Sorting:
345 By default the subvolumes will be sorted by subvolume ID ascend‐
347 ing.
348 -G [+|-]<value>
350 list subvolumes in the filesystem that its generation is
351 >=, <= or = value. '+' means >= value, '-' means <=
352 value, If there is neither '+' nor '-', it means = value.
353 -C [+|-]<value>
355 list subvolumes in the filesystem that its ogeneration is
356 >=, <= or = value. The usage is the same to -G option.
357 --sort=rootid,gen,ogen,path
359 list subvolumes in order by specified items. you can add
360 + or - in front of each items, + means ascending, - means
361 descending. The default is ascending.
362 for --sort you can combine some items together by ,, just
364 like --sort=+ogen,-gen,path,rootid.
365 set-default [<subvolume>|<id> <path>]
367 Set the default subvolume for the (mounted) filesystem.
368 Set the default subvolume for the (mounted) filesystem at path.
370 This will hide the top-level subvolume (i.e. the one mounted
371 with subvol=/ or subvolid=5). Takes action on next mount.
372 There are two ways how to specify the subvolume, by id or by the
374 subvolume path. The id can be obtained from btrfs subvolume
375 list, btrfs subvolume show or btrfs inspect-internal rootid.
376 show [options] <path>
378 Show more information about a subvolume (UUIDs, generations,
379 times, flags, related snapshots).
380 /mnt/btrfs/subvolume
382 Name: subvolume
383 UUID: 5e076a14-4e42-254d-ac8e-55bebea982d1
384 Parent UUID: -
385 Received UUID: -
386 Creation time: 2018-01-01 12:34:56 +0000
387 Subvolume ID: 79
388 Generation: 2844
389 Gen at creation: 2844
390 Parent ID: 5
391 Top level ID: 5
392 Flags: -
393 Snapshot(s):
394 Options
396 -r|--rootid <ID>
398 show details about subvolume with root ID, looked up in
399 path
400 -u|--uuid UUID
402 show details about subvolume with the given UUID, looked
403 up in path
404 snapshot [-r] [-i <qgroupid>] <source> <dest>|[<dest>/]<name>
406 Create a snapshot of the subvolume source with the name name in
407 the dest directory.
408 If only dest is given, the subvolume will be named the basename
410 of source. If source is not a subvolume, btrfs returns an er‐
411 ror.
412 Options
414 -r Make the new snapshot read only.
416 -i <qgroupid>
418 Add the newly created subvolume to a qgroup. This option
419 can be given multiple times.
420 sync <path> [subvolid...]
422 Wait until given subvolume(s) are completely removed from the
423 filesystem after deletion. If no subvolume id is given, wait un‐
424 til all current deletion requests are completed, but do not wait
425 for subvolumes deleted in the meantime.
426 Options
428 -s <N> sleep N seconds between checks (default: 1)
430
432 Deleting a subvolume
433 If we want to delete a subvolume called foo from a btrfs volume mounted
434 at /mnt/bar we could run the following:
435 btrfs subvolume delete /mnt/bar/foo
437
439 btrfs subvolume returns a zero exit status if it succeeds. A non-zero
440 value is returned in case of failure.
441
443 btrfs is part of btrfs-progs. Please refer to the btrfs wiki
444 http://btrfs.wiki.kernel.org for further details.
445
447 mkfs.btrfs(8), mount(8), btrfs-quota(8), btrfs-qgroup(8), btrfs-send(8)
448
450 2022
4515.18 May 25, 2022 BTRFS-SUBVOLUME(8)