Perl Module

The perl module processes attributes through a Perl interpreter.

Please see the raddb/mods-config/perl/example.pl sample.
Please see http://www.perl.org/docs.html for more information about the Perl language.

As of FreeRADIUS v4, the Perl subroutine names called when the perl module is called are automatically derived from the section in which they are called.

e.g. if perl is called in recv Access-Request, firstly a subroutine recv_access_request will be looked for. If that does not exist, then a subroutine recv will be looked for.

This can be overridden by setting func_recv_access_request or func_recv to point to a different subroutine name.

In addition the option func_detach can be used to set a subroutine to call during shutdown.

Each subroutine called during a packet processing section is passed a hash ref which represents the packet.

The hash contains 4 keys request, reply, control and session-state which allow access to the pairs in those FreeRADIUS pair lists.

Nested attributes are represented by nested hashes, while leaf attributes are represented by arrays, allowing access to individual instances of the attribute.

For example, if the perl subroutine starts with my $p = shift(), then attributes in the request can be accessed using syntax of the form:

Perl syntax

FreeRADIUS attribute

%p→{'request'}{'foo'}[0]

request.foo

%p→{'request'}{'baa'}{'baz'}[1]

request.baa.baz[1]

%p→{'request'}{'baa'}{2}{'baz'}[0]

request.baa[2].baz

The interface between FreeRADIUS and Perl is mostly strings.

Attributes of type string are copied to Perl as-is. They are not escaped or interpreted.

Attributes of type octets are copied to Perl as-is. They are not escaped or interpreted.

Numeric attributes are passed as the appropriate Perl numeric type.

All other attributes are printed, and passed to Perl as a string value.

IP addresses are sent as strings, e.g. "192.0.2.25", and not as a 4-byte binary value. The same applies to other attribute data types.

Attributes can be set by assigning values to the array entries of leaf nodes. E.g.

$p→{'reply'}{'foo'}[0] = 'baa'

In addition, the Perl array functions push, pop, shift and unshift can be used to add or remove instances of attributes.

The return codes from functions in the perl_script are passed directly back to the server. These codes are defined in mods-config/example.pl

Configuration Settings

filename: Module to load functions from.

The Perl script to execute when the module is called. This is very similar to using the exec module, but it is persistent, and therefore faster.

perl_flags: Options which are passed to the Perl interpreter.

These are (mostly) the same options as are passed to the perl command line.

The most useful flag is -T. This sets tainting on. Using this flag makes it impossible to leverage bad User-Names into local command execution.

Delete this next line to allow people to pwn your FreeRADIUS server.

func_detach: Subroutine to call during server shutdown

Sample subroutine name overrides

These options cause the old FreeRADIUS v3 default subroutine names to be used

config { … }: You can define configuration items (and nested sub-sections) in perl config { … } section. These items will be accessible in the perl script through %RAD_PERLCONF hash.

For instance:

$RAD_PERLCONF{'name'}
$RAD_PERLCONF{'sub-config'}->{'name'}

Default Configuration

perl {
	filename = ${modconfdir}/${.:instance}/example.pl
	perl_flags = "-T"
#	func_detach = detach
#	func_recv_access_request = authorize
#	func_recv_accounting_request = preacct
#	func_send = postauth
#	config {
#		name = "value"
#		sub-config {
#			name = "value of name from config.sub-config"
#		}
#	}
}