1 .\" # DS - begin display
13 .TH unlang 5 "19 May 2010" "" "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
25 is being processed. Requests are processed through virtual servers
26 (including the default one), in the sections titled "authorize",
27 "authenticate", "post-auth", "preacct", "accounting", "pre-proxy",
28 "post-proxy", and "session".
30 These policies cannot be used in any other part of the configuration
31 files, such as module or client configuration.
33 The keywords for the language are a combination of pre-defined
34 keywords, and references to loadable module names. We document only
35 the pre-defined keywords here.
37 Subject to a few limitations described below, any keyword can appear
38 in any context. The language consists of a series of entries, each
39 one one line. Each entry begins with a keyword. Entries are
40 organized into lists. Processing of the language is line by line,
41 from the start of the list to the end. Actions are executed
44 A reference to the named module. When processing reaches this point,
45 the pre-compiled module is called. The module may succeed or fail,
46 and will return a status to "unlang" if so. This status can be tested
47 in a condition. See the "Simple Conditions" text in the CONDITIONS
48 section, and MODULE RETURN CODES, below.
51 chap # call the CHAP module
53 sql # call the SQL module
59 Checks for a particular condition. If true, the block after the
60 condition is processed. Otherwise, the block is ignored. See
61 CONDITIONS, below, for documentation on the format of the conditions.
72 Define a block to be executed only if the previous "if" condition
84 Define a block to be executed only if the previous "if" condition
85 returned false, and if the specified condition evaluates to true.
96 Evaluate the given string, and choose the first matching "case"
97 statement inside of the current block. If the string is surrounded by
98 double quotes, it is expanded as described in the DATA TYPES section,
101 No statement other than "case" can appear in a "switch" block.
112 Define a static string to match a parent "switch" statement. The
113 strings given here are not expanded as is done with the parent
116 A "case" statement cannot appear outside of a "switch" block.
126 A default entry can be defined by omitting the static string. This
127 entry will be used if no other "case" entry matches. Only one default
128 entry can exist in a "switch" section.
139 Update a particular attribute list, based on the attributes given in
152 The <list> can be one of "request", "reply", "proxy-request",
153 "proxy-reply", "coa", "disconnect", or "control". The "control" list
154 is the list of attributes maintainted internally by the server that
155 controls how the server processes the request. Any attribute that
156 does not go in a packet on the network will generally be placed in the
159 For backwards compatibility with older versions, "check" is accepted
160 as a synonym for "control". The use of "check" is deprecated, and
161 will be removed in a future release.
163 For EAP methods with tunneled authentication sessions (i.e. PEAP and
164 EAP-TTLS), the inner tunnel session can also reference
165 "outer.request", "outer.reply", and "outer.control". Those references
166 allow you to address the relevant list in the outer tunnel session.
168 The "coa" and "disconnect" sections can only be used when the server
169 receives an Access-Request or Accounting-Request. Use "request" and
170 "reply" instead of "coa" when the server receives a CoA-Request or
171 Disconnect-Request packet.
173 Adding one or more attributes to either of the "coa" or "disconnect"
174 list causes server to originate a CoA-Request or Disconnect-Request
175 packet. That packet is sent when the current Access-Request or
176 Accounting-Request has been finished, and a reply sent to the NAS.
177 See raddb/sites-available/originate-coa for additional information.
179 The only contents permitted in an "update" section are attributes and
180 values. The contents of the "update" section are described in the
181 ATTRIBUTES section below.
183 This section contains a simple list of modules. The first module is
184 called when the section is being processed. If the first module
185 succeeds in its operation, then the server stops processing the
186 section, and returns to the parent section.
188 If, however, the module fails, then the next module in the list is
189 tried, as described above. The processing continues until one module
190 succeeds, or until the list has been exhausted.
192 Redundant sections can contain only a list of modules, and cannot
193 contain keywords that perform conditional operations (if, else, etc)
194 or update an attribute list.
201 sql2 # try this only if sql1 fails.
208 This section contains a simple list of modules. When the section is
209 entered, one module is chosen at random to process the request. All
210 of the modules in the list should be the same type (e.g. ldap or sql).
211 All of the modules in the list should behave identically, otherwise
212 the load-balance section will return different results for the same
215 Load-balance sections can contain only a list of modules, and cannot
216 contain keywords that perform conditional operations (if, else, etc)
217 or update an attribute list.
222 ldap1 # 50% of requests go here
224 ldap2 # 50% of requests go here
229 In general, we recommend using "redundant-load-balance" instead of
231 .IP redundant-load-balance
232 This section contains a simple list of modules. When the section is
233 entered, one module is chosen at random to process the request. If
234 that module succeeds, then the server stops processing the section.
235 If, however, the module fails, then one of the remaining modules is
236 chosen at random to process the request. This process repeats until
237 one module succeeds, or until the list has been exhausted.
239 All of the modules in the list should be the same type (e.g. ldap or
240 sql). All of the modules in the list should behave identically,
241 otherwise the load-balance section will return different results for
244 Load-balance sections can contain only a list of modules, and cannot
245 contain keywords that perform conditional operations (if, else, etc)
246 or update an attribute list.
249 redundant-load-balance {
251 ldap1 # 50%, unless ldap2 is down, then 100%
253 ldap2 # 50%, unless ldap1 is down, then 100%
258 The conditions are similar to C conditions in syntax, though
259 quoted strings are supported, as with the Unix shell.
267 Evalutes to true if 'foo' is a non-empty string (single quotes, double
268 quotes, or back-quoted). Also evaluates to true if 'foo' is a
269 non-zero number. Note that the language is poorly typed, so the
270 string "0000" can be interpreted as a numerical zero. This issue can
271 be avoided by comparings strings to an empty string, rather than by
272 evaluating the string by itself.
274 If the word 'foo' is not a quoted string, then it can be taken as a
275 reference to a named attribute. See "Referencing attribute lists",
276 below, for examples of attribute references. The condition evaluates
277 to true if the named attribute exists.
279 Otherwise, if the word 'foo' is not a quoted string, and is not an
280 attribute reference, then it is interpreted as a reference to a module
281 return code. The condition evaluates to true if the most recent
282 module return code matches the name given here. Valid module return
283 codes are given in MODULE RETURN CODES, below.
289 Evalutes to true if 'foo' evaluates to false, and vice-versa.
291 Short-circuit operators
300 "&&" and "||" are short-circuit operators. "&&" evaluates the first
301 condition, and evaluates the second condition if and only if the
302 result of the first condition is true. "||" is similar, but executes
303 the second command if and only if the result of the first condition is
311 Compares 'foo' to 'bar', and evaluates to true if the comparison holds
312 true. Valid comparison operators are "==", "!=", "<", "<=", ">",
313 ">=", "=~", and "!~", all with their usual meanings. Invalid
314 comparison operators are ":=" and "=".
316 Conditions may be nested to any depth, subject only to line length
317 limitations (8192 bytes).
319 There are only a few data types supported in the language. Reference
320 to attributes, numbers, and strings. Any data type can appear in
321 stand-alone condition, in which case they are evaluated as described
322 in "Simple conditions", above. They can also appear (with some
323 exceptions noted below) on the left-hand or on the right-hand side of
326 Numbers are composed of decimal digits. Floating point, hex, and
327 octal numbers are not supported. The maximum value for a number is
328 machine-dependent, but is usually 32-bits, including one bit for a
333 Text that is not enclosed in quotes is interpreted differently
334 depending on where it occurs in a condition. On the left hand side of
335 a condition, it is interpreted as a reference to an attribute. On the
336 right hand side, it is interpreted as a simple string, in the same
337 manner as a single-quoted string.
339 Using attribute references permits limited type-specific comparisons,
340 as seen in the examples below.
343 if (User-Name == "bob") {
347 if (Framed-IP-Address > 127.0.0.1) {
351 if (Service-Type == Login-User) {
356 Double-quoted strings are expanded by inserting the value of any
357 variables (see VARIABLES, below) before being evaluated. If
358 the result is a number it is evaluated in a numerical context.
360 String length is limited by line-length, usually about 8000
361 characters. A double quote character can be used in a string via
362 the normal back-slash escaping method. ("like \\"this\\" !")
365 Single-quoted strings are evaluated as-is. Their values are not
366 expanded as with double-quoted strings above, and they are not
367 interpreted as attribute references.
369 Back-quoted strings are evaluated by expanding the contents of the
370 string, as described above for double-quoted strings. The resulting
371 command given inside of the string in a sub-shell, and taking the
372 output as a string. This behavior is much the same as that of Unix
375 Note that for security reasons, the input string is split into command
376 and arguments before variable expansion is done.
378 For performance reasons, we suggest that the use of back-quoted
379 strings be kept to a minimum. Executing external programs is
380 relatively expensive, and executing a large number of programs for
381 every request can quickly use all of the CPU time in a server. If you
382 believe that you need to execute many programs, we suggest finding
383 alternative ways to achieve the same result. In some cases, using a
384 real language may be sufficient.
386 These strings are valid only on the right-hand side of a comparison,
387 and then only when the comparison operator is "=~" or "!~". They are
388 regular expressions, as implemented by the local regular expression
389 library on the system. This is usually Posix regular expressions.
391 The trailing 'i' is optional, and indicates that the regular
392 expression match should be done in a case-insensitive fashion.
394 If the comparison operator is "=~", then parantheses in the regular
395 expression will define variables containing the matching text, as
396 described below in the VARIABLES section.
398 Run-time variables are referenced using the following syntax
404 Note that unlike C, there is no way to declare variables, or to refer
405 to them outside of a string context. All references to variables MUST
406 be contained inside of a double-quoted or back-quoted string.
408 Many potential variables are defined in the dictionaries that
409 accompany the server. These definitions define only the name and
410 type, and do not define the value of the variable. When the server
411 receives a packet, it uses the packet contents to look up entries in
412 the dictionary, and instantiates variables with a name taken from the
413 dictionaries, and a value taken from the packet contents. This
414 process means that if a variable does not exist, it is usually because
415 it was not mentioned in a packet that the server received.
417 Once the variable is instantiated, it is added to an appropriate
418 attribute list, as described below. In many cases, attributes and
419 variables are inter-changeble, and are often talked about that way.
420 However, variables can also refer to run-time calls to modules, which
421 may perform operations like SQL SELECTs, and which may return the
422 result as the value of the variable.
424 Referencing attribute lists
426 Attribute lists may be referenced via the following syntax
429 %{<list>:Attribute-Name}
432 Where <list> is one of "request", "reply", "control", "proxy-request",
433 "proxy-reply", or "outer.request", "outer.reply", "outer.control",
434 "outer.proxy-request", or "outer.proxy-reply". just as with the
435 "update" section, above. The "<list>:" prefix is optional, and if
436 omitted, is assumed to refer to the "request" list.
438 When a variable is encountered, the given list is examined for an
439 attribute of the given name. If found, the variable reference in the
440 string is replaced with the value of that attribute. Some examples are:
445 %{request:User-Name} # same as above
449 %{outer.reqest:User-Name} # from inside of a TTLS/PEAP tunnel
453 Results of regular expression matches
455 If a regular expression match has previously been performed, then the
456 special variable %{0} will contain a copy of the input string. The
457 variables %{1} through %{8} will contain the substring matches,
458 starting from the left-most parantheses, and onwards. If there are
459 more than 8 parantheses, the additional results will not be placed
463 Obtaining results from databases
465 It is useful to query a database for some information, and to use the
466 result in a condition. The following syntax will call a module, pass
467 it the given string, and replace the variable reference with the
468 resulting string returned from the module.
471 %{module: string ...}
474 The syntax of the string is module-specific. Please read the module
475 documentation for additional details.
480 Conditional syntax similar to that used in Unix shells may also be
483 If %{Foo} has a value, returns that value.
485 Otherwise, returns literal string "bar".
486 .IP %{%{Foo}:-%{Bar}}
487 If %{Foo} has a value, returns that value.
489 Otherwise, returns the expansion of %{Bar}.
491 These conditional expansions can be nested to almost any depth, such
492 as with %{%{One}:-%{%{Two}:-%{Three}}}
495 String lengths and arrays
497 Similar to a Unix shell, there are ways to reference string lenths,
498 and the second or more instance of an attribute in a list. If you
499 need this functionality, we recommend using a real language.
501 The number of characters in %{string}. If %{string} is not
502 set, then the length is not set.
504 e.g. %{#Junk-junk:-foo} will yeild the string "foo".
505 .IP %{Attribute-Name#}
506 Will print the integer value of the attribute, rather than a decoded
507 VALUE or date. This feature applies only to attributes of type
508 "date", "integer", "byte", and "short". It has no effect on any other
509 attributes. It is used when the numerical value is needed (e.g. Unix
510 seconds), rather than a humanly-readable string.
512 e.g. If a request contains "Service-Type = Login-User", the expansion
513 of %{Service-Type#} will yeild "1".
514 .IP %{Attribute-Name[index]}
515 Reference the N'th occurance of the given attribute. The syntax
516 %{<list>:Attribute-Name[index]} may also be used. The indexes start
517 at zero. This feature is NOT available for non-attribute dynamic
518 translations, like %{sql:...}.
520 For example, %{User-Name[0]} is the same as %{User-Name}
522 The variable %{Cisco-AVPair[2]} will reference the value of the
523 THIRD Cisco-AVPair attribute (if it exists) in the request packet,
524 .IP %{Attribute-Name[#]}
525 Returns the total number of attributes of that name in the relevant
526 attribute list. The number will usually be between 0 and 200.
528 For most requests, %{request:User-Name[#]} == 1
529 .IP %{Attribute-Name[*]}
530 Expands to a single string, with the value of each array
531 member separated by a newline.
532 .IP %{#Attribute-Name[index]}
533 Expands to the length of the string %{Attribute-Name[index]}.
535 The attribute lists described above may be edited by listing one or
536 more attributes in an "update" section. Once the attributes have been
537 defined, they may be referenced as described above in the VARIABLES
540 The following syntax defines attributes in an "update" section. Each
541 attribute and value has to be all on one line in the configuration
542 file. There is no need for commas or semi-colons after the value.
545 Attribute-Name = value
550 The Attribute-Name must be a name previously defined in a dictionary.
551 If an undefined name is used, the server will return an error, and
555 The operator used to assign the value of the attribute may be one of
556 the following, with the given meaning.
559 Add the attribute to the list, if and only if an attribute of the same
560 name is not already present in that list.
562 Add the attribute to the list. If any attribute of the same name is
563 already present in that list, its value is replaced with the value of
564 the current attribute.
566 Add the attribute to the tail of the list, even if attributes of the
567 same name are already present in the list.
570 Enforcement and Filtering Operators
572 The following operators may also be used in addition to the ones
573 listed above. Their function is to perform enforcement or filtering
574 on attributes in a list.
576 Remove all matching attributes from the list. Both the attribute name
577 and value have to match in order for the attribute to be removed from
580 Keep all matching attributes. Both the attribute name and value have
581 to match in order for the attribute to remain in the list.
583 Note that this operator is very different than the '=' operator listed
586 Keep all attributes having values less than, or equal to, the value
587 given here. Any larger value is replaced by the value given here. If
588 no attribute exists, it is added with the value given here, as with
591 This operator is valid only for attributes of integer type.
593 Keep all attributes having values greater than, or equal to, the value
594 given here. Any larger value is replaced by the value given here. If
595 no attribute exists, it is added with the value given here, as with
598 This operator is valid only for attributes of integer type.
600 Delete all occurances of the named attribute, no matter what the
605 The format of the value is attribute-specific, and is usually a
606 string, integer, IP address, etc. Prior to the attribute being
607 instantiated, the value may be expanded as described above in the DATA
608 TYPES section, above. This flexibility means that, for example, you
609 can assign an IP address value to an attribute by specifying the IP
610 address directly, or by having the address returned from a database
611 query, or by having the address returned as the output of a program
614 When string values are finally assigned to a variable, they can have a
615 maximum length of 253 characters. This limit is due in part to both
616 protocol and internal server requirements. That is, the strings in
617 the language can be nearly 8k in length, say for a long SQL query.
618 However, the output of that SQL query should be no more than 253
619 characters in length.
621 Other keywords in the language are taken from the names of modules
622 loaded by the server. These keywords are dependent on both the
623 modules, and the local configuration.
625 Some use keywords that are defined in the default configuration file
628 Cause the request to be treated as if a database failure had occurred.
630 Do nothing. This also serves as an instruction to the configurable
631 failover tracking that nothing was done in the current section.
633 Instructs the server that the request was processed properly. This
634 keyword can be used to over-ride earlier failures, if the local
635 administrator determines that the faiures are not catastrophic.
637 Causes the request to be immediately rejected
638 .SH MODULE RETURN CODES
639 When a module is called, it returns one of the following codes to
640 "unlang", with the following meaning.
643 notfound information was not found
645 noop the module did nothing
647 ok the module succeeded
649 updated the module updated the request
651 fail the module failed
653 reject the module rejected the request
655 userlock the user was locked out
657 invalid the configuration was invalid
659 handled the module has handled the request itself
662 These return codes can be tested for in a condition, as described
663 above in the CONDITIONS section.
665 See also the file doc/configurable_failover for additional methods of
666 trapping and modifying module return codes.
668 /etc/raddb/radiusd.conf
670 .BR radiusd.conf (5),
673 Alan DeKok <aland@deployingradius.com>
projects / freeradius.git / blob