



= 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.

NOTE: Uncomment any `func_*` configuration items below which are
included in your module. If the module is called for a section which
does not have a function defined, it will return `noop`.

WARNING: The Perl module does _not_ as yet support nested attributes,
or even flat attributes which have parents.  e.g. Vendor-Specific.Cisco.AVPair.
We hope to fix that soon.



## Configuration Settings

The following hashes are given to the module and
filled with value-pairs (Attribute names and values)

[options="header,autowidth"]
|===
| Value                    | Description
| %RAD_CONFIG              | Config items (was %RAD_CHECK).
| %RAD_REQUEST             | Attributes from the request.
| %RAD_REPLY               | Attributes for the reply.
| %RAD_REQUEST_PROXY       | Attributes from the proxied request.
| %RAD_REQUEST_PROXY_REPLY | Attributes from the proxy reply.
|===

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.

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.

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`


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.



List of functions in the module to call. Uncomment and change if you
want to use function names other than the defaults.



Control which attribute lists are replaced following calls to
the module.
The default is to not replace attribute lists.  Only enable
replacement where it is specifically required.



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:

[source,perl]
----
$RAD_PERLCONF{'name'}
$RAD_PERLCONF{'sub-config'}->{'name'}
----


== Default Configuration

```
perl {
	filename = ${modconfdir}/${.:instance}/example.pl
	perl_flags = "-T"
#	func_authenticate = authenticate
#	func_authorize = authorize
#	func_preacct = preacct
#	func_accounting = accounting
#	func_pre_proxy = pre_proxy
#	func_post_proxy = post_proxy
#	func_post_auth = post_auth
#	func_detach = detach
	replace {
#		request = no
#		reply = no
#		control = no
#		session = no
	}
#	config {
#		name = "value"
#		sub-config {
#			name = "value of name from config.sub-config"
#		}
#	}
}
```
