1 .\" # DS - begin display
13 .TH unlang 5 "01 Jul 2008" "" "FreeRADIUS Processing un-language"
15 unlang \- FreeRADIUS Processing un\-language
17 FreeRADIUS supports a simple processing language in its configuration
18 files. We call it an "un-language" because the intention is NOT to
19 create yet another programming language. If you need something more
20 complicated than what is described here, we suggest using the Perl or
21 Python modules rlm_perl, or rlm_python.
23 The goal of the language is to allow simple policies to be written
24 with minimal effort. Those policies are then applied when a request
27 The keywords for the language are a combination of pre-defined
28 keywords, and references to loadable module names. We document only
29 the pre-defined keywords here.
31 Subject to a few limitations described below, any keyword can appear
32 in any context. The language consists of a series of entries, each
33 one one line. Each entry begins with a keyword. Entries are
34 organized into lists. Processing of the language is line by line,
35 from the start of the list to the end. Actions are executed
38 A reference to the named module. When processing reaches this point,
39 the pre-compiled module is called. The module may succeed or fail,
40 and will return a status to "unlang" if so. This status can be tested
41 in a condition. See the "Simple Conditions" text in the CONDITIONS
42 section, and MODULE RETURN CODES, below.
45 chap # call the CHAP module
47 sql # call the SQL module
53 Checks for a particular condition. If true, the block after the
54 condition is processed. Otherwise, the block is ignored. See
55 CONDITIONS, below, for documentation on the format of the conditions.
66 Define a block to be executed only if the previous "if" condition
78 Define a block to be executed only if the previous "if" condition
79 returned false, and if the specified condition evaluates to true.
90 Evaluate the given string, and choose the first matching "case"
91 statement inside of the current block. If the string is surrounded by
92 double quotes, it is expanded as described in the DATA TYPES section,
95 No statement other than "case" can appear in a "switch" block.
106 Define a static string to match a parent "switch" statement. The
107 strings given here are not expanded as is done with the parent
110 A "case" statement cannot appear outside of a "switch" block.
120 A default entry can be defined by omitting the static string. This
121 entry will be used if no other "case" entry matches. Only one default
122 entry can exist in a "switch" section.
133 Update a particular attribute list, based on the attributes given in
146 The <list> can be one of "request", "reply", "proxy-request",
147 "proxy-reply", "coa", "disconnect", or "control". The "control" list
148 is the list of attributes maintainted internally by the server that
149 controls how the server processes the request. Any attribute that
150 does not go in a packet on the network will generally be placed in the
153 For backwards compatibility with older versions, "check" is accepted
154 as a synonym for "control". The use of "check" is deprecated, and
155 will be removed in a future release.
157 For EAP methods with tunneled authentication sessions (i.e. PEAP and
158 EAP-TTLS), the inner tunnel session can also reference
159 "outer.request", "outer.reply", and "outer.control". Those references
160 allow you to address the relevant list in the outer tunnel session.
162 The "coa" and "disconnect" sections can only be used when the server
163 receives an Access-Request or Accounting-Request. Adding one or more
164 attributes to either of the "coa" or "disconnect" list causes server
165 to originate a CoA-Request or Disconnect-Request packet. That packet
166 is sent when the current Access-Request or Accounting-Request has been
167 finished, and a reply sent to the NAS. See
168 raddb/sites-available/originate-coa for additional information.
170 The only contents permitted in an "update" section are attributes and
171 values. The contents of the "update" section are described in the
172 ATTRIBUTES section below.
174 This section contains a simple list of modules. The first module is
175 called when the section is being processed. If the first module
176 succeeds in its operation, then the server stops processing the
177 section, and returns to the parent section.
179 If, however, the module fails, then the next module in the list is
180 tried, as described above. The processing continues until one module
181 succeeds, or until the list has been exhausted.
183 Redundant sections can contain only a list of modules, and cannot
184 contain keywords that perform conditional operations (if, else, etc)
185 or update an attribute list.
192 sql2 # try this only if sql1 fails.
199 This section contains a simple list of modules. When the section is
200 entered, one module is chosen at random to process the request. All
201 of the modules in the list should be the same type (e.g. ldap or sql).
202 All of the modules in the list should behave identically, otherwise
203 the load-balance section will return different results for the same
206 Load-balance sections can contain only a list of modules, and cannot
207 contain keywords that perform conditional operations (if, else, etc)
208 or update an attribute list.
213 ldap1 # 50% of requests go here
215 ldap2 # 50% of requests go here
220 In general, we recommend using "redundant-load-balance" instead of
222 .IP redundant-load-balance
223 This section contains a simple list of modules. When the section is
224 entered, one module is chosen at random to process the request. If
225 that module succeeds, then the server stops processing the section.
226 If, however, the module fails, then one of the remaining modules is
227 chosen at random to process the request. This process repeats until
228 one module succeeds, or until the list has been exhausted.
230 All of the modules in the list should be the same type (e.g. ldap or
231 sql). All of the modules in the list should behave identically,
232 otherwise the load-balance section will return different results for
235 Load-balance sections can contain only a list of modules, and cannot
236 contain keywords that perform conditional operations (if, else, etc)
237 or update an attribute list.
240 redundant-load-balance {
242 ldap1 # 50%, unless ldap2 is down, then 100%
244 ldap2 # 50%, unless ldap1 is down, then 100%
249 The conditions are similar to C conditions in syntax, though
250 quoted strings are supported, as with the Unix shell.
258 Evalutes to true if 'foo' is a non-empty string (single quotes, double
259 quotes, or back-quoted). Also evaluates to true if 'foo' is a
260 non-zero number. Note that the language is poorly typed, so the
261 string "0000" can be interpreted as a numerical zero. This issue can
262 be avoided by comparings strings to an empty string, rather than by
263 evaluating the string by itself.
265 If the word 'foo' is not a quoted string, then it can be taken as a
266 reference to a named attribute. See "Referencing attribute lists",
267 below, for examples of attribute references. The condition evaluates
268 to true if the named attribute exists.
270 Otherwise, if the word 'foo' is not a quoted string, and is not an
271 attribute reference, then it is interpreted as a reference to a module
272 return code. The condition evaluates to true if the most recent
273 module return code matches the name given here. Valid module return
274 codes are given in MODULE RETURN CODES, below.
280 Evalutes to true if 'foo' evaluates to false, and vice-versa.
282 Short-circuit operators
291 "&&" and "||" are short-circuit operators. "&&" evaluates the first
292 condition, and evaluates the second condition if and only if the
293 result of the first condition is true. "||" is similar, but executes
294 the second command if and only if the result of the first condition is
302 Compares 'foo' to 'bar', and evaluates to true if the comparison holds
303 true. Valid comparison operators are "==", "!=", "<", "<=", ">",
304 ">=", "=~", and "!~", all with their usual meanings. Invalid
305 comparison operators are ":=" and "=".
307 Conditions may be nested to any depth, subject only to line length
308 limitations (8192 bytes).
310 There are only a few data types supported in the language. Reference
311 to attributes, numbers, and strings. Any data type can appear in
312 stand-alone condition, in which case they are evaluated as described
313 in "Simple conditions", above. They can also appear (with some
314 exceptions noted below) on the left-hand or on the right-hand side of
317 Numbers are composed of decimal digits. Floating point, hex, and
318 octal numbers are not supported. The maximum value for a number is
319 machine-dependent, but is usually 32-bits, including one bit for a
324 Text that is not enclosed in quotes is interpreted differently
325 depending on where it occurs in a condition. On the left hand side of
326 a condition, it is interpreted as a reference to an attribute. On the
327 right hand side, it is interpreted as a simple string, in the same
328 manner as a single-quoted string.
330 Using attribute references permits limited type-specific comparisons,
331 as seen in the examples below.
334 if (User-Name == "bob") {
338 if (Framed-IP-Address > 127.0.0.1) {
342 if (Service-Type == Login-User) {
347 Double-quoted strings are expanded by inserting the value of any
348 variables (see VARIABLES, below) before being evaluated. If
349 the result is a number it is evaluated in a numerical context.
351 String length is limited by line-length, usually about 8000
352 characters. A double quote character can be used in a string via
353 the normal back-slash escaping method. ("like \\"this\\" !")
356 Single-quoted strings are evaluated as-is. Their values are not
357 expanded as with double-quoted strings above, and they are not
358 interpreted as attribute references.
360 Back-quoted strings are evaluated by expanding the contents of the
361 string, as described above for double-quoted strings. The resulting
362 command given inside of the string in a sub-shell, and taking the
363 output as a string. This behavior is much the same as that of Unix
366 Note that for security reasons, the input string is split into command
367 and arguments before variable expansion is done.
369 For performance reasons, we suggest that the use of back-quoted
370 strings be kept to a minimum. Executing external programs is
371 relatively expensive, and executing a large number of programs for
372 every request can quickly use all of the CPU time in a server. If you
373 believe that you need to execute many programs, we suggest finding
374 alternative ways to achieve the same result. In some cases, using a
375 real language may be sufficient.
377 These strings are valid only on the right-hand side of a comparison,
378 and then only when the comparison operator is "=~" or "!~". They are
379 regular expressions, as implemented by the local regular expression
380 library on the system. This is usually Posix regular expressions.
382 The trailing 'i' is optional, and indicates that the regular
383 expression match should be done in a case-insensitive fashion.
385 If the comparison operator is "=~", then parantheses in the regular
386 expression will define variables containing the matching text, as
387 described below in the VARIABLES section.
389 Run-time variables are referenced using the following syntax
395 Note that unlike C, there is no way to declare variables, or to refer
396 to them outside of a string context. All references to variables MUST
397 be contained inside of a double-quoted or back-quoted string.
399 Many potential variables are defined in the dictionaries that
400 accompany the server. These definitions define only the name and
401 type, and do not define the value of the variable. When the server
402 receives a packet, it uses the packet contents to look up entries in
403 the dictionary, and instantiates variables with a name taken from the
404 dictionaries, and a value taken from the packet contents. This
405 process means that if a variable does not exist, it is usually because
406 it was not mentioned in a packet that the server received.
408 Once the variable is instantiated, it is added to an appropriate
409 attribute list, as described below. In many cases, attributes and
410 variables are inter-changeble, and are often talked about that way.
411 However, variables can also refer to run-time calls to modules, which
412 may perform operations like SQL SELECTs, and which may return the
413 result as the value of the variable.
415 Referencing attribute lists
417 Attribute lists may be referenced via the following syntax
420 %{<list>:Attribute-Name}
423 Where <list> is one of "request", "reply", "control", "proxy-request",
424 "proxy-reply", or "outer.request", "outer.reply", "outer.control",
425 "outer.proxy-request", or "outer.proxy-reply". just as with the
426 "update" section, above. The "<list>:" prefix is optional, and if
427 omitted, is assumed to refer to the "request" list.
429 When a variable is encountered, the given list is examined for an
430 attribute of the given name. If found, the variable reference in the
431 string is replaced with the value of that attribute. Some examples are:
436 %{request:User-Name} # same as above
440 %{outer.reqest:User-Name} # from inside of a TTLS/PEAP tunnel
444 Results of regular expression matches
446 If a regular expression match has previously been performed, then the
447 special variable %{0} will contain a copy of the input string. The
448 variables %{1} through %{8} will contain the substring matches,
449 starting from the left-most parantheses, and onwards. If there are
450 more than 8 parantheses, the additional results will not be placed
454 Obtaining results from databases
456 It is useful to query a database for some information, and to use the
457 result in a condition. The following syntax will call a module, pass
458 it the given string, and replace the variable reference with the
459 resulting string returned from the module.
462 %{module: string ...}
465 The syntax of the string is module-specific. Please read the module
466 documentation for additional details.
471 Conditional syntax similar to that used in Unix shells may also be
474 If %{Foo} has a value, returns that value.
476 Otherwise, returns literal string "bar".
477 .IP %{%{Foo}:-%{Bar}}
478 If %{Foo} has a value, returns that value.
480 Otherwise, returns the expansion of %{Bar}.
482 These conditional expansions can be nested to almost any depth, such
483 as with %{%{One}:-%{%{Two}:-%{Three}}}
486 String lengths and arrays
488 Similar to a Unix shell, there are ways to reference string lenths,
489 and the second or more instance of an attribute in a list. If you
490 need this functionality, we recommend using a real language.
492 The number of characters in %{string}. If %{string} is not
493 set, then the length is not set.
495 e.g. %{#Junk-junk:-foo} will yeild the string "foo".
496 .IP %{Attribute-Name[index]}
497 Reference the N'th occurance of the given attribute. The syntax
498 %{<list>:Attribute-Name[index]} may also be used. The indexes start
499 at zero. This feature is NOT available for non-attribute dynamic
500 translations, like %{sql:...}.
502 For example, %{User-Name[0]} is the same as %{User-Name}
504 The variable %{Cisco-AVPair[2]} will reference the value of the
505 THIRD Cisco-AVPair attribute (if it exists) in the request packet,
506 .IP %{Attribute-Name[#]}
507 Returns the total number of attributes of that name in the relevant
508 attribute list. The number will usually be between 0 and 200.
510 For most requests, %{request:User-Name[#]} == 1
511 .IP %{Attribute-Name[*]}
512 Expands to a single string, with the value of each array
513 member separated by a newline.
514 .IP %{#Attribute-Name[index]}
515 Expands to the length of the string %{Attribute-Name[index]}.
517 The attribute lists described above may be edited by listing one or
518 more attributes in an "update" section. Once the attributes have been
519 defined, they may be referenced as described above in the VARIABLES
522 The following syntax defines attributes in an "update" section. Each
523 attribute and value has to be all on one line in the configuration
524 file. There is no need for commas or semi-colons after the value.
527 Attribute-Name = value
532 The Attribute-Name must be a name previously defined in a dictionary.
533 If an undefined name is used, the server will return an error, and
537 The operator used to assign the value of the attribute may be one of
538 the following, with the given meaning.
541 Add the attribute to the list, if and only if an attribute of the same
542 name is not already present in that list.
544 Add the attribute to the list. If any attribute of the same name is
545 already present in that list, its value is replaced with the value of
546 the current attribute.
548 Add the attribute to the tail of the list, even if attributes of the
549 same name are already present in the list.
552 Enforcement and Filtering Operators
554 The following operators may also be used in addition to the ones
555 listed above. Their function is to perform enforcement or filtering
556 on attributes in a list.
558 Remove all matching attributes from the list. Both the attribute name
559 and value have to match in order for the attribute to be removed from
562 Keep all matching attributes. Both the attribute name and value have
563 to match in order for the attribute to remain in the list.
565 Note that this operator is very different than the '=' operator listed
568 Keep all attributes having values less than, or equal to, the value
569 given here. Any larger value is replaced by the value given here. If
570 no attribute exists, it is added with the value given here, as with
573 This operator is valid only for attributes of integer type.
575 Keep all attributes having values greater than, or equal to, the value
576 given here. Any larger value is replaced by the value given here. If
577 no attribute exists, it is added with the value given here, as with
580 This operator is valid only for attributes of integer type.
582 Delete all occurances of the named attribute, no matter what the
587 The format of the value is attribute-specific, and is usually a
588 string, integer, IP address, etc. Prior to the attribute being
589 instantiated, the value may be expanded as described above in the DATA
590 TYPES section, above. This flexibility means that, for example, you
591 can assign an IP address value to an attribute by specifying the IP
592 address directly, or by having the address returned from a database
593 query, or by having the address returned as the output of a program
596 When string values are finally assigned to a variable, they can have a
597 maximum length of 253 characters. This limit is due in part to both
598 protocol and internal server requirements. That is, the strings in
599 the language can be nearly 8k in length, say for a long SQL query.
600 However, the output of that SQL query should be no more than 253
601 characters in length.
603 Other keywords in the language are taken from the names of modules
604 loaded by the server. These keywords are dependent on both the
605 modules, and the local configuration.
607 Some use keywords that are defined in the default configuration file
610 Cause the request to be treated as if a database failure had occurred.
612 Do nothing. This also serves as an instruction to the configurable
613 failover tracking that nothing was done in the current section.
615 Instructs the server that the request was processed properly. This
616 keyword can be used to over-ride earlier failures, if the local
617 administrator determines that the faiures are not catastrophic.
619 Causes the request to be immediately rejected
620 .SH MODULE RETURN CODES
621 When a module is called, it returns one of the following codes to
622 "unlang", with the following meaning.
625 notfound information was not found
627 noop the module did nothing
629 ok the module succeeded
631 updated the module updated the request
633 fail the module failed
635 reject the module rejected the request
637 userlock the user was locked out
639 invalid the configuration was invalid
641 handled the module has handled the request itself
644 These return codes can be tested for in a condition, as described
645 above in the CONDITIONS section.
647 /etc/raddb/radiusd.conf
649 .BR radiusd.conf (5),
652 Alan DeKok <aland@deployingradius.com>
projects / freeradius.git / blob