#  -*- text -*-
#
#
#  $Id: f3d77055cdbe45810e3a6519a9b5e47d79270b5e $

#######################################################################
#
#  = Exec Module
#
#  The module `exec` is used for executing external programs.
#
#  This module provides an `xlat`.  To use it, put `exec` into
#  the `instantiate` section.  You can then do dynamic translation of
#  attributes like:
#
#    Attribute-Name = %exec(/path/to/program,args, ...)
#
#  The output of `exec` is interpreted as the data type of the attribute.
#
#  The output of `exec` can even be pairs, such as `User-Name = foo`.
#  Those pairs can be assigned to a list.  If the program fails, it
#  will output nothing.
#
#  Note that when the assignment is to a list, the `exec` call _must_ be
#  inside of a double-quoted string.
#
#    &request += "%exec(/path/to/program,args, ...)"
#
#  The value of the attribute will be replaced with the output of the
#  program which is executed.
#
#  The attributes from the list referenced in the `input_pairs`
#  configuration item will be placed into environment variables of the executed
#  program.
#
#  Alternatively, by setting the `program` item of the module configuration,
#  the module can be called as a module rather than as an xlat function.
#  See the `echo` module for an example of this.
#
#  In this scenario, if the configuration item `output_pairs` is set,
#  and the `wait` configuration item is set to "yes", the output of
#  executing the program will be parsed for attribute pairs which
#  will be added to the list referenced in `output_pairs`.
#
#  When called as a module, the return value of the program run determines
#  the result of the exec instance call as follows:
#
#  [options="header,autowidth"]
#  |===
#  | Code | Return    | Description
#  | < 0  | fail      | the module failed.
#  | = 0  | ok        | the module succeeded.
#  | = 1  | reject    | the module rejected the user.
#  | = 2  | fail      | the module failed.
#  | = 3  | ok        | the module succeeded.
#  | = 4  | handled   | the module has done everything to handle the request.
#  | = 5  | invalid   | the user's configuration entry was invalid.
#  | = 6  | disallow  | the user was locked out.
#  | = 7  | notfound  | the user was not found.
#  | = 8  | noop      | the module did nothing.
#  | = 9  | updated   | the module updated information in the request.
#  | > 9  | fail      | the module failed.
#  |===
#

#
#  ## Configuration Settings
#
exec {
	#
	#  wait:: Wait for the program to finish.
	#
	#  If we do NOT wait, then the program is "fire and
	#  forget", and any output attributes from it are ignored.
	#
	wait = yes

	#
	#  program:: The name of the program to execute, and it's
	#  arguments, when called as a module.
	#
	#  Dynamic translation is done on this field, so things like
	#  the following example will work.
	#
	#  See the `echo` module for examples of how to use the module "in line".
	#
#	program = "/bin/true %{User-Name}"

	#
	#  input_pairs:: The attributes which are placed into the
	#  environment variables for the program.
	#
	#  Allowed values are:
	#
	#  [options="header,autowidth"]
	#  |===
	#  | Pairs          | Description
	#  | &request       | attributes from the request
	#  | &config        | attributes from the configuration items list
	#  | &reply         | attributes from the reply
	#  | &session-state | attributes that persist over multiple request/response rounds.
	#  |===
	#
	input_pairs = &request

	#
	#  output_pairs::: Where to place the output attributes (if any) from
	#  the executed program.
	#
	#  The values allowed, and the restrictions as to availability, are the
	#  same as for the `input_pairs`.
	#
	#  This configuration item is used only when the `program`
	#  configuration item is set, and when `wait = yes` is set.
	#
#	output_pairs = &reply

	#
	#  shell_escape:: Escape the environment variables.
	#
	#  If this is set, all the RADIUS attributes are capitalised and dashes
	#  replaced with underscores. Also, RADIUS values are surrounded with
	#  double-quotes.
	#
	#  That is to say:
	#
	#    User-Name=BobUser => USER_NAME="BobUser"
	#
	#  Note that this escaping only applies to environmental variables
	#  created from the request list.  For environmental variables inherited
	#  from the main radiusd process no escaping is applied.
	#
	shell_escape = yes

	#
	#  env_inherit:: Inherit the environment of the current radiusd process.
	#
	#  Any `input_pairs` will be merged with these environmental variables.
	#
#	env_inherit = no

	#
	#  timeout:: Set a time wait for the program to finish.
	#
	#  Default is `10` seconds, which should be plenty for nearly
	#  anything. Range is `1` to `30` seconds.
	#
	#  WARNING: You are strongly encouraged to NOT increase this
	#  value.  In fact, you are much better off decreasing it to a
	#  lower value.  Doing so will improve network stability and
	#  responsiveness.
	#
	timeout = 10
}
