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

[PATCH docs 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).

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

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

-- 
2.47.3

[PATCH docs 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.

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

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

diff --git a/local-zfs.adoc b/local-zfs.adoc
index 4f20d00..12506d1 100644
--- a/local-zfs.adoc
+++ b/local-zfs.adoc
@@ -586,10 +586,13 @@ 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 set to '50 %' without clamping it to a
+maximum size. 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

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

[Shannon Sterz]

On Tue Feb 24, 2026 at 11:54 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.
>
> This also frames the problem for pre-existing setups in its own
> paragraph.
>
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>  local-zfs.adoc | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/local-zfs.adoc b/local-zfs.adoc
> index 4f20d00..12506d1 100644
> --- a/local-zfs.adoc
> +++ b/local-zfs.adoc
> @@ -586,10 +586,13 @@ 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 set to '50 %' without clamping it to a
> +maximum size. 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.

this and the other patch in this series looks good to me, one small
comment: maybe mention that this isn't something set by the installer or
pve, but rather just the zfs default [1].

[1]: https://openzfs.github.io/openzfs-docs/man/master/4/zfs.4.html#zfs_arc_max

other than that, consider this:

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

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

superseded: [PATCH docs 1/2] local-zfs: Rephrase ARC limit

[Maximiliano Sandoval]

"Shannon Sterz" <s.sterz@proxmox.com> writes:

> On Tue Feb 24, 2026 at 11:54 AM CET, Maximiliano Sandoval wrote:
>> We rephrase the current section putting more emphasis on the current
>> +Before {pve} 8.1, the ARC usage limit was set to '50 %' without clamping it to a
>> [..]
>> +maximum size. 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.
>
> this and the other patch in this series looks good to me, one small
> comment: maybe mention that this isn't something set by the installer or
> pve, but rather just the zfs default [1].
>
> [1]: https://openzfs.github.io/openzfs-docs/man/master/4/zfs.4.html#zfs_arc_max
>
> other than that, consider this:
>
> Reviewed-by: Shannon Sterz <s.sterz@proxmox.com>
>
>>
>>  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

Superseded-by: https://lore.proxmox.com/all/20260226084639.107816-1-m.sandoval@proxmox.com/

-- 
Maximiliano

[PATCH docs 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 12506d1..e03379b 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 set to '50 %' without clamping it to a
 maximum size. For existing installations that predate {pve} 8.1, manual steps
-- 
2.47.3