This file describes howto get/install and configure pam_smb.

How to I get pam_smb?
=-------------------=

pam_smb releases are available from the SAMBA FTP mirrors (see http://samba.org/samba)

Development on pamsmb is done on sourceforge, the project name is pamsmb
see the project page at http://sf.net/projects/pamsmb

The webpage for pam_smb and FAQ are at:

http://pamsmb.sourceforge.net

How do I install pam_smb?
=-----------------------=

Unpack the distribution and cd to the top level directory.
pam_smb uses the GNU configure system, so run

./configure
make
make install

This will install
pam_smb_auth.so in /lib/security
and 
pamsmbd in usually /usr/local/sbin/pamsmbd

Current options to configure for pam_smb are

--disable-encrypt-pass	Disable Encrypted Passwords
--disable-root-only	Disable root only access to the message queue
--disable-use-daemon	Disable pamsmbd


How do I Configure it?
=--------------------=

The pam_smb modules has four configuration steps,
	a) pam.conf and /etc/pam.d configuration + command line parameters.
	b) pam_smb.conf configuration file.
	c) pam_smb.usermap username mapping database
	d) starting pamsmbd at boot time.

a) pam.conf, /etc/pam.d and command line options
	The first thing that needs to be done is the pam module needs
to be inserted into the pam system configuration files so that it is used
for the services the administrator wishes. This procedure is slightly different under Linux and Solaris.

For Linux: the pam config files are stored in /etc/pam.d (one for each service)
my /etc/pam.d/login file is included here

#%PAM-1.0
auth       required     /lib/security/pam_securetty.so
auth       required     /lib/security/pam_smb_auth.so
auth       required     /lib/security/pam_nologin.so
account    required     /lib/security/pam_pwdb.so
password   required     /lib/security/pam_cracklib.so
password   required     /lib/security/pam_pwdb.so shadow nullok use_authtok
session    required     /lib/security/pam_pwdb.so

note the pam_pwdb auth line is removed or commented out.

For Solaris:
        You need to change the /etc/pam.conf other line to

other   auth required   /usr/lib/security/pam_smb_auth.so.1

Pam_smb has some command line parameters that can be passed within the PAM configuration files:

	1. debug - This switches on syslog debugging of the module.
	2. use_first_pass - This is a standard PAM Module command line option.
	*********** N.B. Danger lurks here somewhere *****************
	3. nolocal - This allows authentication of a username/password
			pair which are not in the local password file.
		 Do not switch this on unless you know what you are at.
		 please see the FAQ.
	**************************************************************
	4. cachetime=N, where N is the number of minutes to cache the authentication. if N>1, the cache will keep entries for N minutes, for N=0, it will not cache the entry and for N=-1, the entry will not expire.

b) pam_smb.conf configuration file

The configuration file is stored in /etc/pam_smb.conf and it consists of multiple lines each consisting of a domain and two servers comma separated.

NB: there are no spaces in this file.
e.g.
my local copy is for two domains, STAFF and UNDERGRADUATE and their servers.

UNDERGRADUATE,UGRADPDC,UGRADBDC
STAFF,STAFFPDC,STAFFBDC

A special domain, _TRUSTEDDOMAINS_ may be used to authenticate a user against
all domains using the _TRUSTEDDOMAINS_ servers. More info on the domain trusting is available in the FAQ.

*You must include a PDC and BDC in this list. You cannot have only one. If you don't have a BDC just specify the same machine twice.*

c) Username mapping
In order to get username mapping support you need a file in /etc called for
pam_smb.usermap which has lines of the style

unixuser=NTDOMAIN\ntuser

NTDOMAIN can be omitted and the first domain in the pam_smb.conf file will be used. This mapping is one-to-one and allows either the Unix or NT name to be user at login time.

d) Daemon

pamsmbd needs to be started at boot-time, this depends on your distribution, there is a script in scripts/pamsmbd that can be copied to /etc/rc.d/init.d on redhat systems and linked into the RH rc.d tree.

The daemon accepts four signals, to control it.
TERM - exits the daemon.
USR1 - resets the user authentication cache file
HUP - re-reads the configuration file and pam_smb.usermap file.
USR2 - should print the number of users in the cache to syslog (this may need some more testing...)

Common problems
===============
If you are using pam_smb for user authentication where they are going to access
a user-specific resource on the system, such as ssh, login or where details such as UID or GIDs will be needed, then you MUST have local users on the UNIX system corresponding to the users on the NT box, these users must either have the same usernames or use the username mapping code in the v2 daemon.

If you are just using pam_smb for a yes/no answer, such as a proxy server access list or web password system, you can use the nolocal option to pam_smb to have it avoid looking up local system files.

If you don't want to use local or NIS passwd files, you might want to look at the winbind project part of the main samba project.

