<!--
   $Id: pam_env.sgml 274 2005-07-13 09:52:25Z vorlon $
   
   This file was written by Dave Kinchlea <kinch@kinch.ark.com>
   Ed. AGM
-->

<sect1>Set/unset environment variables

<sect2>Synopsis

<p>
<descrip>

<tag><bf>Module Name:</bf></tag>
<tt/pam_env/

<tag><bf>Author:</bf></tag>
Dave Kinchlea &lt;kinch@kinch.ark.com&gt;

<tag><bf>Maintainer:</bf></tag>
Author

<tag><bf>Management groups provided:</bf></tag>
Authentication (setcred)

<tag><bf>Cryptographically sensitive:</bf></tag>
	
<tag><bf>Security rating:</bf></tag>

<tag><bf>Clean code base:</bf></tag>

<tag><bf>System dependencies:</bf></tag>
<tt>/etc/security/pam_env.conf</tt>

<tag><bf>Network aware:</bf></tag>

</descrip>

<sect2>Overview of module

<p>
This module allows the (un)setting of environment variables. Supported
is the use of previously set environment variables as well as
<em>PAM_ITEM</em>s such as <tt>PAM_RHOST</tt>.

<sect2>Authentication component

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>
<tt/debug/; <tt/conffile=/<em/configuration-file-name/;
<tt/envfile/=<em/env-file-name/; <tt/readenv/=<em/0|1/

<tag><bf>Description:</bf></tag>
This module allows you to (un)set arbitrary environment variables
using fixed strings, the value of previously set environment variables
and/or <em/PAM_ITEM/s.

<p>
All is controlled via a configuration file (by default,
<tt>/etc/security/pam_env.conf</tt> but can be overriden with
<tt>conffile</tt> argument).  Each line starts with the variable name,
there are then two possible options for each variable <bf>DEFAULT</bf>
and <bf>OVERRIDE</bf>.  <bf>DEFAULT</bf> allows an administrator to
set the value of the variable to some default value, if none is
supplied then the empty string is assumed.  The <bf>OVERRIDE</bf>
option tells pam_env that it should enter in its value (overriding the
default value) if there is one to use.  <bf>OVERRIDE</bf> is not used,
<tt>""</tt> is assumed and no override will be done.

<p>
<tscreen>
<verb>
VARIABLE   [DEFAULT=[value]]  [OVERRIDE=[value]]
</verb>
</tscreen>

<p>
(Possibly non-existent) environment variables may be used in values
using the <tt>&dollar;&lcub;string&rcub;</tt> syntax and (possibly
non-existent) <em/PAM_ITEM/s may be used in values using the
<tt>&commat;&lcub;string&rcub;</tt> syntax. Both the <tt>&dollar;</tt>
and <tt>&commat;</tt> characters can be backslash-escaped to be used
as literal values (as in <tt>&bsol;&dollar;</tt>.  Double quotes may
be used in values (but not environment variable names) when white
space is needed <bf>the full value must be delimited by the quotes and
embedded or escaped quotes are not supported</bf>.

<p>
This module can also parse a file with simple <tt>KEY=VAL</tt> pairs
on seperate lines (<tt>/etc/environment</tt> by default). You can
change the default file to parse, with the <em/envfile/ flag and turn
it on or off by setting the <em/readenv/ flag to 1 or 0 respectively.

<p>
The behavior of this module can be modified with one of the following
flags:

<p>
<itemize>

<item><tt/debug/
- write more information to <tt/syslog(3)/.

<item><tt/conffile=/<em/filename/
- by default the file <tt>/etc/security/pam_env.conf</tt> is used as
the configuration file. This option overrides the default. You must
supply a complete path + file name.

<item><tt/envfile=/<em/filename/
- by default the file <tt>/etc/environment</tt> is used to load KEY=VAL
pairs directly into the env. This option overrides the default. You must
supply a complete path + file name.

<item><tt/readenv=/<em/0|1/
- turns on or off the reading of the file specified by envfile (0 is off,
1 is on). By default this option is on.

</itemize>

<tag><bf>Examples/suggested usage:</bf></tag>

See sample <tt>pam_env.conf</tt> for more information and examples.

</descrip>

<!--
End of sgml insert for this module.
-->