1BTRFS-SUBVOLUME(8)                   BTRFS                  BTRFS-SUBVOLUME(8)
2
3
4

NAME

6       btrfs-subvolume - manage btrfs subvolumes
7

SYNOPSIS

9       btrfs subvolume <subcommand> [<args>]
10

DESCRIPTION

12       btrfs subvolume is used to create/delete/list/show btrfs subvolumes and
13       snapshots.
14
15       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
21       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
25       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
31       A subvolume in BTRFS can be accessed in two ways:
32
33       • like any other directory that is accessible to the user
34
35       • like a separately mounted filesystem (options subvol or subvolid)
36
37       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
41       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
47       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
51       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
56       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

SUBVOLUME FLAGS

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
74       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
80       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
89       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

NESTED SUBVOLUMES

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
103       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
110   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
121       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
127       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

MOUNT OPTIONS

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
139       • generic: noatime/relatime/..., nodev, nosuid, ro, rw, dirsync
140
141       • fs-specific: compress, autodefrag, nodatacow, nodatasum
142
143       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
148       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
152       Mounting a read-write snapshot as read-only is possible  and  will  not
153       change the ro property and flag of the subvolume.
154
155       The  name  of the mounted subvolume is stored in file /proc/self/mounts
156       in the 4th column:
157
158          27 21 0:19 /subv1 /mnt rw,relatime - btrfs /dev/sda rw,space_cache
159                     ^^^^^^
160

INODE NUMBERS

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
168       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

PERFORMANCE

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
179       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

SUBVOLUME AND SNAPSHOT

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
192       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
196       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
201       A subvolume in btrfs can be accessed in two ways:
202
203       • like any other directory that is accessible to the user
204
205       • like a separately mounted filesystem (options subvol or subvolid)
206
207       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
211       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
217       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

SUBCOMMAND

222       create [-i <qgroupid>] [<dest>/]<name>
223              Create a subvolume name in dest.
224
225              If dest is not given, subvolume name will be created in the cur‐
226              rent directory.
227
228              Options
229
230              -i <qgroupid>
231                     Add the newly created subvolume to a qgroup. This  option
232                     can be given multiple times.
233
234       delete  [options]  [<subvolume> [<subvolume>...]], delete -i|--subvolid
235       <subvolid> <path>
236              Delete the subvolume(s) from the filesystem.
237
238              If subvolume is not a subvolume, btrfs returns an error but con‐
239              tinues if there are more arguments to process.
240
241              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
245              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
250              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
255              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
264              Options
265
266              -c|--commit-after
267                     wait for transaction commit at the end of the operation.
268
269              -C|--commit-each
270                     wait for transaction commit after deleting  each  subvol‐
271                     ume.
272
273              -i|--subvolid <subvolid>
274                     subvolume  id  to  be  removed instead of the <path> that
275                     should point to the filesystem with the subvolume
276
277              -v|--verbose
278                     (deprecated) alias for global -v option
279
280       find-new <subvolume> <last_gen>
281              List the recently modified files in a subvolume, after  last_gen
282              generation.
283
284       get-default <path>
285              Get the default subvolume of the filesystem path.
286
287              The output format is similar to subvolume list command.
288
289       list      [options]     [-G     [+|-]<value>]     [-C     [+|-]<value>]
290       [--sort=rootid,gen,ogen,path] <path>
291              List the subvolumes present in the filesystem path.
292
293              For every subvolume the following information is  shown  by  de‐
294              fault:
295
296              ID ID gen generation top level parent_ID path path
297
298              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
305              Options
306
307              Path filtering:
308
309              -o     print only subvolumes below specified <path>.
310
311              -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
315              Field selection:
316
317              -p     print the parent ID  (parent  here  means  the  subvolume
318                     which contains this subvolume).
319
320              -c     print  the ogeneration of the subvolume, aliases: ogen or
321                     origin generation.
322
323              -g     print the generation of the subvolume (default).
324
325              -u     print the UUID of the subvolume.
326
327              -q     print the parent UUID of the subvolume (parent here means
328                     subvolume of which this subvolume is a snapshot).
329
330              -R     print the UUID of the sent subvolume, where the subvolume
331                     is the result of a receive operation.
332
333              Type filtering:
334
335              -s     only  snapshot  subvolumes  in  the  filesystem  will  be
336                     listed.
337
338              -r     only  readonly  subvolumes  in  the  filesystem  will  be
339                     listed.
340
341              -d     list deleted subvolumes that are not yet cleaned.
342
343              Other:
344
345              -t     print the result as a table.
346
347              Sorting:
348
349              By default the subvolumes will be sorted by subvolume ID ascend‐
350              ing.
351
352              -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
357              -C [+|-]<value>
358                     list subvolumes in the filesystem that its ogeneration is
359                     >=, <= or = value. The usage is the same to -G option.
360
361              --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
366                     for --sort you can combine some items together by ,, just
367                     like --sort=+ogen,-gen,path,rootid.
368
369       set-default [<subvolume>|<id> <path>]
370              Set the default subvolume for the (mounted) filesystem.
371
372              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
376              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
380       show [options] <path>
381              Show  more  information  about  a subvolume (UUIDs, generations,
382              times, flags, related snapshots).
383
384                 /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
398              Options
399
400              -r|--rootid <ID>
401                     show details about subvolume with root ID, looked  up  in
402                     path
403
404              -u|--uuid UUID
405                     show  details about subvolume with the given UUID, looked
406                     up in path
407
408       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
412              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
416              Options
417
418              -r     Make the new snapshot read only.
419
420              -i <qgroupid>
421                     Add  the newly created subvolume to a qgroup. This option
422                     can be given multiple times.
423
424       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
430              Options
431
432              -s <N> sleep N seconds between checks (default: 1)
433

EXAMPLES

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
439          btrfs subvolume delete /mnt/bar/foo
440

EXIT STATUS

442       btrfs subvolume returns a zero exit status if it succeeds.  A  non-zero
443       value is returned in case of failure.
444

AVAILABILITY

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

SEE ALSO

451       btrfs-qgroup(8), btrfs-quota(8), btrfs-send(8), mkfs.btrfs(8), mount(8)
452
453
454
455
4566.1.3                            Jan 25, 2023               BTRFS-SUBVOLUME(8)
Impressum