Documentation/btrfs-subvolume.asciidoc

   1 btrfs-subvolume(8)
   2 ==================
   3
   4 NAME
   5 ----
   6 btrfs-subvolume - manage btrfs subvolumes
   7
   8 SYNOPSIS
   9 --------
  10 *btrfs subvolume* <subcommand> [<args>]
  11
  12 DESCRIPTION
  13 -----------
  14 *btrfs subvolume* is used to create/delete/list/show btrfs subvolumes and
  15 snapshots.
  16
  17 SUBVOLUME AND SNAPSHOT
  18 ----------------------
  19
  20 A subvolume is a part of filesystem with its own and independent
  21 file/directory hierarchy. Subvolumes can share file extents. A snapshot is
  22 also subvolume, but with a given initial content of the original subvolume.
  23
  24 NOTE: A subvolume in btrfs is not like an LVM logical volume, which is
  25 block-level snapshot while btrfs subvolumes are file extent-based.
  26
  27 A subvolume looks like a normal directory, with some additional operations
  28 described below. Subvolumes can be renamed or moved, nesting subvolumes is not
  29 restricted but has some implications regarding snapshotting.
  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 * like a separately mounted filesystem (options 'subvol' or 'subvolid')
  35
  36 In the latter case the parent directory is not visible and accessible. This is
  37 similar to a bind mount, and in fact the subvolume mount does exactly that.
  38
  39 A freshly created filesystem is also a subvolume, called 'top-level',
  40 internally has an id 5. This subvolume cannot be removed or replaced by another
  41 subvolume. This is also the subvolume that will be mounted by default, unless
  42 the default subvolume has been changed (see subcommand 'set-default').
  43
  44 A snapshot is a subvolume like any other, with given initial content. By
  45 default, snapshots are created read-write. File modifications in a snapshot
  46 do not affect the files in the original subvolume.
  47
  48 SUBCOMMAND
  49 -----------
  50 *create* [-i <qgroupid>] [<dest>/]<name>::
  51 Create a subvolume <name> in <dest>.
  52 +
  53 If <dest> is not given, subvolume <name> will be created in the current
  54 directory.
  55 +
  56 `Options`
  57 +
  58 -i <qgroupid>::::
  59 Add the newly created subvolume to a qgroup. This option can be given multiple
  60 times.
  61
  62 *delete* [options] <subvolume> [<subvolume>...]::
  63 Delete the subvolume(s) from the filesystem.
  64 +
  65 If <subvolume> is not a subvolume, btrfs returns an error but continues if
  66 there are more arguments to process.
  67 +
  68 The corresponding directory is removed instantly but the data blocks are
  69 removed later in the background. The command returns immediatelly. See `btrfs
  70 subvolume sync` how to wait until the subvolume gets completely removed.
  71 +
  72 The deletion does not involve full transaction commit by default due to
  73 performance reasons.  As a consequence, the subvolume may appear again after a
  74 crash.  Use one of the '--commit' options to wait until the operation is
  75 safely stored on the device.
  76 +
  77 `Options`
  78 +
  79 -c|--commit-after::::
  80 wait for transaction commit at the end of the operation
  81 +
  82 -C|--commit-each::::
  83 wait for transaction commit after deleting each subvolume
  84
  85 *find-new* <subvolume> <last_gen>::
  86 List the recently modified files in a subvolume, after <last_gen> ID.
  87
  88 *get-default* <path>::
  89 Get the default subvolume of the filesystem <path>.
  90 +
  91 The output format is similar to *subvolume list* command.
  92
  93 *list* [options] [-G [\+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] <path>::
  94 List the subvolumes present in the filesystem <path>.
  95 +
  96 For every subvolume the following information is shown by default. +
  97 ID <ID> top level <ID> path <path> +
  98 where path is the relative path of the subvolume to the top level subvolume.
  99 The subvolume's ID may be used by the subvolume set-default command,
 100 or at mount time via the subvolid= option.
 101 If `-p` is given, then parent <ID> is added to the output between ID
 102 and top level. The parent's ID may be used at mount time via the
 103 `subvolrootid=` option.
 104 +
 105 `Options`
 106 +
 107 -p::::
 108 print parent ID.
 109 -a::::
 110 print all the subvolumes in the filesystem and distinguish between
 111 absolute and relative path with respect to the given <path>.
 112 -c::::
 113 print the ogeneration of the subvolume, aliases: ogen or origin generation.
 114 -g::::
 115 print the generation of the subvolume.
 116 -o::::
 117 print only subvolumes below specified <path>.
 118 -u::::
 119 print the UUID of the subvolume.
 120 -q::::
 121 print the parent uuid of subvolumes (and snapshots).
 122 -R::::
 123 print the UUID of the sent subvolume, where the subvolume is the result of a receive operation
 124 -t::::
 125 print the result as a table.
 126 -s::::
 127 only snapshot subvolumes in the filesystem will be listed.
 128 -r::::
 129 only readonly subvolumes in the filesystem will be listed.
 130 -G [+|-]<value>::::
 131 list subvolumes in the filesystem that its generation is
 132 >=, \<= or = value. \'\+' means >= value, \'-' means \<= value, If there is
 133 neither \'+' nor \'-', it means = value.
 134 -C [+|-]<value>::::
 135 list subvolumes in the filesystem that its ogeneration is
 136 >=, \<= or = value. The usage is the same to '-G' option.
 137 --sort=rootid,gen,ogen,path::::
 138 list subvolumes in order by specified items.
 139 you can add \'\+' or \'-' in front of each items, \'+' means ascending,
 140 \'-' means descending. The default is ascending.
 141 +
 142 for --sort you can combine some items together by \',', just like
 143 --sort=+ogen,-gen,path,rootid.
 144
 145 *set-default* [<subvolume>|<id> <path>]::
 146 Set the default subvolume of the (mounted) filesystem.
 147 +
 148 There are two ways how to specify the subvolume, by <id> or by the <subvolume>
 149 path.
 150 The id can be obtained from *btrfs subvolume list*, *btrfs subvolume show* or
 151 *btrfs inspect-internal rootid*.
 152
 153 *show* <path>::
 154 Show information of a given subvolume in the <path>.
 155
 156 *snapshot* [-r] <source> <dest>|[<dest>/]<name>::
 157 Create a snapshot of the subvolume <source> with the
 158 name <name> in the <dest> directory.
 159 +
 160 If only <dest> is given, the subvolume will be named the basename of <source>.
 161 If <source> is not a subvolume, btrfs returns an error.
 162 +
 163 `Options`
 164 +
 165 -r::::
 166 Make the new snapshot read only.
 167
 168 *sync* <path> [subvolid...]::
 169 Wait until given subvolume(s) are completely removed from the filesystem
 170 after deletion. If no subvolume id is given, wait until all current  deletion
 171 requests are completed, but do not wait for subvolumes deleted meanwhile.
 172 The status of subvolume ids is checked periodically.
 173 +
 174 `Options`
 175 +
 176 -s <N>::::
 177 sleep N seconds between checks (default: 1)
 178
 179 EXIT STATUS
 180 -----------
 181 *btrfs subvolume* returns a zero exit status if it succeeds. A non-zero value is
 182 returned in case of failure.
 183
 184 AVAILABILITY
 185 ------------
 186 *btrfs* is part of btrfs-progs.
 187 Please refer to the btrfs wiki http://btrfs.wiki.kernel.org for
 188 further details.
 189
 190 SEE ALSO
 191 --------
 192 `mkfs.btrfs`(8),
 193 `mount`(8),
 194 `btrfs-quota`(8),
 195 `btrfs-qgroup`(8),