Re: man/man8/ldconfig.8: document system-wide tunables

[DJ Delorie <dj@redhat.com>]

Alejandro Colomar <alx@kernel.org> writes:
> Please split into separate patches with commit messages,

How do you want them split?  Per man page, or one for breaking out
ld.so.conf and one for adding tunables.conf?

Also, I've been using the output of "git show" for these patches.

> Let's start a new paragraph:
>
> 	.P

We still need a better language ;-) ("why doesn't it know to start a
paragraph after a heading?" ;)

>> +The file allows lines to start with the word
>> +.I include
>> +followed by a path wildcard,
>
> What is a path wildcard?  We should specify it, since different programs
> treat wildcards differently.  Is it a glob(7)?

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

>> +and will include any files matching that wildcard.
>> +The file is parsed by
>> +.B \%ldconfig
>
> .BR \%ldconfig (8)

Fixed.

> However, I think 'system-wide' is unnecessary here: 'tunables
> configuration file' should be enough.  By being in /etc/, it is known to
> be system-wide.

Fixed.

>> +.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.
>
> 	.P

Fixed, but that's a lot of one-sentence paragraphs.

>> +.IR /etc/ld.so.cache .
>> +.P
>> +Each line may include zero or more words or symbols at the beginning:
>> +.TP
>> +.B overridable
>> +.TQ
>> +.B +
>> +Allow the tunable to be overridden by the environment variable
>> +(this is the default).
>
> Which environment variable?

Fixed.

> Should we document an ENVIRONMENT section in ldconfig(8)?

No, the environment variable is read at runtime, not by ldconfig.

>> +(such as setuid, or elevated capabilities)
>
> Do you mean the system call setuid(2)?  Or a setuid program?

a set-user-ID program.  Fixed.

>> +.IP
>> +.EX
>> +.RI [ filter : pattern ]
>> +.EE
>
> You should indent this compared to the surrounding text:
>
> 	.IP
> 	.in +4n

Isn't that what the .IP does ?

>> +filter limits the following tunables to processes starting from the
>> +file matching the pattern.
>
> What do you mean by processes starting from the file?  Processes that
> exec(3) the file and its children?

It actually means exactly what it says, but I admit it can be confusing.
When the dynamic linker creates a process, and uses the image in file
/file/ as the template, that new process is affected.

i.e.  If you type "/usr/bin/ls" and the filter is "/usr/bin/ls", that
new copy of /usr/bin/ls is affected.

>> +The file may be fully qualified or just the basename.
>
> 'fully qualified' isn't something we say of paths.  We should say an
> absolute pathname.  Is it only absolute pathnames and basenames?  How
> about relative pathnames?

No, for security and logical reasons, it cannot be a relative path.  So
you end up with "one specific version of XYZ" or "any version of XYZ".
No wildcards either.  It's intended for rare exceptions.

commit a9b49369175e67e07b556ec28cd2d9d5538c0fe6
Author: DJ Delorie <dj@redhat.com>
Date:   Mon Jul 13 17:30:56 2026 -0400

    man/man8/ldconfig.8: document system-wide tunables

diff --git a/man/man5/ld.so.conf.5 b/man/man5/ld.so.conf.5
index 481cf9152..9954c74bc 100644
--- a/man/man5/ld.so.conf.5
+++ b/man/man5/ld.so.conf.5
@@ -6,9 +6,36 @@ .SH SYNOPSIS
 .B /etc/ld.so.conf
 .fi
 .SH DESCRIPTION
+.P
 This file contains a list of directories,
 one per line,
 in which to search for libraries.
+.P
+The file
+(and any other files included by it)
+is parsed by
+.B \%ldconfig
+and the results stored in
+.IR /etc/ld.so.cache .
+.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
+Example config file:
+.IP
+.EX
+/lib
+/usr/lib
+/usr/local/lib
+include /etc/ld.so.conf.d/*.conf
+.EE
 .SH FILES
 .I /etc/ld.so.conf
 .SH SEE ALSO
diff --git a/man/man5/tunables.conf.5 b/man/man5/tunables.conf.5
new file mode 100644
index 000000000..b983a2bfe
--- /dev/null
+++ b/man/man5/tunables.conf.5
@@ -0,0 +1,112 @@
+.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.
+.P
+For a list of valid tunables,
+please consult the glibc manual.
+.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,
+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
+.EX
+.RI [ filter : pattern ]
+.EE
+.TP
+.B proc
+The
+.I proc
+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
+.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
+.SH FILES
+.I /etc/ld.so.conf
+.SH SEE ALSO
+.BR ld.so (8),
+.BR ldconfig (8)
diff --git a/man/man8/ld.so.8 b/man/man8/ld.so.8
index 5f3c22ef2..40f129b71 100644
--- a/man/man8/ld.so.8
+++ b/man/man8/ld.so.8
@@ -792,7 +792,8 @@ .SH FILES
 .TP
 .I /etc/ld.so.cache
 File containing a compiled list of directories in which to search for
-shared objects and an ordered list of candidate shared objects.
+shared objects and an ordered list of candidate shared objects,
+and any system-wide tunables to be applied.
 See
 .BR ldconfig (8).
 .TP
diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
index 9ac146b44..234169504 100644
--- a/man/man8/ldconfig.8
+++ b/man/man8/ldconfig.8
@@ -17,6 +17,8 @@ .SH SYNOPSIS
 .IR conf ]
 .RB [ \-r\~\c
 .IR root ]
+.RB [ \-t\~\c
+.IR tunconf ]
 .IR directory \~.\|.\|.
 .YS
 .SY /sbin/ldconfig
@@ -85,6 +87,13 @@ .SH DESCRIPTION
 .P
 Failure to follow this pattern may result in compatibility issues
 after an upgrade.
+.P
+If the file
+.I /etc/tunables.conf
+exists,
+it contains tunables to be applied to all processes.
+These tunables are stored
+in the cache and applied to every process at its startup.
 .SH OPTIONS
 .TP
 .BI \-\-format= fmt
@@ -157,6 +166,12 @@ .SH OPTIONS
 .I root
 as the root directory.
 .TP
+.BI \-t\~ tunconf
+Use
+.I tunconf
+instead of
+.IR /etc/tunables.conf .
+.TP
 .B \-\-verbose
 .TQ
 .B \-v
@@ -178,8 +193,6 @@ .SH OPTIONS
 is also specified,
 the cache is still rebuilt.
 .SH FILES
-.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf
-.\"
 .\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf
 .PD 0
 .TP
@@ -190,11 +203,17 @@ .SH FILES
 See
 .BR ld.so.conf (5).
 .TP
+.I /etc/tunables.conf
+See
+.BR tunables.conf (5).
+.TP
 .I /etc/ld.so.cache
 contains an ordered list of libraries found in the directories
 specified in
 .IR /etc/ld.so.conf ,
-as well as those found in the trusted directories.
+as well as those found in the trusted directories,
+and any system-wide tunables listed in
+.IR /etc/tunables.conf .
 .PD
 .SH SEE ALSO
 .BR ldd (1),