lib/libpam/modules/pam_exec/pam_exec.8

   1 .\" Copyright (c) 2001,2003 Networks Associates Technology, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Portions of this software were developed for the FreeBSD Project by
   5 .\" ThinkSec AS and NAI Labs, the Security Research Division of Network
   6 .\" Associates, Inc.  under DARPA/SPAWAR contract N66001-01-C-8035
   7 .\" ("CBOSS"), as part of the DARPA CHATS research program.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. The name of the author may not be used to endorse or promote
  18 .\"    products derived from this software without specific prior written
  19 .\"    permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd February 8, 2012
  36 .Dt PAM_EXEC 8
  37 .Os
  38 .Sh NAME
  39 .Nm pam_exec
  40 .Nd Exec PAM module
  41 .Sh SYNOPSIS
  42 .Op Ar service-name
  43 .Ar module-type
  44 .Ar control-flag
  45 .Pa pam_exec
  46 .Op Ar arguments
  47 .Sh DESCRIPTION
  48 The exec service module for PAM executes the program designated by
  49 its first argument if no options are specified, with its remaining
  50 arguments as command-line arguments.
  51 If options are specified, the program and its arguments follow the last
  52 option or
  53 .Cm --
  54 if the program name conflicts with an option name.
  55 .Pp
  56 The following options may be passed before the program and its
  57 arguments:
  58 .Bl -tag -width ".Cm return_prog_exit_status"
  59 .It Cm return_prog_exit_status
  60 Use the program exit status as the return code of the pam_sm_* function.
  61 It must be a valid return value for this function.
  62 .It Cm --
  63 Stop options parsing;
  64 program and its arguments follow.
  65 .El
  66 .Pp
  67 The child's environment is set to the current PAM environment list,
  68 as returned by
  69 .Xr pam_getenvlist 3 .
  70 In addition, the following PAM items are exported as environment
  71 variables:
  72 .Ev PAM_RHOST ,
  73 .Ev PAM_RUSER ,
  74 .Ev PAM_SERVICE ,
  75 .Ev PAM_SM_FUNC ,
  76 .Ev PAM_TTY
  77 and
  78 .Ev PAM_USER .
  79 .Pp
  80 The
  81 .Ev PAM_SM_FUNC
  82 variable contains the name of the PAM service module function being
  83 called.
  84 It may be:
  85 .Bl -dash -offset indent -compact
  86 .It
  87 pam_sm_acct_mgmt
  88 .It
  89 pam_sm_authenticate
  90 .It
  91 pam_sm_chauthtok
  92 .It
  93 pam_sm_close_session
  94 .It
  95 pam_sm_open_session
  96 .It
  97 pam_sm_setcred
  98 .El
  99 .Pp
 100 If
 101 .Cm return_prog_exit_status
 102 is not set (default), the
 103 .Ev PAM_SM_FUNC
 104 function returns
 105 .Er PAM_SUCCESS
 106 if the program exit status is 0,
 107 .Er PAM_PERM_DENIED
 108 otherwise.
 109 .Pp
 110 If
 111 .Cm return_prog_exit_status
 112 is set, the program exit status is used.
 113 It should be
 114 .Er PAM_SUCCESS
 115 or one of the error codes allowed by the calling
 116 .Ev PAM_SM_FUNC
 117 function.
 118 The valid codes are documented in each function man page.
 119 If the exit status is not a valid return code,
 120 .Er PAM_SERVICE_ERR
 121 is returned.
 122 Each valid codes numerical value is available as an environment variable
 123 (eg.\&
 124 .Ev PAM_SUCESS ,
 125 .Ev PAM_USER_UNKNOWN ,
 126 etc).
 127 This is useful in shell scripts for instance.
 128 .Sh SEE ALSO
 129 .Xr pam_get_item 3 ,
 130 .Xr pam.conf 5 ,
 131 .Xr pam 8 ,
 132 .Xr pam_sm_acct_mgmt 8 ,
 133 .Xr pam_sm_authenticate 8 ,
 134 .Xr pam_sm_chauthtok 8 ,
 135 .Xr pam_sm_close_session 8 ,
 136 .Xr pam_sm_open_session 8 ,
 137 .Xr pam_sm_setcred 8
 138 .Sh AUTHORS
 139 The
 140 .Nm
 141 module and this manual page were developed for the
 142 .Fx
 143 Project by
 144 ThinkSec AS and NAI Labs, the Security Research Division of Network
 145 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
 146 .Pq Dq CBOSS ,
 147 as part of the DARPA CHATS research program.