#  -*- text -*-
#
#
#  $Id: 2b0c971fa006b6767945e925fce3dffb2115e33c $

#######################################################################
#
#  = Perl Module
#
#  The `perl` module processes attributes through a Perl interpreter.
#
#  * Please see the `mods-config/perl/example.pl` sample.
#  * Please see http://www.perl.org/docs.html for more information about the
#  Perl language.
#
#  NOTE: 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:
#
#  [options-"header,autowidth"]
#  |===
#  | 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
#
perl {
	#
	#  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.
	#
	filename = ${modconfdir}/${.:instance}/example.pl

	#
	#  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.
	#
	perl_flags = "-T"

	#
	#  func_detach:: Subroutine to call during server shutdown
	#
#	func_detach = detach

	#
	#  Sample subroutine name overrides
	#
	#  These options cause the old FreeRADIUS v3 default subroutine
	#  names to be used
#	func_recv_access_request = authorize
#	func_recv_accounting_request = preacct
#	func_send = postauth

	#
	#  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'}
	#  ----
	#
#	config {
#		name = "value"
#		sub-config {
#			name = "value of name from config.sub-config"
#		}
#	}
}
