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 8549c65e0575d71724aafcda9a4223be7ed9bafa..80c89748c0312791d89e4d01a609332f22c628b4 100644 (file)
--- 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 e1cbaa6097d2178a6d79c036af514419c19b45a7..21edc221a27a969c612fa816fa7b47280b708bc5 100644 (file)
--- 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.