use listings for file contents
[pve-docs.git] / local-zfs.adoc
CommitLineData
9ee94323
DM
1ZFS on Linux
2------------
3include::attributes.txt[]
4
5ZFS is a combined file system and logical volume manager designed by
6Sun Microsystems. Starting with {pve} 3.4, the native Linux
7kernel port of the ZFS file system is introduced as optional
5eba0743
FG
8file system and also as an additional selection for the root
9file system. There is no need for manually compile ZFS modules - all
9ee94323
DM
10packages are included.
11
5eba0743 12By using ZFS, its possible to achieve maximum enterprise features with
9ee94323
DM
13low budget hardware, but also high performance systems by leveraging
14SSD caching or even SSD only setups. ZFS can replace cost intense
15hardware raid cards by moderate CPU and memory load combined with easy
16management.
17
18.General ZFS advantages
19
20* Easy configuration and management with {pve} GUI and CLI.
21
22* Reliable
23
24* Protection against data corruption
25
5eba0743 26* Data compression on file system level
9ee94323
DM
27
28* Snapshots
29
30* Copy-on-write clone
31
32* Various raid levels: RAID0, RAID1, RAID10, RAIDZ-1, RAIDZ-2 and RAIDZ-3
33
34* Can use SSD for cache
35
36* Self healing
37
38* Continuous integrity checking
39
40* Designed for high storage capacities
41
42* Protection against data corruption
43
44* Asynchronous replication over network
45
46* Open Source
47
48* Encryption
49
50* ...
51
52
53Hardware
54~~~~~~~~
55
56ZFS depends heavily on memory, so you need at least 8GB to start. In
57practice, use as much you can get for your hardware/budget. To prevent
58data corruption, we recommend the use of high quality ECC RAM.
59
60If you use a dedicated cache and/or log disk, you should use a
61enterprise class SSD (e.g. Intel SSD DC S3700 Series). This can
62increase the overall performance significantly.
63
5eba0743 64IMPORTANT: Do not use ZFS on top of hardware controller which has its
9ee94323
DM
65own cache management. ZFS needs to directly communicate with disks. An
66HBA adapter is the way to go, or something like LSI controller flashed
8c1189b6 67in ``IT'' mode.
9ee94323
DM
68
69If you are experimenting with an installation of {pve} inside a VM
8c1189b6 70(Nested Virtualization), don't use `virtio` for disks of that VM,
9ee94323 71since they are not supported by ZFS. Use IDE or SCSI instead (works
8c1189b6 72also with `virtio` SCSI controller type).
9ee94323
DM
73
74
5eba0743 75Installation as Root File System
9ee94323
DM
76~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77
78When you install using the {pve} installer, you can choose ZFS for the
79root file system. You need to select the RAID type at installation
80time:
81
82[horizontal]
8c1189b6
FG
83RAID0:: Also called ``striping''. The capacity of such volume is the sum
84of the capacities of all disks. But RAID0 does not add any redundancy,
9ee94323
DM
85so the failure of a single drive makes the volume unusable.
86
8c1189b6 87RAID1:: Also called ``mirroring''. Data is written identically to all
9ee94323
DM
88disks. This mode requires at least 2 disks with the same size. The
89resulting capacity is that of a single disk.
90
91RAID10:: A combination of RAID0 and RAID1. Requires at least 4 disks.
92
93RAIDZ-1:: A variation on RAID-5, single parity. Requires at least 3 disks.
94
95RAIDZ-2:: A variation on RAID-5, double parity. Requires at least 4 disks.
96
97RAIDZ-3:: A variation on RAID-5, triple parity. Requires at least 5 disks.
98
99The installer automatically partitions the disks, creates a ZFS pool
8c1189b6
FG
100called `rpool`, and installs the root file system on the ZFS subvolume
101`rpool/ROOT/pve-1`.
9ee94323 102
8c1189b6 103Another subvolume called `rpool/data` is created to store VM
9ee94323 104images. In order to use that with the {pve} tools, the installer
8c1189b6 105creates the following configuration entry in `/etc/pve/storage.cfg`:
9ee94323
DM
106
107----
108zfspool: local-zfs
109 pool rpool/data
110 sparse
111 content images,rootdir
112----
113
114After installation, you can view your ZFS pool status using the
8c1189b6 115`zpool` command:
9ee94323
DM
116
117----
118# zpool status
119 pool: rpool
120 state: ONLINE
121 scan: none requested
122config:
123
124 NAME STATE READ WRITE CKSUM
125 rpool ONLINE 0 0 0
126 mirror-0 ONLINE 0 0 0
127 sda2 ONLINE 0 0 0
128 sdb2 ONLINE 0 0 0
129 mirror-1 ONLINE 0 0 0
130 sdc ONLINE 0 0 0
131 sdd ONLINE 0 0 0
132
133errors: No known data errors
134----
135
8c1189b6 136The `zfs` command is used configure and manage your ZFS file
9ee94323
DM
137systems. The following command lists all file systems after
138installation:
139
140----
141# zfs list
142NAME USED AVAIL REFER MOUNTPOINT
143rpool 4.94G 7.68T 96K /rpool
144rpool/ROOT 702M 7.68T 96K /rpool/ROOT
145rpool/ROOT/pve-1 702M 7.68T 702M /
146rpool/data 96K 7.68T 96K /rpool/data
147rpool/swap 4.25G 7.69T 64K -
148----
149
150
151Bootloader
152~~~~~~~~~~
153
154The default ZFS disk partitioning scheme does not use the first 2048
155sectors. This gives enough room to install a GRUB boot partition. The
156{pve} installer automatically allocates that space, and installs the
157GRUB boot loader there. If you use a redundant RAID setup, it installs
158the boot loader on all disk required for booting. So you can boot
159even if some disks fail.
160
e300cf7d 161NOTE: It is not possible to use ZFS as root file system with UEFI
9ee94323
DM
162boot.
163
164
165ZFS Administration
166~~~~~~~~~~~~~~~~~~
167
168This section gives you some usage examples for common tasks. ZFS
169itself is really powerful and provides many options. The main commands
8c1189b6
FG
170to manage ZFS are `zfs` and `zpool`. Both commands come with great
171manual pages, which can be read with:
9ee94323
DM
172
173----
174# man zpool
175# man zfs
176-----
177
5eba0743 178.Create a new zpool
9ee94323 179
8c1189b6
FG
180To create a new pool, at least one disk is needed. The `ashift` should
181have the same sector-size (2 power of `ashift`) or larger as the
9ee94323
DM
182underlying disk.
183
184 zpool create -f -o ashift=12 <pool> <device>
185
5eba0743 186To activate compression
9ee94323
DM
187
188 zfs set compression=lz4 <pool>
189
190.Create a new pool with RAID-0
191
192Minimum 1 Disk
193
194 zpool create -f -o ashift=12 <pool> <device1> <device2>
195
196.Create a new pool with RAID-1
197
198Minimum 2 Disks
199
200 zpool create -f -o ashift=12 <pool> mirror <device1> <device2>
201
202.Create a new pool with RAID-10
203
204Minimum 4 Disks
205
206 zpool create -f -o ashift=12 <pool> mirror <device1> <device2> mirror <device3> <device4>
207
208.Create a new pool with RAIDZ-1
209
210Minimum 3 Disks
211
212 zpool create -f -o ashift=12 <pool> raidz1 <device1> <device2> <device3>
213
214.Create a new pool with RAIDZ-2
215
216Minimum 4 Disks
217
218 zpool create -f -o ashift=12 <pool> raidz2 <device1> <device2> <device3> <device4>
219
5eba0743 220.Create a new pool with cache (L2ARC)
9ee94323
DM
221
222It is possible to use a dedicated cache drive partition to increase
223the performance (use SSD).
224
8c1189b6 225As `<device>` it is possible to use more devices, like it's shown in
9ee94323
DM
226"Create a new pool with RAID*".
227
228 zpool create -f -o ashift=12 <pool> <device> cache <cache_device>
229
5eba0743 230.Create a new pool with log (ZIL)
9ee94323
DM
231
232It is possible to use a dedicated cache drive partition to increase
233the performance(SSD).
234
8c1189b6 235As `<device>` it is possible to use more devices, like it's shown in
9ee94323
DM
236"Create a new pool with RAID*".
237
238 zpool create -f -o ashift=12 <pool> <device> log <log_device>
239
5eba0743 240.Add cache and log to an existing pool
9ee94323
DM
241
242If you have an pool without cache and log. First partition the SSD in
8c1189b6 2432 partition with `parted` or `gdisk`
9ee94323 244
e300cf7d 245IMPORTANT: Always use GPT partition tables.
9ee94323
DM
246
247The maximum size of a log device should be about half the size of
248physical memory, so this is usually quite small. The rest of the SSD
5eba0743 249can be used as cache.
9ee94323
DM
250
251 zpool add -f <pool> log <device-part1> cache <device-part2>
252
5eba0743 253.Changing a failed device
9ee94323
DM
254
255 zpool replace -f <pool> <old device> <new-device>
256
257
258Activate E-Mail Notification
259~~~~~~~~~~~~~~~~~~~~~~~~~~~~
260
261ZFS comes with an event daemon, which monitors events generated by the
5eba0743 262ZFS kernel module. The daemon can also send emails on ZFS events like
9ee94323
DM
263pool errors.
264
8c1189b6
FG
265To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
266favourite editor, and uncomment the `ZED_EMAIL_ADDR` setting:
9ee94323 267
083adc34 268--------
9ee94323 269ZED_EMAIL_ADDR="root"
083adc34 270--------
9ee94323 271
8c1189b6 272Please note {pve} forwards mails to `root` to the email address
9ee94323
DM
273configured for the root user.
274
8c1189b6 275IMPORTANT: The only setting that is required is `ZED_EMAIL_ADDR`. All
9ee94323
DM
276other settings are optional.
277
278
5eba0743 279Limit ZFS Memory Usage
9ee94323
DM
280~~~~~~~~~~~~~~~~~~~~~~
281
5eba0743 282It is good to use at most 50 percent (which is the default) of the
d362b7f4
DM
283system memory for ZFS ARC to prevent performance shortage of the
284host. Use your preferred editor to change the configuration in
8c1189b6 285`/etc/modprobe.d/zfs.conf` and insert:
9ee94323 286
5eba0743
FG
287--------
288options zfs zfs_arc_max=8589934592
289--------
9ee94323
DM
290
291This example setting limits the usage to 8GB.
292
293[IMPORTANT]
294====
5eba0743
FG
295If your root file system is ZFS you must update your initramfs every
296time this value changes:
9ee94323
DM
297
298 update-initramfs -u
299====
300
301
302.SWAP on ZFS
303
304SWAP on ZFS on Linux may generate some troubles, like blocking the
305server or generating a high IO load, often seen when starting a Backup
306to an external Storage.
307
308We strongly recommend to use enough memory, so that you normally do not
309run into low memory situations. Additionally, you can lower the
8c1189b6 310``swappiness'' value. A good value for servers is 10:
9ee94323
DM
311
312 sysctl -w vm.swappiness=10
313
8c1189b6 314To make the swappiness persistent, open `/etc/sysctl.conf` with
9ee94323
DM
315an editor of your choice and add the following line:
316
083adc34
FG
317--------
318vm.swappiness = 10
319--------
9ee94323 320
8c1189b6 321.Linux kernel `swappiness` parameter values
9ee94323
DM
322[width="100%",cols="<m,2d",options="header"]
323|===========================================================
324| Value | Strategy
325| vm.swappiness = 0 | The kernel will swap only to avoid
326an 'out of memory' condition
327| vm.swappiness = 1 | Minimum amount of swapping without
328disabling it entirely.
329| vm.swappiness = 10 | This value is sometimes recommended to
330improve performance when sufficient memory exists in a system.
331| vm.swappiness = 60 | The default value.
332| vm.swappiness = 100 | The kernel will swap aggressively.
333|===========================================================