Echo Module
The echo module an example of the exec module configured
with a program configuration item set so it can be called
as any other module, i.e.
echo
The sample program below is a trivial example and should be replaced
with something more meaningful.
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. |
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.
Dynamic translation is done on this field, so things like the following example will work.
The example program below has a few important features which should be noted:
-
The string for the program name uses 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.
-
The argument to "/bin/echo" is a double-quoted string. That is, the attribute name, operator, and value are passed to "echo" as one argument. If the parameters to the "echo" command were not quoted, then they would be passed as three separate arguments.
-
The attribute value is surrounded by single quotes. These single quotes are inside of the single argument to the "echo" command.
-
If instead the "echo" command was passed three separate arguments, then the attribute value would be printed without the quotes. Because quoting an argument to a command results in the unquoted string being passed to the command, as the argument.
The summary of all of the above is that when printing attributes it’s usually easier to run one shell script with no arguments. That shell script can then print the attribute names, operators, and values.
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:
| 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.
| 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. |