[PATCH v9 5/5] Add system-wide tunables: manual

[Arjun Shankar]

Hi DJ,

> Document the syntax and operation.

This only needed a clarification. No changes since last time.
Reviewed-by: Arjun Shankar <arjun@redhat.com>

> ---
>  manual/tunables.texi | 94 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 94 insertions(+)
>
> diff --git a/manual/tunables.texi b/manual/tunables.texi
> index e0f141077b..847903e6ee 100644
> --- a/manual/tunables.texi
> +++ b/manual/tunables.texi
> @@ -67,6 +67,7 @@ glibc.elf.thp: 0 (min: 0, max: 1)
>  @end example
>
>  @menu
> +* System-wide Tunables:: Tunables that affect every process
>  * Tunable names::  The structure of a tunable name
>  * Memory Allocation Tunables::  Tunables in the memory allocation subsystem
>  * Dynamic Linking Tunables:: Tunables in the dynamic linking subsystem
> @@ -82,6 +83,99 @@ glibc.elf.thp: 0 (min: 0, max: 1)
>
>  @end menu
>
> +@node System-wide Tunables
> +@section System-wide Tunables
> +@cindex System-wide Tunables
> +@cindex /etc/tunables.conf
> +
> +In addition to setting the @code{GLIBC_TUNABLES} environment variable,
> +tunables may be provided globally via the file
> +@file{/etc/tunables.conf}, which gets stored in glibc's dynamic
> +library cache @file{/etc/ld.so.cache} and read by every program at
> +startup.  @file{/etc/tunables.conf} contains one tunable per line:
> +
> +@example
> +glibc.malloc.trim_threshold=128
> +glibc.malloc.check=3
> +@end example
> +
> +@file{ldconfig} (with whatever options you normally use) will read the
> +tunables in @file{/etc/tunables.conf} and save them as an extension
> +in @file{/etc/ld.so.cache}.  Tunables in the cache are applied to
> +every program at startup, programs which are already running are not
> +affected.
> +
> +@file{/etc/tunables.conf} supports the same ``include @var{file}''
> +syntax as @file{ld.so.conf}.
> +
> +Tunables in @file{/etc/tunables.conf} serve as defaults.  They
> +override the built-in defaults in each program, but may be overridden
> +by the @code{GLIBC_TUNABLES} environment variable.  Each tunable may
> +have one or more prefixes which modifies the behavior of the tunable.
> +
> +@table @code
> +
> +@item overridable
> +@item +
> +@item nonoverridable
> +@item -
> +Prefixing the tunable name with @code{nonoverridable} or @code{-}
> +blocks changes from the environment variable, giving the global
> +setting precedence.  Prefixing with @code{overridable} or @code{+}
> +(the default) reverts this behavior, which is only useful with the
> +filters (below).
> +
> +@item onlysecure
> +@item @@
> +Tunables prefixed with @code{onlysecure} or @code{@@} will apply only
> +to processes that are AT_SECURE (i.e. setuid or setgid binaries, or
> +elevated capabilities).
> +
> +@item nonsecure
> +@item $
> +Tunables prefixed with @code{nonsecure} or @code{$} will apply only to
> +processes that aren't AT_SECURE.
> +
> +@item anysecure
> +@item *
> +Tunables prefixed with @code{anysecure} or @code{*} will apply to all
> +processes.
> +
> +@end table
> +
> +Filters make the system-wide tunables only affect certain programs.
> +This allows having a non-overridable default for most of the system
> +but a different, overridable, value for certain programs that might
> +not work at all with the default setting.  The syntax for filters is
> +to have each filter on its own line, followed by tunables that are
> +applied when the filter matches, with this format:
> +
> +@example
> +[ @var{filtername} : @var{pattern} ]
> +@end example
> +
> +Existing filters are:
> +
> +@table @code
> +@item proc
> +Matches the process name.  The pattern is either a fully qualified
> +path, or the basename of such a path.  The process name is read from
> +@file{/proc/self/exe} (if available) or @file{argv[0]} (unless
> +AT_SECURE is in effect).  Example:
> +
> +@example
> +-glibc.cpu.x86_shstk=1
> +[proc:/usr/bin/program_that_crashes_with_shstk]
> ++glibc.cpu.x86_shstk=0
> +@end example
> +
> +@end table
> +
> +Note that the effects of a filter only last until the next filter, or
> +a line with @code{[]} on it (``no filter''), or the end of the file
> +(if the filter appears in an included file, at the end of the included
> +file).
> +
>  @node Tunable names
>  @section Tunable names
>  @cindex Tunable names
> --
> 2.47.3
>