From: Alan T. DeKok Date: Sun, 4 May 2025 00:23:20 +0000 (-0400) Subject: notes on "don't use exec, it's slow" X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2473aa7db78b313ba0afcf0f4eb5e5b726c570c8;p=thirdparty%2Ffreeradius-server.git notes on "don't use exec, it's slow" --- 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 8549c65e057..80c89748c03 100644 --- a/doc/antora/modules/reference/pages/raddb/mods-available/exec.adoc +++ b/doc/antora/modules/reference/pages/raddb/mods-available/exec.adoc @@ -6,22 +6,53 @@ 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: +== Don't use this module. - Attribute-Name = %exec(/path/to/program,args, ...) +We provide this module for the _extremely rare_ case when it is +useful. The main utility of the module is for testing, and for +doing some unusual things which aren't possible via any other +method. -The output of `exec` is interpreted as the data type of the attribute. +It can be appealing to just ignore `unlang`, and run `%exec()` +everywhere. This kind of configuration can be written quickly, +means that you don't need to spend any time understanding the +server configuration. This process is generally more effort than +it is worth. -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. +The biggest problem with `exec` is that it is slow. Very, very, +very, slow. We have tested the server at 80K Access-Requests per +second (to OpenLDAP) on low-end hardware. This is fast enough to +run a major ISP. + +In contrast, when each Access-Request causes an `exec` script to be +run, the rate of access-Request can drop by a factor of 100 or +more. It is not unusual for the server to max out at a few hundred +authentications per second when running multiple scripts per packet. + +The server has sufficient functionality that it is essentially +never necessary to `exec` and external script. Please use the +built-in functionality of the server; it is hundreds of times +faster than running a script, and it is designed to process +packets. An external script is worse, by nearly all possible +standards of measurement. + +== %exec() function + +This module also provides a dynamic expansion function. You can +then run a script like this: + + Attribute-Name = %exec('/path/to/program', 'args', ...) + +The output of `exec` is parsed and assigned to the attribute. + +Depending on the module configuration, 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, ...)" + &request += "%exec(/path/to/program,args, ...)" The value of the attribute will be replaced with the output of the program which is executed. diff --git a/raddb/mods-available/exec b/raddb/mods-available/exec index e1cbaa6097d..21edc221a27 100644 --- a/raddb/mods-available/exec +++ b/raddb/mods-available/exec @@ -9,22 +9,53 @@ # # 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: +# == Don't use this module. # -# Attribute-Name = %exec(/path/to/program,args, ...) +# We provide this module for the _extremely rare_ case when it is +# useful. The main utility of the module is for testing, and for +# doing some unusual things which aren't possible via any other +# method. # -# The output of `exec` is interpreted as the data type of the attribute. +# It can be appealing to just ignore `unlang`, and run `%exec()` +# everywhere. This kind of configuration can be written quickly, +# means that you don't need to spend any time understanding the +# server configuration. This process is generally more effort than +# it is worth. # -# 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. +# The biggest problem with `exec` is that it is slow. Very, very, +# very, slow. We have tested the server at 80K Access-Requests per +# second (to OpenLDAP) on low-end hardware. This is fast enough to +# run a major ISP. +# +# In contrast, when each Access-Request causes an `exec` script to be +# run, the rate of access-Request can drop by a factor of 100 or +# more. It is not unusual for the server to max out at a few hundred +# authentications per second when running multiple scripts per packet. +# +# The server has sufficient functionality that it is essentially +# never necessary to `exec` and external script. Please use the +# built-in functionality of the server; it is hundreds of times +# faster than running a script, and it is designed to process +# packets. An external script is worse, by nearly all possible +# standards of measurement. +# +# == %exec() function +# +# This module also provides a dynamic expansion function. You can +# then run a script like this: +# +# Attribute-Name = %exec('/path/to/program', 'args', ...) +# +# The output of `exec` is parsed and assigned to the attribute. +# +# Depending on the module configuration, 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, ...)" +# &request += "%exec(/path/to/program,args, ...)" # # The value of the attribute will be replaced with the output of the # program which is executed.