vzdump: remove usage examples involving 'notification-{target, policy}'
[pve-docs.git] / 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.