[pve-devel] [PATCH pve-docs v3] fix #5644: Split the section on creating a swap partition on a ZVol.

[pve-devel] [PATCH pve-docs v3] fix #5644: Split the section on creating a swap partition on a ZVol.

[Alexander Abraham]

The section "SWAP on ZFS" was split into two parts. The first part
contains general instructions on how to create a swap partition and
how to set the level of "swappiness". The second part contains a
warning about creating a swap partition on a ZFS volume.The official
ZFS documentation, which has been linked in a footnote, explains
that creating a swap partition on a ZFS volume could lead to
dangerous and undefined behavior.

Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>
---
 local-zfs.adoc | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/local-zfs.adoc b/local-zfs.adoc
index c64fb27..d411222 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -622,14 +622,9 @@ 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.
+[[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
@@ -637,18 +632,18 @@ 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"]
 |===========================================================
@@ -663,6 +658,15 @@ improve performance when sufficient memory exists in a system.
 | vm.swappiness = 100 | The kernel will swap aggressively.
 |===========================================================
 
+[[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.
+
 [[zfs_encryption]]
 Encrypted ZFS Datasets
 ~~~~~~~~~~~~~~~~~~~~~~
-- 
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 v3] fix #5644: Split the section on creating a swap partition on a ZVol.

[Fiona Ebner]

Nit: we usually don't use a dot at the end of a commit title

Am 05.02.25 um 13:41 schrieb Alexander Abraham:
> The section "SWAP on ZFS" was split into two parts. The first part
> contains general instructions on how to create a swap partition and
> how to set the level of "swappiness". The second part contains a
> warning about creating a swap partition on a ZFS volume.The official
> ZFS documentation, which has been linked in a footnote, explains
> that creating a swap partition on a ZFS volume could lead to
> dangerous and undefined behavior.
> 
> Signed-off-by: Alexander Abraham <a.abraham@proxmox.com>

Shaping up nicely now! A few more comments/nits below.

> ---
>  local-zfs.adoc | 26 +++++++++++++++-----------
>  1 file changed, 15 insertions(+), 11 deletions(-)
> 
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index c64fb27..d411222 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -622,14 +622,9 @@ 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.
> +[[creating_swap_partitions]]
> +Creating SWAP Partitions
> +~~~~~~~~~~~~~~~~~~~~~~~~
>  

This is not related to ZFS, so a second patch could move this section to
a different place, see Alexander Zeidler's suggestion in v2:
https://lore.proxmox.com/pve-devel/D7ITC3NDGSV5.1S3BV4L2Q49LF@proxmox.com/

>  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
> @@ -637,18 +632,18 @@ 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"]
>  |===========================================================

Is there a specific reason behind these whitespace changes or were they
done by accident?

> @@ -663,6 +658,15 @@ improve performance when sufficient memory exists in a system.
>  | vm.swappiness = 100 | The kernel will swap aggressively.
>  |===========================================================
>  
> +[[zfs_swap]]
> +SWAP on ZFS
> +~~~~~~~~~~~
> +
> +It is strongly recommended to not use a ZFS volume for creating a swap partition

Missing a comma before "because"

> +because this could lead to deadlocks. These deadlocks could cause the affected 

Nit: I'd replace "could" with "can" both times

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

Nit: I'd move the footnote link on its own line, then it will overshoot
the line length a bit less.

> +warns about using a ZFS volume for creating a swap partition.
> +
>  [[zfs_encryption]]
>  Encrypted ZFS Datasets
>  ~~~~~~~~~~~~~~~~~~~~~~



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

[pve-devel] [PATCH pve-docs] fix #5644: Moved the section on ZFS

[Alexander Abraham]

I moved the section on creating swap partitions on ZFS between
the "Disk Health Monitoring" section and the "Logical Volume
Manager" section. I also incorporated all suggestions Fiona
made, except one: No comma was put before "because" because
the subordinate clause is introduced by "because". One only
puts commas after suboridnate clauses if these introduce a
sentence.

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

diff --git a/local-zfs.adoc b/local-zfs.adoc
index c64fb27..3c9564f 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,47 +623,6 @@ 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.
-|===========================================================
-
 [[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/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] fix #5644: Moved the section on ZFS

[Fiona Ebner]

The commit title seems to be cut off/incomplete and is missing the "v4".

Sending patches to existing threads is usually done only in exceptional
cases and almost always just for follow-ups. Please send a stand-alone
v5 next time.

Am 14.05.25 um 18:49 schrieb Alexander Abraham:
> I moved the section on creating swap partitions on ZFS between

Please avoid using "I" to describe changes in commit messages.

> the "Disk Health Monitoring" section and the "Logical Volume
> Manager" section.

> I also incorporated all suggestions Fiona
> made, except one: No comma was put before "because" because
> the subordinate clause is introduced by "because". One only
> puts commas after suboridnate clauses if these introduce a
> sentence.

This should not be part of the commit message, because this is
irrelevant for git history, which is only concerned about the final
version that actually gets applied. This is relevant to ease patch
review, so it should be put below the three dashes...

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

...here. This will not end up in the final commit message and there's no
issue with using "I" here either.

>  local-zfs.adoc       | 42 +---------------------------------------
>  pve-swap-on-zfs.adoc | 46 ++++++++++++++++++++++++++++++++++++++++++++
>  sysadmin.adoc        |  2 ++
>  3 files changed, 49 insertions(+), 41 deletions(-)
>  create mode 100644 pve-swap-on-zfs.adoc
> 
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index c64fb27..3c9564f 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -1,6 +1,7 @@
>  [[chapter_zfs]]
>  ZFS on Linux
>  ------------
> +
>  ifdef::wiki[]
>  :pve-toplevel:
>  endif::wiki[]

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

> @@ -622,47 +623,6 @@ 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.
> -|===========================================================
> -
>  [[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
> +-----------

This section should still be part of the ZFS documentation. Only the
"Creating SWAP Partitions" part should be moved out. And the new file
should then not include "zfs" in its name.

> +
> +It is strongly recommended to not use a ZFS volume for creating a swap 

Nit: could be more direct with "Do not use a ZFS volume"

> +partition because this could lead to deadlocks. These deadlocks could 
> +cause the affected system to freeze. The OpenZFS documentation 

The three lines above all have trailing spaces.

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

There's a trailing space here as well. Make sure to configure your
editor so that you notice those.

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



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