lib/libpam/modules/pam_exec/pam_exec.8

   1 .\" Copyright (c) 2001,2003 Networks Associates Technology, Inc.
   2 .\" Copyright (c) 2017 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 August 14, 2018
  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 .It Cm --
  80 Stop options parsing;
  81 program and its arguments follow.
  82 .El
  83 .Pp
  84 The child's environment is set to the current PAM environment list,
  85 as returned by
  86 .Xr pam_getenvlist 3 .
  87 In addition, the following PAM items are exported as environment
  88 variables:
  89 .Ev PAM_RHOST ,
  90 .Ev PAM_RUSER ,
  91 .Ev PAM_SERVICE ,
  92 .Ev PAM_SM_FUNC ,
  93 .Ev PAM_TTY
  94 and
  95 .Ev PAM_USER .
  96 .Pp
  97 The
  98 .Ev PAM_SM_FUNC
  99 variable contains the name of the PAM service module function being
 100 called.
 101 It may be:
 102 .Bl -dash -offset indent -compact
 103 .It
 104 pam_sm_acct_mgmt
 105 .It
 106 pam_sm_authenticate
 107 .It
 108 pam_sm_chauthtok
 109 .It
 110 pam_sm_close_session
 111 .It
 112 pam_sm_open_session
 113 .It
 114 pam_sm_setcred
 115 .El
 116 .Pp
 117 If
 118 .Cm return_prog_exit_status
 119 is not set (default), the
 120 .Ev PAM_SM_FUNC
 121 function returns
 122 .Er PAM_SUCCESS
 123 if the program exit status is 0,
 124 .Er PAM_PERM_DENIED
 125 otherwise.
 126 .Pp
 127 If
 128 .Cm return_prog_exit_status
 129 is set, the program exit status is used.
 130 It should be
 131 .Er PAM_SUCCESS
 132 or one of the error codes allowed by the calling
 133 .Ev PAM_SM_FUNC
 134 function.
 135 The valid codes are documented in each function man page.
 136 If the exit status is not a valid return code,
 137 .Er PAM_SERVICE_ERR
 138 is returned.
 139 Each valid codes numerical value is available as an environment variable
 140 (eg.\&
 141 .Ev PAM_SUCESS ,
 142 .Ev PAM_USER_UNKNOWN ,
 143 etc).
 144 This is useful in shell scripts for instance.
 145 .Sh SEE ALSO
 146 .Xr pam_get_item 3 ,
 147 .Xr pam.conf 5 ,
 148 .Xr pam 8 ,
 149 .Xr pam_sm_acct_mgmt 8 ,
 150 .Xr pam_sm_authenticate 8 ,
 151 .Xr pam_sm_chauthtok 8 ,
 152 .Xr pam_sm_close_session 8 ,
 153 .Xr pam_sm_open_session 8 ,
 154 .Xr pam_sm_setcred 8
 155 .Sh AUTHORS
 156 The
 157 .Nm
 158 module and this manual page were developed for the
 159 .Fx
 160 Project by
 161 ThinkSec AS and NAI Labs, the Security Research Division of Network
 162 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
 163 .Pq Dq CBOSS ,
 164 as part of the DARPA CHATS research program.