summaryrefslogtreecommitdiffstats
path: root/modules/pam_namespace/pam_namespace.8.xml
diff options
context:
space:
mode:
Diffstat (limited to 'modules/pam_namespace/pam_namespace.8.xml')
-rw-r--r--modules/pam_namespace/pam_namespace.8.xml418
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>