lib/libpam/modules/pam_exec/pam_exec.8

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