Adding upstream version 1.3.1.upstream/1.3.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 418 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 0000000..f0f80d3
--- /dev/null
+++ b/modules/pam_namespace/pam_namespace.8.xml
@@ -0,0 +1,418 @@
+<?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>
+      <arg choice="opt">
+        unmount_on_close
+      </arg>
+      <arg choice="opt">
+        use_current_context
+      </arg>
+      <arg choice="opt">
+        use_default_context
+      </arg>
+      <arg choice="opt">
+        mount_private
+      </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 instance directory after it is set up
+      and mounted on the polyinstantiated directory. The script receives the
+      polyinstantiated directory path, the instance directory path, flag
+      whether the instance directory was newly created (0 for no, 1 for yes),
+      and the user name 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>
+
+      <varlistentry>
+        <term>
+          <option>unmount_on_close</option>
+        </term>
+        <listitem>
+          <para>
+           Explicitly unmount the polyinstantiated directories instead
+           of relying on automatic namespace destruction after the last
+           process in a namespace exits. This option should be used
+           only in case it is ensured by other means that there cannot be
+           any processes running in the private namespace left after the
+           session close. It is also useful only in case there are
+           multiple pam session calls in sequence from the same process.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>use_current_context</option>
+        </term>
+        <listitem>
+          <para>
+	    Useful for services which do not change the SELinux context
+	    with setexeccon call. The module will use the current SELinux
+	    context of the calling process for the level and context
+	    polyinstantiation.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>use_default_context</option>
+        </term>
+        <listitem>
+          <para>
+	    Useful for services which do not use pam_selinux for changing
+	    the SELinux context with setexeccon call. The module will use
+	    the default SELinux context of the user for the level and context
+	    polyinstantiation.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <option>mount_private</option>
+        </term>
+        <listitem>
+          <para>
+	    This option can be used on systems where the / mount point or
+	    its submounts are made shared (for example with a
+	    <command>mount --make-rshared /</command> command).
+	    The module will mark the whole directory tree so any mount and
+	    unmount operations in the polyinstantiation namespace are private.
+	    Normally the pam_namespace will try to detect the
+	    shared / mount point and make the polyinstantiated directories
+	    private automatically. This option has to be used just when
+	    only a subtree is shared and / is not.
+          </para>
+          <para>
+	    Note that mounts and unmounts done in the private namespace will not
+	    affect the parent namespace if this option is used or when the
+	    shared / mount point is autodetected.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_namespace-types">
+    <title>MODULE TYPES PROVIDED</title>
+    <para>
+      Only the <option>session</option> module type is provided.
+      The module must not be called from multithreaded processes.
+    </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>Main configuration file</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><filename>/etc/security/namespace.d</filename></term>
+        <listitem>
+          <para>Directory for additional configuration files</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><filename>/etc/security/namespace.init</filename></term>
+        <listitem>
+          <para>Init script for instance directories</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>5</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;.
+      Additional improvements by Xavier Toth &lt;txtoth@gmail.com&gt; and Tomas Mraz
+      &lt;tmraz@redhat.com&gt;.
+    </para>
+  </refsect1>
+</refentry>