]>
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 | ||
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. |