[pve-devel] [PATCH pve-docs v6] 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 | 44 +++++---------------------------------------
 pve-swap.adoc  | 35 +++++++++++++++++++++++++++++++++++
 sysadmin.adoc  |  2 ++
 3 files changed, 42 insertions(+), 39 deletions(-)
 create mode 100644 pve-swap.adoc

diff --git a/local-zfs.adoc b/local-zfs.adoc
index c64fb27..07adaf0 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -1,9 +1,6 @@
 [[chapter_zfs]]
 ZFS on Linux
 ------------
-ifdef::wiki[]
-:pve-toplevel:
-endif::wiki[]
 
 ZFS is a combined file system and logical volume manager designed by
 Sun Microsystems. Starting with {pve} 3.4, the native Linux
@@ -622,46 +619,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.adoc b/pve-swap.adoc
new file mode 100644
index 0000000..6bc62b0
--- /dev/null
+++ b/pve-swap.adoc
@@ -0,0 +1,35 @@
+[[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..5b12634 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.adoc[]
+
 include::local-lvm.adoc[]
 
 include::local-zfs.adoc[]
-- 
2.39.5