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
156 /proc/self/mountinfo 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 use 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 [options] [<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 -p|--parents
235 Create any missing parent directories for each argument
236 (like mkdir -p).
237 delete [options] [<subvolume> [<subvolume>...]], delete -i|--subvolid
239 <subvolid> <path>
240 Delete the subvolume(s) from the filesystem.
241 If subvolume is not a subvolume, btrfs returns an error but con‐
243 tinues if there are more arguments to process.
244 If --subvolid is used, path must point to a btrfs filesystem.
246 See btrfs subvolume list or btrfs inspect-internal rootid how to
247 get the subvolume id.
248 The corresponding directory is removed instantly but the data
250 blocks are removed later in the background. The command returns
251 immediately. See btrfs subvolume sync how to wait until the sub‐
252 volume gets completely removed.
253 The deletion does not involve full transaction commit by default
255 due to performance reasons. As a consequence, the subvolume may
256 appear again after a crash. Use one of the --commit options to
257 wait until the operation is safely stored on the device.
258 Deleting subvolume needs sufficient permissions, by default the
260 owner cannot delete it unless it's enabled by a mount option
261 user_subvol_rm_allowed, or deletion is run as root. The default
262 subvolume (see btrfs subvolume set-default) cannot be deleted
263 and returns error (EPERM) and this is logged to the system log.
264 A subvolume that's currently involved in send (see
265 btrfs-send(8)) also cannot be deleted until the send is fin‐
266 ished. This is also logged in the system log.
267 Options
269 -c|--commit-after
271 wait for transaction commit at the end of the operation.
272 -C|--commit-each
274 wait for transaction commit after deleting each subvol‐
275 ume.
276 -i|--subvolid <subvolid>
278 subvolume id to be removed instead of the <path> that
279 should point to the filesystem with the subvolume
280 -v|--verbose
282 (deprecated) alias for global -v option
283 find-new <subvolume> <last_gen>
285 List the recently modified files in a subvolume, after last_gen
286 generation.
287 get-default <path>
289 Get the default subvolume of the filesystem path.
290 The output format is similar to subvolume list command.
292 list [options] [-G [+|-]<value>] [-C [+|-]<value>]
294 [--sort=rootid,gen,ogen,path] <path>
295 List the subvolumes present in the filesystem path.
296 For every subvolume the following information is shown by de‐
298 fault:
299 ID ID gen generation top level parent_ID path path
301 where ID is subvolume's (root)id, generation is an internal
303 counter which is updated every transaction, parent_ID is the
304 same as the parent subvolume's id, and path is the relative path
305 of the subvolume to the top level subvolume. The subvolume's ID
306 may be used by the subvolume set-default command, or at mount
307 time via the subvolid= option.
308 Options
310 Path filtering:
312 -o Print only subvolumes below specified <path>. Note that
314 this is not a recursive command, and won't show nested
315 subvolumes under <path>.
316 -a print all the subvolumes in the filesystem and distin‐
318 guish between absolute and relative path with respect to
319 the given path.
320 Field selection:
322 -p print the parent ID (parent here means the subvolume
324 which contains this subvolume).
325 -c print the ogeneration of the subvolume, aliases: ogen or
327 origin generation.
328 -g print the generation of the subvolume (default).
330 -u print the UUID of the subvolume.
332 -q print the parent UUID of the subvolume (parent here means
334 subvolume of which this subvolume is a snapshot).
335 -R print the UUID of the sent subvolume, where the subvolume
337 is the result of a receive operation.
338 Type filtering:
340 -s only snapshot subvolumes in the filesystem will be
342 listed.
343 -r only readonly subvolumes in the filesystem will be
345 listed.
346 -d list deleted subvolumes that are not yet cleaned.
348 Other:
350 -t print the result as a table.
352 Sorting:
354 By default the subvolumes will be sorted by subvolume ID ascend‐
356 ing.
357 -G [+|-]<value>
359 list subvolumes in the filesystem that its generation is
360 >=, <= or = value. '+' means >= value, '-' means <=
361 value, If there is neither '+' nor '-', it means = value.
362 -C [+|-]<value>
364 list subvolumes in the filesystem that its ogeneration is
365 >=, <= or = value. The usage is the same to -G option.
366 --sort=rootid,gen,ogen,path
368 list subvolumes in order by specified items. you can add
369 + or - in front of each items, + means ascending, - means
370 descending. The default is ascending.
371 for --sort you can combine some items together by ,, just
373 like --sort=+ogen,-gen,path,rootid.
374 set-default [<subvolume>|<id> <path>]
376 Set the default subvolume for the (mounted) filesystem.
377 Set the default subvolume for the (mounted) filesystem at path.
379 This will hide the top-level subvolume (i.e. the one mounted
380 with subvol=/ or subvolid=5). Takes action on next mount.
381 There are two ways how to specify the subvolume, by id or by the
383 subvolume path. The id can be obtained from btrfs subvolume
384 list btrfs subvolume show or btrfs inspect-internal rootid.
385 show [options] <path>
387 Show more information about a subvolume (UUIDs, generations,
388 times, flags, related snapshots).
389 /mnt/btrfs/subvolume
391 Name: subvolume
392 UUID: 5e076a14-4e42-254d-ac8e-55bebea982d1
393 Parent UUID: -
394 Received UUID: -
395 Creation time: 2018-01-01 12:34:56 +0000
396 Subvolume ID: 79
397 Generation: 2844
398 Gen at creation: 2844
399 Parent ID: 5
400 Top level ID: 5
401 Flags: -
402 Snapshot(s):
403 Options
405 -r|--rootid <ID>
407 show details about subvolume with root ID, looked up in
408 path
409 -u|--uuid UUID
411 show details about subvolume with the given UUID, looked
412 up in path
413 snapshot [-r] [-i <qgroupid>] <source> <dest>|[<dest>/]<name>
415 Create a snapshot of the subvolume source with the name name in
416 the dest directory.
417 If only dest is given, the subvolume will be named the basename
419 of source. If source is not a subvolume, btrfs returns an er‐
420 ror.
421 Options
423 -r Make the new snapshot read only.
425 -i <qgroupid>
427 Add the newly created subvolume to a qgroup. This option
428 can be given multiple times.
429 sync <path> [subvolid...]
431 Wait until given subvolume(s) are completely removed from the
432 filesystem after deletion. If no subvolume id is given, wait un‐
433 til all current deletion requests are completed, but do not wait
434 for subvolumes deleted in the meantime.
435 Options
437 -s <N> sleep N seconds between checks (default: 1)
439
441 Deleting a subvolume
442 If we want to delete a subvolume called foo from a btrfs volume mounted
443 at /mnt/bar we could run the following:
444 btrfs subvolume delete /mnt/bar/foo
446
448 btrfs subvolume returns a zero exit status if it succeeds. A non-zero
449 value is returned in case of failure.
450
452 btrfs is part of btrfs-progs. Please refer to the documentation at
453 https://btrfs.readthedocs.io.
454
456 btrfs-qgroup(8), btrfs-quota(8), btrfs-send(8), mkfs.btrfs(8), mount(8)
4576.6.2 Nov 24, 2023 BTRFS-SUBVOLUME(8)