various minor cleanups

[pve-docs.git] / local-zfs.adoc

diff --git a/local-zfs.adoc b/local-zfs.adoc
index ff602ed13503587c79353ae3150fe05a8182a61f..370bbc5c5327fe367b0f389457bc60d24948de37 100644 (file)
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -5,11 +5,11 @@ include::attributes.txt[]
 ZFS is a combined file system and logical volume manager designed by
 Sun Microsystems. Starting with {pve} 3.4, the native Linux
 kernel port of the ZFS file system is introduced as optional
 ZFS is a combined file system and logical volume manager designed by
 Sun Microsystems. Starting with {pve} 3.4, the native Linux
 kernel port of the ZFS file system is introduced as optional

-file-system and also as an additional selection for the root
-file-system. There is no need for manually compile ZFS modules - all
+file system and also as an additional selection for the root
+file system. There is no need for manually compile ZFS modules - all

 packages are included.
 
 packages are included.
 

-By using ZFS, its possible to achieve maximal enterprise features with
+By using ZFS, its possible to achieve maximum enterprise features with

 low budget hardware, but also high performance systems by leveraging
 SSD caching or even SSD only setups. ZFS can replace cost intense
 hardware raid cards by moderate CPU and memory load combined with easy
 low budget hardware, but also high performance systems by leveraging
 SSD caching or even SSD only setups. ZFS can replace cost intense
 hardware raid cards by moderate CPU and memory load combined with easy


@@ -23,7 +23,7 @@ management.
 
 * Protection against data corruption
 
 
 * Protection against data corruption
 

-* Data compression on file-system level
+* Data compression on file system level

 
 * Snapshots
 
 
 * Snapshots
 


@@ -61,18 +61,18 @@ If you use a dedicated cache and/or log disk, you should use a
 enterprise class SSD (e.g. Intel SSD DC S3700 Series). This can
 increase the overall performance significantly.
 
 enterprise class SSD (e.g. Intel SSD DC S3700 Series). This can
 increase the overall performance significantly.
 

-IMPORTANT: Do not use ZFS on top of hardware controller which has it's
+IMPORTANT: Do not use ZFS on top of hardware controller which has its

 own cache management. ZFS needs to directly communicate with disks. An
 HBA adapter is the way to go, or something like LSI controller flashed
 own cache management. ZFS needs to directly communicate with disks. An
 HBA adapter is the way to go, or something like LSI controller flashed

-in 'IT' mode.
+in ``IT'' mode.

 
 If you are experimenting with an installation of {pve} inside a VM
 
 If you are experimenting with an installation of {pve} inside a VM

-(Nested Virtualization), don't use 'virtio' for disks of that VM,
+(Nested Virtualization), don't use `virtio` for disks of that VM,

 since they are not supported by ZFS. Use IDE or SCSI instead (works
 since they are not supported by ZFS. Use IDE or SCSI instead (works

-also with 'virtio' SCSI controller type).
+also with `virtio` SCSI controller type).

 
 
 
 

-Installation as root file system
+Installation as Root File System

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When you install using the {pve} installer, you can choose ZFS for the
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When you install using the {pve} installer, you can choose ZFS for the


@@ -80,11 +80,11 @@ root file system. You need to select the RAID type at installation
 time:
 
 [horizontal]
 time:
 
 [horizontal]

-RAID0:: Also called 'striping'. The capacity of such volume is the sum
-of the capacity of all disks. But RAID0 does not add any redundancy,
+RAID0:: Also called ``striping''. The capacity of such volume is the sum
+of the capacities of all disks. But RAID0 does not add any redundancy,

 so the failure of a single drive makes the volume unusable.
 
 so the failure of a single drive makes the volume unusable.
 

-RAID1:: Also called mirroring. Data is written identically to all
+RAID1:: Also called ``mirroring''. Data is written identically to all

 disks. This mode requires at least 2 disks with the same size. The
 resulting capacity is that of a single disk.
 
 disks. This mode requires at least 2 disks with the same size. The
 resulting capacity is that of a single disk.
 


@@ -97,12 +97,12 @@ RAIDZ-2:: A variation on RAID-5, double parity. Requires at least 4 disks.
 RAIDZ-3:: A variation on RAID-5, triple parity. Requires at least 5 disks.
 
 The installer automatically partitions the disks, creates a ZFS pool
 RAIDZ-3:: A variation on RAID-5, triple parity. Requires at least 5 disks.
 
 The installer automatically partitions the disks, creates a ZFS pool

