[PATCH docs v2 0/2] local-zfs: rephrase ARC limit

[PATCH docs v2 0/2] local-zfs: rephrase ARC limit

[Maximiliano Sandoval]

See the first commit for more information.

Regarding adding the manual page: It is not very obvious where to find the
documentation for the value (I was personally interested in the units for
zfs_arc_max). Only after a `man -Kw zfs_arc_max` I found zfs(4) (as its sole
output).

I also considered just saying that we only fallback to ZFS' defaults without
specifying the exact values, perhaps only that they quite high compared to 10%.

Differences from v1:
 - Document that we used ZFS' defaults before 8.1
 - Use lowercase in commit message

Maximiliano Sandoval (2):
  local-zfs: rephrase ARC limit
  local-zfs: add reference to the zfs(4) manual

 local-zfs.adoc | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

-- 
2.47.3

[PATCH docs v2 1/2] local-zfs: rephrase ARC limit

[Maximiliano Sandoval]

We rephrase the current section putting more emphasis on the current
state of things given than Proxmox VE 8.1 was released over two years
ago.

We also document ZFS' default size. See [zfs-6a629f3] for more details.

This also frames the problem for pre-existing setups in its own
paragraph.

[zfs-6a629f3] https://github.com/openzfs/zfs/commit/6a629f32344468ae81b264055916641480cb438d

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 local-zfs.adoc | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/local-zfs.adoc b/local-zfs.adoc
index 85fa092..b3a462d 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -586,10 +586,15 @@ configured for the root user.
 Limit ZFS Memory Usage
 ~~~~~~~~~~~~~~~~~~~~~~
 
-ZFS uses '50 %' of the host memory for the **A**daptive **R**eplacement
-**C**ache (ARC) by default. For new installations starting with {pve} 8.1, the
-ARC usage limit will be set to '10 %' of the installed physical memory, clamped
-to a maximum of +16 GiB+. This value is written to `/etc/modprobe.d/zfs.conf`.
+ZFS uses '10 %' of the host memory, clamped to a maximum of +16 GiB+, for the
+**A**daptive **R**eplacement **C**ache (ARC) by default. This value is written
+to `/etc/modprobe.d/zfs.conf` during installation.
+
+Before {pve} 8.1, the ARC usage limit was not set during installation and
+matched ZFS' default value which was either 62.5% starting on ZFS 2.3.0 or 50%
+for older versions. For existing installations that predate {pve} 8.1, manual
+steps would have to be performed in order to lower the usage limit as described
+below.
 
 Allocating enough memory for the ARC is crucial for IO performance, so reduce it
 with caution. As a general rule of thumb, allocate at least +2 GiB Base + 1
-- 
2.47.3

[PATCH docs v2 2/2] local-zfs: add reference to the zfs(4) manual

[Maximiliano Sandoval]

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 local-zfs.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/local-zfs.adoc b/local-zfs.adoc
index b3a462d..07e70e3 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -588,7 +588,8 @@ Limit ZFS Memory Usage
 
 ZFS uses '10 %' of the host memory, clamped to a maximum of +16 GiB+, for the
 **A**daptive **R**eplacement **C**ache (ARC) by default. This value is written
-to `/etc/modprobe.d/zfs.conf` during installation.
+to `/etc/modprobe.d/zfs.conf` during installation. See the manual `man 4 zfs`
+for more information about ZFS kernel module parameters.
 
 Before {pve} 8.1, the ARC usage limit was not set during installation and
 matched ZFS' default value which was either 62.5% starting on ZFS 2.3.0 or 50%
-- 
2.47.3

Re: [PATCH docs v2 1/2] local-zfs: rephrase ARC limit

[Shannon Sterz]

On Thu Feb 26, 2026 at 9:46 AM CET, Maximiliano Sandoval wrote:
> We rephrase the current section putting more emphasis on the current
> state of things given than Proxmox VE 8.1 was released over two years
> ago.
>
> We also document ZFS' default size. See [zfs-6a629f3] for more details.
>
> This also frames the problem for pre-existing setups in its own
> paragraph.
>
> [zfs-6a629f3] https://github.com/openzfs/zfs/commit/6a629f32344468ae81b264055916641480cb438d
>
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>  local-zfs.adoc | 13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)
>
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index 85fa092..b3a462d 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -586,10 +586,15 @@ configured for the root user.
>  Limit ZFS Memory Usage
>  ~~~~~~~~~~~~~~~~~~~~~~
>
> -ZFS uses '50 %' of the host memory for the **A**daptive **R**eplacement
> -**C**ache (ARC) by default. For new installations starting with {pve} 8.1, the
> -ARC usage limit will be set to '10 %' of the installed physical memory, clamped
> -to a maximum of +16 GiB+. This value is written to `/etc/modprobe.d/zfs.conf`.
> +ZFS uses '10 %' of the host memory, clamped to a maximum of +16 GiB+, for the
> +**A**daptive **R**eplacement **C**ache (ARC) by default. This value is written
> +to `/etc/modprobe.d/zfs.conf` during installation.
> +
> +Before {pve} 8.1, the ARC usage limit was not set during installation and
> +matched ZFS' default value which was either 62.5% starting on ZFS 2.3.0 or 50%

