.TH "md_src_libgetenv_README" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
md_src_libgetenv_README \- README 

.IP "\(bu" 2
infos = Information about elektrify getenv below
.IP "\(bu" 2
infos/author = Markus Raab elektra@libelektra.org
.IP "\(bu" 2
infos/description =
.PP
.PP
.SH "kdb-elektrify-getenv(1) -- elektrify the environment of applications "
.PP
.PP
\fCkdb elektrify-getenv\fP <application> <options>
.PP
.SS "DESCRIPTION"
.PP
When an application is elektrified using libelektragetenv, it does not only request \fCenviron\fP, but also Elektra for every getenv(3) and secure_getenv(3) library call\&.
.PP
Its main purpose is to:
.PP
.IP "\(bu" 2
have standard ways to modify the environment
.IP "\(bu" 2
make relogin (or even restart!) of applications unnecessary
.IP "\(bu" 2
allow a hierarchical structure for environment
.IP "\(bu" 2
allow settings to only apply for individual applications or only in special context
.IP "\(bu" 2
still preserve the advantages (inheriting of environment to subprocesses)
.IP "\(bu" 2
Availability in at, cron and similar scripts\&.
.PP
.PP
It is implemented using a LD_PRELOAD technique, see \fBUSAGE\fP below for global activation\&.
.PP
.SS "LOOKUPS"
.PP
The main purpose of this approach is to finally have a well-defined way to set and get environment variables\&. Elektra's variables will be in use immediately for every newly started application (no relogin necessary)\&.
.PP
To do so, getenv(3) will lookup multiple sources next to searching in the environment (environ)\&. As running example will use \fCgetenv('HOME') -> /path/to/home\fP:
.PP
.IP "1." 4
Given commandline parameters will always be preferred (see \fBOPTIONS\fP below)\&.
.PP
E\&.g\&. \fCkdb elektrify-getenv <app> --elektra:HOME=/path/to/home\fP
.IP "2." 4
Then \fC/env/override/<key>\fP will be looked up, where <key> is the parameter to \fCgetenv\fP\&. If found, the key will be returned, if it is a null keys, \fCgetenv\fP will return \fCNULL\fP\&.
.PP
E\&.g\&. \fCkdb set user/env/override/HOME /path/to/home\fP
.IP "3." 4
Then environment will be requested\&.
.PP
E\&.g\&. \fCHOME=/path/to/home kdb elektrify-getenv <application>\fP
.PP
.IP "3." 4
Then \fC/env/fallback/<key>\fP will be looked up\&. If found, the key will be returned, if it is a null keys, \fCgetenv\fP will return \fCNULL\fP\&.
.PP
E\&.g\&. \fCkdb set user/env/fallback/HOME /path/to/home\fP
.PP
.PP
.SS "OPTIONS"
.PP
When \fCelektrify-getenv\fP is active, every application additionally accepts Elektra's getenv options\&. Interleaving Elektra's and the application's options is allowed\&. Elektra will parse its options (starting with --elektra) first and discard them before the other application is started\&. Therefore the application will not see that they even existed, e\&.g\&.: given \fCkdb elektrify-getenv <application> -V --elektra-debug -L\fP the application will be called with \fC<application> -V -L\fP\&.
.PP
.SS "Internal Options"
.PP
.IP "\(bu" 2
\fC--elektra-help\fP: Outputs this help\&.
.IP "\(bu" 2
\fC--elektra-version\fP: Gives version information\&.
.IP "\(bu" 2
\fC--elektra-debug=file\fP, \fCELEKTRA_DEBUG\fP or \fC/env/option/debug\fP: Trace all getenv(3) calls to a file\&. stderr if no file is given, e\&.g\&. \fCkdb set user/env/option/debug ''\fP\&. Note that null values (no forth argument), will disable debug messages\&. See examples below\&.
.IP "\(bu" 2
\fC--elektra-clearenv\fP, \fCELEKTRA_CLEARENV\fP or \fC/env/option/clearenv\fP: Call clearenv(3) before entering main\&. This is a recommended security feature\&. Elektra itself, if configured that way, will still be able to use the environment\&.
.IP "\(bu" 2
\fC--elektra-reload-timeout=time_in_ms\fP, \fCELEKTRA_RELOAD_TIMEOUT\fP or \fC/env/option/reload_timeout\fP: Activate a timeout based feature when a time is given in ms (and is not 0)\&.
.PP
.PP
Internal Options are available in three different variants:
.PP
.IP "1." 4
as commandline parameter: \fC--elektra-<option>\fP, which are \fInot\fP passed through exec(3) calls\&.
.PP
.IP "1." 4
as environment variable: \fCELEKTRA_<OPTION>\fP\&. which might be passed through exec(3) calls, but are removed by clearenv(3) calls\&.
.PP
.IP "1." 4
as Elektra KDB entry: \fC/env/option/<option>\fP, which are the way to achieve an option to be enabled for every application\&.
.PP
E\&.g\&. \fCkdb set user/env/option/clearenv ''\fP to clear the environment for all applications started by that user (note that at least \fCPATH\fP should to be set using \fCkdb set user/env/fallback/PATH '/bin:/usr/bin'\fP then)\&.
.PP
Note, that null keys are equal to non-set options\&. E\&.g\&. \fCkdb set system/env/option/debug '/tmp/elektra\&.log'\fP and \fCkdb set user/env/option/debug\fP will activate logging for the system, except for the current user\&.
.PP
.PP
.SS "Contextual Options"
.PP
.IP "\(bu" 2
\fC--elektra%<name>%=<value>\fP or \fC/env/layer/<name>\fP: Add the contextual information (=layer) \fC%<name>%\fP with it's value \fC<value>\fP\&. Note that \fCname%\fP is predefined with \fCargv[0]\fP and \fCbasename%\fP with \fCbasename(argv[0])\fP\&.
.PP
.PP
Values can contain / to form hierarchies, e\&.g\&. \fC--elektraname%=app/profile\fP
.PP
.SS "Options for Applications"
.PP
.IP "\(bu" 2
\fC--elektra:key=value\fP, \fC/env/override/<key>\fP or \fC/env/fallback/<key>\fP: set a key/value to be preferred, i\&.e\&. the first to considered as explained in \fBLOOKUP\fP\&.
.PP
.PP
Keys can contain / to form hierarchies, e\&.g\&. \fC--elektra:my/HOME=/path/to/home\fP\&.
.PP
.SS "USAGE"
.PP
To always use Elektra's getenv environment, simply add the output to the file: 
.PP
.nf
kdb elektrify-getenv | tail -1 | sudo tee -a /etc/ld.so.preload

