Radius(3)

💖 Radius(3) — Authen::Radius 💖

okay bestie so this is the Authen::Radius page from the User Contributed Perl Documentation, and it's literally your whole cheat sheet for talking to a RADIUS server from Perl. no cap, it's a vibe. 🎀

---

✨ NAME ✨

Authen::Radius — it gives you simple Radius client facilities, fr fr. like, you want to send RADIUS requests and catch the responses without manually packing bytes like some kind of gremlin? this is the module for you. 💅

---

🌸 SYNOPSIS 🌸

like, the quickest possible taste test:

  use Authen::Radius;

  $r = new Authen::Radius(Host => 'myserver', Secret => 'mysecret');
  print "auth result=", $r->check_pwd('myname', 'mypwd'), "\n";

and here's the full-glam version where you build your own attributes 🦋:

  $r = new Authen::Radius(Host => 'myserver', Secret => 'mysecret');
  Authen::Radius->load_dictionary();
  $r->add_attributes (
        { Name => 'User-Name', Value => 'myname' },
        { Name => 'Password', Value => 'mypwd' },
# 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 => 'User-Password', Value => 'mypwd' },
        { Name => 'h323-return-code', Value => '0' }, # Cisco AV pair
        { Name => 'Digest-Attributes', Value => { Method => 'REGISTER' } }
  );
  $r->send_packet(ACCESS_REQUEST) and $type = $r->recv_packet();
  print "server response type = $type\n";
  for $a ($r->get_attributes()) {
    print "attr: name=$a->{'Name'} value=$a->{'Value'}\n";
  }

---

🌈 DESCRIPTION 🌈

so the "Authen::Radius" module hands you one simple class, and that class lets you send/receive Radius requests/responses to/from a Radius server. that's the whole thing. iconic. ✨

---

👑 CONSTRUCTOR 👑

