## Configuration Settings
-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.
-
-If we are looking for the program to output
-attributes, and want to add those attributes to the
-request, then we MUST wait for the program to
-finish, and therefore set 'wait=yes'
-
-
program:: The name of the program to execute, and it's
arguments.
-input_pairs:: The attributes which are placed into the
-environment variables for the program.
-
-If your program does not require access to values from
-environment variables, then do not set this.
-
-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.
-|===
-
-
-
-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`.
-
-
-
-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"
-
-
-
-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.
-Decreasing can be used to cause authentication to fail sooner
-when you know it's going to fail anyway due to the time taken,
-thereby saving resources.
-
== Default Configuration
exec echo {
wait = yes
program = """/bin/echo "Filter-Id := '%{User-Name}'" """
- input_pairs = &request
- output_pairs = &reply
+ input_pairs = request
+ output_pairs = reply
shell_escape = yes
# timeout = 10
}
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, ...)"
+ request += "%exec(/path/to/program,args, ...)"
The value of the attribute will be replaced with the output of the
program which is executed.
If we do NOT wait, then the program is "fire and
forget", and any output attributes from it are ignored.
+If we are looking for the program to output
+attributes, and want to add those attributes to the
+request, then we MUST wait for the program to
+finish, and therefore set `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.
+The string is dynamically expanded, so it can contain
+attribute references, etc. However, quoting of programs
+and arguments is complex. The program name and arguments
+are parsed by the server as a single string. But that
+string is parsed by the shell into multiple arguments,
+which are then passed to the program.
+
+We recommend not using the `exec` module, and instead using
+the `%exec(...)` function. That function will generally be
+easier to use and understand.
+
+Where this module is used, the `program` string below
+should use triple quotes. These allow the text inside of
+the string to contain double-quote characters without
+needing to escape them. This doesn't affect the output
+string, but it does make the configuration easier to read.
-See the `echo` module for examples of how to use the module "in line".
+If the program is expected to take quoted strings as
+arguments, then the quotes have to be done carefully. See
+the `echo` module for more information, and for a worked
+example/
+
+The summary of all of the above is that it's usually easier
+to run one shell script with no arguments. That shell
+script can then print the attribute names, operators, and
+values.
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.
-|===
+The `input_pairs` can be any "group" style attribute.
+Usually it is the top-level list such as `request`,
+`reply`, etc.
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`.
+The values allowed 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.
+configuration item is set, and when `wait = yes` is also
+set. Otherwise it is ignored.
-env_inherit:: Inherit the environment of the current radiusd process.
+env_inherit:: Pass the server environment variables to the called program
+
+For security, the server environment variables are not passed to the
+program being executed. Setting this flag to `yes` will pass the
+server environment variables to the program.
Any `input_pairs` will be merged with these environmental variables.
+The default is `no`.
+
timeout:: Set a time wait for the program to finish.
```
exec {
wait = yes
-# program = "/bin/true %{User-Name}"
- input_pairs = &request
-# output_pairs = &reply
+# program = """/bin/true "%{User-Name}" """
+ input_pairs = request
+# output_pairs = reply
shell_escape = yes
-# env_inherit = no
+ env_inherit = no
timeout = 10
}
```
# ## Configuration Settings
#
exec echo {
- #
- # 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.
- #
- # If we are looking for the program to output
- # attributes, and want to add those attributes to the
- # request, then we MUST wait for the program to
- # finish, and therefore set 'wait=yes'
- #
wait = yes
#
#
program = """/bin/echo "Filter-Id := '%{User-Name}'" """
- #
- # input_pairs:: The attributes which are placed into the
- # environment variables for the program.
- #
- # If your program does not require access to values from
- # environment variables, then do not set this.
- #
- # 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`.
- #
- 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"
- #
+ input_pairs = request
+ output_pairs = reply
shell_escape = yes
- #
- # 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.
- # Decreasing can be used to cause authentication to fail sooner
- # when you know it's going to fail anyway due to the time taken,
- # thereby saving resources.
- #
# timeout = 10
}
# If we do NOT wait, then the program is "fire and
# forget", and any output attributes from it are ignored.
#
+ # If we are looking for the program to output
+ # attributes, and want to add those attributes to the
+ # request, then we MUST wait for the program to
+ # finish, and therefore set `wait=yes`
+ #
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}"
+ # The string is dynamically expanded, so it can contain
+ # attribute references, etc. However, quoting of programs
+ # and arguments is complex. The program name and arguments
+ # are parsed by the server as a single string. But that
+ # string is parsed by the shell into multiple arguments,
+ # which are then passed to the program.
+ #
+ # We recommend not using the `exec` module, and instead using
+ # the `%exec(...)` function. That function will generally be
+ # easier to use and understand.
+ #
+ # Where this module is used, the `program` string below
+ # should use triple quotes. These allow the text inside of
+ # the string to contain double-quote characters without
+ # needing to escape them. This doesn't affect the output
+ # string, but it does make the configuration easier to read.
+ #
+ # If the program is expected to take quoted strings as
+ # arguments, then the quotes have to be done carefully. See
+ # the `echo` module for more information, and for a worked
+ # example/
+ #
+ # The summary of all of the above is that it's usually easier
+ # to run one shell script with no arguments. That shell
+ # script can then print the attribute names, operators, and
+ # values.
+ #
+# program = """/bin/true "%{User-Name}" """
#
# input_pairs:: The attributes which are placed into the
# environment variables for the program.
#
- # Allowed values are:
+ # The `input_pairs` can be any "group" style attribute.
+ # Usually it is the top-level list such as `request`,
+ # `reply`, etc.
#
- # [options="header,autowidth"]
- # |===
- # | Pairs | Description
- # | &request | attributes from the request
- # | &control | attributes from the control list
- # | &reply | attributes from the reply
- # | &session-state | attributes that persist over multiple request/response rounds.
- # |===
- #
- input_pairs = &request
+ 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`.
+ # The values allowed 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.
+ # configuration item is set, and when `wait = yes` is also
+ # set. Otherwise it is ignored.
#
-# output_pairs = &reply
+# output_pairs = reply
#
# shell_escape:: Escape the environment variables.
shell_escape = yes
#
- # env_inherit:: Inherit the environment of the current radiusd process.
+ # env_inherit:: Pass the server environment variables to the called program
+ #
+ # For security, the server environment variables are not passed to the
+ # program being executed. Setting this flag to `yes` will pass the
+ # server environment variables to the program.
#
# Any `input_pairs` will be merged with these environmental variables.
#
-# env_inherit = no
+ # The default is `no`.
+ #
+ env_inherit = no
#
# timeout:: Set a time wait for the program to finish.
static const conf_parser_t module_config[] = {
{ FR_CONF_OFFSET("wait", rlm_exec_t, wait), .dflt = "yes" },
- { FR_CONF_OFFSET("input_pairs", rlm_exec_t, input_list) },
- { FR_CONF_OFFSET("output_pairs", rlm_exec_t, output_list) },
+ { FR_CONF_OFFSET_FLAGS("input_pairs", CONF_FLAG_ATTRIBUTE, rlm_exec_t, input_list) },
+ { FR_CONF_OFFSET_FLAGS("output_pairs", CONF_FLAG_ATTRIBUTE, rlm_exec_t, output_list) },
{ FR_CONF_OFFSET("shell_escape", rlm_exec_t, shell_escape), .dflt = "yes" },
{ FR_CONF_OFFSET("env_inherit", rlm_exec_t, env_inherit), .dflt = "no" },
{ FR_CONF_OFFSET_IS_SET("timeout", FR_TYPE_TIME_DELTA, 0, rlm_exec_t, timeout) },
projects / thirdparty / freeradius-server.git / commitdiff
