Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------
        * modules/pam_namespace/pam_namespace.c: New module
        originally written by Janak Desai.
        * modules/pam_namespace/Makefile.am: New.
        * modules/pam_namespace/README: New.
        * modules/pam_namespace/md5.c: New.
        * modules/pam_namespace/md5.h: New.
        * modules/pam_namespace/namespace.conf: New.
        * modules/pam_namespace/namespace.conf.5: New.
        * modules/pam_namespace/namespace.conf.5.xml: New.
        * modules/pam_namespace/namespace.init: New.
        * modules/pam_namespace/pam_namespace.8: New.
        * modules/pam_namespace/pam_namespace.8.xml: New.
        * modules/Makefile.am: Added pam_namespace.
        * configure.in: Added pam_namespace, test for unshare
        library call.

1 files changed, 317 insertions, 0 deletions

diff --git a/modules/pam_namespace/pam_namespace.8.xml b/modules/pam_namespace/pam_namespace.8.xml
new file mode 100644
index 00000000..4c93ecf0
--- /dev/null
+++ b/modules/pam_namespace/pam_namespace.8.xml
@@ -0,0 +1,317 @@
+<?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_namespace'>
+
+  <refmeta>
+    <refentrytitle>pam_namespace</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id='pam_namespace-name'>
+    <refname>pam_namespace</refname>
+    <refpurpose>
+      PAM module for configuring namespace for a session
+    </refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_namespace-cmdsynopsis">
+      <command>pam_namespace.so</command>
+      <arg choice="opt">
+        debug
+      </arg>
+      <arg choice="opt">
+        unmnt_remnt
+      </arg>
+      <arg choice="opt">
+        unmnt_only
+      </arg>
+      <arg choice="opt">
+        require_selinux
+      </arg>
+      <arg choice="opt">
+        gen_hash
+      </arg>
+      <arg choice="opt">
+        ignore_config_error
+      </arg>
+      <arg choice="opt">
+        ignore_instance_parent_mode
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+
+  <refsect1 id="pam_namespace-description">
+    <title>DESCRIPTION</title>
+    <para>
+      The pam_namespace PAM module sets up a private namespace for a session
+      with polyinstantiated directories. A polyinstantiated directory
+      provides a different instance of itself based on user name, or when
+      using SELinux, user name, security context or both.  If an executable
+      script <filename>/etc/security/namespace.init</filename> exists, it
+      is used to initialize the namespace every time a new instance
+      directory is setup. The script receives the polyinstantiated
+      directory path and the instance directory path as its arguments.
+    </para>
+
+    <para>
+      The pam_namespace module disassociates the session namespace from
+      the parent namespace. Any mounts/unmounts performed in the parent
+      namespace, such as mounting of devices, are not reflected in the
+      session namespace. To propagate selected mount/unmount events from
+      the parent namespace into the disassociated session namespace, an
+      administrator may use the special shared-subtree feature. For
+      additional information on shared-subtree feature, please refer to
+      the mount(8) man page and the shared-subtree description at
+      http://lwn.net/Articles/159077 and http://lwn.net/Articles/159092.
+    </para>
+
+  </refsect1>
+
+  <refsect1 id="pam_namespace-options">
+    <title>OPTIONS</title>
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <option>debug</option>
+        </term>
+        <listitem>
+          <para>
+            A lot of debug information is logged using syslog
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>unmnt_remnt</option>
+        </term>
+        <listitem>
+          <para>
+            For programs such as su and newrole, the login
+            session has already setup a polyinstantiated
+            namespace. For these programs, polyinstantiation
+            is performed based on new user id or security
+            context, however the command first needs to
+            undo the polyinstantiation performed by login.
+            This argument instructs the command to
+            first undo previous polyinstantiation before
+            proceeding with new polyinstantiation based on
+            new id/context
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>unmnt_only</option>
+        </term>
+        <listitem>
+          <para>
+            For trusted programs that want to undo any
+            existing bind mounts and process instance
+            directories on their own, this argument allows
+            them to unmount currently mounted instance
+            directories
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>require_selinux</option>
+        </term>
+        <listitem>
+          <para>
+            If selinux is not enabled, return failure
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>gen_hash</option>
+        </term>
+        <listitem>
+          <para>
+            Instead of using the security context string
+            for the instance name, generate and use its
+            md5 hash.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>ignore_config_error</option>
+        </term>
+        <listitem>
+          <para>
+            If a line in the configuration file corresponding
+            to a polyinstantiated directory contains format
+            error, skip that line process the next line.
+            Without this option, pam will return an error
+            to the calling program resulting in termination
+            of the session.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>ignore_instance_parent_mode</option>
+        </term>
+        <listitem>
+          <para>
+	    Instance parent directories by default are expected to have
+	    the restrictive mode of 000. Using this option, an administrator
+	    can choose to ignore the mode of the instance parent. This option
+            should be used with caution as it will reduce security and
+            isolation goals of the polyinstantiation mechanism.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_namespace-services">
+    <title>MODULE SERVICES PROVIDED</title>
+    <para>
+      The <option>session</option> service is supported.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_namespace-return_values">
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+           <para>
+             Namespace setup was successful.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SERVICE_ERR</term>
+        <listitem>
+           <para>
+             Unexpected system error occurred while setting up namespace.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SESSION_ERR</term>
+        <listitem>
+           <para>
+             Unexpected namespace configuration error occurred.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_namespace-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/etc/security/namespace.conf</filename></term>
+        <listitem>
+          <para>Configuration file</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_namespace-examples">
+    <title>EXAMPLES</title>
+
+    <para>
+      For the &lt;service&gt;s you need polyinstantiation (login for example)
+      put the following line in /etc/pam.d/&lt;service&gt; as the last line for
+      session group:
+    </para>
+
+    <para>
+      session  required  pam_namespace.so [arguments]
+    </para>
+
+    <para>
+      To use polyinstantiation with graphical display manager gdm, insert the
+      following line, before exit 0, in /etc/gdm/PostSession/Default:
+    </para>
+
+    <para>
+      /usr/sbin/gdm-safe-restart
+    </para>
+
+    <para>
+      This allows gdm to restart after each session and appropriately adjust
+      namespaces of display manager and the X server. If polyinstantiation
+      of /tmp is desired along with the graphical environment, then additional
+      configuration changes are needed to address the interaction of X server
+      and font server namespaces with their use of /tmp to create
+      communication sockets. Please use the initialization script
+      <filename>/etc/security/namespace.init</filename> to ensure that
+      the X server and its clients can appropriately access the
+      communication socket X0. Please refer to the sample instructions
+      provided in the comment section of the instance initialization script
+      <filename>/etc/security/namespace.init</filename>. In addition,
+      perform the following changes to use graphical environment with
+      polyinstantiation of /tmp:
+    </para>
+
+    <para>
+    <literallayout>
+      1. Disable the use of font server by commenting out "FontPath"
+         line in /etc/X11/xorg.conf. If you do want to use the font server
+         then you will have to augment the instance initialization
+         script to appropriately provide /tmp/.font-unix from the
+         polyinstantiated /tmp.
+      2. Ensure that the gdm service is setup to use pam_namespace,
+         as described above, by modifying /etc/pam.d/gdm.
+      3. Ensure that the display manager is configured to restart X server
+         with each new session. This default setup can be verified by
+         making sure that /usr/share/gdm/defaults.conf contains
+         "AlwaysRestartServer=true", and it is not overridden by
+         /etc/gdm/custom.conf.
+    </literallayout>
+    </para>
+
+  </refsect1>
+
+  <refsect1 id="pam_namespace-see_also">
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>namespace.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_namespace-authors">
+    <title>AUTHORS</title>
+    <para>
+      The namespace setup scheme was designed by Stephen Smalley, Janak Desai
+      and Chad Sellers.
+      The pam_namespace PAM module was developed by Janak Desai &lt;janak@us.ibm.com&gt;, Chad Sellers &lt;csellers@tresys.com&gt; and Steve Grubb &lt;sgrubb@redhat.com&gt;.
+    </para>
+  </refsect1>
+</refentry>