nit: i think "starting with" sounds more natural in english

> +for older versions. For existing installations that predate {pve} 8.1, manual
> +steps would have to be performed in order to lower the usage limit as described
> +below.
>
>  Allocating enough memory for the ARC is crucial for IO performance, so reduce it
>  with caution. As a general rule of thumb, allocate at least +2 GiB Base + 1

Re: [PATCH docs v2 0/2] local-zfs: rephrase ARC limit

[Shannon Sterz]

On Thu Feb 26, 2026 at 9:46 AM CET, Maximiliano Sandoval wrote:
> See the first commit for more information.
>
> Regarding adding the manual page: It is not very obvious where to find the
> documentation for the value (I was personally interested in the units for
> zfs_arc_max). Only after a `man -Kw zfs_arc_max` I found zfs(4) (as its sole
> output).
>
> I also considered just saying that we only fallback to ZFS' defaults without
> specifying the exact values, perhaps only that they quite high compared to 10%.
>
> Differences from v1:
>  - Document that we used ZFS' defaults before 8.1
>  - Use lowercase in commit message
>
> Maximiliano Sandoval (2):
>   local-zfs: rephrase ARC limit
>   local-zfs: add reference to the zfs(4) manual
>
>  local-zfs.adoc | 14 ++++++++++----
>  1 file changed, 10 insertions(+), 4 deletions(-)

other than the small nit i left on the first commit, this looks alright
to me, consider this:

Reviewed-by: Shannon Sterz <s.sterz@proxmox.com>

Re: [PATCH docs v2 1/2] local-zfs: rephrase ARC limit

[Friedrich Weber]

Hi, thanks for looking into this!

On 26/02/2026 09:47, Maximiliano Sandoval wrote:
> We rephrase the current section putting more emphasis on the current
> state of things given than Proxmox VE 8.1 was released over two years
> ago.
> 
> We also document ZFS' default size. See [zfs-6a629f3] for more details.
> 
> This also frames the problem for pre-existing setups in its own
> paragraph.
> 
> [zfs-6a629f3] https://github.com/openzfs/zfs/commit/6a629f32344468ae81b264055916641480cb438d
> 
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>  local-zfs.adoc | 13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)
> 
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index 85fa092..b3a462d 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -586,10 +586,15 @@ configured for the root user.
>  Limit ZFS Memory Usage
>  ~~~~~~~~~~~~~~~~~~~~~~
>  
> -ZFS uses '50 %' of the host memory for the **A**daptive **R**eplacement
> -**C**ache (ARC) by default. For new installations starting with {pve} 8.1, the
> -ARC usage limit will be set to '10 %' of the installed physical memory, clamped
> -to a maximum of +16 GiB+. This value is written to `/etc/modprobe.d/zfs.conf`.
> +ZFS uses '10 %' of the host memory, clamped to a maximum of +16 GiB+, for the
> +**A**daptive **R**eplacement **C**ache (ARC) by default. This value is written
> +to `/etc/modprobe.d/zfs.conf` during installation.
> +
> +Before {pve} 8.1, the ARC usage limit was not set during installation and
> +matched ZFS' default value which was either 62.5% starting on ZFS 2.3.0 or 50%

I'm not sure there is a case where a user could have PVE < 8.1 but ZFS
>= 2.3? But it's probably OK to still mention the 62.5%.

There is one more complication: IIRC PVE 8.1 installers only set the ARC
size limit when installing on ZFS, so e.g. installations on ext4+LVM
which later got a zpool would still have ZFS defaults. This was only
changed with the PVE 8.4 installer I think [1], now all installations
limit the ARC size.

> +for older versions. For existing installations that predate {pve} 8.1, manual
> +steps would have to be performed in order to lower the usage limit as described
> +below.
>  
>  Allocating enough memory for the ARC is crucial for IO performance, so reduce it
>  with caution. As a general rule of thumb, allocate at least +2 GiB Base + 1

[1] https://bugzilla.proxmox.com/show_bug.cgi?id=6285