contrib/openpam/bin/pamtest/pamtest.1

   1 .\"-
   2 .\" Copyright (c) 2011 Dag-Erling Smørgrav
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $Id: pamtest.1 471 2011-11-03 09:44:40Z des $
  27 .\"
  28 .Dd November 2, 2011
  29 .Dt PAMTEST 1
  30 .Os
  31 .Sh NAME
  32 .Nm pamtest
  33 .Nd PAM policy tester
  34 .Sh SYNOPSYS
  35 .Nm
  36 .Op Fl dksv
  37 .Op Fl H Ar rhost
  38 .Op Fl h Ar host
  39 .Op Fl t Ar tty
  40 .Op Fl U Ar ruser
  41 .Op Fl u Ar user
  42 .Ar service
  43 .Op Ar command ...
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility offers an easy way to test PAM modules and policies from the
  48 command line.
  49 .Pp
  50 The
  51 .Nm
  52 utility loads the PAM policy specified by the
  53 .Ar service
  54 argument, starts a PAM transaction by calling
  55 .Xr pam_start 3 ,
  56 then executes the primitives specified by the remaining command-line
  57 arguments.
  58 Finally, it ends the transaction by calling
  59 .Xr pam_end 3 .
  60 .Pp
  61 The commands are:
  62 .Bl -tag -width 6n
  63 .It Cm authenticate , Cm auth
  64 Call
  65 .Xr pam_authenticate 3 .
  66 .It Cm acct_mgmt , Cm account
  67 Call
  68 .Xr pam_acct_mgmt 3 .
  69 .It Cm chauthtok , Cm change
  70 Call
  71 .Xr pam_chauthtok 3
  72 with the
  73 .Dv PAM_CHANGE_EXPIRED_AUTHTOK
  74 flag set.
  75 .It Cm forcechauthtok , Cm forcechange
  76 Call
  77 .Xr pam_chauthtok 3
  78 with no flags set.
  79 .It Cm setcred , Cm establish_cred
  80 Call
  81 .Xr pam_setcred 3
  82 with the
  83 .Dv PAM_ESTABLISH_CRED
  84 flag set.
  85 .It Cm open_session , Cm open
  86 Call
  87 .Xr pam_open_session 3 .
  88 .It Cm close_session , Cm close
  89 Call
  90 .Xr pam_close_session 3 .
  91 .It Cm unsetcred , Cm delete_cred
  92 Call
  93 .Xr pam_setcred 3
  94 with the
  95 .Dv PAM_DELETE_CRED
  96 flag set.
  97 .It Cm listenv , Cm env
  98 Call
  99 .Xr pam_getenvlist 3
 100 and print the contents of the list it returns.
 101 .El
 102 .Pp
 103 The following options are available:
 104 .Bl -tag -width Fl
 105 .It Fl d
 106 Enables debug messages within the OpenPAM library.
 107 See
 108 .Xr openpam_log 3
 109 for details.
 110 .It Fl H Ar rhost
 111 Specify the name of the fictitious remote host.
 112 The default is to use the name of the local host.
 113 .It Fl h Ar host
 114 Specify the name of the local host.
 115 The default is to use the result of calling
 116 .Xr gethostname 3 .
 117 .It Fl k
 118 Keep going even if one of the commands fails.
 119 .It Fl s
 120 Set the
 121 .Dv PAM_SILENT
 122 flag when calling the
 123 .Xr pam_authenticate 3 ,
 124 .Xr pam_acct_mgmt 3 ,
 125 .Xr pam_chauthok 3 ,
 126 .Xr pam_setcred 3 ,
 127 .Xr pam_open_session 3
 128 and
 129 .Xr pam_close_session 3
 130 primitives.
 131 .It Fl t Ar tty
 132 Specify the name of the tty.
 133 The default is to use the result of calling
 134 .Xr ttyname 3 .
 135 .It Fl U Ar ruser
 136 Specify the name of the supplicant (remote user).
 137 .It Fl u Ar user
 138 Specify the name of the principal (local user).
 139 .It Fl v
 140 Enables debug messages from
 141 .Nm
 142 itself.
 143 .El
 144 .Sh EXAMPLES
 145 Simulate a typical PAM transaction using the
 146 .Dq system
 147 policy:
 148 .Bd -literal -offset indent
 149 pamtest -v system auth account change setcred open close unsetcred
 150 .Ed
 151 .Sh SEE ALSO
 152 .Xr openpam 3
 153 .Xr pam 3
 154 .Xr pam.conf 5
 155 .Sh AUTHORS
 156 The
 157 .Nm
 158 utility and this manual page were written by
 159 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
 160 .Sh BUGS
 161 The
 162 .Nm
 163 utility does not (yet) support setting and getting individual PAM
 164 items or environment variables.
 165 .Pp
 166 The
 167 .Nm
 168 utility does not afford the user complete control over the flags
 169 passed to the
 170 .Xr pam_authenticate 3 ,
 171 .Xr pam_acct_mgmt 3 ,
 172 .Xr pam_chauthok 3 ,
 173 .Xr pam_setcred 3 ,
 174 .Xr pam_open_session 3
 175 and
 176 .Xr pam_close_session 3
 177 primitives.