illumos pam.d

pam.conf.4.diff

--- old_man     Sat Jun 30 12:29:25 2012
+++ new_man_1   Sat Jun 30 12:29:15 2012
@@ -1,416 +1,433 @@
 
 
 
 File Formats                                          PAM.CONF(4)
 
 
 
 NAME
-     pam.conf - configuration file for  pluggable  authentication
+     pam.d, pam.conf - configuration for pluggable authentication
      modules
 
 SYNOPSIS
+     /etc/pam.d
      /etc/pam.conf
 
 
 DESCRIPTION
-     pam.conf is the configuration file for the Pluggable Authen-
-     tication  Module architecture, or PAM. A PAM module provides
-     functionality for one or more  of  four  possible  services:
-     authentication,  account management, session management, and
-     password management.
+     /etc/pam.d is the configuration directory for the  Pluggable
+     Authentication  Module  architecture,  or PAM.  A PAM module
+     provides functionality for one or more of four possible ser-
+     vices:  authentication,  account management, session manage-
+     ment, and password management.  The configuration  directory
+     contains  per-service  'shards'  of  the  legacy, monolithic
+     pam.conf file.
 
      authentication service module
 
          Provides functionality to authenticate a user and set up
          user credentials.
 
 
      account management module
 
          Provides  functionality  to  determine  if  the  current
          user's  account  is  valid.   This includes checking for
          password and account expiration, as  well  as  verifying
          access hour restrictions.
 
 
      session management module
 
          Provides functionality to set  up  and  terminate  login
          sessions.
 
 
      password management module
 
          Provides functionality to change a user's authentication
          token or password.
 
 
 
      Each of the four service modules can  be  implemented  as  a
      shared  library  object  which  can  be  referenced  in  the
      pam.conf configuration file.
 
   Simplified pam.conf Configuration File
      The pam.conf file contains a listing of services. Each  ser-
      vice  is  paired with a corresponding service module. When a
      service is requested, its associated module is invoked. Each
      entry  may be a maximum of 256 characters, including the end
      of line, and has the following format:
 
        service_name module_type control_flag module_path options
 
 
 
 
+     If shard files are used in /etc/pam.d instead of the  monol-
+     ithic  pam.conf  file,  then  the service_name column is not
+     present in  those  files.   The  service_name  is,  instead,
+     derived  from the filename of the shard.  As an example, for
+     the service  'login'  the  configuration  would  now  be  in
+     /etc/pam.d/login and would omit the first column (previously
+     containing 'login').
+
+
      The following is an example of a pam.conf configuration file
      with support for authentication, account management, session
      management and password management modules (See the pam.conf
      file  that  is  shipped with your system for the contents of
      this file):
 
        login   auth requisite          pam_authtok_get.so.1
        login   auth required           pam_dhkeys.so.1
        login   auth required           pam_unix_auth.so.1
        login   auth required           pam_dial_auth.so.1
 
        other   account requisite       pam_roles.so.1
        other   account required        pam_unix_account.so.1
 
        other   session required        pam_unix_session.so.1
 
        other   password required       pam_dhkeys.so.1
        other   password requisite      pam_authtok_get.so.1
        other   password requisite      pam_authtok_check.so.1
        other   password required       pam_authtok_store.so.1
 
 
 
      service_name denotes the service (for example, login,  dtlo-
      gin, or rlogin).
 
 
      The keyword, "other," indicates the module  that  all  other
      applications  which  have not been specified should use. The
      "other" keyword can also be used if all services of the same
      module_type have the same requirements.
 
 
      In the example, since all of the services use the same  ses-
      sion module, they could have been replaced by a single other
      line.
 
 
      module_type denotes the service module type:  authentication
      (auth),  account  management  (account),  session management
      (session), or password management (password).
 
 
      The control_flag field determines the behavior of stacking.
 
 
      The module_path field specifies the relative pathname  to  a
      shared  library  object,  or  an  included PAM configuration
      file, which implements the  service  functionality.  If  the
      pathname is not absolute, shared library objects are assumed
