$Header: /cvsroot/pam-cifs/pam-cifs/INSTALL,v 1.13 2007/09/25 12:04:41 wimalopaan 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
   if you want to build without LDAP-support: export PAM_CIFS_WITHOUT_LDAP=1 

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> or source=ldap:<attributeName>
5) ssuffix=<sourcesuffix>

the actual source-name will be: <source>/<username><sourcesuffix>.
If the ldap-syntax for source is used, the value is taken from the
attribute <attributeName> from the users ldap-entry.

source must be a share-name. If not, pam_cifs tries to step up the 
path-components of source until it really can mount successfully a share
(this only works if background=0, see below). This can be useful in cases,
where the server exports only one share (e.g. //server/home) with the 
directories for each user in it, but these directories aren't exported themselves. 
In this case mount.cifs can't mount these directories, it only can mount the
share.

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=0|1

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=opt1,opt2,...

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=0|1

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.

14) ldap=<uri>

URI of the LDAP-Server (e.g. ldaps://host), which is used for some of the above 
parameters if they can be fetched via LDAP (e.g. source=ldap:homeDirectory)
pam_cifs can use the LDAP-connection of pam_ldap. For this to take place, don't (!)
insert pam_ldap into the session stack. If you do this, pam_ldap will delete its
connection.
pam_cifs will look into the pam-stack-variables if it can get pam_ldap data and then
extract the connection to the LDAP-Server.
(should not be neccessary if using together with pam_ldap)

15) ldapbasedn=<basedn>

The BaseDN for the search on LDAP-Server. 
(should not be neccessary if using together with pam_ldap)

16) ldapbinddn=<binddn>

The BindDN for connecting to the LDAP-Server
(should not be neccessary if using together with pam_ldap)

17) ldapbindpw=<password>

The BindPW for BindDN for connecting to the LDAP-Server
(should not be neccessary if using together with pam_ldap)

18) ldaploginattribute=<attributeName>

The LDAP-Attribute of a LDAP-Entry which resembles the user-account name 
e.g. sAMAccountName (if one uses MS AD-Server, otherwise uid)
(should not be neccessary if using together with pam_ldap)

19) ldapobjectclass=<objectClass>

The LDAP objectClass the ldap-object below <ldapbasedn>, which contains 
the <ldaploginattribute>, must belong to. Default value is "Users".

20) nouserinsource=0|1

If nouserinsource=1 is set, then the source-uri will be constructed 
as above but without the <user> component. You can see this as if <user>
is the empty string. This is useful for mounting group-shares: if the 
cifs-server allows mounting the group-share for a specific user-group and the 
mounting user belongs to that group, the mount should succeed. Multiple 
different users on the same machine can make their own private mounts of the 
group share. If the users require to mount several different groups shares, 
on should use multiple instances of pam_cifs in the session pam-stack.

21) unix=0|1
user local user ids (unix=0 default) or server user uids (unix=1, only with samba)

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
