local-btrfs.adoc

   1 [[chapter_btrfs]]
   2 BTRFS
   3 -----
   4 ifdef::wiki[]
   5 :pve-toplevel:
   6 endif::wiki[]
   7
   8 WARNING: BTRFS integration is currently a **technology preview** in {pve}.
   9
  10 BTRFS is a modern copy on write file system natively supported by the Linux
  11 kernel, implementing features such as snapshots, built-in RAID and self healing
  12 via checksums for data and metadata. Starting with {pve} 7.0, BTRFS is
  13 introduced as optional selection for the root file system.
  14
  15 .General BTRFS advantages
  16
  17 * Main system setup almost identical to the traditional ext4 based setup
  18
  19 * Snapshots
  20
  21 * Data compression on file system level
  22
  23 * Copy-on-write clone
  24
  25 * RAID0, RAID1 and RAID10
  26
  27 * Protection against data corruption
  28
  29 * Self healing
  30
  31 * natively supported by the Linux kernel
  32
  33 * ...
  34
  35 .Caveats
  36
  37 * RAID levels 5/6 are experimental and dangerous
  38
  39 Installation as Root File System
  40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  41
  42 When you install using the {pve} installer, you can choose BTRFS for the root
  43 file system. You need to select the RAID type at installation time:
  44
  45 [horizontal]
  46 RAID0:: Also called ``striping''. The capacity of such volume is the sum
  47 of the capacities of all disks. But RAID0 does not add any redundancy,
  48 so the failure of a single drive makes the volume unusable.
  49
  50 RAID1:: Also called ``mirroring''. Data is written identically to all
  51 disks. This mode requires at least 2 disks with the same size. The
  52 resulting capacity is that of a single disk.
  53
  54 RAID10:: A combination of RAID0 and RAID1. Requires at least 4 disks.
  55
  56 The installer automatically partitions the disks and creates an additional
  57 subvolume at `/var/lib/pve/local-btrfs`.  In order to use that with the {pve}
  58 tools, the installer creates the following configuration entry in
  59 `/etc/pve/storage.cfg`:
  60
  61 ----
  62 dir: local
  63         path /var/lib/vz
  64         content iso,vztmpl,backup
  65         disable
  66
  67 btrfs: local-btrfs
  68         path /var/lib/pve/local-btrfs
  69         content iso,vztmpl,backup,images,rootdir
  70 ----
  71
  72 This explicitly disables the default `local` storage in favor of a btrfs
  73 specific storage entry on the additional subvolume.
  74
  75 The `btrfs` command is used to configure and manage the btrfs file system,
  76 After the installation, the following command lists all additional subvolumes:
  77
  78 ----
  79 # btrfs subvolume list /
  80 ID 256 gen 6 top level 5 path var/lib/pve/local-btrfs
  81 ----
  82
  83 BTRFS Administration
  84 ~~~~~~~~~~~~~~~~~~~~
  85
  86 This section gives you some usage examples for common tasks.
  87
  88 Creating a BTRFS file system
  89 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  90
  91 To create BTRFS file systems, `mkfs.btrfs` is used. The `-d` and `-m` parameters
  92 are used to set the profile for metadata and data respectively. With the
  93 optional `-L` parameter, a label can be set.
  94
  95 Generally, the following modes are supported: `single`, `raid0`, `raid1`,
  96 `raid10`.
  97
  98 Create a BTRFS file system on a single disk `/dev/sdb` with the label
  99 `My-Storage`:
 100
 101 ----
 102  # mkfs.btrfs -m single -d single -L My-Storage /dev/sdb
 103 ----
 104
 105 Or create a RAID1 on the two partitions `/dev/sdb1` and `/dev/sdc1`:
 106
 107 ----
 108  # mkfs.btrfs -m raid1 -d raid1 -L My-Storage /dev/sdb1 /dev/sdc1
 109 ----
 110
 111 Mounting a BTRFS file system
 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 113
 114 The new file-system can then be mounted either manually, for example:
 115
 116 ----
 117  # mkdir /my-storage
 118  # mount /dev/sdb /my-storage
 119 ----
 120
 121 A BTRFS can also be added to `/etc/fstab` like any other mount point,
 122 automatically mounting it on boot. It's recommended to avoid  using
 123 block-device paths but use the `UUID` value the `mkfs.btrfs` command printed,
 124 especially there is more than one disk in a BTRFS setup.
 125
 126 For example:
 127
 128 .File `/etc/fstab`
 129 ----
 130 # ... other mount points left out for brevity
 131
 132 # using the UUID from the mkfs.btrfs output is highly recommended
 133 UUID=e2c0c3ff-2114-4f54-b767-3a203e49f6f3 /my-storage btrfs defaults 0 0
 134 ----
 135
 136 TIP: If you do not have the UUID available anymore you can use the `blkid` tool
 137  to list all properties of block-devices.
 138
 139 Afterwards you can trigger the first mount by executing:
 140
 141 ----
 142 mount /my-storage
 143 ----
 144 After the next reboot this will be automatically done by the system at boot.
 145
 146 Adding a BTRFS file system to {pve}
 147 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 148
 149 You can add an existing BTRFS file system to {pve} via the web-interface, or
 150 using the CLI, for example:
 151
 152 ----
 153 pvesm add btrfs my-storage --path /my-storage
 154 ----
 155
 156 Creating a subvolume
 157 ^^^^^^^^^^^^^^^^^^^^
 158
 159 Creating a subvolume links it to a path in the btrfs file system, where it will
 160 appear as a regular directory.
 161
 162 ----
 163 # btrfs subvolume create /some/path
 164 ----
 165
 166 Afterwards `/some/path` will act like a regular directory.
 167
 168 Deleting a subvolume
 169 ^^^^^^^^^^^^^^^^^^^^
 170
 171 Contrary to directories removed via `rmdir`, subvolumes do not need to be empty
 172 in order to be deleted via the `btrfs` command.
 173
 174 ----
 175 # btrfs subvolume delete /some/path
 176 ----
 177
 178 Creating a snapshot of a subvolume
 179 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 180
 181 BTRFS does not actually distinguish between snapshots and normal subvolumes, so
 182 taking a snapshot can also be seen as creating an arbitrary copy of a subvolume.
 183 By convention, {pve} will use the read-only flag when creating snapshots of
 184 guest disks or subvolumes, but this flag can also be changed later on.
 185
 186 ----
 187 # btrfs subvolume snapshot -r /some/path /a/new/path
 188 ----
 189
 190 This will create a read-only "clone" of the subvolume on `/some/path` at
 191 `/a/new/path`. Any future modifications to `/some/path` cause the modified data
 192 to be copied before modification.
 193
 194 If the read-only (`-r`) option is left out, both subvolumes will be writable.
 195
 196 Enabling compression
 197 ^^^^^^^^^^^^^^^^^^^^
 198
 199 By default, BTRFS does not compress data. To enable compression, the `compress`
 200 mount option can be added. Note that data already written will not be compressed
 201 after the fact.
 202
 203 By default, the rootfs will be listed in `/etc/fstab` as follows:
 204
 205 ----
 206 UUID=<uuid of your root file system> / btrfs defaults 0 1
 207 ----
 208
 209 You can simply append `compress=zstd`, `compress=lzo`, or `compress=zlib` to the
 210 `defaults` above like so:
 211
 212 ----
 213 UUID=<uuid of your root file system> / btrfs defaults,compress=zstd 0 1
 214 ----
 215
 216 This change will take effect after rebooting.