-     to be relative to /usr/lib/security/$ISA/, and included  PAM
-     configuration   files   are   assumed   to  be  relative  to
-     /usr/lib/security/.
+     to be relative to /usr/lib/security/$ISA/,  and  PAM  confi-
+     guration files included in shards are assumed to be relative
+     to /etc/pam.d/, or /usr/lib/security/  if  included  in  the
+     legacy pam.conf.
 
 
      The ISA token  is  replaced  by  an  implementation  defined
      directory  name  which defines the path relative to the cal-
      ling program's instruction set architecture.
 
 
      The options field is used by the PAM framework layer to pass
      module  specific  options  to  the  modules. It is up to the
      module to parse and interpret the options.
 
 
      This field can be used by the modules to turn  on  debugging
      or  to pass any module specific parameters such as a TIMEOUT
      value. The options supported by the modules  are  documented
      in their respective manual pages.
 
   Integrating Multiple Authentication Services With Stacking
      When a service_name of the same module_type is defined  more
      than  once,  the  service is said to be stacked. Each module
      referenced in the module_path for that service is then  pro-
      cessed  in  the  order  that  it occurs in the configuration
      file. The control_flag field specifies the continuation  and
      failure semantics of the modules, and can contain one of the
      following values:
 
      binding
                    If the service module returns success  and  no
                    preceding  required modules returned failures,
                    immediately return success without calling any
                    subsequent  modules. If a failure is returned,
                    treat  the  failure  as  a   required   module
                    failure,  and  continue  to  process  the  PAM
                    stack.
 
 
      include
                    Process the  lines from the PAM  configuration
                    file  that  is specified in the module_path at
                    this point in the  PAM  stack.  The  ``other''
                    keyword  is used if the specified service_name
                    is not found. 32 levels of included PAM confi-
                    guration  files are supported. Any options are
                    ignored.
 
      optional
                    If the service module returns success,  record
                    the  success,  and continue to process the PAM
                    stack. If a failure is returned, and it is the
                    first   optional   module  failure,  save  the
                    failure code as an optional failure.  Continue
                    to process the PAM stack.
 
 
      required
                    If the service module returns success,  record
                    the  success,  and continue to process the PAM
                    stack. If a failure is returned, and it is the
                    first  required failure, save the failure code
                    as a required failure.   Continue  to  process
                    the PAM stack.
 
 
      requisite
                    If the service module returns success,  record
                    the  success,  and continue to process the PAM
                    stack. If a failure is  returned,  immediately
                    return  the  first  non-optional failure value
                    recorded  without   calling   any   subsequent
                    modules. That is, return this failure unless a
                    previous required service module failed. If  a
                    previous  required service module failed, then
                    return the first of those values.
 
 
      sufficient
                    If the service module return  success  and  no
                    preceding  required modules returned failures,
                    immediately return success without calling any
                    subsequent  modules. If a failure is returned,
                    treat  the  failure  as  an  optional   module
                    failure,  and  continue  to  process  the  PAM
                    stack.
 
 
 
      If the PAM stack runs to  completion,  that  is,  neither  a
      requisite  module failed, nor a binding or sufficient module
      success stops it, success is returned if no required modules
      failed and at least one required, requisite, optional module
      succeeded. If no module succeeded and a required or  binding
      module  failed, the first of those errors is returned. If no
      required or binding module failed  and  an  optional  module
      failed,  the  first of the option module errors is returned.
      If no module in the stack succeeded or failed, that is,  all
      modules  returned an ignore status, a default error based on
      module  type,  for  example,  "User  account  expired,"   is
      returned.
 
 
      All errors in pam.conf  entries  are  logged  to  syslog  as
      LOG_AUTH  |  LOG_ERR  errors.  The  use of a service with an
      error noted in the pam.conf  entry  for  that  service  will
      fail.  The  system  administrator  will  need to correct the
      noted errors before that service may be used. If no services
      are  available  or  the pam.conf file is missing, the system
      administrator may enter system maintenance mode  to  correct
      or restore the file.
 
 
      The following is a sample configuration file that stacks the
      su, login, and rlogin services.
 
        su     auth required       pam_inhouse.so.1
        su     auth requisite      pam_authtok_get.so.1
        su     auth required       pam_dhkeys.so.1
        su     auth required       pam_unix_auth.so.1
 
        login   auth requisite     pam_authtok_get.so.1
        login   auth required      pam_dhkeys.so.1
        login   auth required      pam_unix_auth.so.1
        login   auth required      pam_dial_auth.so.1
        login   auth optional      pam_inhouse.so.1
 
        rlogin  auth sufficient    pam_rhosts_auth.so.1
        rlogin  auth requisite     pam_authtok_get.so.1
        rlogin  auth required      pam_dhkeys.so.1
        rlogin  auth required      pam_unix_auth.so.1
 
 
 
      In the case of su, the user is authenticated by the  inhouse
      and   authtok_get,   dhkeys,  and  unix_auth  authentication
      modules.  Because the inhouse and the  other  authentication
      modules  are  required and requisite, respectively, an error
      is returned back to the application if any module fails.  In
      addition,  if  the requisite authentication (pam_authtok_get
      authentication) fails, the other authentication modules  are
      never invoked, and the error is returned immediately back to
      the application.
 
 
      In the case of login, the required keyword for  control_flag
      requires  that the user be allowed to login only if the user
      is  authenticated   by   all   the   service   modules.   If
      pam_unix_auth  authentication  fails,  control  continues to
      proceed down  the  stack,  and  the  inhouse  authentication
      module  is  invoked.  inhouse  authentication is optional by
      virtue of the optional keyword in  the  control_flag  field.
      The  user  can  still  log in even if inhouse authentication
      fails, assuming the modules stacked above succeeded.
 
 
      In  the  case  of  rlogin,  the   sufficient   keyword   for
      control_flag  specifies  that  if  the rhosts authentication
      check succeeds, then PAM should return success to rlogin and
      rlogin  should not prompt the user for a password. The other
      authentication modules, which are in the stack, will only be
      invoked  if  the  rhosts check fails.  This gives the system
      administrator the flexibility to determine if  rhosts  alone
      is sufficient enough to authenticate a remote user.
 
 
      Some modules return PAM_IGNORE  in  certain  situations.  In
      these  cases  the  PAM framework ignores the entire entry in
      pam.conf  regardless  of  whether  or  not  it  is  binding,
      requisite, required, optional, or sufficient.
 
   Utilities and Files
      The specific service names and module types for each service
      should  be  documented in the man page for that service. For
      instance, the sshd(1M) man page lists all of the PAM service
      names and module types for the sshd command.
 
 
      The PAM configuration file does not dictate either the  name
      or the location of the service specific modules. The conven-
      tion, however, is the following:
 
      pam_module_name.so.x
                                   File  that  implements  various
                                   function  of specific authenti-
                                   cation services. As  the  rela-
                                   tive     pathname    specified,
                                   /usr/lib/security/$ISA       is
                                   prepended to it.
 
 
      /etc/pam.conf
                                   Configuration file
 
 