-called 'rpool', and installs the root file system on the ZFS subvolume
-'rpool/ROOT/pve-1'.
+called `rpool`, and installs the root file system on the ZFS subvolume
+`rpool/ROOT/pve-1`.

 
 

-Another subvolume called 'rpool/data' is created to store VM
+Another subvolume called `rpool/data` is created to store VM

 images. In order to use that with the {pve} tools, the installer
 images. In order to use that with the {pve} tools, the installer

-creates the following configuration entry in '/etc/pve/storage.cfg':
+creates the following configuration entry in `/etc/pve/storage.cfg`:

 
 ----
 zfspool: local-zfs
 
 ----
 zfspool: local-zfs


@@ -112,7 +112,7 @@ zfspool: local-zfs
 ----
 
 After installation, you can view your ZFS pool status using the
 ----
 
 After installation, you can view your ZFS pool status using the

-'zpool' command:
+`zpool` command:

 
 ----
 # zpool status
 
 ----
 # zpool status


@@ -133,7 +133,7 @@ config:
 errors: No known data errors
 ----
 
 errors: No known data errors
 ----
 

-The 'zfs' command is used configure and manage your ZFS file
+The `zfs` command is used configure and manage your ZFS file

 systems. The following command lists all file systems after
 installation:
 
 systems. The following command lists all file systems after
 installation:
 


@@ -158,7 +158,7 @@ GRUB boot loader there. If you use a redundant RAID setup, it installs
 the boot loader on all disk required for booting. So you can boot
 even if some disks fail.
 
 the boot loader on all disk required for booting. So you can boot
 even if some disks fail.
 

-NOTE: It is not possible to use ZFS as root partition with UEFI
+NOTE: It is not possible to use ZFS as root file system with UEFI

 boot.
 
 
 boot.
 
 


@@ -167,23 +167,23 @@ ZFS Administration
 
 This section gives you some usage examples for common tasks. ZFS
 itself is really powerful and provides many options. The main commands
 
 This section gives you some usage examples for common tasks. ZFS
 itself is really powerful and provides many options. The main commands

-to manage ZFS are 'zfs' and 'zpool'. Both commands comes with great
-manual pages, worth to read:
+to manage ZFS are `zfs` and `zpool`. Both commands come with great
+manual pages, which can be read with:

 
 ----
 # man zpool
 # man zfs
 -----
 
 
 ----
 # man zpool
 # man zfs
 -----
 

-.Create a new ZPool
+.Create a new zpool

 
 

-To create a new pool, at least one disk is needed. The 'ashift' should
-have the same sector-size (2 power of 'ashift') or larger as the
+To create a new pool, at least one disk is needed. The `ashift` should
+have the same sector-size (2 power of `ashift`) or larger as the

 underlying disk.
 
  zpool create -f -o ashift=12 <pool> <device>
 
 underlying disk.
 
  zpool create -f -o ashift=12 <pool> <device>
 

-To activate the compression 
+To activate compression

 
  zfs set compression=lz4 <pool>
 
 
  zfs set compression=lz4 <pool>
 


@@ -217,40 +217,40 @@ Minimum 4 Disks
 
  zpool create -f -o ashift=12 <pool> raidz2 <device1> <device2> <device3> <device4>
 
 
  zpool create -f -o ashift=12 <pool> raidz2 <device1> <device2> <device3> <device4>
 

-.Create a new pool with Cache (L2ARC)
+.Create a new pool with cache (L2ARC)

 
 It is possible to use a dedicated cache drive partition to increase
 the performance (use SSD).
 
 
 It is possible to use a dedicated cache drive partition to increase
 the performance (use SSD).
 

-As '<device>' it is possible to use more devices, like it's shown in
+As `<device>` it is possible to use more devices, like it's shown in

 "Create a new pool with RAID*".
 
  zpool create -f -o ashift=12 <pool> <device> cache <cache_device>
 
 "Create a new pool with RAID*".
 
  zpool create -f -o ashift=12 <pool> <device> cache <cache_device>
 

-.Create a new pool with Log (ZIL)
+.Create a new pool with log (ZIL)

 
 It is possible to use a dedicated cache drive partition to increase
 the performance(SSD).
 
 
 It is possible to use a dedicated cache drive partition to increase
 the performance(SSD).
 

-As '<device>' it is possible to use more devices, like it's shown in
+As `<device>` it is possible to use more devices, like it's shown in

 "Create a new pool with RAID*".
 
  zpool create -f -o ashift=12 <pool> <device> log <log_device>
 
 "Create a new pool with RAID*".
 
  zpool create -f -o ashift=12 <pool> <device> log <log_device>
 

