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