Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PAM(8)				  PAM Manual				PAM(8)

       PAM - Pluggable Authentication Modules


       This manual is intended to offer	a quick	introduction to	PAM.  For more
       information the reader is directed to the Linux-PAM system  administra-
       tors' guide.

       PAM  Is	a  system of libraries that handle the authentication tasks of
       applications (services) on the system.  The library provides  a	stable
       general interface (Application Programming Interface - API) that	privi-
       lege granting programs (such as login(1)	and su(1)) defer to to perform
       standard	authentication tasks.

       The principal feature of	the PAM	approach is that the nature of the au-
       thentication is dynamically configurable.  In other words,  the	system
       administrator is	free to	choose how individual service-providing	appli-
       cations will authenticate users.	This dynamic configuration is  set  by
       the  contents  of the single PAM	configuration file /etc/pam.conf.  Al-
       ternatively, the	configuration can be set by  individual	 configuration
       files  located  in the /etc/pam.d/ directory.  The presence of this di-
       rectory will cause PAM to ignore	/etc/pam.conf.

       From the	point of view of the system administrator, for whom this  man-
       ual  is provided, it is not of primary importance to understand the in-
       ternal behavior of the PAM library.  The	important point	 to  recognize
       is  that	the configuration file(s) define the connection	between	appli-
       cations (services) and the pluggable authentication modules (PAMs) that
       perform the actual authentication tasks.

       PAM separates the tasks of authentication into four independent manage-
       ment groups: account management;	 authentication	 management;  password
       management;  and	 session  management.  (We highlight the abbreviations
       used for	these groups in	the configuration file.)

       Simply put, these groups	take care of different aspects	of  a  typical
       user's request for a restricted service:

       account - provide account verification types of service:	has the	user's
       password	expired?; is this user permitted access	to the requested  ser-

       authentication  - establish the user is who they	claim to be. Typically
       this is via some	challenge-response request that	the user must satisfy:
       if you are who you claim	to be please enter your	password.  Not all au-
       thentications are of this type, there exist hardware based  authentica-
       tion  schemes  (such  as	the use	of smart-cards and biometric devices),
       with suitable modules, these may	be  substituted	 seamlessly  for  more
       standard	approaches to authentication - such is the flexibility of PAM.

       password	 - this	group's	responsibility is the task of updating authen-
       tication	mechanisms. Typically, such services are strongly  coupled  to
       those of	the auth group.	Some authentication mechanisms lend themselves
       well to being updated with such a  function.  Standard  UN*X  password-
       based  access  is the obvious example: please enter a replacement pass-

       session - this group of tasks cover things that should be done prior to
       a service being given and after it is withdrawn.	Such tasks include the
       maintenance of audit trails and the mounting of the user's home	direc-
       tory.  The session management group is important	as it provides both an
       opening and closing hook	for modules to affect the  services  available
       to a user.

The configuration file(s)
       When  a	PAM  aware privilege granting application is started, it acti-
       vates its attachment to the PAM-API.  This activation performs a	number
       of  tasks,  the	most  important	being the reading of the configuration
       file(s):	/etc/pam.conf.	Alternatively, this may	be the contents	of the
       /etc/pam.d/ directory.

       These  files  list  the	PAMs that will do the authentication tasks re-
       quired by this service, and the appropriate behavior of the PAM-API  in
       the event that individual PAMs fail.

       The  syntax  of the /etc/pam.conf configuration file is as follows. The
       file is made up of a list of rules, each	rule is	typically placed on  a
       single  line, but may be	extended with an escaped end of	line: `\<LF>'.
       Comments	are preceded with `#' marks and	extend	to  the	 next  end  of

       The  format of each rule	is a space separated collection	of tokens, the
       first three being case-insensitive:

	  service  type	 control  module-path  module-arguments

       The syntax of files contained in	the /etc/pam.d/	directory, are identi-
       cal except for the absence of any service field.	In this	case, the ser-
       vice is the name	of the file in the /etc/pam.d/ directory.  This	 file-
       name must be in lower case.

       An  important  feature of PAM, is that a	number of rules	may be stacked
       to combine the services of a number of PAMs for a given	authentication

       The  service is typically the familiar name of the corresponding	appli-
       cation: login and su are	good examples. The service-name, other,	is re-
       served  for  giving default rules.  Only	lines that mention the current
       service (or in the absence of such, the other entries) will be  associ-
       ated with the given service-application.

       The  type  is  the management group that	the rule corresponds to. It is
       used to specify which of	the management groups the subsequent module is
       to  be associated with. Valid entries are: account; auth; password; and
       session.	 The meaning of	each of	these tokens was explained above.

       The third field,	control, indicates the behavior	of the PAM-API	should
       the  module  fail  to succeed in	its authentication task. Valid control
       values are: requisite - failure of such a PAM results in	the  immediate
       termination of the authentication process; required - failure of	such a
       PAM will	ultimately lead	to the PAM-API returning failure but only  af-
       ter the remaining stacked modules (for this service and type) have been
       invoked;	sufficient - success of	such a module is enough	to satisfy the
       authentication  requirements  of	 the  stack of modules (if a prior re-
       quired module has failed	the success of this one	is ignored);  optional
       -  the success or failure of this module	is only	important if it	is the
       only module in the stack	associated with	this service+type.

       module-path - this is the full filename of the PAM to be	 used  by  the

       module-arguments	 - these are a space separated list of tokens that can
       be used to modify the specific behavior of the given  PAM.  Such	 argu-
       ments will be documented	for each individual module.

       /etc/pam.conf - the configuration file
       /etc/pam.d/  -  the  PAM	 configuration directory. If this directory is
       present,	the /etc/pam.conf file is ignored.
       /usr/lib/ - the dynamic library
       /usr/lib/pam_*.so - the PAMs

       Typically errors	generated by the PAM  system  of  libraries,  will  be
       written to syslog(3).

       DCE-RFC 86.0, October 1995.
       Contains	additional features, currently under consideration by the DCE-
       RFC committee.

       None known.

       The three Linux-PAM Guides, for System administrators, module  develop-
       ers, and	application developers.

PAM 0.56			  1997 Feb 9				PAM(8)


Want to link to this manual page? Use this URL:

home | help