-.Add Cache and Log to an existing pool
+.Add cache and log to an existing pool

 
 If you have an pool without cache and log. First partition the SSD in
 
 If you have an pool without cache and log. First partition the SSD in

-2 partition with parted or gdisk
+2 partition with `parted` or `gdisk`

 
 

-IMPORTANT: Always use GPT partition tables (gdisk or parted).
+IMPORTANT: Always use GPT partition tables.

 
 The maximum size of a log device should be about half the size of
 physical memory, so this is usually quite small. The rest of the SSD
 
 The maximum size of a log device should be about half the size of
 physical memory, so this is usually quite small. The rest of the SSD

-can be used to the cache.
+can be used as cache.

 
  zpool add -f <pool> log <device-part1> cache <device-part2> 
 
 
  zpool add -f <pool> log <device-part1> cache <device-part2> 
 

-.Changing a failed Device
+.Changing a failed device

 
  zpool replace -f <pool> <old device> <new-device>
 
 
  zpool replace -f <pool> <old device> <new-device>
 


@@ -259,36 +259,39 @@ Activate E-Mail Notification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ZFS comes with an event daemon, which monitors events generated by the
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ZFS comes with an event daemon, which monitors events generated by the

-ZFS kernel module. The daemon can also send E-Mails on ZFS event like
+ZFS kernel module. The daemon can also send emails on ZFS events like

 pool errors.
 
 pool errors.
 

-To activate the daemon it is necessary to edit /etc/zfs/zed.d/zed.rc with your favored editor, and uncomment the 'ZED_EMAIL_ADDR' setting:
+To activate the daemon it is necessary to edit `/etc/zfs/zed.d/zed.rc` with your
+favourite editor, and uncomment the `ZED_EMAIL_ADDR` setting:

 
 ZED_EMAIL_ADDR="root"
 
 
 ZED_EMAIL_ADDR="root"
 

-Please note {pve} forwards mails to 'root' to the email address
+Please note {pve} forwards mails to `root` to the email address

 configured for the root user.
 
 configured for the root user.
 

-IMPORTANT: the only settings that is required is ZED_EMAIL_ADDR. All
+IMPORTANT: The only setting that is required is `ZED_EMAIL_ADDR`. All

 other settings are optional.
 
 
 other settings are optional.
 
 

-Limit ZFS memory usage
+Limit ZFS Memory Usage

 ~~~~~~~~~~~~~~~~~~~~~~
 
 ~~~~~~~~~~~~~~~~~~~~~~
 

-It is good to use maximal 50 percent (which is the default) of the
+It is good to use at most 50 percent (which is the default) of the

 system memory for ZFS ARC to prevent performance shortage of the
 host. Use your preferred editor to change the configuration in
 system memory for ZFS ARC to prevent performance shortage of the
 host. Use your preferred editor to change the configuration in

-/etc/modprobe.d/zfs.conf and insert:
+`/etc/modprobe.d/zfs.conf` and insert:

 
 

- options zfs zfs_arc_max=8589934592
+--------
+options zfs zfs_arc_max=8589934592
+--------

 
 This example setting limits the usage to 8GB.
 
 [IMPORTANT]
 ====
 
 This example setting limits the usage to 8GB.
 
 [IMPORTANT]
 ====

-If your root fs is ZFS you must update your initramfs every
-time this value changes.
+If your root file system is ZFS you must update your initramfs every
+time this value changes:

 
  update-initramfs -u
 ====
 
  update-initramfs -u
 ====


@@ -302,16 +305,16 @@ to an external Storage.
 
 We strongly recommend to use enough memory, so that you normally do not
 run into low memory situations. Additionally, you can lower the
 
 We strongly recommend to use enough memory, so that you normally do not
 run into low memory situations. Additionally, you can lower the

-'swappiness' value. A good value for servers is 10:
+``swappiness'' value. A good value for servers is 10:

 
  sysctl -w vm.swappiness=10
 
 
  sysctl -w vm.swappiness=10
 

-To make the swappiness persistence, open '/etc/sysctl.conf' with
+To make the swappiness persistent, open `/etc/sysctl.conf` with

 an editor of your choice and add the following line:
 
  vm.swappiness = 10
 
 an editor of your choice and add the following line:
 
  vm.swappiness = 10
 

-.Linux Kernel 'swappiness' parameter values
+.Linux kernel `swappiness` parameter values

 [width="100%",cols="<m,2d",options="header"]
 |===========================================================
 | Value               | Strategy
 [width="100%",cols="<m,2d",options="header"]
 |===========================================================
 | Value               | Strategy