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

[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@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



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

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

[Fiona Ebner]

Please use present tense in the commit title/subject like is customary
in Proxmox VE development.

Am 27.05.25 um 14:39 schrieb 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.

Tip: try to write the commit message with the perspective of a future
reader in mind. I.e. somebody who stumbles upon this patch in the future
and wants to understand the changes and why the changes were made.

Then you will quickly notice that the part about "moving the warning for
ZFS" is wrong. This patch here does not move the warning at all, it
re-phrases it and adds a reference.

> 
> Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>
> ---

Meta-information for reviewers should go here, e.g. the changelog
between patch revisions:

Changes in v6:
* Keep ZFS warning in its original file.
* etc.

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

This hunk should not be there. Please re-read/spot check your diffs for
such things before sending patches.

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

This line removal also seems unrelated to the actual change.

>  [[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

Already stated in the review of v5: there is a line-break much earlier
than it needs to be. Please use the full 80 column width like the rest
of the file does.

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

Hope you're not getting tired of these reviews, because it might seem
overkill for such small changes. And sure, I could've gone with an
earlier revision already, manually fixing things up while applying, but
the point is that you learn about these things, so that you get used to
the workflow and have an easier time in the future.


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel