[pve-devel] [PATCH pve-docs v5] fix #5644: Moved the swap partition section

[Alexander Abraham]

The section about "Creating SWAP partitions" lives in its own
file and the warning about creating SWAP partitions on ZFS was
moved back to the original file with all documentation about
working with ZVols.

Signed-off-by: Alexander Abraham <a.abraham at proxmox.com>
---
 local-zfs.adoc       | 42 ++++++----------------------------------
 pve-swap-on-zfs.adoc | 46 ++++++++++++++++++++++++++++++++++++++++++++
 pve-swap.adoc        | 36 ++++++++++++++++++++++++++++++++++
 sysadmin.adoc        |  2 ++
 4 files changed, 90 insertions(+), 36 deletions(-)
 create mode 100644 pve-swap-on-zfs.adoc
 create mode 100644 pve-swap.adoc

diff --git a/local-zfs.adoc b/local-zfs.adoc
index c64fb27..77d1055 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -1,6 +1,7 @@
 [[chapter_zfs]]
 ZFS on Linux
 ------------
+
 ifdef::wiki[]
 :pve-toplevel:
 endif::wiki[]
@@ -622,46 +623,15 @@ time this value changes:
 You *must reboot* to activate these changes.
 ====
 
-
 [[zfs_swap]]
 SWAP on ZFS
 ~~~~~~~~~~~
 
-Swap-space created on a zvol may generate some troubles, like blocking the
-server or generating a high IO load, often seen when starting a Backup
-to an external Storage.
-
-We strongly recommend to use enough memory, so that you normally do not
-run into low memory situations. Should you need or want to add swap, it is
-preferred to create a partition on a physical disk and use it as a swap device.
-You can leave some space free for this purpose in the advanced options of the
-installer. Additionally, you can lower the
-``swappiness'' value. A good value for servers is 10:
-
-----
-# sysctl -w vm.swappiness=10
-----
-
-To make the swappiness persistent, open `/etc/sysctl.conf` with
-an editor of your choice and add the following line:
-
---------
-vm.swappiness = 10
---------
-
-.Linux kernel `swappiness` parameter values
-[width="100%",cols="<m,2d",options="header"]
-|===========================================================
-| Value               | Strategy
-| vm.swappiness = 0   | The kernel will swap only to avoid
-an 'out of memory' condition
-| vm.swappiness = 1   | Minimum amount of swapping without
-disabling it entirely.
-| vm.swappiness = 10  | This value is sometimes recommended to
-improve performance when sufficient memory exists in a system.
-| vm.swappiness = 60  | The default value.
-| vm.swappiness = 100 | The kernel will swap aggressively.
-|===========================================================
+Do not use a ZFS volume for creating a swap
+partition because this could lead to deadlocks. These deadlocks could
+cause the affected system to freeze. The OpenZFS documentation
+footnote:[https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#using-a-zvol-for-a-swap-device-on-linux]
+warns about using a ZFS volume for creating a swap partition.
 
 [[zfs_encryption]]
 Encrypted ZFS Datasets
diff --git a/pve-swap-on-zfs.adoc b/pve-swap-on-zfs.adoc
new file mode 100644
index 0000000..aec3a70
--- /dev/null
+++ b/pve-swap-on-zfs.adoc
@@ -0,0 +1,46 @@
+[[zfs_swap]]
+SWAP on ZFS
+-----------
+
+It is strongly recommended to not use a ZFS volume for creating a swap 
+partition because this could lead to deadlocks. These deadlocks could 
+cause the affected system to freeze. The OpenZFS documentation 
+footnote:[https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#using-a-zvol-for-a-swap-device-on-linux]
+warns about using a ZFS volume for creating a swap partition.
+
+[[creating_swap_partitions]]
+Creating SWAP Partitions
+------------------------
+
+We strongly recommend to use enough memory, so that you normally do not
+run into low memory situations. Should you need or want to add swap, it is
+preferred to create a partition on a physical disk and use it as a swap device.
+You can leave some space free for this purpose in the advanced options of the
+installer. Additionally, you can lower the
+``swappiness'' value. A good value for servers is 10: 
+
+----
+# sysctl -w vm.swappiness=10
+----
+
+To make the swappiness persistent, open `/etc/sysctl.conf` with
+an editor of your choice and add the following line:
+
+--------
+vm.swappiness = 10
+--------
+
+.Linux kernel `swappiness` parameter values
+[width="100%",cols="<m,2d",options="header"]
+|===========================================================
+| Value               | Strategy
+| vm.swappiness = 0   | The kernel will swap only to avoid
+an 'out of memory' condition
+| vm.swappiness = 1   | Minimum amount of swapping without
+disabling it entirely.
+| vm.swappiness = 10  | This value is sometimes recommended to
+improve performance when sufficient memory exists in a system.
+| vm.swappiness = 60  | The default value.
+| vm.swappiness = 100 | The kernel will swap aggressively.
+|===========================================================
+
diff --git a/pve-swap.adoc b/pve-swap.adoc
new file mode 100644
index 0000000..6aac186
--- /dev/null
+++ b/pve-swap.adoc
@@ -0,0 +1,36 @@
+[[creating_swap_partitions]]
+Creating SWAP Partitions
+------------------------
+
+We strongly recommend to use enough memory, so that you normally do not
+run into low memory situations. Should you need or want to add swap, it is
+preferred to create a partition on a physical disk and use it as a swap device.
+You can leave some space free for this purpose in the advanced options of the
+installer. Additionally, you can lower the
+``swappiness'' value. A good value for servers is 10:
+
+----
+# sysctl -w vm.swappiness=10
+----
+
+To make the swappiness persistent, open `/etc/sysctl.conf` with
+an editor of your choice and add the following line:
+
+--------
+vm.swappiness = 10
+--------
+
+.Linux kernel `swappiness` parameter values
+[width="100%",cols="<m,2d",options="header"]
+|===========================================================
+| Value               | Strategy
+| vm.swappiness = 0   | The kernel will swap only to avoid
+an 'out of memory' condition
+| vm.swappiness = 1   | Minimum amount of swapping without
+disabling it entirely.
+| vm.swappiness = 10  | This value is sometimes recommended to
+improve performance when sufficient memory exists in a system.
+| vm.swappiness = 60  | The default value.
+| vm.swappiness = 100 | The kernel will swap aggressively.
+|===========================================================
+
diff --git a/sysadmin.adoc b/sysadmin.adoc
index dd43f73..9b2db52 100644
--- a/sysadmin.adoc
+++ b/sysadmin.adoc
@@ -71,6 +71,8 @@ include::pve-external-metric-server.adoc[]
 
 include::pve-disk-health-monitoring.adoc[]
 
+include::pve-swap-on-zfs.adoc[]
+
 include::local-lvm.adoc[]
 
 include::local-zfs.adoc[]
-- 
2.39.5