[pve-devel] [ZFS on swap correction 1/1] Section on ZFS and swap corrected.

[Fiona Ebner]

We already discussed this off-list yesterday, but mentioning it here for
completeness and for the mail archive:

The subject prefix for the title should be "PATCH docs" or "PATCH
pve-docs". E.g., this can be configured in .git/config for the repository

> [format]
> 	subjectprefix = PATCH docs

Regarding the cover letter, we don't use mark-down or similar in commit
messages and commit subjects.

Your Signed-off-by trailer is missing.

The commit title and message could indicate what exactly was corrected,
e.g. "improve language". "Corrected" by itself could refer to anything ;)

Am 17.12.24 um 10:30 schrieb Alexander Abraham:
> ---

Just mentioning it here for completeness, if you ever need to add
additional context/hints for reviewers/testers that should not be
included in the git history, you can put it right here, below the "---".

>  local-zfs.adoc | 36 +-----------------------------------
>  1 file changed, 1 insertion(+), 35 deletions(-)
> 
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index c64fb27..bcd02f7 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -627,41 +627,7 @@ You *must reboot* to activate these changes.
>  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.
> -|===========================================================
> +It is strongly recommended to not use a ZFS volume for a swap partition because this could lead to deadlocks freezing thge affected system and other unpredictable behavior. The OpenZFS documentation, which can be viewed https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#using-a-zvol-for-a-swap-device-on-linux[here], warns against using a ZFS volume for a swap partition.
>  

Style nit: please split up this line using a character limit of 80. It
will still be rendered correctly in the resulting documentations ;)

Always see the surrounding documentation or code for style hints for
some orientation about how things should be structured, but of course
the style guides for specific topics in the wiki take precedence. See also:

https://pve.proxmox.com/wiki/Technical_Writing_Style_Guide

I'd not drop the "high IO load" in favor of the less precise "other
unpredictable behavior". There is a typo "thge" in the new version. I'd
put the link to OpenZFS documentation as a footnote.

Why remove all of the guidance for using a partition as swap and how to
configure it? If there is good rationale behind this, the commit message
should describe it.

>  [[zfs_encryption]]
>  Encrypted ZFS Datasets