Re: [PATCH v2 2/4] man/man5/tunables.conf: Document system-wide tunables config

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 4725 bytes --]

Hi DJ,

On 2026-07-14T22:58:09-0400, DJ Delorie wrote:
> ---
>  man/man5/tunables.conf.5 | 116 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 116 insertions(+)
>  create mode 100644 man/man5/tunables.conf.5
> 
> diff --git a/man/man5/tunables.conf.5 b/man/man5/tunables.conf.5
> new file mode 100644
> index 000000000..e2b31e351
> --- /dev/null
> +++ b/man/man5/tunables.conf.5
> @@ -0,0 +1,116 @@
> +.TH tunables.conf 5 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +tunables.conf \- tunables configuration file
> +.SH SYNOPSIS
> +.nf
> +.B /etc/tunables.conf
> +.fi
> +.SH DESCRIPTION
> +Each line in the file
> +.I /etc/tunables.conf
> +specifies a tunable,
> +which is a name and value separated by an equals sign.

I suspect a tunable _is_ _not_ a name=value.  That's _how_ you specify
a tunable, which is a different thing.

In fact, I think we'd have to document what a tunable actually is.
From the glibc manual, I see:

	Tunables are a feature in the GNU C Library that allows
	application authors and distribution maintainers to alter the
	runtime library behavior to match their workload.  [...]

This seems more like a description of what a tunable is.
I'd put such a short description in the first paragraph, and move the
specification of how a tunable is specified in /etc/tunables.conf to the
second paragraph.

> +.P
> +For a list of valid tunables,

Maybe s/valid/supported/?

> +please consult the glibc manual.

s/please//

Also, a link to the specific point in the glibc manual would help:

	consult the
	.UR https://sourceware.org/glibc/manual/latest/html_node/Tunables.html
	glibc manual
	.UE .

However, I see that link documents the list of supported tunables by
saying you should run `ld.so --list-tunables`, so maybe we should
document that directly?  It shouldn't take much space.

Also, I see --list-tunables is already documented in ld.so(8), so we
only need to refer to that page.

	For a list of the supported tunables,
	see
	.B \-\-list\-tunables
	in
	.BR ld.so (8).

> +.P
> +The syntax allows lines to start with the word
> +.I include
> +followed by a path wildcard,
> +and will include any files matching that wildcard.
> +The wildcard is a path specification in the
> +.BR \%glob (7)
> +format.
> +Files matching that wildcard will be processed
> +as if their contents were included in the main config file.
> +.P
> +The file is parsed by
> +.BR \%ldconfig (8)
> +and the results stored in
> +.IR /etc/ld.so.cache .
> +The resulting data is read when a new process starts.
> +.P
> +Each line may include zero or more words or symbols at the beginning,

s/words/keywords/

Also, do symbols allow/require whitespace after them?

> +which affect how each tunable affects each processes:
> +.TP
> +.B overridable
> +.TQ
> +.B +
> +Allow the tunable to be overridden by the
> +.B GLIBC_TUNABLES
> +environment variable when the process runs
> +(this is the default).
> +.TP
> +.B nonoverridable
> +.TQ
> +.B \-
> +Do not allow the tunable to be overridden by the environment variable.
> +.TP
> +.B onlysecure
> +.TQ
> +.B @
> +The tunable only applies to
> +.B AT_SECURE
> +processes,
> +such as a set-user-ID process,
> +or one with elevated capabilities.
> +.TP
> +.B nonsecure
> +.TQ
> +.B $
> +The tunable only applies to
> +.RB non- AT_SECURE
> +processes (this is the default).
> +.TP
> +.B anysecure
> +.TQ
> +.B *
> +The tunable only applies to both
> +.B AT_SECURE
> +and
> +.RB non- AT_SECURE
> +processes.
> +.P
> +The file may also contain
> +.IR filters ,
> +which limit the tunables following it,
> +up to the end of the file
> +(or end of the included file,
> +or start of a new included file)
> +or a line with only
> +.B []
> +on it.
> +The syntax is:
> +.IP
> +.in +4n
> +.EX
> +.RI [ filter : pattern ]
> +.EE
> +.in
> +.TP
> +.B proc
> +The
> +.I proc

s/I/B/

(This and many other issues were reported in the previous patch set;
 please revise that.)


Have a lovely day!
Alex

> +filter limits the following tunables to processes
> +whose name matches the pattern.
> +The pattern may be an absolute path
> +or just the base name.
> +.P
> +Example config file:
> +.IP
> +.in +4n
> +.EX
> +glibc.malloc.arenas_max=5
> +onlysecure glibc.malloc.arenas_max=1
> +\-glibc.pthread.rseq=1
> +[proc:/bin/bad.program]
> +\-glibc.pthread.rseq=0
> +[proc:some.program]
> +\-glibc.malloc.mmap_threshold=65536
> +.EE
> +.in
> +.SH FILES
> +.I /etc/ld.so.conf
> +.SH SEE ALSO
> +.BR ld.so (8),
> +.BR ldconfig (8)
> -- 
> 2.47.3
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]