README.tunables

   1                         TUNABLE FRAMEWORK
   2                         =================
   3
   4 Tunables is a feature in the GNU C Library that allows application authors and
   5 distribution maintainers to alter the runtime library behaviour to match their
   6 workload.
   7
   8 The tunable framework allows modules within glibc to register variables that
   9 may be tweaked through an environment variable.  It aims to enforce a strict
  10 namespace rule to bring consistency to naming of these tunable environment
  11 variables across the project.  This document is a guide for glibc developers to
  12 add tunables to the framework.
  13
  14 ADDING A NEW TUNABLE
  15 --------------------
  16
  17 The TOP_NAMESPACE macro is defined by default as 'glibc'.  If distributions
  18 intend to add their own tunables, they should do so in a different top
  19 namespace by overriding the TOP_NAMESPACE macro for that tunable.  Downstream
  20 implementations are discouraged from using the 'glibc' top namespace for
  21 tunables they don't already have consensus to push upstream.
  22
  23 There are two steps to adding a tunable:
  24
  25 1. Add a tunable ID:
  26
  27 Modules that wish to use the tunables interface must define the
  28 TUNABLE_NAMESPACE macro.  Following this, for each tunable you want to
  29 add, make an entry in elf/dl-tunables.list.  The format of the file is as
  30 follows:
  31
  32 TOP_NAMESPACE {
  33   NAMESPACE1 {
  34     TUNABLE1 {
  35       # tunable attributes, one per line
  36     }
  37     # A tunable with default attributes, i.e. string variable.
  38     TUNABLE2
  39     TUNABLE3 {
  40       # its attributes
  41     }
  42   }
  43   NAMESPACE2 {
  44     ...
  45   }
  46 }
  47
  48 The list of allowed attributes are:
  49
  50 - type:                 Data type.  Defaults to STRING.  Allowed types are:
  51                         INT_32, UINT_64, SIZE_T and STRING.  Numeric types may
  52                         be in octal or hexadecimal format too.
  53
  54 - minval:               Optional minimum acceptable value.  For a string type
  55                         this is the minimum length of the value.
  56
  57 - maxval:               Optional maximum acceptable value.  For a string type
  58                         this is the maximum length of the value.
  59
  60 - default:              Specify an optional default value for the tunable.
  61
  62 - env_alias:            An alias environment variable
  63
  64 - security_level:       Specify security level of the tunable.  Valid values:
  65
  66                         SXID_ERASE: (default) Don't read for AT_SECURE binaries and
  67                                     removed so that child processes can't read it.
  68                         SXID_IGNORE: Don't read for AT_SECURE binaries, but retained for
  69                                      non-AT_SECURE subprocesses.
  70                         NONE: Read all the time.
  71
  72 2. Call either the TUNABLE_SET_VALUE and pass into it the tunable name and a
  73    pointer to the variable that should be set with the tunable value.
  74    If additional work needs to be done after setting the value, use the
  75    TUNABLE_SET_VALUE_WITH_CALLBACK instead and additionally pass a pointer to
  76    the function that should be called if the tunable value has been set.
  77
  78 FUTURE WORK
  79 -----------
  80
  81 The framework currently only allows a one-time initialization of variables
  82 through environment variables and in some cases, modification of variables via
  83 an API call.  A future goals for this project include:
  84
  85 - Setting system-wide and user-wide defaults for tunables through some
  86   mechanism like a configuration file.
  87
  88 - Allow tweaking of some tunables at runtime