From: Alan T. DeKok Date: Thu, 6 Mar 2025 16:08:16 +0000 (-0500) Subject: remove '&' from exec X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=04923a266412c81c26612a721e9da813c48a9a06;p=thirdparty%2Ffreeradius-server.git remove '&' from exec and update the documentation --- diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/echo.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/echo.adoc index cf4d9b2490..1010de5e0d 100644 --- a/doc/antora/modules/reference/pages/raddb/mods-available/echo.adoc +++ b/doc/antora/modules/reference/pages/raddb/mods-available/echo.adoc @@ -40,17 +40,6 @@ NOTE: See `doc/configurable_failover` for details. ## 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. @@ -92,55 +81,6 @@ Any string values should also be quoted. -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 @@ -148,8 +88,8 @@ thereby saving resources. 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 } diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/exec.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/exec.adoc index 28f8fe5939..8549c65e05 100644 --- a/doc/antora/modules/reference/pages/raddb/mods-available/exec.adoc +++ b/doc/antora/modules/reference/pages/raddb/mods-available/exec.adoc @@ -21,7 +21,7 @@ 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, ...)" + request += "%exec(/path/to/program,args, ...)" The value of the attribute will be replaced with the output of the program which is executed. @@ -69,42 +69,62 @@ 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, 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. @@ -124,10 +144,16 @@ from the main radiusd process no escaping is applied. -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. @@ -146,11 +172,11 @@ responsiveness. ``` 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 } ``` diff --git a/raddb/mods-available/echo b/raddb/mods-available/echo index 08ce8fe386..2cc988e6c4 100644 --- a/raddb/mods-available/echo +++ b/raddb/mods-available/echo @@ -43,17 +43,6 @@ # ## 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 # @@ -97,58 +86,9 @@ exec echo { # 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 } diff --git a/raddb/mods-available/exec b/raddb/mods-available/exec index a03704feef..e1cbaa6097 100644 --- a/raddb/mods-available/exec +++ b/raddb/mods-available/exec @@ -73,47 +73,67 @@ exec { # 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. @@ -133,11 +153,17 @@ exec { 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. diff --git a/src/modules/rlm_exec/rlm_exec.c b/src/modules/rlm_exec/rlm_exec.c index 3c1ac23a4d..8dc72ae97b 100644 --- a/src/modules/rlm_exec/rlm_exec.c +++ b/src/modules/rlm_exec/rlm_exec.c @@ -57,8 +57,8 @@ typedef struct { 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) },