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

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



_______________________________________________
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 v5] fix #5644: Moved the swap partition section

[Fiona Ebner]

Am 27.05.25 um 12:35 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.
> 
> Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>
> ---
>  local-zfs.adoc       | 42 ++++++----------------------------------
>  pve-swap-on-zfs.adoc | 46 ++++++++++++++++++++++++++++++++++++++++++++

This file should not be here.

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

Already mentioned this in v4:

This hunk seems unrelated. If there is a reason for it, please send it
as a separate patch.

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

Style nit: The line break here is very early, more words fit until the
limit is reached.

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

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

Includes the wrong file.

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