1 .TH unlang 5 "16 Jan 2008" "" "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, may be expanded as described in the DATA TYPES section,
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 For EAP methods with tunneled authentication sessions (i.e. PEAP and
145 EAP-TTLS), the inner tunnel session can also reference
146 "outer.request", "outer.reply", and "outer.control". Those references
147 will update the relevant list in the outer tunnel session.
149 The only contents permitted in an "update" section are attributes and
150 values. The contents of the "update" section are described in the
151 ATTRIBUTES section below.
153 This section contains a simple list of modules. The first module is
154 called when the section is being processed. If the first module
155 succeeds in its operation, then the server stops processing the
156 section, and returns to the parent section.
158 If, however, the module fails, then the next module in the list is
159 tried, as described above. The processing continues until one module
160 succeeds, or until the list has been exhausted.
162 Redundant sections can contain only a list of modules, and cannot
163 contain keywords that perform conditional operations (if, else, etc)
164 or update an attribute list.
171 sql2 # try this only if sql1 fails.
178 This section contains a simple list of modules. When the section is
179 entered, one module is chosen at random to process the request. All
180 of the modules in the list should be the same type (e.g. ldap or sql).
181 All of the modules in the list should behave identically, otherwise
182 the load-balance section will return different results for the same
185 Load-balance sections can contain only a list of modules, and cannot
186 contain keywords that perform conditional operations (if, else, etc)
187 or update an attribute list.
192 ldap1 # 50% of requests go here
194 ldap2 # 50% of requests go here
199 In general, we recommend using "redundant-load-balance" instead of
201 .IP redundant-load-balance
202 This section contains a simple list of modules. When the section is
203 entered, one module is chosen at random to process the request. If
204 that module succeeds, then the server stops processing the section.
205 If, however, the module fails, then one of the remaining modules is
206 chosen at random to process the request. This process repeats until
207 one module succeeds, or until the list has been exhausted.
209 All of the modules in the list should be the same type (e.g. ldap or
210 sql). All of the modules in the list should behave identically,
211 otherwise the load-balance section will return different results for
214 Load-balance sections can contain only a list of modules, and cannot
215 contain keywords that perform conditional operations (if, else, etc)
216 or update an attribute list.
219 redundant-load-balance {
221 ldap1 # 50%, unless ldap2 is down, then 100%
223 ldap2 # 50%, unless ldap1 is down, then 100%
228 The conditions are similar to C conditions in syntax, though
229 quoted strings are supported, as with the Unix shell.
237 Evalutes to true if 'foo' is a non-empty string (single quotes, double
238 quotes, or back-quoted). Also evaluates to true if 'foo' is a
239 non-zero number. Note that the language is poorly typed, so the
240 string "0000" can be interpreted as a numerical zero. This issue can
241 be avoided by comparings strings to an empty string, rather than by
242 evaluating the string by itself.
244 If the word 'foo' is not a quoted string, then it can be taken as a
245 reference to a named attribute. See "Referencing attribute lists",
246 below, for examples of attribute references. The condition evaluates
247 to true if the named attribute exists.
249 Otherwise, if the word 'foo' is not a quoted string, and is not an
250 attribute reference, then it is interpreted as a reference to a module
251 return code. The condition evaluates to true if the most recent
252 module return code matches the name given here. Valid module return
253 codes are given in MODULE RETURN CODES, below.
259 Evalutes to true if 'foo' evaluates to false, and vice-versa.
261 Short-circuit operators
270 "&&" and "||" are short-circuit operators. "&&" evaluates the first
271 condition, and evaluates the second condition if and only if the
272 result of the first condition is true. "||" is similar, but executes
273 the second command if and only if the result of the first condition is
281 Compares 'foo' to 'bar', and evaluates to true if the comparison holds
282 true. Valid comparison operators are "==", "!=", "<", "<=", ">",
283 ">=", "=~", and "!~", all with their usual meanings. Invalid
284 comparison operators are ":=" and "=".
286 Conditions may be nested to any depth, subject only to line length
287 limitations (8192 bytes).
289 There are only a few data types supported in the language. Reference
290 to attributes, numbers, and strings. Any data type can appear in
291 stand-alone condition, in which case they are evaluated as described
292 in "Simple conditions", above. They can also appear (with some
293 exceptions noted below) on the left-hand or on the right-hand side of
296 Numbers are composed of decimal digits. Floating point, hex, and
297 octal numbers are not supported. The maximum value for a number is
298 machine-dependent, but is usually 32-bits, including one bit for a
303 Text that is not enclosed in quotes is interpreted differently
304 depending on where it occurs in a condition. On the left hand side of
305 a condition, it is interpreted as a reference to an attribute. On the
306 right hand side, it is interpreted as a simple string, in the same
307 manner as a single-quoted string.
309 Using attribute references permits limited type-specific comparisons,
310 as seen in the examples below.
313 if (User-Name == "bob") {
317 if (Framed-IP-Address > 127.0.0.1) {
321 if (Service-Type == Login-User) {
326 Double-quoted strings are expanded by inserting the value of any
327 variables (see VARIABLES, below) before being evaluated. If
328 the result is a number it is evaluated in a numerical context.
330 String length is limited by line-length, usually about 8000
331 characters. A double quote character (") can be used in a string via
332 the normal back-slash escaping method. ("like \\"this\\" !")
335 Single-quoted strings are evaluated as-is. Their values are not
336 expanded as with double-quoted strings above, and they are not
337 interpreted as attribute references.
339 Back-quoted strings are evaluated by expanding the contents of the
340 string, as described above for double-quoted strings. The resulting
341 command given inside of the string in a sub-shell, and taking the
342 output as a string. This behavior is much the same as that of Unix
345 Note that for security reasons, the input string is split into command
346 and arguments before variable expansion is done.
348 For performance reasons, we suggest that the use of back-quoted
349 strings be kept to a minimum. Executing external programs is
350 relatively expensive, and executing a large number of programs for
351 every request can quickly use all of the CPU time in a server. If you
352 believe that you need to execute many programs, we suggest finding
353 alternative ways to achieve the same result. In some cases, using a
354 real language may be sufficient.
356 These strings are valid only on the right-hand side of a comparison,
357 and then only when the comparison operator is "=~" or "!~". They are
358 regular expressions, as implemented by the local regular expression
359 library on the system. This is usually Posix regular expressions.
361 The trailing 'i' is optional, and indicates that the regular
362 expression match should be done in a case-insensitive fashion.
364 If the comparison operator is "=~", then parantheses in the regular
365 expression will define variables containing the matching text, as
366 described below in the VARIABLES section.
368 Run-time variables are referenced using the following syntax
374 Note that unlike C, there is no way to declare variables, or to refer
375 to them outside of a string context. All references to variables MUST
376 be contained inside of a double-quoted or back-quoted string.
378 Many potential variables are defined in the dictionaries that
379 accompany the server. These definitions define only the name and
380 type, and do not define the value of the variable. When the server
381 receives a packet, it uses the packet contents to look up entries in
382 the dictionary, and instantiates variables with a name taken from the
383 dictionaries, and a value taken from the packet contents. This
384 process means that if a variable does not exist, it is usually because
385 it was not mentioned in a packet that the server received.
387 Once the variable is instantiated, it is added to an appropriate
388 attribute list, as described below. In many cases, attributes and
389 variables are inter-changeble, and are often talked about that way.
390 However, variables can also refer to run-time calls to modules, which
391 may perform operations like SQL SELECTs, and which may return the
392 result as the value of the variable.
394 Referencing attribute lists
396 Attribute lists may be referenced via the following syntax
399 %{<list>:Attribute-Name}
402 Where <list> is one of "request", "reply", "proxy-request",
403 "proxy-reply", "control", "outer.request", "outer.reply", or
404 "outer.control", as described above for the "update" section. The
405 "<list>:" prefix is optional, and if omitted, is assumed to refer to
408 When a variable is encountered, the given list is examined for an
409 attribute of the given name. If found, the variable reference in the
410 string is replaced with the value of that attribute. Some examples are:
415 %{request:User-Name} # same as above
421 Results of regular expression matches
423 If a regular expression match has previously been performed, then the
424 special variable %{0} will contain a copy of the input string. The
425 variables %{1} through %{8} will contain the substring matches,
426 starting from the left-most parantheses, and onwards. If there are
427 more than 8 parantheses, the additional results will not be placed
431 Obtaining results from databases
433 It is useful to query a database for some information, and to use the
434 result in a condition. The following syntax will call a module, pass
435 it the given string, and replace the variable reference with the
436 resulting string returned from the module.
439 %{module: string ...}
442 The syntax of the string is module-specific. Please read the module
443 documentation for additional details.
448 Conditional syntax similar to that used in Unix shells may also be
451 If %{Foo} has a value, returns that value.
453 Otherwise, returns literal string "bar".
454 .IP %{%{Foo}:-%{Bar}}
455 If %{Foo} has a value, returns that value.
457 Otherwise, returns the expansion of %{Bar}.
459 These conditional expansions can be nested to almost any depth, such
460 as with %{%{One}:-%{%{Two}:-%{Three}}}
463 String lengths and arrays
465 Similar to a Unix shell, there are ways to reference string lenths,
466 and the second or more instance of an attribute in a list. If you
467 need this functionality, we recommend using a real language.
469 The number of characters in %{string}. If %{string} is not
470 set, then the length is not set.
472 e.g. %{#Junk-junk:-foo} will yeild the string "foo".
473 .IP %{Attribute-Name[index]}
474 Reference the N'th occurance of the given attribute. The syntax
475 %{<list>:Attribute-Name[index]} may also be used. The indexes start
476 at zero. This feature is NOT available for non-attribute dynamic
477 translations, like %{sql:...}.
479 For example, %{User-Name[0]} is the same as %{User-Name}
481 The variable %{Cisco-AVPair[2]} will reference the value of the
482 THIRD Cisco-AVPair attribute (if it exists) in the request packet,
483 .IP %{Attribute-Name[#]}
484 Returns the total number of attributes of that name in the relevant
485 attribute list. The number will usually be between 0 and 200.
487 For most requests, %{request:User-Name[#]} == 1
488 .IP %{Attribute-Name[*]}
489 Expands to a single string, with the value of each array
490 member separated by a newline.
491 .IP %{#Attribute-Name[index]}
492 Expands to the length of the string %{Attribute-Name[index]}.
494 The attribute lists described above may be edited by listing one or
495 more attributes in an "update" section. Once the attributes have been
496 defined, they may be referenced as described above in the VARIABLES
499 The following syntax defines attributes in an "update" section. Each
500 attribute and value has to be all on one line in the configuration
501 file. There is no need for commas or semi-colons after the value.
504 Attribute-Name = value
509 The Attribute-Name must be a name previously defined in a dictionary.
510 If an undefined name is used, the server will return an error, and
514 The operator used to assign the value of the attribute may be one of
515 the following, with the given meaning.
518 Add the attribute to the list, if and only if an attribute of the same
519 name is already present in that list.
521 Add the attribute to the list. If any attribute of the same name is
522 already present in that list, its value is replaced with the value of
523 the current attribute.
525 Add the attribute to the tail of the list, even if attributes of the
526 same name are already present in the list.
529 Enforcement and Filtering Operators
531 The following operators may also be used in addition to the ones
532 listed above. Their function is to perform enforcement or filtering
533 on attributes in a list.
535 Remove all matching attributes from the list. Both the attribute name
536 and value have to match in order for the attribute to be removed from
539 Remove all non-matching attributes from the list. Both the attribute
540 name and value have to match in order for the attribute to remain in
543 Note that this operator is very different than the '=' operator listed
546 Enforce that the integer value of the attribute is less than or equal
547 to the value given here. If there is no attribute of the same name in
548 the list, the attribute is added with the given value, is with "+=".
549 If an attribute in the list exists, and has value less than given
550 here, it's value is unchanged. If an attribute in the list exists,
551 and has a value greater than given here, then that value is replaced
552 with the one given here.
554 This operator is valid only for attributes of integer type.
556 Enforce that the integer value of the attribute is greater than or
557 equal to the value given here. If there is no attribute of the same
558 name in the list, the attribute is added with the given value, is with
559 "+=". If an attribute in the list exists, and has value greater than
560 given here, it's value is unchanged. If an attribute in the list
561 exists, and has value less than given here, then that value is
562 replaced with the one given here.
564 This operator is valid only for attributes of integer type.
568 The format of the value is attribute-specific, and is usually a
569 string, integer, IP address, etc. Prior to the attribute being
570 instantiated, the value may be expanded as described above in the DATA
571 TYPES section, above. This flexibility means that, for example, you
572 can assign an IP address value to an attribute by specifying the IP
573 address directly, or by having the address returned from a database
574 query, or by having the address returned as the output of a program
577 When string values are finally assigned to a variable, they can have a
578 maximum length of 253 characters. This limit is due in part to both
579 protocol and internal server requirements. That is, the strings in
580 the language can be nearly 8k in length, say for a long SQL query.
581 However, the output of that SQL query should be no more than 253
582 characters in length.
584 Other keywords in the language are taken from the names of modules
585 loaded by the server. These keywords are dependent on both the
586 modules, and the local configuration.
588 Some use keywords that are defined in the default configuration file
591 Cause the request to be treated as if a database failure had occurred.
593 Do nothing. This also serves as an instruction to the configurable
594 failover tracking that nothing was done in the current section.
596 Instructs the server that the request was processed properly. This
597 keyword can be used to over-ride earlier failures, if the local
598 administrator determines that the faiures are not catastrophic.
600 Causes the request to be immediately rejected
601 .SH MODULE RETURN CODES
602 When a module is called, it returns one of the following codes to
603 "unlang", with the following meaning.
606 notfound information was not found
608 noop the module did nothing
610 ok the module succeeded
612 updated the module updated the request
614 fail the module failed
616 reject the module rejected the request
618 userlock the user was locked out
620 invalid the configuration was invalid
622 handled the module has handled the request itself
625 These return codes can be tested for in a condition, as described
626 above in the CONDITIONS section.
628 /etc/raddb/radiusd.conf
630 .BR radiusd.conf (5),
633 Alan DeKok <aland@deployingradius.com>
projects / freeradius.git / blob