csu3_am335x/EVSE/GPL/linux-pam-1.5.2/modules/pam_env/pam_env.8.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id='pam_env'>

  <refmeta>
    <refentrytitle>pam_env</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id='pam_env-name'>
    <refname>pam_env</refname>
    <refpurpose>
      PAM module to set/unset environment variables
    </refpurpose>
  </refnamediv>

<!-- body begins here -->

  <refsynopsisdiv>
    <cmdsynopsis id="pam_env-cmdsynopsis">
      <command>pam_env.so</command>
      <arg choice="opt">
        debug
      </arg>
      <arg choice="opt">
        conffile=<replaceable>conf-file</replaceable>
      </arg>
      <arg choice="opt">
        envfile=<replaceable>env-file</replaceable>
      </arg>
      <arg choice="opt">
        readenv=<replaceable>0|1</replaceable>
      </arg>
      <arg choice="opt">
        user_envfile=<replaceable>env-file</replaceable>
      </arg>
      <arg choice="opt">
        user_readenv=<replaceable>0|1</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>


  <refsect1 id="pam_env-description">
    <title>DESCRIPTION</title>
    <para>
      The pam_env PAM module allows the (un)setting of environment
      variables. Supported is the use of previously set environment
      variables as well as <emphasis>PAM_ITEM</emphasis>s such as
      <emphasis>PAM_RHOST</emphasis>.
    </para>
    <para>
      By default rules for (un)setting of variables are taken from the
      config file <filename>/etc/security/pam_env.conf</filename>. An
      alternate file can be specified with the <emphasis>conffile</emphasis>
      option.
    </para>
    <para>
      Second a file (<filename>/etc/environment</filename> by default) with simple
      <emphasis>KEY=VAL</emphasis> pairs on separate lines will be read.
      With the <emphasis>envfile</emphasis> option an alternate file can be specified.
      And with the <emphasis>readenv</emphasis> option this can be completely disabled.
    </para>
    <para>
      Third it will read a user configuration file
      (<filename>$HOME/.pam_environment</filename> by default).
      The default file can be changed with the
      <emphasis>user_envfile</emphasis> option
      and it can be turned on and off with the <emphasis>user_readenv</emphasis> option.
    </para>
    <para>
      Since setting of PAM environment variables can have side effects
      to other modules, this module should be the last one on the stack.
    </para>
  </refsect1>

  <refsect1 id="pam_env-options">
    <title>OPTIONS</title>
    <variablelist>

      <varlistentry>
        <term>
          <option>conffile=<replaceable>/path/to/pam_env.conf</replaceable></option>
        </term>
        <listitem>
          <para>
            Indicate an alternative <filename>pam_env.conf</filename>
            style configuration file to override the default. This can
            be useful when different services need different environments.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>debug</option>
        </term>
        <listitem>
          <para>
            A lot of debug information is printed with
            <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>envfile=<replaceable>/path/to/environment</replaceable></option>
        </term>
        <listitem>
          <para>
            Indicate an alternative <filename>environment</filename>
            file to override the default. The syntax are simple
	    <emphasis>KEY=VAL</emphasis> pairs on separate lines. The
	    <emphasis>export</emphasis> instruction can be specified for bash
	    compatibility, but will be ignored.
	    This can be useful when different  services need different environments.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>readenv=<replaceable>0|1</replaceable></option>
        </term>
        <listitem>
          <para>
            Turns on or off the reading of the file specified by envfile
            (0 is off, 1 is on). By default this option is on.
          </para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term>
          <option>user_envfile=<replaceable>filename</replaceable></option>
        </term>
        <listitem>
          <para>
            Indicate an alternative <filename>.pam_environment</filename>
            file to override the default.The syntax is the same as
	    for <emphasis>/etc/security/pam_env.conf</emphasis>.
	    The filename is relative to the user home directory.
	    This can be useful when different services need different
	    environments.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>user_readenv=<replaceable>0|1</replaceable></option>
        </term>
        <listitem>
          <para>
            Turns on or off the reading of the user specific environment
            file. 0 is off, 1 is on. By default this option is off as user
            supplied environment variables in the PAM environment could affect
            behavior of subsequent modules in the stack without the consent
            of the system administrator.
          </para>
          <para>
            Due to problematic security this functionality is deprecated
            since the 1.5.0 version and will be removed completely at some
            point in the future.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1 id="pam_env-types">
    <title>MODULE TYPES PROVIDED</title>
    <para>
      The <option>auth</option> and <option>session</option> module
      types are provided.
    </para>
  </refsect1>

  <refsect1 id="pam_env-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_ABORT</term>
        <listitem>
           <para>
             Not all relevant data or options could be gotten.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_BUF_ERR</term>
        <listitem>
           <para>
              Memory buffer error.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_IGNORE</term>
        <listitem>
           <para>
             No pam_env.conf and environment file was found.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
           <para>
             Environment variables were set.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="pam_env-files">
    <title>FILES</title>
    <variablelist>
      <varlistentry>
        <term><filename>/etc/security/pam_env.conf</filename></term>
        <listitem>
          <para>Default configuration file</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>/etc/environment</filename></term>
        <listitem>
          <para>Default environment file</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>$HOME/.pam_environment</filename></term>
        <listitem>
          <para>User specific environment file</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="pam_env-see_also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam_env.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum>
      </citerefentry>.
    </para>
  </refsect1>

  <refsect1 id="pam_env-authors">
    <title>AUTHOR</title>
    <para>
      pam_env was written by Dave Kinchlea &lt;kinch@kinch.ark.com&gt;.
    </para>
  </refsect1>
</refentry>