[pve-devel] [PATCH pve-docs v8] fix #5644: Moved the section on swap partitions

[pve-devel] [PATCH pve-docs v8] fix #5644: Moved the section on swap partitions

[Alexander Abraham]

The section on running swap on ZFS was split into two parts.
The part describing setting the swappiness level was moved to a
separate file and the part about creating swap partitions on a ZFS
volume was replaced with a warning about doing so.

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

---

Changes in v8:
* Moved the changelog below the three dashes.

Changes in v7:
* Keep ZFS warning in its original file.
* Corrected some formatting errors.

 local-zfs.adoc | 49 ++++++++++---------------------------------------
 pve-swap.adoc  | 35 +++++++++++++++++++++++++++++++++++
 sysadmin.adoc  |  2 ++
 3 files changed, 47 insertions(+), 39 deletions(-)
 create mode 100644 pve-swap.adoc

diff --git a/local-zfs.adoc b/local-zfs.adoc
index c64fb27..bfd2295 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -1,9 +1,10 @@
 [[chapter_zfs]]
 ZFS on Linux
 ------------
-ifdef::wiki[]
-:pve-toplevel:
-endif::wiki[]
+
+-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
@@ -620,48 +621,18 @@ 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 v8] fix #5644: Moved the section on swap partitions

[Christoph Heiss]

Please take earlier review comments into account. To quote Fiona from
v6:

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

Commit messages are always present tense, as the commit/patch itself
_changes_ something, but it _hasn't _changed before_ the commit.

Also, this does more than just moving the section, as it inserts a new
paragraph w.r.t. swap on zfs. I'd separate the local-zfs.adoc changes in
a separate patch, as it doesn't have much to do with the section move
itself.

On Tue Jun 3, 2025 at 3:12 PM CEST, Alexander Abraham wrote:
> The section on running swap on ZFS was split into two parts.
> The part describing setting the swappiness level was moved to a
> separate file and the part about creating swap partitions on a ZFS
> volume was replaced with a warning about doing so.
>
> Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>
>
> ---
>
> Changes in v8:
> * Moved the changelog below the three dashes.
>
> Changes in v7:
> * Keep ZFS warning in its original file.
> * Corrected some formatting errors.

It's customary to always include the full changelog, e.g. since v1.
Makes it easier for reviewer.

>
>  local-zfs.adoc | 49 ++++++++++---------------------------------------
>  pve-swap.adoc  | 35 +++++++++++++++++++++++++++++++++++
>  sysadmin.adoc  |  2 ++
>  3 files changed, 47 insertions(+), 39 deletions(-)
>  create mode 100644 pve-swap.adoc
>
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index c64fb27..bfd2295 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -1,9 +1,10 @@
>  [[chapter_zfs]]
>  ZFS on Linux
>  ------------
> -ifdef::wiki[]
> -:pve-toplevel:
> -endif::wiki[]
> +
> +-ifdef::wiki[]
> +-:pve-toplevel:
> +-endif::wiki[]

Erroneous hunk maybe from a bad rebase or such?

This was also already noted by Fiona in v6.

>
>  ZFS is a combined file system and logical volume manager designed by
>  Sun Microsystems. Starting with {pve} 3.4, the native Linux
> @@ -620,48 +621,18 @@ 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

nit: [..] creating a swap partition as it could lead

sounds a bit better.

> +to deadlocks. These deadlocks could cause the  affected system to freeze. The

Whitespace errors, I'd also rephrase it a bit to

[..] to deadlocks, which can cause systems to freeze.

> +OpenZFS documentation
> +footnote:[https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#using-a-zvol-for-a-swap-device-on-linux]

Any reason for a footnote and not just a direct link?

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



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