💫 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 (😭 tragic). you can grab the error status with "Authen::Radius::get_error" (that's the errorcode) or "Authen::Radius::strerror" (the verbose error string), so you're never just standing there like 👁️👄👁️ wondering what happened.

• Service — the default is "radius", and the alternative is "radius-acct". If you do not specify port in the "Host" as a "hostname:port", then port specified in your /etc/services will be used. If there is nothing there, and you did not specify port either then default is 1645 for "radius" and 1813 for "radius-acct". yes, two whole port numbers, memorize them, iykyk.
• Debug — optional param, and any Perl true value turns on debugging (verbose mode). she's chatty. 💬
• LocalAddr — optional, and it may contain local IP/host bind address from which RADIUS packets are sent. so you can pick where you're dialing out from, main character energy. 🫶
• Rfc3579MessageAuth — optional, and it controls whether a Message-Authenticator attribute is generated for Access-Request packets (RFC3579, section 3.2). It is enabled by default to mitigate the Blast-RADIUS protocol vulnerability (https://www.blastradius.fail/); pass "Rfc3579MessageAuth => 0" to disable it when talking to a server that cannot handle the attribute. The Message-Authenticator is always generated for Status-Server packets. no take-backsies on that one.

⚠️ bestie please read this one — turning Rfc3579MessageAuth off is a deliberate security downgrade for the Blast-RADIUS vuln. only do it for servers that literally cannot handle the attribute. 💀

• NodeList — optional, and it 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 IP (with an optional port number), i.e. 'radius1.mytel.com' or 'radius.myhost.com:1812'.

so, Radius Cluster contains a set of Radius servers, and at any given moment of time only one server is considered to be "active" (so requests are send to this server). and you're like… how the active node is determined? 🧐 Initially in addition to the "NodeList" parameter you may supply the "Host" 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 "discovery" 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. first to the group chat wins. 💅

---

🦋 METHODS 🦋

🍓 load_dictionary ( [ DICTIONARY ], [format => 'freeradius' | 'gnuradius'] ) 🍓

Loads the definitions in the specified Radius dictionary file (standard Livingston radiusd format). Tries to load "/etc/raddb/dictionary" when no argument is specified, or dies. "format" should be specified if dictionary has other format (currently supported: FreeRADIUS and GNU Radius).

📌 NOTE: you need to load valid dictionary if you plan to send RADIUS requests with attributes other than just "User-Name"/"Password". like, literally don't skip this step, it's giving "why is nothing working" energy otherwise. 💀

🍓 check_pwd ( USERNAME, PASSWORD [,NASIPADDRESS] ) 🍓

Checks with the RADIUS server if the specified "PASSWORD" is valid for user "USERNAME". Unless "NASIPADDRESS" is specified, the script will attempt to determine it's local IP address (IP address for the RADIUS socket) and this value will be placed in the NAS-IP-Address attribute. ✨

this method is actually a wrapper for subsequent calls to "clear_attributes", "add_attributes", "send_packet" and "recv_packet" — she does a lot of work behind the scenes, humble queen. 👑

It returns 1 if the "PASSWORD" is correct, or undef otherwise.

🍓 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 "Name"d with their dictionary name (provided a dictionary has been loaded first), or with their raw Radius attribute-type values. The "Type" pair should be specified when adding attributes that are not in the dictionary (or when no dictionary was loaded). Values for "TYPE" can be '"string"', '"integer"', '"ipaddr"', '"ipv6addr"', '"ipv6prefix"', '"ifid"' or '"avpair"'. The "VENDOR" may be Vendor's name from the dictionary or their integer id. For tagged attributes (RFC2868) tag can be specified in "Name" using 'Name:Tag' format, or by using "Tag" pair. TAG value is expected to be an integer, within [1:31] range (zero value isn't supported). 🙈

🍓 get_attributes 🍓

Returns a list of references to anon hashes with the following key/value pairs : { Name => NAME, Code => RAWTYPE, Value => VALUE, RawValue => RAWVALUE, Vendor => VENDOR, Tag => TAG, AttrName => NAME }. Each hash represents an attribute in the current object.

The "Name" and "Value" pairs will contain values as translated by the dictionary (if one was loaded). The "Code" and "RawValue" 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 "Value" undefined and "Name" set to attribute ID ("Code" value). For tagged attribute (RFC2868), it will include the tag into the "NAME" as 'Name:Tag'. Original Name is stored in "AttrName". Also value of tag is stored in "Tag" (undef for non-tagged attributes). it's giving "every detail, every time." 💅

🍓 clear_attributes 🍓

Clears all attributes for the current object. fresh start, blank slate, new era. 🧚

🍓 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 "REQUEST_TYPE". Exported "REQUEST_TYPE" methods are "ACCESS_REQUEST", "ACCESS_ACCEPT", "ACCESS_REJECT", "ACCESS_CHALLENGE", "ACCOUNTING_REQUEST", "ACCOUNTING_RESPONSE", "ACCOUNTING_STATUS", "STATUS_SERVER", "DISCONNECT_REQUEST", "DISCONNECT_ACCEPT", "DISCONNECT_REJECT", "COA_REQUEST", "COA_ACCEPT", "COA_REJECT", "COA_ACK", and "COA_NAK". Returns the number of bytes sent, or undef on failure. ✨

If the RETRANSMIT 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. so it's the same request, just re-run through the group chat. 🔁

🍓 recv_packet ( DETECT_BAD_ID ) 🍓

Receives a Radius reply packet. Returns the Radius Reply type (see possible values for "REQUEST_TYPE" in method "send_packet") or undef on failure. Note that failure may be due to a failed recv() or a bad Radius response authenticator. Use "get_error" to find out. 🔍

If the DETECT_BAD_ID parameter is supplied and contains a non-zero value, then calculation of the packet identifier is performed before authenticator check and EBADID error returned in case when packet identifier from the response doesn't match to the request. If the DETECT_BAD_ID is not provided or contains zero value then EBADAUTH returned in such case. two different error flavors, pick your fighter. 💀

🍓 set_timeout ( TIMEOUT ) 🍓

Sets socket I/O activity timeout. "TIMEOUT" should be specified in floating seconds since the epoch. ⏰

🍓 get_error 🍓

Returns the last "ERRORCODE" for the current object. Errorcodes are one-word strings always beginning with an '"E"'. iconic naming convention honestly. 👑

🍓 strerror ( [ ERRORCODE ] ) 🍓

Returns a verbose error string for the last error for the current object, or for the specified "ERRORCODE". she'll explain it to you nicely. 🫶

🍓 error_comment 🍓

Returns the last error explanation for the current object. Error explanation is generated by system call.

🍓 get_active_node 🍓

Returns currently active radius node in standard numbers-and-dots notation with port delimited by colon. like 1.2.3.4:1812 vibes. 🌸

---

💜 AUTHOR 💜

Carl Declerck <carl@miskatonic.inbe.net> — original design. Alexander Kapitanenko <kapitan at portaone.com> and Andrew Zhilenko <andrew at portaone.com> — later modifications. 🎀

PortaOne Development Team <perl-radius at portaone.com> is the current module's maintainer at CPAN. thank you for your service, legends. 🫡

---

and that's the whole page bestie!! 🌈 this shipped as part of perl v5.42.2, dated 2026-05-19 — so if anyone asks, that's the version and date on this Radius(3) page. now go forth and authenticate. slay. 💅✨