number of modules can be listed in a "redundant" section. The server
will process each in turn, until one of the modules succeeds. It willthen stop processing the "redundant" list.
- Rewriting results for single modules
- ------------------------------------
+1. Rewriting results for single modules
+ ------------------------------------
Normally, when a module fails, the entire section ("authorize",
"accounting", etc.) stops being processed. In some cases, we may want
means "if the detail module fails, stop processing the accounting
section".
- Fail-over configuration entries
- -------------------------------
+2. Fail-over configuration entries
+ -------------------------------
Modules normally return on of the following codes as their result:
fail the module failed
reject the module rejected the user
userlock the user was locked out
- invalid the users configuration entry was invilad
+ invalid the user's configuration entry was invalid
handled the module has done everything to handle the request
In a configurable fail-over section, each of these codes may be
listed, with a value. If the code is not listed, or a configurable
-fail-over section is not defined, then default values are used.
+fail-over section is not defined, then values that make sense for the
+requested "group" (group, redundant, load-balance, etc) are used.
+
+ The special code "default" can be used to set all return codes to
+the specified value. This value will be used with a lower priority
+than ones that are explicitly set.
The values for each code may be one of two things:
Value Meaning
----- -------
- <number> Priority for this return code
+ <number> Priority for this return code.
return stop processing this configurable fail-over list.
- reject Stop processing this configurable fail-over list
+ reject Stop processing this configurable fail-over list.
and immediately return a reject.
The <number> used for a value may be any decimal number between 1
modules will be "ok", because it has higher priority than "fail".
This configurability allows the administrator to permit some modules
-to fail, so long as a later module succeds.
+to fail, so long as a later module succeeds.
- More Complex Configurations
- ---------------------------
+3. More Complex Configurations
+ ---------------------------
The "authorize" section is normally a list of module names. We can
create sub-lists by using the section name "group". The "redundant"
"group" section.
- The Gory Details
- ----------------
+4. Virtual Modules
+ ---------------
+
+ Some configurations may require using the same list of modules, in
+the same order, in multiple sections. For those systems, the
+configuration can be simplified through the use of "virtual" modules.
+These modules are configured as named sub-sections of the
+"instantiate" section, as follows:
+
+ instantiate {
+ ...
+
+ redundant sql1_or_2 {
+ sql1
+ sql2
+ }
+ }
+
+ The name "sql1_or_2" can then be used in any other section, such as
+"authorize" or "accounting". The result will be *exactly* as if that
+section was placed at the location of the "sql1_or_2" reference.
+
+ These virtual modules are full-fledged objects in and of themselves.
+One virtual module can refer to another virtual module, and they can
+contain "if" conditions, or any other configuration permitted in a
+section.
+
+
+5. Redundancy and Load-Balancing
+ -----------------------------
+
+ See "man unlang" or doc/load-balance.txt for information on simple
+redundancy (fail-over) and load balancing.
+
+
+6. The Gory Details
+ ----------------
The fundamental object is called a MODCALLABLE, because it is something that
can be passed a specific radius request and returns one of the RLM_MODULE_*
}
}
-This is the same as the first example, with the default behavior explicitly
+This is the same as the first example, with the behavior explicitly
spelled out. Each SINGLE becomes its own section, containing a list of
RESULTs that it may return and what ACTION should follow from them. So
-preprocess is called, and if it returns for example RLM_MODULE_REJECT, then
-the reject=return rule is applied, and the authorize{...} GROUP itself
-immediately returns RLM_MODULE_REJECT.
+preprocess is called, and if it returns for example RLM_MODULE_REJECT,
+then the reject=return rule is applied, and the authorize{...} GROUP
+itself immediately returns RLM_MODULE_REJECT.
If preprocess returns RLM_MODULE_NOOP, the corresponding ACTION is "2". An
integer ACTION serves two purposes - first, it tells the parent GROUP to go
because to say the user was not found at all would be a lie, since preprocess
apparently found him, or else it would have returned RLM_MODULE_NOTFOUND too.
+We could use the "default" code to simplify the above example a
+little. The following two configurations are identical:
+
+...
+ files {
+ notfound = 1
+ noop = 2
+ ok = 3
+ updated = 4
+ default = return
+ }
+...
+
+When putting the "default" first, later definitions over-ride it's
+return code:
+
+...
+ files {
+ default = return
+ notfound = 1
+ noop = 2
+ ok = 3
+ updated = 4
+ }
+...
+
+
[Take a deep breath - the worst is over]
That RESULT preference/desirability stuff is pretty complex, but my hope is