local-btrfs.adoc

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