|
| 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, SIZE_T and STRING. |
| 52 | + |
| 53 | +- minval: Optional minimum acceptable value. For a string type |
| 54 | + this is the minimum length of the value. |
| 55 | + |
| 56 | +- maxval: Optional maximum acceptable value. For a string type |
| 57 | + this is the maximum length of the value. |
| 58 | + |
| 59 | +- env_alias: An alias environment variable |
| 60 | + |
| 61 | +- is_secure: Specify whether the tunable should be read for setuid |
| 62 | + binaries. True allows the tunable to be read for |
| 63 | + setuid binaries while false disables it. Note that |
| 64 | + even if this is set as true and the value is read, it |
| 65 | + may not be used if it does not validate against the |
| 66 | + acceptable values or is not considered safe by the |
| 67 | + module. |
| 68 | + |
| 69 | +2. Call either the TUNABLE_SET_VALUE and pass into it the tunable name and a |
| 70 | + pointer to the variable that should be set with the tunable value. |
| 71 | + If additional work needs to be done after setting the value, use the |
| 72 | + TUNABLE_SET_VALUE_WITH_CALLBACK instead and additionally pass a pointer to |
| 73 | + the function that should be called if the tunable value has been set. |
| 74 | + |
| 75 | +FUTURE WORK |
| 76 | +----------- |
| 77 | + |
| 78 | +The framework currently only allows a one-time initialization of variables |
| 79 | +through environment variables and in some cases, modification of variables via |
| 80 | +an API call. A future goals for this project include: |
| 81 | + |
| 82 | +- Setting system-wide and user-wide defaults for tunables through some |
| 83 | + mechanism like a configuration file. |
| 84 | + |
| 85 | +- Allow tweaking of some tunables at runtime |
0 commit comments