[PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Gabriel Goller]

Add missing documentation for two neighbor table garbage collector
sysctl parameters in ip-sysctl.rst:

 * neigh/default/gc_interval: controls how often the garbage collector
   runs for neighbor entries (default: 30 seconds)
 * neigh/default/gc_stale_time: controls how long an unused neighbor
   entry is kept before becoming eligible for garbage collection
   (default: 60 seconds)

Signed-off-by: Gabriel Goller <g.goller@proxmox.com>
---
 Documentation/networking/ip-sysctl.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst
index 28c7e4f5ecf9..033e18303d79 100644
--- a/Documentation/networking/ip-sysctl.rst
+++ b/Documentation/networking/ip-sysctl.rst
@@ -202,6 +202,21 @@ neigh/default/gc_thresh3 - INTEGER
 
 	Default: 1024
 
+neigh/default/gc_interval - INTEGER
+	How often the garbage collector for neighbor entries should run. This
+	value applies to the entire table, not individual entries.
+
+	Default: 30 seconds
+
+neigh/default/gc_stale_time - INTEGER
+	Determines how long a neighbor entry can remain unused before it is
+	considered stale and eligible for garbage collection. Entries that have
+	not been used for longer than this time will be removed by the garbage
+	collector, unless they have active references, are marked as PERMANENT,
+	or carry the NTF_EXT_LEARNED or NTF_EXT_VALIDATED flag.
+
+	Default: 60 seconds
+
 neigh/default/unres_qlen_bytes - INTEGER
 	The maximum number of bytes which may be used by packets
 	queued for each	unresolved address by other network layers.
-- 
2.47.3

RE: [PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Keller, Jacob E]

> -----Original Message-----
> From: Gabriel Goller <g.goller@proxmox.com>
> Sent: Thursday, February 19, 2026 8:22 AM
> To: David S. Miller <davem@davemloft.net>; Eric Dumazet
> <edumazet@google.com>; Jakub Kicinski <kuba@kernel.org>; Paolo Abeni
> <pabeni@redhat.com>; Simon Horman <horms@kernel.org>; Jonathan
> Corbet <corbet@lwn.net>; Shuah Khan <skhan@linuxfoundation.org>
> Cc: netdev@vger.kernel.org; linux-doc@vger.kernel.org; linux-
> kernel@vger.kernel.org
> Subject: [PATCH net-next] docs: net: document neigh gc_interval and
> gc_stale_time sysctls
> 
> Add missing documentation for two neighbor table garbage collector
> sysctl parameters in ip-sysctl.rst:
> 
>  * neigh/default/gc_interval: controls how often the garbage collector
>    runs for neighbor entries (default: 30 seconds)
>  * neigh/default/gc_stale_time: controls how long an unused neighbor
>    entry is kept before becoming eligible for garbage collection
>    (default: 60 seconds)
> 
> Signed-off-by: Gabriel Goller <g.goller@proxmox.com>
> ---

Reviewed-by: Jacob Keller <Jacob.e.keller@intel.com>

>  Documentation/networking/ip-sysctl.rst | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/Documentation/networking/ip-sysctl.rst
> b/Documentation/networking/ip-sysctl.rst
> index 28c7e4f5ecf9..033e18303d79 100644
> --- a/Documentation/networking/ip-sysctl.rst
> +++ b/Documentation/networking/ip-sysctl.rst
> @@ -202,6 +202,21 @@ neigh/default/gc_thresh3 - INTEGER
> 
>  	Default: 1024
> 
> +neigh/default/gc_interval - INTEGER
> +	How often the garbage collector for neighbor entries should run. This
> +	value applies to the entire table, not individual entries.
> +
> +	Default: 30 seconds
> +
> +neigh/default/gc_stale_time - INTEGER
> +	Determines how long a neighbor entry can remain unused before it is
> +	considered stale and eligible for garbage collection. Entries that have
> +	not been used for longer than this time will be removed by the
> garbage
> +	collector, unless they have active references, are marked as
> PERMANENT,
> +	or carry the NTF_EXT_LEARNED or NTF_EXT_VALIDATED flag.
> +
> +	Default: 60 seconds
> +
>  neigh/default/unres_qlen_bytes - INTEGER
>  	The maximum number of bytes which may be used by packets
>  	queued for each	unresolved address by other network layers.
> --
> 2.47.3
> 
> 

Re: [PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Jakub Kicinski]

On Thu, 19 Feb 2026 17:21:58 +0100 Gabriel Goller wrote:
> +neigh/default/gc_interval - INTEGER
> +	How often the garbage collector for neighbor entries should run. This
> +	value applies to the entire table, not individual entries.
> +
> +	Default: 30 seconds

AI suggests that this value is not actually currently used
in our implementation. I can't find any use either, TBH.
It's read and can be written but it's seemingly not used for anything.

