]>
Commit | Line | Data |
---|---|---|
ea856d57 WB |
1 | [[chapter_btrfs]] |
2 | BTRFS | |
3 | ----- | |
4 | ifdef::wiki[] | |
5 | :pve-toplevel: | |
6 | endif::wiki[] | |
7 | ||
d9bfc251 TL |
8 | WARNING: BTRFS integration is currently a **technology preview** in {pve}. |
9 | ||
ea856d57 WB |
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 | ||
8dcb70bb TL |
98 | Create a BTRFS file system on a single disk `/dev/sdb` with the label |
99 | `My-Storage`: | |
ea856d57 WB |
100 | |
101 | ---- | |
8dcb70bb | 102 | # mkfs.btrfs -m single -d single -L My-Storage /dev/sdb |
ea856d57 WB |
103 | ---- |
104 | ||
8dcb70bb | 105 | Or create a RAID1 on the two partitions `/dev/sdb1` and `/dev/sdc1`: |
ea856d57 WB |
106 | |
107 | ---- | |
108 | # mkfs.btrfs -m raid1 -d raid1 -L My-Storage /dev/sdb1 /dev/sdc1 | |
109 | ---- | |
110 | ||
8dcb70bb TL |
111 | Mounting a BTRFS file system |
112 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
ea856d57 | 113 | |
8dcb70bb | 114 | The new file-system can then be mounted either manually, for example: |
ea856d57 WB |
115 | |
116 | ---- | |
117 | # mkdir /my-storage | |
8dcb70bb TL |
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 | |
ea856d57 | 143 | ---- |
8dcb70bb | 144 | After the next reboot this will be automatically done by the system at boot. |
ea856d57 | 145 | |
b039a463 TL |
146 | Adding a BTRFS file system to {pve} |
147 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
148 | ||
e2b3622a | 149 | You can add an existing BTRFS file system to {pve} via the web interface, or |
b039a463 TL |
150 | using the CLI, for example: |
151 | ||
152 | ---- | |
153 | pvesm add btrfs my-storage --path /my-storage | |
154 | ---- | |
155 | ||
ea856d57 WB |
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. | |
00271f41 TL |
217 | |
218 | Checking Space Usage | |
219 | ^^^^^^^^^^^^^^^^^^^^ | |
220 | ||
221 | The classic `df` tool may output confusing values for some btrfs setups. | |
222 | For a better estimate use the `btrfs filesystem usage /PATH` command, for example: | |
223 | ||
224 | ---- | |
225 | # btrfs fi usage /my-storage | |
226 | ---- |