.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Radius 3pm"
.TH Radius 3pm "2020-10-24" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Authen::Radius \- provide simple Radius client facilities
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Authen::Radius;
\&
\&  $r = new Authen::Radius(Host => \*(Aqmyserver\*(Aq, Secret => \*(Aqmysecret\*(Aq);
\&  print "auth result=", $r\->check_pwd(\*(Aqmyname\*(Aq, \*(Aqmypwd\*(Aq), "\en";
\&
\&  $r = new Authen::Radius(Host => \*(Aqmyserver\*(Aq, Secret => \*(Aqmysecret\*(Aq);
\&  Authen::Radius\->load_dictionary();
\&  $r\->add_attributes (
\&        { Name => \*(AqUser\-Name\*(Aq, Value => \*(Aqmyname\*(Aq },
\&        { Name => \*(AqPassword\*(Aq, Value => \*(Aqmypwd\*(Aq },
\&# RFC 2865 http://www.ietf.org/rfc/rfc2865.txt calls this attribute
\&# User\-Password. Check your local RADIUS dictionary to find
\&# out which name is used on your system
\&#       { Name => \*(AqUser\-Password\*(Aq, Value => \*(Aqmypwd\*(Aq },
\&        { Name => \*(Aqh323\-return\-code\*(Aq, Value => \*(Aq0\*(Aq }, # Cisco AV pair
\&        { Name => \*(AqDigest\-Attributes\*(Aq, Value => { Method => \*(AqREGISTER\*(Aq } }
\&  );
\&  $r\->send_packet(ACCESS_REQUEST) and $type = $r\->recv_packet();
\&  print "server response type = $type\en";
\&  for $a ($r\->get_attributes()) {
\&    print "attr: name=$a\->{\*(AqName\*(Aq} value=$a\->{\*(AqValue\*(Aq}\en";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Authen::Radius\*(C'\fR module provides a simple class that allows you to
send/receive Radius requests/responses to/from a Radius server.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( Host => \s-1HOST,\s0 Secret => \s-1SECRET\s0 [, TimeOut => \s-1TIMEOUT\s0] [,Service => \s-1SERVICE\s0] [, Debug => Bool] [, LocalAddr => hostname[:port]] [,Rfc3579MessageAuth => Bool] [,NodeList= NodeListArrayRef])" 4
.IX Item "new ( Host => HOST, Secret => SECRET [, TimeOut => TIMEOUT] [,Service => SERVICE] [, Debug => Bool] [, LocalAddr => hostname[:port]] [,Rfc3579MessageAuth => Bool] [,NodeList= NodeListArrayRef])"
Creates & returns a blessed reference to a Radius object, or undef on
failure.  Error status may be retrieved with \f(CW\*(C`Authen::Radius::get_error\*(C'\fR
(errorcode) or \f(CW\*(C`Authen::Radius::strerror\*(C'\fR (verbose error string).
.Sp
The default \f(CW\*(C`Service\*(C'\fR is \f(CW\*(C`radius\*(C'\fR, the alternative is \f(CW\*(C`radius\-acct\*(C'\fR.
If you do not specify port in the \f(CW\*(C`Host\*(C'\fR as a \f(CW\*(C`hostname:port\*(C'\fR, then port
specified in your \fI/etc/services\fR will be used. If there is nothing
there, and you did not specify port either then default is 1812 for
\&\f(CW\*(C`radius\*(C'\fR and 1813 for \f(CW\*(C`radius\-acct\*(C'\fR.
.Sp
Optional parameter \f(CW\*(C`Debug\*(C'\fR with a Perl \*(L"true\*(R" value turns on debugging
(verbose mode).
.Sp
Optional parameter \f(CW\*(C`LocalAddr\*(C'\fR may contain local IP/host bind address from
which \s-1RADIUS\s0 packets are sent.
.Sp
Optional parameter \f(CW\*(C`Rfc3579MessageAuth\*(C'\fR with a Perl \*(L"true\*(R" value turns on generating
of Message-Authenticator for Access-Request (\s-1RFC3579,\s0 section 3.2).
The Message-Authenticator is always generated for Status-Server packets.
.Sp
Optional parameter \f(CW\*(C`NodeList\*(C'\fR may contain a Perl reference to an array, containing a list of
Radius Cluster nodes. Each nodes in the list can be specified using a hostname or \s-1IP\s0 (with an optional
port number), i.e. 'radius1.mytel.com' or 'radius.myhost.com:1812'. Radius Cluster contains a set of Radius
servers, at any given moment of time only one server is considered to be \*(L"active\*(R"
(so requests are send to this server).
How the active node is determined? Initially in addition to the \f(CW\*(C`NodeList\*(C'\fR
parameter you may supply the \f(CW\*(C`Host\*(C'\fR parameter and specify which server should
become the first active node. If this parameter is absent, or the current
active node does not reply anymore, the process of \*(L"discovery\*(R" will be
performed: a request will be sent to all nodes and the consecutive communication
continues with the node, which will be the first to reply.
.SH "METHODS"
.IX Header "METHODS"
.IP "load_dictionary ( [ \s-1DICTIONARY\s0 ], [format => 'freeradius' | 'gnuradius'] )" 4
.IX Item "load_dictionary ( [ DICTIONARY ], [format => 'freeradius' | 'gnuradius'] )"
Loads the definitions in the specified Radius dictionary file (standard
Livingston radiusd format). Tries to load \f(CW\*(C`/etc/raddb/dictionary\*(C'\fR when no
argument is specified, or dies. \f(CW\*(C`format\*(C'\fR should be specified if dictionary has
other format (currently supported: FreeRADIUS and \s-1GNU\s0 Radius)
.Sp
\&\s-1NOTE:\s0 you need to load valid dictionary if you plan to send \s-1RADIUS\s0 requests
with attributes other than just \f(CW\*(C`User\-Name\*(C'\fR/\f(CW\*(C`Password\*(C'\fR.
.IP "check_pwd ( \s-1USERNAME, PASSWORD\s0 [,NASIPADDRESS] )" 4
.IX Item "check_pwd ( USERNAME, PASSWORD [,NASIPADDRESS] )"
Checks with the \s-1RADIUS\s0 server if the specified \f(CW\*(C`PASSWORD\*(C'\fR is valid for user
\&\f(CW\*(C`USERNAME\*(C'\fR. Unless \f(CW\*(C`NASIPADDRESS\*(C'\fR is specified, the script will attempt
to determine it's local \s-1IP\s0 address (\s-1IP\s0 address for the \s-1RADIUS\s0 socket) and
this value will be placed in the NAS-IP-Address attribute.
This method is actually a wrapper for subsequent calls to
\&\f(CW\*(C`clear_attributes\*(C'\fR, \f(CW\*(C`add_attributes\*(C'\fR, \f(CW\*(C`send_packet\*(C'\fR and \f(CW\*(C`recv_packet\*(C'\fR. It
returns 1 if the \f(CW\*(C`PASSWORD\*(C'\fR is correct, or undef otherwise.
.IP "add_attributes ( { Name => \s-1NAME,\s0 Value => \s-1VALUE\s0 [, Type => \s-1TYPE\s0] [, Vendor => \s-1VENDOR\s0] [, Tag => \s-1TAG\s0 ] }, ... )" 4
.IX Item "add_attributes ( { Name => NAME, Value => VALUE [, Type => TYPE] [, Vendor => VENDOR] [, Tag => TAG ] }, ... )"
Adds any number of Radius attributes to the current Radius object. Attributes
are specified as a list of anon hashes. They may be \f(CW\*(C`Name\*(C'\fRd with their
dictionary name (provided a dictionary has been loaded first), or with
their raw Radius attribute-type values. The \f(CW\*(C`Type\*(C'\fR pair should be specified
when adding attributes that are not in the dictionary (or when no dictionary
was loaded). Values for \f(CW\*(C`TYPE\*(C'\fR can be '\f(CW\*(C`string\*(C'\fR', '\f(CW\*(C`integer\*(C'\fR', '\f(CW\*(C`ipaddr\*(C'\fR',
\&'\f(CW\*(C`ipv6addr\*(C'\fR', '\f(CW\*(C`ipv6prefix\*(C'\fR', '\f(CW\*(C`ifid\*(C'\fR' or '\f(CW\*(C`avpair\*(C'\fR'. The \f(CW\*(C`VENDOR\*(C'\fR may be
Vendor's name from the dictionary or their integer id. For tagged attributes
(\s-1RFC2868\s0) tag can be specified in \f(CW\*(C`Name\*(C'\fR using 'Name:Tag' format, or by
using \f(CW\*(C`Tag\*(C'\fR pair. \s-1TAG\s0 value is expected to be an integer, within [1:31] range
(zero value isn't supported).
.IP "get_attributes" 4
.IX Item "get_attributes"
Returns a list of references to anon hashes with the following key/value
pairs : { Name => \s-1NAME,\s0 Code => \s-1RAWTYPE,\s0 Value => \s-1VALUE,\s0 RawValue =>
\&\s-1RAWVALUE,\s0 Vendor => \s-1VENDOR,\s0 Tag => \s-1TAG,\s0 AttrName => \s-1NAME\s0 }. Each hash
represents an attribute in the current object. The \f(CW\*(C`Name\*(C'\fR and \f(CW\*(C`Value\*(C'\fR pairs
will contain values as translated by the dictionary (if one was loaded). The
\&\f(CW\*(C`Code\*(C'\fR and \f(CW\*(C`RawValue\*(C'\fR pairs always contain the raw attribute type & value as
received from the server.  If some attribute doesn't exist in dictionary or
type of attribute not specified then corresponding \f(CW\*(C`Value\*(C'\fR undefined and
\&\f(CW\*(C`Name\*(C'\fR set to attribute \s-1ID\s0 (\f(CW\*(C`Code\*(C'\fR value). For tagged attribute (\s-1RFC2868\s0), it
will include the tag into the \f(CW\*(C`NAME\*(C'\fR as 'Name:Tag'. Original Name is stored in
\&\f(CW\*(C`AttrName\*(C'\fR.  Also value of tag is stored in \f(CW\*(C`Tag\*(C'\fR (undef for non-tagged
attributes).
.IP "clear_attributes" 4
.IX Item "clear_attributes"
Clears all attributes for the current object.
.IP "send_packet ( \s-1REQUEST_TYPE, RETRANSMIT\s0 )" 4
.IX Item "send_packet ( REQUEST_TYPE, RETRANSMIT )"
Packs up a Radius packet based on the current secret & attributes and
sends it to the server with a Request type of \f(CW\*(C`REQUEST_TYPE\*(C'\fR. Exported
\&\f(CW\*(C`REQUEST_TYPE\*(C'\fR methods are \f(CW\*(C`ACCESS_REQUEST\*(C'\fR, \f(CW\*(C`ACCESS_ACCEPT\*(C'\fR,
\&\f(CW\*(C`ACCESS_REJECT\*(C'\fR, \f(CW\*(C`ACCESS_CHALLENGE\*(C'\fR, \f(CW\*(C`ACCOUNTING_REQUEST\*(C'\fR, \f(CW\*(C`ACCOUNTING_RESPONSE\*(C'\fR,
\&\f(CW\*(C`ACCOUNTING_STATUS\*(C'\fR, \f(CW\*(C`STATUS_SERVER\*(C'\fR, \f(CW\*(C`DISCONNECT_REQUEST\*(C'\fR, \f(CW\*(C`DISCONNECT_ACCEPT\*(C'\fR,
\&\f(CW\*(C`DISCONNECT_REJECT\*(C'\fR, \f(CW\*(C`COA_REQUEST\*(C'\fR, \f(CW\*(C`COA_ACCEPT\*(C'\fR, \f(CW\*(C`COA_REJECT\*(C'\fR, \f(CW\*(C`COA_ACK\*(C'\fR,
and \f(CW\*(C`COA_NAK\*(C'\fR.
Returns the number of bytes sent, or undef on failure.
.Sp
If the \s-1RETRANSMIT\s0 parameter is provided and contains a non-zero value, then
it is considered that we are re-sending the request, which was already sent
previously. In this case the previous value of packet identifier is used.
.IP "recv_packet ( \s-1DETECT_BAD_ID\s0 )" 4
.IX Item "recv_packet ( DETECT_BAD_ID )"
Receives a Radius reply packet. Returns the Radius Reply type (see possible
values for \f(CW\*(C`REQUEST_TYPE\*(C'\fR in method \f(CW\*(C`send_packet\*(C'\fR) or undef on failure. Note
that failure may be due to a failed \fBrecv()\fR or a bad Radius response
authenticator. Use \f(CW\*(C`get_error\*(C'\fR to find out.
.Sp
If the \s-1DETECT_BAD_ID\s0 parameter is supplied and contains a non-zero value, then
calculation of the packet identifier is performed before authenticator check
and \s-1EBADID\s0 error returned in case when packet identifier from the response
doesn't match to the request. If the \s-1DETECT_BAD_ID\s0 is not provided or contains zero value then
\&\s-1EBADAUTH\s0 returned in such case.
.IP "set_timeout ( \s-1TIMEOUT\s0 )" 4
.IX Item "set_timeout ( TIMEOUT )"
Sets socket I/O activity timeout. \f(CW\*(C`TIMEOUT\*(C'\fR should be specified in floating seconds
since the epoch.
.IP "get_error" 4
.IX Item "get_error"
Returns the last \f(CW\*(C`ERRORCODE\*(C'\fR for the current object. Errorcodes are one-word
strings always beginning with an '\f(CW\*(C`E\*(C'\fR'.
.IP "strerror ( [ \s-1ERRORCODE\s0 ] )" 4
.IX Item "strerror ( [ ERRORCODE ] )"
Returns a verbose error string for the last error for the current object, or
for the specified \f(CW\*(C`ERRORCODE\*(C'\fR.
.IP "error_comment" 4
.IX Item "error_comment"
Returns the last error explanation for the current object. Error explanation
is generated by system call.
.IP "get_active_node" 4
.IX Item "get_active_node"
Returns currently active radius node in standard numbers-and-dots notation with
port delimited by colon.
.SH "AUTHOR"
.IX Header "AUTHOR"
Carl Declerck <carl@miskatonic.inbe.net> \- original design
Alexander Kapitanenko <kapitan at portaone.com> and Andrew
Zhilenko <andrew at portaone.com> \- later modifications.
.PP
PortaOne Development Team <perl\-radius at portaone.com> is
the current module's maintainer at \s-1CPAN.\s0