.TH pam_radius_auth 8
.\" Copyright 2017 Cumulus Networks, Inc.  All rights reserved.
.\" Based on USAGE file in the source package
.SH NAME
pam_radius_auth.so \- PAM RADIUS client plugin
.SH SYNOPSIS
.SH DESCRIPTION
.B pam_radius_auth
is the RADIUS client PAM plugin.
It supports IPv4 and IPv6 connections to a RADIUS server.  It only supports
authentication and accounting for sessions, it does not support changing passwords,
because the RADIUS protocol does not support it.
.PP
This PAM module takes a number of standard PAM configuration options,
as well as some specific to this plugin.
.PP
These options can be enabled by editing the generated entries in the
.I /etc/pam.d
directory to add them to the radius plugin.  The files can be found by running
the command:
.IP
.B grep radius /etc/pam.d/*
.PP
They can also be set by editing the configuration file
.I /usr/share/pam-configs/radius
and then running
.B pam-auth-config
to re-generate the files in /etc/pam.d/.
.BR NOTE :
The file
.I /usr/share/pam-configs/radius
is not a configuration file, and may be overwritten on upgrades.
.PP
All of the following arguments are optional, and can be combined as needed.
Note that not all of these options are relevant in for all uses of the module.
.TP
.I accounting_bug
When used, the accounting response vector is NOT
validated.  This option will probably only be necessary
on REALLY OLD (i.e. Livingston 1.16) servers.
.TP
.I client_id=bar
send a NAS-Identifier RADIUS attribute with string 'bar'.
If the client_id is not specified, the PAM_SERVICE
type is used instead. ('login', 'su', 'passwd', etc.)
This feature may be disabled by using 'client_id='.
i.e. A blank client ID.
.TP
.I conf=foo
set the configuration filename to 'foo'.
The default is
.IR /etc/pam_radius_auth.conf .
.TP
.I debug
print out extensive debugging information via pam_log.
These messages generally end up being handled by
syslog(), and go to /var/log/messages.  Depending on
your host operating system, the log messages may be
elsewhere.
.IP
This variable may also be set in the
.I /etc/pam_radius_auth
file.  See that file for details.
.IP
You should generally use the debug option when first
trying configuring this module, as it will help
enormously in tracking down problems.
.TP
.I force_prompt
Request a new password and not using the previously entered
password. This useful for multi-factor authentication
when used with a Token.
.TP
.I localifdown
This option tells pam_radius to return PAM_IGNORE instead
of PAM_AUTHINFO_UNAVAIL if RADIUS auth failed due to
network unavailability.  PAM_IGNORE tells the pam stack
to continue down the stack regardless of the control flag.
.TP
.I max_challenge=#
configure maximum number of challenges that a server
may request. This is a workaround for broken servers
and disabled by default.
.TP
.I retry=#
How many times to re-send a packet if there is no
response.  Once the retry count has been reached,
the module fails, and PAM continues to the next module.
.TP
.I prompt=string
Specifies the prompt, without the ': ', that PAM should
display when prompting for the password. This is useful
when using hardware tokens as part of multi-factor
authentication and presenting the same prompt twice would
confuse users.  Use prompt=TokenCode (or some other
relevant string different from Password) in this
situation.
.TP
.I ruser
If PAM_USER is root, Use the value of PAM_RUSER instead
of PAM_USER to determine the username to authenticate via
RADIUS.  This is to allow 'su' to act like 'sudo'.
.TP
.I skip_passwd
Do not prompt for a password, even if there was none
retrieved from the previous layer.
Send the previous one (if it exists), or else send a NULL
password.
If this fails, exit.
If an Access-Challenge is returned, display the challenge
message, and ask the user for the response.
Return success/failure as appropriate.
.IP
The password sent to the next authentication module will
NOT be the response to the challenge.  If a password from
a previous authentication module exists, it is passed on.
Otherwise, no password is sent to the next module.
.TP
.I try_first_pass
Instead of prompting the user for a password, retrieve
the password from the previous authentication module.
If the password exists, try it, and return success if it
passes.
If there was no previous password, or the previous password
fails authentication, prompt the user with
"Enter RADIUS password: ", and ask for another password.
Try this password, and return success/failure as appropriate.
.IP
This is the default for authentication.
.TP
.I use_first_pass
Instead of prompting the user for a password, retrieve
the password from the previous authentication module.
If the password does not exist, return failure.
If the password exists, try it, returning success/failure
as appropriate.
.TP
.I use_authtok
force the use of a previously entered password.
This is  needed for pluggable password strength checking
i.e. try cracklib to be sure it's secure, then go update
the RADIUS server.
.SH "SEE ALSO"
.BR pam_radius_auth (5),
.BR nss_mapuser (5),
.BR pam-auth-update (8)
.SH FILES
.IR /etc/pam_radius_auth.conf ,
- RADIUS client configuration parameters
.I /usr/share/pam-config/radius
- configuration to generate RADIUS entries in the PAM files
.SH AUTHOR
Dave Olson <olson@cumulusnetworks.com>, based on the USAGE file written by multiple
contributors