.fi
.PP
.PP
this also can be done using Elektra: 
.PP
.nf
sudo kdb mount /etc/ld.so.preload system/ld/preload line null
sudo kdb set "system/ld/preload/new"  `kdb elektrify-getenv | tail -1`

.fi
.PP
.PP
.SS "CONTEXT"
.PP
The metadata \fCcontext\fP in the specification can be used to facilitate a context-dependent lookup\&. In its metavalue all replacements of \fC%<name>%\fP will be replaced by the given contextual options \fC--elektra%<name>%=<value>\fP and \fC/env/layer/<name>\fP keys\&.
.PP
E\&.g\&. to have a different home directory for any user and application: 
.PP
.nf
kdb set user/env/layer/user markus
kdb set user/users/markus/konqueror/HOME /home/download
kdb setmeta spec/env/override/HOME context  /users/%user%/%name%/HOME

.fi
.PP
.PP
.SS "BUGS"
.PP
Some applications do not use \fCgetenv(3)\fP or \fCsecure_getenv(3)\fP for requesting the environment, e\&.g\&. shells\&. This approach cannot work for them\&.
.PP
In the startup-phase (before main is even entered), \fCgetenv(3)\fP will not consider \fC/env/override/\fP or \fC/env/fallback\fP\&.
.PP
Elektra internally tries to avoid using the environment\&. Some resolvers, however, use it to be conform to some specifications, e\&.g\&. XDG\&. Depending on the setup you use, these parameters might be used\&. For more information see: 
.PP
.nf
kdb info resolver

.fi
.PP
.PP
For these parameters, \fC/env/override/\fP or \fC/env/fallback\fP will \fInot\fP be used internally, but will be used if applications request them, too\&.
.PP
If you use the standard resolvers, the bug won't have any effect\&.
.PP
Also note that \fC--elektra-debug\fP or \fCELEKTRA_DEBUG\fP does \fInot\fP log \fCgetenv(3)\fP used by plugins during the startup-phase\&.
.PP
Commandline Arguments are always to the outmost command, e\&.g\&. \fCnice ls --elektra:COLUMNS=20\fP won't have any effect because only for \fCnice\fP \fCCOLUMNS\fP will be set\&.
.PP
.SS "EXAMPLES"
.PP
For illustration this section gives some more examples\&. 
.PP
.nf
kdb elektrify-getenv man man --elektra:MANWIDTH=40

.fi
.PP
.PP
Will use MANWIDTH 40 for this invocation of man man\&. This feature is handy, if an option is only available by environment, but not by command-line arguments, because sometimes environment variables are not trivial to set (e\&.g\&. in Makefiles)\&.
.PP
Debugging: 
.PP
.nf
# system wide to stderr (not recommended!):
sudo kdb set system/env/option/debug ""
# system wide to /var/log/elektra.log:
sudo kdb set system/env/option/debug "/var/log/error.log"
# but for my user to ~/.elektra.log:
kdb set user/env/option/debug "$HOME/.elektra.log"
# or disable it for my user:
kdb set user/env/option/debug

.fi
.PP
.PP
Some more examples: 
.PP
.nf
kdb set user/env/override/MANOPT -- "--regex -LC"
kdb elektrify-getenv getenv MANOPT   # to check if it is set as expected
kdb getenv MANOPT   # if /etc/ld.so.preload is active

.fi
.PP
.PP
Will permanently and user-wide change MANOPT to include --regex, and -LC so that regular expressions will be used (note \fCman echo\fP will return many man pages then) and that they will be shown in English\&. This feature is handy to change the default behaviour of applications (either system, user or directory-wide)\&.
.PP
.PP
.nf
kdb set system/env/override/HTTP_PROXY http://proxy.hogege.com:8000/
.fi
.PP
.PP
Will permanently and system-wide change the proxy for all applications that honor HTTP_PROXY, e\&.g\&. w3m\&. We can also link \fChttp_proxy\fP to the value of \fCHTTP_PROXY\fP: 
.PP
.nf
kdb setmeta spec/env/override/http_proxy "override/#0" /env/override/HTTP_PROXY
kdb get /env/override/http_proxy
.fi
.PP