1 .TH unlang 5 "12 Jun 2007" "" "FreeRADIUS Processing un-language"
3 unlang \- FreeRADIUS Processing un\-language
5 FreeRADIUS supports a simple processing language in its configuration
6 files. We call it an "un-language" because the intention is NOT to
7 create yet another programming language. If you need something more
8 complicated than what is described here, we suggest using the Perl or
9 Python modules rlm_perl, or rlm_python.
11 The goal of the language is to allow simple policies to be written
12 with minimal effort. Those policies are then applied when a request
15 The keywords for the language are a combination of pre-defined
16 keywords, and references to loadable module names. We document only
17 the pre-defined keywords here.
19 Subject to a few limitations described below, any keyword can appear
20 in any context. The language consists of a series of entries, each
21 one one line. Each entry begins with a keyword. Entries are
22 organized into lists. Processing of the language is line by line,
23 from the start of the list to the end. Actions are executed
26 A reference to the named module. When processing reaches this point,
27 the pre-compiled module is called. The module may succeed or fail,
28 and will return a status to "unlang" if so. This status can be tested
29 in a condition. See the "Simple Conditions" text in the CONDITIONS
30 section, and MODULE RETURN CODES, below.
33 chap # call the CHAP module
35 sql # call the SQL module
41 Checks for a particular condition. If true, the block after the
42 condition is processed. Otherwise, the block is ignored. See
43 CONDITIONS, below, for documentation on the format of the conditions.
54 Define a block to be executed only if the previous "if" condition
66 Define a block to be executed only if the previous "if" condition
67 returned false, and if the specified condition evaluates to true.
78 Evaluate the given string, and choose the first matching "case"
79 statement inside of the current block. If the string is surrounded by
80 double quotes, it is expanded as described below in the STRINGS AND
83 No statement other than "case" can appear in a "switch" block.
94 Define a static string to match a parent "switch" statement. The
95 strings given here are not expanded as is done with the parent
98 A "case" statement cannot appear outside of a "switch" block.
108 A default entry can be defined by omitting the static string. This
109 entry will be used if no other "case" entry matches. Only one default
110 entry can exist in a "switch" section.
121 Update a particular attribute list, based on the attributes given in
134 The <list> can be one of "request", "reply", "proxy-request",
135 "proxy-reply", or "control". The "control" list is the list of
136 attributes maintainted internally by the server that controls how the
137 server processes the request. Any attribute that does not go in a
138 packet on the network will generally be placed in the "control" list.
140 For backwards compatibility with older versions, "check" is accepted
141 as a synonym for "control". The use of "check" is deprecated, and
142 will be removed in a future release.
144 The only contents permitted in an "update" section are attributes and
145 values. The contents of the "update" section are described in the
146 ATTRIBUTES section below.
148 This section contains a simple list of modules. The first module is
149 called when the section is being processed. If the first module
150 succeeds in its operation, then the server stops processing the
151 section, and returns to the parent section.
153 If, however, the module fails, then the next module in the list is
154 tried, as described above. The processing continues until one module
155 succeeds, or until the list has been exhausted.
157 Redundant sections can contain only a list of modules, and cannot
158 contain keywords that perform conditional operations (if, else, etc)
159 or update an attribute list.
166 sql2 # try this only if sql1 fails.
173 This section contains a simple list of modules. When the section is
174 entered, one module is chosen at random to process the request. All
175 of the modules in the list should be the same type (e.g. ldap or sql).
176 All of the modules in the list should behave identically, otherwise
177 the load-balance section will return different results for the same
180 Load-balance sections can contain only a list of modules, and cannot
181 contain keywords that perform conditional operations (if, else, etc)
182 or update an attribute list.
187 ldap1 # 50% of requests go here
189 ldap2 # 50% of requests go here
194 In general, we recommend using "redundant-load-balance" instead of
196 .IP redundant-load-balance
197 This section contains a simple list of modules. When the section is
198 entered, one module is chosen at random to process the request. If
199 that module succeeds, then the server stops processing the section.
200 If, however, the module fails, then one of the remaining modules is
201 chosen at random to process the request. This process repeats until
202 one module succeeds, or until the list has been exhausted.
204 All of the modules in the list should be the same type (e.g. ldap or
205 sql). All of the modules in the list should behave identically,
206 otherwise the load-balance section will return different results for
209 Load-balance sections can contain only a list of modules, and cannot
210 contain keywords that perform conditional operations (if, else, etc)
211 or update an attribute list.
214 redundant load-balance {
216 ldap1 # 50%, unless ldap2 is down, then 100%
218 ldap2 # 50%, unless ldap1 is down, then 100%
223 The conditions are similar to C conditions in syntax, though
224 quoted strings are supported, as with the Unix shell.
232 Evalutes to true if 'foo' is a non-empty string (single quotes, double
233 quotes, or back-quoted). Also evaluates to true if 'foo' is a
234 non-zero number. Note that the language is not typed, so the string
235 "0000" can be interpreted as a numerical zero. This issue can be
236 avoided by comparings strings to an empty string, rather than by
237 evaluating the string by itself.
239 If the text is not quoted, then it is used as a test for one of the
240 module return codes. The condition evaluates to true if the most
241 recent module return code matches the name given here. Valid module
242 return codes are given in MODULE RETURN CODES, below.
248 Evalutes to true if 'foo' evaluates to false, and vice-versa.
250 Short-circuit operators
259 "&&" and "||" are short-circuit operators. "&&" evaluates the first
260 condition, and evaluates the second condition if and only if the
261 result of the first condition is true. "||" is similar, but executes
262 the second command if and only if the result of the first condition is
270 Compares 'foo' to 'bar', and evaluates to true if the comparison holds
271 true. Valid comparison operators are "==", "!=", "<", "<=", ">",
272 ">=", "=~", and "!~", all with their usual meanings. Invalid
273 comparison operators are ":=" and "=".
275 Conditions may be nested to any depth, subject only to line length
276 limitations (8192 bytes).
277 .SH STRINGS AND NUMBERS
278 Strings and numbers can appear as stand-alone conditions, in which
279 case they are evaluated as described in "Simple conditions", above.
280 They can also appear (with some exceptions noted below) on the
281 left-hand or on the right-hand side of a comparison.
283 Numbers are composed of decimal digits. Floating point, hex, and
284 octal numbers are not supported. The maximum value for a number is
285 machine-dependent, but is usually 32-bits, including one bit for a
290 Double-quoted strings are expanded by inserting the value of any
291 variables (see VARIABLES, below) before being evaluated. If
292 the result is a number it is evaluated in a numerical context.
294 String length is limited by line-length, usually about 8000 characters.
297 Single-quoted strings are evaluated as-is.
299 Back-quoted strings are evaluated by expanding the contents of the
300 string, as described above for double-quoted strings. The resulting
301 command given inside of the string in a sub-shell, and taking the
302 output as a string. This behavior is much the same as that of Unix
305 Note that for security reasons, the input string is split into command
306 and arguments before variable expansion is done.
308 For performance reasons, we suggest that the use of back-quoted
309 strings be kept to a minimum. Executing external programs is
310 relatively expensive, and executing a large number of programs for
311 every request can quickly use all of the CPU time in a server. If you
312 believe that you need to execute many programs, we suggest finding
313 alternative ways to achieve the same result. In some cases, using a
314 real language may be sufficient.
316 These strings are valid only on the right-hand side of a comparison,
317 and then only when the comparison operator is "=~" or "!~". They are
318 regular expressions, as implemented by the local regular expression
319 library on the system. This is usually Posix regular expressions.
321 The trailing 'i' is optional, and indicates that the regular
322 expression match should be done in a case-insensitive fashion.
324 If the comparison operator is "=~", then parantheses in the regular
325 expression will define variables containing the matching text, as
326 described below in the VARIABLES section.
328 Run-time variables are referenced using the following syntax
334 Note that unlike C, there is no way to declare variables, or to refer
335 to them outside of a string context. All references to variables MUST
336 be contained inside of a double-quoted or back-quoted string.
338 Many potential variables are defined in the dictionaries that
339 accompany the server. These definitions define only the name and
340 type, and do not define the value of the variable. When the server
341 receives a packet, it uses the packet contents to look up entries in
342 the dictionary, and instantiates variables with a name taken from the
343 dictionaries, and a value taken from the packet contents. This
344 process means that if a variable does not exist, it is usually because
345 it was not mentioned in a packet that the server received.
347 Once the variable is instantiated, it is added to an appropriate
348 attribute list, as described below. In many cases, attributes and
349 variables are inter-changeble, and are often talked about that way.
350 However, variables can also refer to run-time calls to modules, which
351 may perform operations like SQL SELECTs, and which may return the
352 result as the value of the variable.
354 Referencing attribute lists
356 Attribute lists may be referenced via the following syntax
359 %{<list>:Attribute-Name}
362 Where <list> is one of "request", "reply", "proxy-request",
363 "proxy-reply", or "control", as described above in the documentation
364 for the "update" section. The "<list>:" prefix is optional, and if
365 omitted, is assumed to refer to the "request" list.
367 When a variable is encountered, the given list is examined for an
368 attribute of the given name. If found, the variable reference in the
369 string is replaced with the value of that attribute. Some examples are:
374 %{request:User-Name} # same as above
380 Results of regular expression matches
382 If a regular expression match has previously been performed, then the
383 special variable %{0} will contain a copy of the input string. The
384 variables %{1} through %{8} will contain the substring matches,
385 starting from the left-most parantheses, and onwards. If there are
386 more than 8 parantheses, the additional results will not be placed
390 Obtaining results from databases
392 It is useful to query a database for some information, and to use the
393 result in a condition. The following syntax will call a module, pass
394 it the given string, and replace the variable reference with the
395 resulting string returned from the module.
398 %{module: string ...}
401 The syntax of the string is module-specific. Please read the module
402 documentation for additional details.
407 Conditional syntax similar to that used in Unix shells may also be
410 If %{Foo} has a value, returns that value.
412 Otherwise, returns literal string "bar".
413 .IP %{%{Foo}:-%{Bar}}
414 If %{Foo} has a value, returns that value.
416 Otherwise, returns the expansion of %{Bar}.
418 These conditional expansions can be nested to almost any depth, such
419 as with %{%{One}:-%{%{Two}:-%{Three}}}
422 String lengths and arrays
424 Similar to a Unix shell, there are ways to reference string lenths,
425 and the second or more instance of an attribute in a list. If you
426 need this functionality, we recommend using a real language.
428 The number of characters in %{string}. If %{string} is not
429 set, then the length is not set.
431 e.g. %{#Junk-junk:-foo} will yeild the string "foo".
432 .IP %{Attribute-Name[index]}
433 Reference the N'th occurance of the given attribute. The syntax
434 %{<list>:Attribute-Name[index]} may also be used. The indexes start
435 at zero. This feature is NOT available for non-attribute dynamic
436 translations, like %{sql:...}.
438 For example, %{User-Name[0]} is the same as %{User-Name}
440 The variable %{Cisco-AVPair[2]} will reference the value of the
441 THIRD Cisco-AVPair attribute (if it exists) in the request packet,
442 .IP %{Attribute-Name[#]}
443 Returns the total number of attributes of that name in the relevant
444 attribute list. The number will usually be between 0 and 200.
446 For most requests, %{request:User-Name[#]} == 1
447 .IP %{Attribute-Name[*]}
448 Expands to a single string, with the value of each array
449 member separated by a newline.
450 .IP %{#Attribute-Name[index]}
451 Expands to the length of the string %{Attribute-Name[index]}.
453 The attribute lists described above may be edited by listing one or
454 more attributes in an "update" section. Once the attributes have been
455 defined, they may be referenced as described above in the VARIABLES
458 The following syntax defines attributes in an "update" section. Each
459 attribute and value has to be all on one line in the configuration
460 file. There is no need for commas or semi-colons after the value.
463 Attribute-Name = value
468 The Attribute-Name must be a name previously defined in a dictionary.
469 If an undefined name is used, the server will return an error, and
473 The operator used to assign the value of the attribute may be one of
474 the following, with the given meaning.
477 Add the attribute to the list, if and only if an attribute of the same
478 name is already present in that list.
480 Add the attribute to the list. If any attribute of the same name is
481 already present in that list, its value is replaced with the value of
482 the current attribute.
484 Add the attribute to the tail of the list, even if attributes of the
485 same name are already present in the list.
487 Remove all matching attributes from the list. Both the attribute name
488 and value have to match in order for the attribute to be removed from
491 Enforce that the integer value of the attribute is less than or equal
492 to the value given here. If there is no attribute of the same name in
493 the list, the attribute is added with the given value, is with "+=".
494 If an attribute in the list exists, and has value less than given
495 here, it's value is unchanged. If an attribute in the exists, and has
496 value greater than given here, it's value is replaced with the value
499 This operator is valid only for attributes of integer type.
501 Enforce that the integer value of the attribute is greater than or
502 equal to the value given here. If there is no attribute of the same
503 name in the list, the attribute is added with the given value, is with
504 "+=". If an attribute in the list exists, and has value greater than
505 given here, it's value is unchanged. If an attribute in the exists,
506 and has value less than given here, it's value is replaced with the
509 This operator is valid only for attributes of integer type.
513 The format of the value is attribute-specific, and is usually a
514 string, integer, IP address, etc. Prior to the attribute being
515 instantiated, the value is handled as described above in the STRINGS
516 AND NUMBERS section. This flexibility means that, for example, you
517 can assign an IP address value to an attribute by specifying the IP
518 address directly, or by having the address returned from a database
519 query, or by having the address returned as the output of a program
522 When string values are finally assigned to a variable, they can have a
523 maximum length of 253 characters. This limit is due in part to both
524 protocol and internal server requirements. That is, the strings in
525 the language can be nearly 8k in length, say for a long SQL query.
526 However, the output of that SQL query should be no more than 253
527 characters in length.
529 Other keywords in the language are taken from the names of modules
530 loaded by the server. These keywords are dependent on both the
531 modules, and the local configuration.
533 Some use keywords that are defined in the default configuration file
536 Cause the request to be treated as if a database failure had occured.
538 Do nothing. This also serves as an instruction to the configurable
539 failover tracking that nothing was done in the current section.
541 Instructs the server that the request was processed properly. This
542 keyword can be used to over-ride earlier failures, if the local
543 administrator determines that the faiures are not catastrophic.
545 Causes the request to be immediately rejected
546 .SH MODULE RETURN CODES
547 When a module is called, it returns one of the following codes to
548 "unlang", with the following meaning.
551 notfound information was not found
553 noop the module did nothing
555 ok the module succeeded
557 updated the module updated the request
559 fail the module failed
561 reject the module rejected the request
563 userlock the user was locked out
565 invalid the configuration was invalid
567 handled the module has handled the request itself
570 These return codes can be tested for in a condition, as described
571 above in the CONDITIONS section.
573 /etc/raddb/vmpsd.conf,
574 /etc/raddb/radiusd.conf
576 .BR radiusd.conf (5),
580 Alan DeKok <aland@deployingradius.com>
projects / freeradius.git / blob