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:
| 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
- 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.
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.
- input_pairs
-
The attributes which are placed into the environment variables for the program.
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 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 also
set. Otherwise it is ignored.
- 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.
- 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.
Default is 10 seconds, which should be plenty for nearly
anything. Range is 1 to 30 seconds.
| 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. |