KDE can be configured to support the PAM ("Pluggable Authentication 
Module") system for password checking by the display manager kdm and 
by the screen saver kscreensaver (for unlocking the display).

PAM is a flexible application-transparent configurable user-authentication 
system found on FreeBSD, Solaris, and Linux, where it is most commonly
found on RedHat Linux systems.  (There may be ports to other unices too).

Information about PAM may be found on its homepage
      http://www.kernel.org/pub/linux/libs/pam/
(Despite the location, this information is NOT Linux-specific.)

Known Solaris Issues:
--------------------

For compiling PAM support on Solaris,  PAM_MESSAGE_NONCONST must
be defined.   This should now be handled automatically by the 
autoconf script:  just use ./configure --with-pam  . 

--------------------

If both PAM and shadow passwords are used on your system, do *NOT*
configure KDE for shadow password support: configure it for PAM, and PAM
will take care of everything.

Using PAM
---------

By default, use of PAM is DISABLED in KDE.  To enable it, use
./configure --with-pam

This form configures KDE to use the default PAM services "xdm",
(which is likely to be present and properly configured on most
PAM-aware systems) and "kscreensaver" (for password checking,
when unlocking  a locked screen).

 SINCE A PAM SERVICE "kscreensaver" IS NOT PRESENT BY DEFAULT, 
IT IS IMPORTANT THAT YOU CONFIGURE THIS PAM SERVICE.  
(An example configuration file "kscreensaver.pamd" is provided  in 
the top directory of the kdebase sources, but be aware that it may 
not be appropriate for your particular PAM version.) 
If the "kscreensaver" service is not provided, you will 
NOT be able to unlock a locked screen ...

If the PAM service "xdm" is not present, or if you wish to customize the
PAM configuration for kdm, use:

./configure --with-pam=<pam_service_name> 

where <pam_service_name> is the name of the PAM service you wish to use.  
(Note that the required pam service name "kscreensaver" will NOT be changed by
this configuration option, only the service name used by kdm is changed).

(Exception: --with-pam=yes is equivalent to --with-pam, and --with-pam=no
is equivalent to  --without-pam,  which is the default). 

You must then (as root) configure this new PAM service, if it has not
already been configured.  PAM services are generally configured by lines
beginning with the entry <pam_service_name> in a file /etc/pam.conf or, on
some systems, in individual files /etc/pam.d/<pam_service_name>.

If your system uses /etc/pam.d for configuration you may wish to use

./configure -with-pam=kde

so KDE uses a PAM service called "kde", and make a symlink
ln -s ./xdm /etc/pam.d/kde,  (assuming xdm is PAM-configured).

You can later customize your system by creating your own /etc/pam.d/kde.  
A sample (for RedHat Linux 5.x) is provided in kdebase/kde.pamd

PAM writes entries to the system log identified by the PAM service name;
this method has the advantage that such entries will identify the PAM
service involved as "kde" rather than "xdm", which is presumably not
running.

If there is ever any doubt about which PAM service name kdebase was
compiled with, it can be determined by examining the PAM-generated entries
in the system log associated with kdm logins or kscreensaver
authentication failures....


PAM configuration files have four types of entries for each service:

type		used by kdm		used by kscreensaver
----		-----------		--------------------
auth		    x				x
account		    x				
password	    x				
session		    x

There may be more than one entry of each type. Check existing PAM
configuration files and PAM documentation on your system for guidance as
to what entries to make.  If you call a PAM service that is not
configured, the default action of PAM is likely to be denial of service.

Note: kdm implements PAM "session" support, which is not implemented in
certain PAM-aware xdm's that it may be replacing (e.g., the Red Hat 
Linux 5.x xdm did not implement it).  This may be configured to carry out 
actions when a user opens or closes an kdm session, if a suitable PAM 
module is available (e.g., mount and unmount user-specific filesystems).

Note 2: Screensavers typically only authenticate a user to allow her to
continue working. They may also renew tokens etc., where supported.
See the Linux PAM Administrators guide, which is part of the PAM
distribution, for more details. 

$Id: README.pam,v 2.3 2001/01/30 23:09:27 esken Exp $
