diff options
Diffstat (limited to 'modules/pam_namespace')
| -rw-r--r-- | modules/pam_namespace/.cvsignore | 6 | ||||
| -rw-r--r-- | modules/pam_namespace/Makefile.am | 3 | ||||
| -rw-r--r-- | modules/pam_namespace/README | 93 | ||||
| -rw-r--r-- | modules/pam_namespace/README.xml | 139 | ||||
| -rw-r--r-- | modules/pam_namespace/pam_namespace.8 | 161 |
5 files changed, 262 insertions, 140 deletions
diff --git a/modules/pam_namespace/.cvsignore b/modules/pam_namespace/.cvsignore new file mode 100644 index 00000000..9fb98574 --- /dev/null +++ b/modules/pam_namespace/.cvsignore @@ -0,0 +1,6 @@ +*.la +*.lo +.deps +.libs +Makefile +Makefile.in diff --git a/modules/pam_namespace/Makefile.am b/modules/pam_namespace/Makefile.am index 5d6dc018..38eb50ec 100644 --- a/modules/pam_namespace/Makefile.am +++ b/modules/pam_namespace/Makefile.am @@ -8,9 +8,10 @@ MAN8 = pam_namespace.8 man_MANS = $(MAN5) $(MAN8) -XMLS = namespace.conf.5.xml pam_namespace.8.xml +XMLS = README.xml namespace.conf.5.xml pam_namespace.8.xml if ENABLE_REGENERATE_MAN +noinst_DATA = README -include $(top_srcdir)/Make.xml.rules endif diff --git a/modules/pam_namespace/README b/modules/pam_namespace/README index 7edfe55e..c47ba232 100644 --- a/modules/pam_namespace/README +++ b/modules/pam_namespace/README @@ -1,3 +1,7 @@ +pam_namespace — PAM module for configuring namespace for a session + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + pam_namespace module: Setup a private namespace with polyinstantiated directories. @@ -24,25 +28,25 @@ Where: This field cannot be blank. <instance_prefix> - is the string prefix used to build the pathname for the - instantiation of <polydir>. The directory security context, or - optionally its md5sum string (32 hex characters), is appended to + instantiation of <polydir>. The directory security context, or + optionally its md5sum string (32 hex characters), is appended to the prefix to generate the final instance directory path. This directory is created if it did not exist already, and is then - bind mounted on the <polydir> to provide an instance of <polydir> - based on the <method> column. The special string $HOME is replaced with - the user's home directory, and $USER with the username. - This field cannot be blank. + bind mounted on the <polydir> to provide an instance of <polydir> + based on the <method> column. The special string $HOME is replaced with + the user's home directory, and $USER with the username. + This field cannot be blank. <method> - is the method used for polyinstantiation. It can take 3 different - values; "user" for polyinstantiation based on user name, "context" - for polyinstantiation based on process security context, and "both" - for polyinstantiation based on both user name and security context. - Methods "context" and "both" are only available with SELinux. This - field cannot be blank. + values; "user" for polyinstantiation based on user name, "context" + for polyinstantiation based on process security context, and "both" + for polyinstantiation based on both user name and security context. + Methods "context" and "both" are only available with SELinux. This + field cannot be blank. <list_of_uids> - is a comma separated list of user names for whom the - polyinstantiation is not performed. If left blank, polyinstantiation - will be performed for all users. + polyinstantiation is not performed. If left blank, polyinstantiation + will be performed for all users. EXAMPLE /etc/security/namespace.conf configuration file: ======================================================= @@ -68,55 +72,58 @@ EXAMPLE /etc/security/namespace.conf configuration file: # caution, as it will reduce security and isolation achieved by # polyinstantiation. # -/tmp /tmp-inst/ both root,adm -/var/tmp /var/tmp/tmp-inst/ both root,adm +/tmp /tmp-inst/ both root,adm +/var/tmp /var/tmp/tmp-inst/ both root,adm $HOME $HOME/$USER.inst/inst- context ARGUMENTS RECOGNIZED: debug - Verbose logging by syslog + Verbose logging by syslog unmnt_remnt - 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. + 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. unmnt_only - 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. + 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. require_selinux - If selinux is not enabled, return failure. + If selinux is not enabled, return failure. gen_hash - Instead of using the security context string for the instance - name, generate and use its md5 hash. + Instead of using the security context string for the instance + name, generate and use its md5 hash. ignore_config_error - 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. + 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. ignore_instance_parent_mode - 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. + 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. MODULE SERVICES PROVIDED: - session open_session and close_session + session open_session and close_session USAGE: - For the <service>s you need polyinstantiation (login for example) - put the following line in /etc/pam.d/<service> as the last line for - session group: + For the <service>s you need polyinstantiation (login for example) + put the following line in /etc/pam.d/<service> as the last line for + session group: + + session required pam_namespace.so [arguments] + + This module also depends on pam_selinux.so setting the context. + - session required pam_namespace.so [arguments] - This module also depends on pam_selinux.so setting the context. diff --git a/modules/pam_namespace/README.xml b/modules/pam_namespace/README.xml new file mode 100644 index 00000000..98ab7532 --- /dev/null +++ b/modules/pam_namespace/README.xml @@ -0,0 +1,139 @@ +<?xml version="1.0" encoding='UTF-8'?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" +"http://www.docbook.org/xml/4.4/docbookx.dtd"> +<article> + <articleinfo> + <title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="pam_namespace.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_namespace-name"]/*)'/> + </title> + </articleinfo> + <section> + <programlisting><![CDATA[ + +pam_namespace module: +Setup a private namespace with polyinstantiated directories. + +THEORY OF OPERATION: +The pam namespace module consults /etc/security/namespace.conf +configuration file and sets up a private namespace with polyinstantiated +directories for a session managed by PAM. A skeleton namespace.conf +installed by default provides example for polyinstantiating /tmp, /var/tmp +and users' home directory. + +If an executable script /etc/security/namespace.init 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. + +Each line in namespace.conf describes a limit for a user in the form: + +<polydir> <instance_prefix> <method> <list_of_uids> + +Where: +<polydir> - is the absolute pathname of the directory to polyinstantiate + Special entry $HOME is supported to designate user's home directory. + This field cannot be blank. + +<instance_prefix> - is the string prefix used to build the pathname for the + instantiation of <polydir>. The directory security context, or + optionally its md5sum string (32 hex characters), is appended to + the prefix to generate the final instance directory path. + This directory is created if it did not exist already, and is then + bind mounted on the <polydir> to provide an instance of <polydir> + based on the <method> column. The special string $HOME is replaced with + the user's home directory, and $USER with the username. + This field cannot be blank. + +<method> - is the method used for polyinstantiation. It can take 3 different + values; "user" for polyinstantiation based on user name, "context" + for polyinstantiation based on process security context, and "both" + for polyinstantiation based on both user name and security context. + Methods "context" and "both" are only available with SELinux. This + field cannot be blank. + +<list_of_uids> - is a comma separated list of user names for whom the + polyinstantiation is not performed. If left blank, polyinstantiation + will be performed for all users. + +EXAMPLE /etc/security/namespace.conf configuration file: +======================================================= +# Following three lines will polyinstantiate /tmp, /var/tmp and user's home +# directories. /tmp and /var/tmp will be polyinstantiated based on both +# security context as well as user name, whereas home directory will +# be polyinstantiated based on security context only. Polyinstantiation +# will not be performed for user root and adm for directories /tmp and +# /var/tmp, whereas home directories will be polyinstantiated for all +# users. The user name and/or context is appended to the instance prefix. +# +# Note that instance directories do not have to reside inside the +# polyinstantiated directory. In the examples below, instances of /tmp +# will be created in /tmp-inst directory, where as instances of /var/tmp +# and users home directories will reside within the directories that +# are being polyinstantiated. +# +# Instance parent directories must exist for the polyinstantiation +# mechanism to work. By default, they should be created with the mode +# of 000. pam_namespace module will enforce this mode unless it +# is explicitly called with an argument to ignore the mode of the +# instance parent. System administrators should use this argument with +# caution, as it will reduce security and isolation achieved by +# polyinstantiation. +# +/tmp /tmp-inst/ both root,adm +/var/tmp /var/tmp/tmp-inst/ both root,adm +$HOME $HOME/$USER.inst/inst- context + +ARGUMENTS RECOGNIZED: + debug + Verbose logging by syslog + + unmnt_remnt + 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. + + unmnt_only + 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. + + require_selinux + If selinux is not enabled, return failure. + + gen_hash + Instead of using the security context string for the instance + name, generate and use its md5 hash. + + ignore_config_error + 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. + + ignore_instance_parent_mode + 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. + +MODULE SERVICES PROVIDED: + session open_session and close_session + +USAGE: + For the <service>s you need polyinstantiation (login for example) + put the following line in /etc/pam.d/<service> as the last line for + session group: + + session required pam_namespace.so [arguments] + + This module also depends on pam_selinux.so setting the context. +]]> + </programlisting> + </section> +</article> + diff --git a/modules/pam_namespace/pam_namespace.8 b/modules/pam_namespace/pam_namespace.8 index 88594304..126cfc88 100644 --- a/modules/pam_namespace/pam_namespace.8 +++ b/modules/pam_namespace/pam_namespace.8 @@ -1,141 +1,110 @@ -.\"Generated by db2man.xsl. Don't modify this, modify the source. -.de Sh \" Subsection -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. -.TH "PAM_NAMESPACE" 8 "" "" "" -.SH NAME +.\" Title: pam_namespace +.\" Author: +.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Date: 06/27/2006 +.\" Manual: Linux\-PAM Manual +.\" Source: Linux\-PAM Manual +.\" +.TH "PAM_NAMESPACE" "8" "06/27/2006" "Linux\-PAM Manual" "Linux\-PAM Manual" +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.SH "NAME" pam_namespace \- PAM module for configuring namespace for a session .SH "SYNOPSIS" -.ad l -.hy 0 .HP 17 -\fBpam_namespace\&.so\fR [debug] [unmnt_remnt] [unmnt_only] [require_selinux] [gen_hash] [ignore_config_error] [ignore_instance_parent_mode] -.ad -.hy - +\fBpam_namespace.so\fR [debug] [unmnt_remnt] [unmnt_only] [require_selinux] [gen_hash] [ignore_config_error] [ignore_instance_parent_mode] .SH "DESCRIPTION" - .PP -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 \fI/etc/security/namespace\&.init\fR 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\&. - +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 +\fI/etc/security/namespace.init\fR +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. .PP -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\&. - +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. .SH "OPTIONS" - -.TP +.TP 3n \fBdebug\fR A lot of debug information is logged using syslog - -.TP +.TP 3n \fBunmnt_remnt\fR -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 - -.TP +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 +.TP 3n \fBunmnt_only\fR 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 - -.TP +.TP 3n \fBrequire_selinux\fR If selinux is not enabled, return failure - -.TP +.TP 3n \fBgen_hash\fR -Instead of using the security context string for the instance name, generate and use its md5 hash\&. - -.TP +Instead of using the security context string for the instance name, generate and use its md5 hash. +.TP 3n \fBignore_config_error\fR -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\&. - -.TP +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. +.TP 3n \fBignore_instance_parent_mode\fR -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\&. - +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. .SH "MODULE SERVICES PROVIDED" - .PP -The \fBsession\fR service is supported\&. - +The +\fBsession\fR +service is supported. .SH "RETURN VALUES" - -.TP +.TP 3n PAM_SUCCESS -Namespace setup was successful\&. - -.TP +Namespace setup was successful. +.TP 3n PAM_SERVICE_ERR -Unexpected system error occurred while setting up namespace\&. - -.TP +Unexpected system error occurred while setting up namespace. +.TP 3n PAM_SESSION_ERR -Unexpected namespace configuration error occurred\&. - +Unexpected namespace configuration error occurred. .SH "FILES" - -.TP -\fI/etc/security/namespace\&.conf\fR +.TP 3n +\fI/etc/security/namespace.conf\fR Configuration file - .SH "EXAMPLES" - .PP -For the <service>s you need polyinstantiation (login for example) put the following line in /etc/pam\&.d/<service> as the last line for session group: - +For the <service>s you need polyinstantiation (login for example) put the following line in /etc/pam.d/<service> as the last line for session group: .PP -session required pam_namespace\&.so [arguments] - +session required pam_namespace.so [arguments] .PP To use polyinstantiation with graphical display manager gdm, insert the following line, before exit 0, in /etc/gdm/PostSession/Default: - .PP /usr/sbin/gdm\-safe\-restart - .PP -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 \fI/etc/security/namespace\&.init\fR 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 \fI/etc/security/namespace\&.init\fR\&. In addition, perform the following changes to use graphical environment with polyinstantiation of /tmp: - +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 +\fI/etc/security/namespace.init\fR +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 +\fI/etc/security/namespace.init\fR. In addition, perform the following changes to use graphical environment with polyinstantiation of /tmp: .PP - +.sp +.RS 3n .nf - - 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 + 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 + 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\&. + /etc/gdm/custom.conf. .fi - - +.RE +.sp .SH "SEE ALSO" - .PP - \fBnamespace\&.conf\fR(5), \fBpam\&.d\fR(8), \fBmount\fR(8), \fBpam\fR(8)\&. +\fBnamespace.conf\fR(5), +\fBpam.d\fR(8), +\fBmount\fR(8), +\fBpam\fR(8). .SH "AUTHORS" - .PP -The namespace setup scheme was designed by Stephen Smalley, Janak Desai and Chad Sellers\&. The pam_namespace PAM module was developed by Janak Desai <janak@us\&.ibm\&.com>, Chad Sellers <csellers@tresys\&.com> and Steve Grubb <sgrubb@redhat\&.com>\&. - +The namespace setup scheme was designed by Stephen Smalley, Janak Desai and Chad Sellers. The pam_namespace PAM module was developed by Janak Desai <janak@us.ibm.com>, Chad Sellers <csellers@tresys.com> and Steve Grubb <sgrubb@redhat.com>. |