> +neigh/default/gc_stale_time - INTEGER
> +	Determines how long a neighbor entry can remain unused before it is
> +	considered stale and eligible for garbage collection. Entries that have
> +	not been used for longer than this time will be removed by the garbage
> +	collector, unless they have active references, are marked as PERMANENT,
> +	or carry the NTF_EXT_LEARNED or NTF_EXT_VALIDATED flag.
> +
> +	Default: 60 seconds

AI adds:

  Important caveat: This check is only reached when total_entries >= gc_thresh1
  (line 1000-1001). Below that threshold, the periodic GC skips the scan
  entirely.

If true I think we should mention that ?
-- 
pw-bot: cr

Re: [PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Gabriel Goller]

On 20.02.2026 16:43, Jakub Kicinski wrote:
> On Thu, 19 Feb 2026 17:21:58 +0100 Gabriel Goller wrote:
> > +neigh/default/gc_interval - INTEGER
> > +	How often the garbage collector for neighbor entries should run. This
> > +	value applies to the entire table, not individual entries.
> > +
> > +	Default: 30 seconds
> 
> AI suggests that this value is not actually currently used
> in our implementation. I can't find any use either, TBH.
> It's read and can be written but it's seemingly not used for anything.

You're right, I'll remove this section.

> > +neigh/default/gc_stale_time - INTEGER
> > +	Determines how long a neighbor entry can remain unused before it is
> > +	considered stale and eligible for garbage collection. Entries that have
> > +	not been used for longer than this time will be removed by the garbage
> > +	collector, unless they have active references, are marked as PERMANENT,
> > +	or carry the NTF_EXT_LEARNED or NTF_EXT_VALIDATED flag.
> > +
> > +	Default: 60 seconds
> 
> AI adds:
> 
>   Important caveat: This check is only reached when total_entries >= gc_thresh1
>   (line 1000-1001). Below that threshold, the periodic GC skips the scan
>   entirely.
> 
> If true I think we should mention that ?

Yes this is true -- I'll mention this in the description.

Thanks for the review!

Re: [PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Gabriel Goller]

Superseded by:
- [PATCH net-next v2] docs: net: document neigh gc_stale_time sysctl
  https://lore.kernel.org/netdev/20260223101257.47563-1-g.goller@proxmox.com/

--
pw-bot: superseded

Re: [PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Jakub Kicinski]

On Mon, 23 Feb 2026 11:23:29 +0100 Gabriel Goller wrote:
> Superseded by:
> - [PATCH net-next v2] docs: net: document neigh gc_stale_time sysctl
>   https://lore.kernel.org/netdev/20260223101257.47563-1-g.goller@proxmox.com/
> 
> --
> pw-bot: superseded

Where did you get the idea to send this email??

Re: [PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Gabriel Goller]

On 23.02.2026 14:58, Jakub Kicinski wrote:
> On Mon, 23 Feb 2026 11:23:29 +0100 Gabriel Goller wrote:
> > Superseded by:
> > - [PATCH net-next v2] docs: net: document neigh gc_stale_time sysctl
> >   https://lore.kernel.org/netdev/20260223101257.47563-1-g.goller@proxmox.com/
> > 
> > --
> > pw-bot: superseded
> 
> Where did you get the idea to send this email??

Haha, I changed the title of the patch in the new version, so Patchwork
didn't automatically recognize it and mark the old one as superseded.

I saw in Documentation/process/maintainer-netdev.rst that there's a way
to manually set the state to superseded using pw-bot commands. However,
it turns out I don't have the necessary permissions to do that :)

Re: [PATCH net-next] docs: net: document neigh gc_interval and gc_stale_time sysctls

[Jakub Kicinski]

On Tue, 24 Feb 2026 10:06:41 +0100 Gabriel Goller wrote:
> On 23.02.2026 14:58, Jakub Kicinski wrote:
> > On Mon, 23 Feb 2026 11:23:29 +0100 Gabriel Goller wrote:  
> > > Superseded by:
> > > - [PATCH net-next v2] docs: net: document neigh gc_stale_time sysctl
> > >   https://lore.kernel.org/netdev/20260223101257.47563-1-g.goller@proxmox.com/
> > > 
> > > --
> > > pw-bot: superseded  
> > 
> > Where did you get the idea to send this email??  
> 
> Haha, I changed the title of the patch in the new version, so Patchwork
> didn't automatically recognize it and mark the old one as superseded.

Oh, that's nice of you! Would have been useful to mention the reason in
the email to avoid my grumbling :)

> I saw in Documentation/process/maintainer-netdev.rst that there's a way
> to manually set the state to superseded using pw-bot commands. However,
> it turns out I don't have the necessary permissions to do that :)

You should as the author, I think the issue is DKIM. Your email from the
archive fails DKIM verification, probably because headers were modified
to look like they were sent by the list? You can try to complain to
your email provider, most get it right.