]>
Commit | Line | Data |
---|---|---|
67e58f39 SP |
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 |