#  -*- text -*-
#
#
#  $Id: ffea814f16336c54f86d4c178af3fa8e95dbbf92 $

#######################################################################
#
#  = 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`
#
#  WARN:: The Perl module is slow compared to `unlang`. The only
#  reason to use Perl is when you need to use a third-party API that
#  is only accessible via a Perl library.
#

#
#  == 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"
##		}
##	}
}