+     /etc/pam.d
+                                  Configuration directory
+
+
      /usr/lib/$ISA/libpam.so.1
                                   File that  implements  the  PAM
                                   framework library
 
 
 EXAMPLES
      Example 1 Using the include control flag
 
      The following example collects the common Unix modules  into
      a  single  file to be included as needed in the example of a
      pam.conf  file.  The  common  Unix  module  file  is   named
      unix_common and consists of:
 
 
        OTHER   auth requisite          pam_authtok_get.so.1
        OTHER   auth required           pam_dhkeys.so.1
        OTHER   auth required           pam_unix_auth.so.1
        OTHER   auth required           pam_unix_cred.so.1
        OTHER   account requisite       pam_roles.so.1
        OTHER   account required        pam_unix_account.so.1
        OTHER   session required        pam_unix_session.so.1
        OTHER   password required       pam_dhkeys.so.1
        OTHER   password requisite      pam_authtok_get.so.1
        OTHER   password requisite      pam_authtok_check.so.1
        OTHER   password required       pam_authtok_store.so.1
 
 
 
 
      The pam.conf file and consists of:
 
 
        # Authentication management
        #
        # login service (explicit because of pam_dial_auth)
        #
        login   auth include            unix_common
        login   auth required           pam_dial_auth.so.1
        #
        # rlogin service (explicit because of pam_rhost_auth)
        #
        rlogin  auth sufficient         pam_rhosts_auth.so.1
        rlogin  auth include            unix_common
        #
        # Default definitions for Authentication management
        # Used when service name is not explicitly mentioned
        #
        OTHER   auth include            unix_common
        #
        # Default definition for Account management
        # Used when service name is not explicitly mentioned
        #
        OTHER   account include       unix_common
        #
        # Default definition for Session management
        # Used when service name is not explicitly mentioned
        #
        OTHER   session include         unix_common
        #
        # Default definition for  Password management
        # Used when service name is not explicitly mentioned
        #
        OTHER   password include        unix_common
 
 
 
 ATTRIBUTES
      See attributes(5) for descriptions of the  following  attri-
      butes:
 
 
 
      _______________________________________
     |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
     |____________________|_________________|
     | Interface Stability|  See Below.     |
     |____________________|_________________|
 
 
 
      The format is Stable. The contents has no  stability  attri-
      butes.
 
 SEE ALSO
      login(1),    passwd(1),     in.ftpd(1M),     in.rlogind(1M),
      in.rshd(1M),    in.telnetd(1M),    in.uucpd(1M),   init(1M),
      rpc.rexd(1M),  sac(1M),   ttymon(1M),   su(1M),   pam(3PAM),
      syslog(3C),    libpam(3LIB),    attributes(5),   environ(5),
      pam_authtok_check(5),                    pam_authtok_get(5),
      pam_authtok_store(5),       pam_dhkeys(5),      pam_krb5(5),
      pam_passwd_auth(5),  pam_unix_account(5),  pam_unix_auth(5),
      pam_unix_session(5)
 
 NOTES
      The pam_unix module is no longer  supported.  Similar  func-
      tionality     is     provided    by    pam_authtok_check(5),
      pam_authtok_get(5),   pam_authtok_store(5),   pam_dhkeys(5),
      pam_passwd_auth(5),  pam_unix_account(5),  pam_unix_auth(5),
      and pam_unix_session(5).
 
 
      With the removal of the pam_unix module, the SunOS delivered
      PAM   service   modules   no  longer  need  or  support  the
      "use_first_pass" or  "try_first_pass"  options.  This  func-
      tionality is provided by stacking pam_authtok_get(5) above a
      module that requires a password.