rlm_exec

Synopsis

The exec module executes programs.

This module is useful for gluing third-party programs into FreeRADIUS. However, executing programs is very slow. The exec module may look like it works for one or two tests, but in a live situation it can cause the server to become unresponsive under load. The perl module is recommended for general-purpose computing.

The return value of the program run determines the result of the exec instance call, as follows (see doc/configurable_failover for details):

Table 1. Program return codes to module return codes
< 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	userlock	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

Default configuration

Processing Sections

Any.

The module behaves the same for all processing sections, with the exception of accounting and post-auth.

Return codes: noop The module did nothing.
: fail The module could not find a program to execute.
: invalid The module configuration was incorrect.
: other The module returns the return code from the executed program.

accounting

The exec module searches for the Exec-Program and Exec-Program-Wait attributes in the reply list. If those attributes are found, then the contents are interpreted as a program to run.

Any output of the program is interpreted as a list of attributes, which is added to the reply.

If neither the Exec-Program or the Exec-Program-Wait attribute is found in the reply list, the module executes the configured program as described above.

See exec-program-wait for a sample script.

Return codes: noop The module did not find the Exec-Program or the Exec-Program-Wait attribute in the reply list.
: other The module returns the return code from the executed program.

post-auth

The exec module behaves as described in accounting, above.

Expansions

This module registers only one expansion.

exec

Syntax: %{exec: …}
Contents: The contents of the expansion should be a program to execute, with arguments. For security reasons, the full path to the program must be used., e.g., /bin/true. The output of the expansion is any text that was printed by the program, when wait = yes.
: The stdin of the executed program is connected to /dev/null.
: If wait = yes, then the stdout of the executed program is captured by the module and returned as the output of the expansion. Otherwise, stdout is connected to /dev/null.
: The stderr of the executed program is connected to /dev/null.

Directives

input_pairs

Syntax: input_pairs = string
Default: request
Description: The name of the list that will be input to the executed program.
: If set, the input_pairs are put into the environment variables of the executed program. The attribute names are converted to all upper-case and hyphens are converted to underscores. For example, the attribute User-Name = "bob" will be converted to an environment variable USER_NAME="bob".

Note	The environment variables may be visible to other programs. The perl module does not have this security problem, and is therefor recommended for use instead.

output_pairs

Syntax: output = string
Default: none
Description: The name of the list where the output attributes will be added. This directive is valid only when the wait = yes is also set.

program

Syntax: program = string
Default: none
Description: The name of the program to execute, along with any arguments. The full path to the program must be used.
: In order to avoid security issues, the program string is split into multiple sub-strings based on spaces, and each sub-string is expanded individually. The resulting set of strings is then passed as separate arguments to the program being executed. There is then no possibility that spaces in the input strings would be interpreted as argument separators.
: The expanded arguments can still, however, be interpreted to be command-line options to the program. It is recommended to use programs specifically written for use with the exec module or a program string with a -- separator between the program name and arguents, e.g., /bin/true — …

shell_escape

Syntax: shell_escape = boolean
Default: yes
Description: Escape any shell "special characters" before passing them to the executed program.

timeout

Syntax: *timeout = integer
Default: 0
Description: If wait = yes, the server may end up waiting for a very long time for the program to finish. When multiple threads are waiting for a long-running program, the entire server can become unresponsive.
: The timeout directive allows the server to stop waiting after a configurable time. It is recommended that the value be set to 1 to prevent misbehaving programs from blocking the server.

wait

Syntax: wait = boolean
Default: no
Description: If set to no, the module executes the program and does not wait for it to finish. Any output from the program is also discarded.
: If set to yes, the module executes the program and waits for it to finish. If output_pairs is set and the output can be parsed as attributes, the attributes are added to the output_pairs list.
: If output_pairs is not set, then any output from the program is discarded.