[thirdparty/glibc.git] / README.tunables

			TUNABLE FRAMEWORK
			=================

Tunables is a feature in the GNU C Library that allows application authors and
distribution maintainers to alter the runtime library behaviour to match their
workload.

The tunable framework allows modules within glibc to register variables that
may be tweaked through an environment variable.  It aims to enforce a strict
namespace rule to bring consistency to naming of these tunable environment
variables across the project.  This document is a guide for glibc developers to
add tunables to the framework.

ADDING A NEW TUNABLE
--------------------

The TOP_NAMESPACE macro is defined by default as 'glibc'.  If distributions
intend to add their own tunables, they should do so in a different top
namespace by overriding the TOP_NAMESPACE macro for that tunable.  Downstream
implementations are discouraged from using the 'glibc' top namespace for
tunables they don't already have consensus to push upstream.

There are two steps to adding a tunable:

1. Add a tunable ID:

Modules that wish to use the tunables interface must define the
TUNABLE_NAMESPACE macro.  Following this, for each tunable you want to
add, make an entry in elf/dl-tunables.list.  The format of the file is as
follows:

TOP_NAMESPACE {
  NAMESPACE1 {
    TUNABLE1 {
      # tunable attributes, one per line
    }
    # A tunable with default attributes, i.e. string variable.
    TUNABLE2
    TUNABLE3 {
      # its attributes
    }
  }
  NAMESPACE2 {
    ...
  }
}

The list of allowed attributes are:

- type:			Data type.  Defaults to STRING.  Allowed types are:
			INT_32, UINT_64, SIZE_T and STRING.  Numeric types may
			be in octal or hexadecimal format too.

- minval:		Optional minimum acceptable value.  For a string type
			this is the minimum length of the value.

- maxval:		Optional maximum acceptable value.  For a string type
			this is the maximum length of the value.

- default:		Specify an optional default value for the tunable.

- env_alias:		An alias environment variable

- security_level:	Specify security level of the tunable.  Valid values:

			SXID_ERASE: (default) Don't read for AT_SECURE binaries and
				    removed so that child processes can't read it.
			SXID_IGNORE: Don't read for AT_SECURE binaries, but retained for
				     non-AT_SECURE subprocesses.
			NONE: Read all the time.

2. Call either the TUNABLE_SET_VALUE and pass into it the tunable name and a
   pointer to the variable that should be set with the tunable value.
   If additional work needs to be done after setting the value, use the
   TUNABLE_SET_VALUE_WITH_CALLBACK instead and additionally pass a pointer to
   the function that should be called if the tunable value has been set.

FUTURE WORK
-----------

The framework currently only allows a one-time initialization of variables
through environment variables and in some cases, modification of variables via
an API call.  A future goals for this project include:

- Setting system-wide and user-wide defaults for tunables through some
  mechanism like a configuration file.

- Allow tweaking of some tunables at runtime
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:
ad2f35cb SP	51	INT_32, UINT_64, SIZE_T and STRING. Numeric types may
ad2f35cb SP	52	be in octal or hexadecimal format too.
67e58f39 SP	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
d1310307 SP	60	- default: Specify an optional default value for the tunable.
d1310307 SP	61
67e58f39 SP	62	- env_alias: An alias environment variable
67e58f39 SP	63
65eff7fb SL	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.
67e58f39 SP	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