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 use case 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 across rollbacks is it's own
123 subvolume. This could be e.g. /var. Further more-fine grained parti‐
124 tioning could be done, e.g. adding separate subvolumes for /var/log,
125 /var/cache etc.
126 That there are separate subvolumes requires 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 e.g. 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 change 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 Deleting subvolume needs sufficient permissions, by default the
256 owner cannot delete it unless it's enabled by a mount option
257 user_subvol_rm_allowed, or deletion is run as root. The default
258 subvolume (see btrfs subvolume set-default) cannot be deleted
259 and returns error (EPERM) and this is logged to the system log.
260 A subvolume that's currently involved in send (see btrfs send)
261 also cannot be deleted until the send is finished. This is also
262 logged in the system log.
263 Options
265 -c|--commit-after
267 wait for transaction commit at the end of the operation.
268 -C|--commit-each
270 wait for transaction commit after deleting each subvol‐
271 ume.
272 -i|--subvolid <subvolid>
274 subvolume id to be removed instead of the <path> that
275 should point to the filesystem with the subvolume
276 -v|--verbose
278 (deprecated) alias for global -v option
279 find-new <subvolume> <last_gen>
281 List the recently modified files in a subvolume, after last_gen
282 generation.
283 get-default <path>
285 Get the default subvolume of the filesystem path.
286 The output format is similar to subvolume list command.
288 list [options] [-G [+|-]<value>] [-C [+|-]<value>]
290 [--sort=rootid,gen,ogen,path] <path>
291 List the subvolumes present in the filesystem path.
292 For every subvolume the following information is shown by de‐
294 fault:
295 ID ID gen generation top level parent_ID path path
297 where ID is subvolume's (root)id, generation is an internal
299 counter which is updated every transaction, parent_ID is the
300 same as the parent subvolume's id, and path is the relative path
301 of the subvolume to the top level subvolume. The subvolume's ID
302 may be used by the subvolume set-default command, or at mount
303 time via the subvolid= option.
304 Options
306 Path filtering:
308 -o print only subvolumes below specified <path>.
310 -a print all the subvolumes in the filesystem and distin‐
312 guish between absolute and relative path with respect to
313 the given path.
314 Field selection:
316 -p print the parent ID (parent here means the subvolume
318 which contains this subvolume).
319 -c print the ogeneration of the subvolume, aliases: ogen or
321 origin generation.
322 -g print the generation of the subvolume (default).
324 -u print the UUID of the subvolume.
326 -q print the parent UUID of the subvolume (parent here means
328 subvolume of which this subvolume is a snapshot).
329 -R print the UUID of the sent subvolume, where the subvolume
331 is the result of a receive operation.
332 Type filtering:
334 -s only snapshot subvolumes in the filesystem will be
336 listed.
337 -r only readonly subvolumes in the filesystem will be
339 listed.
340 -d list deleted subvolumes that are not yet cleaned.
342 Other:
344 -t print the result as a table.
346 Sorting:
348 By default the subvolumes will be sorted by subvolume ID ascend‐
350 ing.
351 -G [+|-]<value>
353 list subvolumes in the filesystem that its generation is
354 >=, <= or = value. '+' means >= value, '-' means <=
355 value, If there is neither '+' nor '-', it means = value.
356 -C [+|-]<value>
358 list subvolumes in the filesystem that its ogeneration is
359 >=, <= or = value. The usage is the same to -G option.
360 --sort=rootid,gen,ogen,path
362 list subvolumes in order by specified items. you can add
363 + or - in front of each items, + means ascending, - means
364 descending. The default is ascending.
365 for --sort you can combine some items together by ,, just
367 like --sort=+ogen,-gen,path,rootid.
368 set-default [<subvolume>|<id> <path>]
370 Set the default subvolume for the (mounted) filesystem.
371 Set the default subvolume for the (mounted) filesystem at path.
373 This will hide the top-level subvolume (i.e. the one mounted
374 with subvol=/ or subvolid=5). Takes action on next mount.
375 There are two ways how to specify the subvolume, by id or by the
377 subvolume path. The id can be obtained from btrfs subvolume
378 list, btrfs subvolume show or btrfs inspect-internal rootid.
379 show [options] <path>
381 Show more information about a subvolume (UUIDs, generations,
382 times, flags, related snapshots).
383 /mnt/btrfs/subvolume
385 Name: subvolume
386 UUID: 5e076a14-4e42-254d-ac8e-55bebea982d1
387 Parent UUID: -
388 Received UUID: -
389 Creation time: 2018-01-01 12:34:56 +0000
390 Subvolume ID: 79
391 Generation: 2844
392 Gen at creation: 2844
393 Parent ID: 5
394 Top level ID: 5
395 Flags: -
396 Snapshot(s):
397 Options
399 -r|--rootid <ID>
401 show details about subvolume with root ID, looked up in
402 path
403 -u|--uuid UUID
405 show details about subvolume with the given UUID, looked
406 up in path
407 snapshot [-r] [-i <qgroupid>] <source> <dest>|[<dest>/]<name>
409 Create a snapshot of the subvolume source with the name name in
410 the dest directory.
411 If only dest is given, the subvolume will be named the basename
413 of source. If source is not a subvolume, btrfs returns an er‐
414 ror.
415 Options
417 -r Make the new snapshot read only.
419 -i <qgroupid>
421 Add the newly created subvolume to a qgroup. This option
422 can be given multiple times.
423 sync <path> [subvolid...]
425 Wait until given subvolume(s) are completely removed from the
426 filesystem after deletion. If no subvolume id is given, wait un‐
427 til all current deletion requests are completed, but do not wait
428 for subvolumes deleted in the meantime.
429 Options
431 -s <N> sleep N seconds between checks (default: 1)
433
435 Deleting a subvolume
436 If we want to delete a subvolume called foo from a btrfs volume mounted
437 at /mnt/bar we could run the following:
438 btrfs subvolume delete /mnt/bar/foo
440
442 btrfs subvolume returns a zero exit status if it succeeds. A non-zero
443 value is returned in case of failure.
444
446 btrfs is part of btrfs-progs. Please refer to the documentation at
447 https://btrfs.readthedocs.io or wiki http://btrfs.wiki.kernel.org for
448 further information.
449
451 btrfs-qgroup(8), btrfs-quota(8), btrfs-send(8), mkfs.btrfs(8), mount(8)
4526.1.3 Jan 25, 2023 BTRFS-SUBVOLUME(8)