$Header: /cvsroot/pam-cifs/pam-cifs/INSTALL,v 1.7 2006/08/02 07:46:32 bjornts Exp $

pam_cifs - Linux-PAM module for mount/umount CIFS shares

Copyright (C) 2005  Wilhelm Meier (meier@informatik.fh-kl.de)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-----------------------------------------------------------------


Quick Install
-------------

1) make all

2) cp pam_cifs.so /lib/security
   (will be done by: make install)

3) edit /etc/pam.d/system-auth
   pam_cifs must be able to get the auth-token (sse below). Place it after 
   pam_unix (local users don't have access to shared cifs ressources) 
   and before pam_ldap (use_first_pass) 

4) cp cifsumountd /usr/sbin
   (will be done by: make install)

5) (gentoo) use cifsumount-script for starting/stopping the daemon 
   SIGHUP: to enforce a new check if somethong can be unmounted
   SIGTERM: normal termination

Limitations:
------------

1) It can only mount CIFS-shares. This not much of a limitation, since the is the only purpose
   of this module. Other filesystems should be mounted by other means, either pam-modules 
   or e.g. the automounter 


Options
-------

(for default values: see pam_cifs.h)

1) debug 

if this option (without value) is given, most actions are logged via syslog

(the following option are only for session-management)

2) prefix=<pathToMountPointPrefix>
3) suffix=<mountPointSuffix>

the actual mount-point will be: <prefix>/<username><suffix>

4) source=<unc>
5) ssuffix=<sourcesuffix>

the actual source-name will be: <source>/<username><sourcesuffix>

6) linkname=<name>

if this opion is given, a link from $HOME/<name> to the actual mount-point 
will be created if not already there 

7) min_uid=<number>
8) max_uid=<number>

mount-operations will be only performed if min_uid <= <uid> <= max_uid

9) make_mount_point

if this option is given, the mount-point <prefix>/<username><suffix> will be created. 
As a prerequisite, the directory <prefix> must already exist.

10) windomain=<domain>

specifies the windows-domain to mount from

11) mount_home

mount as users home. Can't be used together with make_mount_point.
In addition, suffix must be set to first element of home directory
path (regexp) for cifsumountd to work with this.

12) options

Options to mount.cifs, to be given behind -o to the mount command. 
Comma-separated list of options.  Note that "options=serverino" is
necessary with mount_home for KDE to work with a cifs-mounted home
directory, for instance.

13) background

Sets whether the execution of the pam stack is to wait for the 
mount.cifs command to finish (background=0) or not (background=1).
The latter is a lot faster, the former is useful if you've got 
processes starting at the end of the pam stack which depend on 
access to the mounted volume.

Requisites:
-----------

1) pam_mkhomedir (to make the home dir (if needed))
2) pam_ldap
3) nss_ldap

4) cifs-kernel-support > 1.34

5) mount.cifs


Sample /etc/pam.d/system-auth:
--------------------

The following /etc/pam.d/system-auth is an example! In this case, local users (/etc/passwd, /etc/shadow)
are authenticated via pam_unix.so, so the can't use network shares with pam_cifs, because 
pam_unix.so is sufficient and before pam_cifs.so. Users from the LDAP can use network shares.

If this is not what you want, place pam_cifs.so (required) before pam_unix.so (suffcient) and pam_ldap.so (suffcient). Use use_first_pass option for pam_unix.so and pam_ldap.so.

#%PAM-1.0

auth       required	/lib/security/pam_env.so
auth       sufficient	/lib/security/pam_unix.so likeauth nullok # get auth-token, local users don't use pam_cifs
auth       required	/lib/security/pam_cifs.so debug # get the auth-token
auth       sufficient	/lib/security/pam_ldap.so use_first_pass debug
auth       required	/lib/security/pam_deny.so

account    sufficient	/lib/security/pam_ldap.so debug
account    required	/lib/security/pam_unix.so

password   required	/lib/security/pam_cracklib.so retry=3
password   sufficient	/lib/security/pam_ldap.so debug
password   sufficient	/lib/security/pam_unix.so nullok md5 shadow use_authtok
password   required	/lib/security/pam_deny.so

session    required	/lib/security/pam_limits.so
session    required	/lib/security/pam_mkhomedir.so umask=077 skel=/etc/skel # be sure to have a /etc/skel/windows
session    required	/lib/security/pam_unix.so
session    optional	/lib/security/pam_cifs.so debug min_uid=1001 make_mount_point linkname=windows

# If you want to enable pam_console, uncomment the following line
# and read carefully README.pam_console in /usr/share/doc/pam*
#session    optional	/lib/security/pam_console.so
