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 `/dev/sdb1`
  99
 100 ----
 101  # mkfs.btrfs -m single -d single -L My-Storage /dev/sdb1
 102 ----
 103
 104 Or create a RAID1 on `/dev/sdb1` and `/dev/sdc1`
 105
 106 ----
 107  # mkfs.btrfs -m raid1 -d raid1 -L My-Storage /dev/sdb1 /dev/sdc1
 108 ----
 109
 110 This can then be mounted or used in `/etc/fstab` like any other mount point.
 111
 112 For example
 113
 114 ----
 115  # mkdir /my-storage
 116  # mount /dev/sdb1 /my-storage
 117 ----
 118
 119 Creating a subvolume
 120 ^^^^^^^^^^^^^^^^^^^^
 121
 122 Creating a subvolume links it to a path in the btrfs file system, where it will
 123 appear as a regular directory.
 124
 125 ----
 126 # btrfs subvolume create /some/path
 127 ----
 128
 129 Afterwards `/some/path` will act like a regular directory.
 130
 131 Deleting a subvolume
 132 ^^^^^^^^^^^^^^^^^^^^
 133
 134 Contrary to directories removed via `rmdir`, subvolumes do not need to be empty
 135 in order to be deleted via the `btrfs` command.
 136
 137 ----
 138 # btrfs subvolume delete /some/path
 139 ----
 140
 141 Creating a snapshot of a subvolume
 142 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 143
 144 BTRFS does not actually distinguish between snapshots and normal subvolumes, so
 145 taking a snapshot can also be seen as creating an arbitrary copy of a subvolume.
 146 By convention, {pve} will use the read-only flag when creating snapshots of
 147 guest disks or subvolumes, but this flag can also be changed later on.
 148
 149 ----
 150 # btrfs subvolume snapshot -r /some/path /a/new/path
 151 ----
 152
 153 This will create a read-only "clone" of the subvolume on `/some/path` at
 154 `/a/new/path`. Any future modifications to `/some/path` cause the modified data
 155 to be copied before modification.
 156
 157 If the read-only (`-r`) option is left out, both subvolumes will be writable.
 158
 159 Enabling compression
 160 ^^^^^^^^^^^^^^^^^^^^
 161
 162 By default, BTRFS does not compress data. To enable compression, the `compress`
 163 mount option can be added. Note that data already written will not be compressed
 164 after the fact.
 165
 166 By default, the rootfs will be listed in `/etc/fstab` as follows:
 167
 168 ----
 169 UUID=<uuid of your root file system> / btrfs defaults 0 1
 170 ----
 171
 172 You can simply append `compress=zstd`, `compress=lzo`, or `compress=zlib` to the
 173 `defaults` above like so:
 174
 175 ----
 176 UUID=<uuid of your root file system> / btrfs defaults,compress=zstd 0 1
 177 ----
 178
 179 This change will take effect after rebooting.