#  -*- text -*-
#
#
#  $Id: a1826df90966de79e1b31ed80806edb19172c1ce $

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

#
#  ## 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`
#
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

	#
	#  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.
	#
	replace {
#		request = no
#		reply = no
#		control = no
#		session = no
	}

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