.TH "PAM_SSHAUTH" "8" "2015-07-02"
.nh
.ad l
.SH "NAME"
pam_sshauth \- PAM module which authenticates against an ssh server
.SH "SYNOPSIS"
.HP \w'\fBpam_sshauth\&.so\fR\ 'u
\fBpam_sshauth\&.so\fR [debug] [nostrict] [shm_askpass] [authtries=\fItries\fR] [try_first_pass] [host=\fIhost\fR] [port=\fIport\fR]
.SH "DESCRIPTION"
.PP
pam_sshauth is a PAM module that can be used to authenticate a user based on
whether they can ssh into an external machine\&.  It is written using sshlib\&.
.PP
The following PAM environment list variables are set by the module:
\fIPAM_SSHAUTH_HOST\fR
and
\fIPAM_SSHAUTH_PORT\fR\&.
Both of these reflect what was passed on the PAM command line to the module\&.
.PP
The module will attempt to initiate an SSH session with the host specified\&.  It
will support public-key, simple password, and keyboard-interactive
authentication methods\&.  Note that, in order for keyboard-interactive methods
to work, the SSH server must have enabled \fIChallengeResponseAuthentication\fR
in it's configuration\&.  This would be needed if you'd like the
\fBpam_sshauth\fR module to handle password expiry messages when talking to the
SSH server\&.
.PP
.SH "OPTIONS"
.PP
.PP
\fBdebug\fR
.RS 4
Log debug information to syslog\&.  The LOG_AUTH facility is used\&.
.RE
.PP
\fBnostrict\fR
.RS 4
If contacting a host for which we don't have an entry in
/etc/ssh/known_hosts, ask, via the pam prompts, if you'd like to trust
this host\&.  The default will be to fail the authentication\&.
.RE
.PP
\fBshm_askpass\fR
.RS 4
Properly handle interaction with the ASKPASS helper shm_askpass to allow
you to spawn ssh sockets\&.
.RE
.PP
\fBhost=\fR\fB\fIhost\fR\fR
.RS 4
Specifies the host we're to authenticate with\&.
.RE
.PP
\fBport=\fR\fB\fIport\fR\fR
.RS 4
Specifies the port we're to contact the remote ssh server on (if not specified,
it defaults to 22)\&.
.RE
.PP
\fBauthtries=\fR\fB\fInum\fR\fR
.RS 4
Specifies the number of times we will try to authenticate\&.  Defaults to 3\&.
Note that this is only the number of times \fBpam_sshauth\fR will try\&.  If the SSH
server has a smaller number specified via MaxAuthTries, \fBpam_sshauth\fR will not
override that\&.
.RE
.PP
\fBtry_first_pass\fR
.RS 4
Use the authentication token previously obtained by another module in the
pam stack\&.  If the token cannot be obtained, the \fBpam_sshauth\fR will prompt
for a password\&.
.RE
.PP
.SH "MODULE TYPES PROVIDED"
.PP
Only the \fBauth\fR module type is provided\&.
.SH "RETURN VALUES"
.PP
.PP
PAM_SUCCESS
.RS 4
The user authenticated successfully\&.
.RE
.PP
PAM_AUTH_ERR
.RS 4
The user did not authenticate successfully\&.
.RE
.PP
PAM_SYSTEM_ERR
.RS 4
A system error occurred in establishing the ssh connection to the host
specified\&.  Check the syslog for details\&.
.RE
.SH "EXAMPLES"
.PP
For an authentication line:
.sp
.if n \{\
.RS 4
.\}
.nf
        auth required pam_sshauth\&.so debug nostrict host=192.168.0.254 port=22
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBpam.conf\fR(5),
\fBpam.d\fR(5),
\fBpam\fR(7)
.SH "FILES"
/etc/ssh/ssh_known_hosts
.RS 4
Servers to be authenticated must have an entry present in this
file. The format of this file is documented in the \fBsshd\fR(8) man
page.
.SH "AUTHOR"
.PP
pam_sshauth was written by Scott Balneaves <sbalneav\&@ltsp\&.org\&>\&.