1unlang(5) FreeRADIUS Processing un-language unlang(5)
2
6 unlang - FreeRADIUS Processing un-language
7
9 FreeRADIUS supports a simple processing language in its configuration
10 files. We call it an "un-language" because the intention is NOT to
11 create yet another programming language. If you need something more
12 complicated than what is described here, we suggest using the Perl or
13 Python modules rlm_perl, or rlm_python.
14 The goal of the language is to allow simple policies to be written with
16 minimal effort. Those policies are then applied when a request is
17 being processed. Requests are processed through virtual servers
18 (including the default one), in the sections titled "authorize",
19 "authenticate", "post-auth", "preacct", "accounting", "pre-proxy",
20 "post-proxy", and "session".
21 These policies cannot be used in any other part of the configuration
23 files, such as module or client configuration.
24
26 The keywords for the language are a combination of pre-defined key‐
27 words, and references to loadable module names. We document only the
28 pre-defined keywords here.
29 Subject to a few limitations described below, any keyword can appear in
31 any context. The language consists of a series of entries, each one
32 one line. Each entry begins with a keyword. Entries are organized
33 into lists. Processing of the language is line by line, from the start
34 of the list to the end. Actions are executed per-keyword.
35 module-name
37 A reference to the named module. When processing reaches this
38 point, the pre-compiled module is called. The module may suc‐
39 ceed or fail, and will return a status to "unlang" if so. This
40 status can be tested in a condition. See the "Simple Condi‐
41 tions" text in the CONDITIONS section, and MODULE RETURN CODES,
42 below.
43 chap # call the CHAP module
45 sql # call the SQL module
46 ...
47 if
49 Checks for a particular condition. If true, the block after the
50 condition is processed. Otherwise, the block is ignored. See
51 CONDITIONS, below, for documentation on the format of the condi‐
52 tions.
53 if (condition) {
55 ...
56 }
57 else
59 Define a block to be executed only if the previous "if" condi‐
60 tion returned false.
61 else {
63 ...
64 }
65 elsif
67 Define a block to be executed only if the previous "if" condi‐
68 tion returned false, and if the specified condition evaluates to
69 true.
70 elsif (condition) {
72 ...
73 }
74 switch
76 Evaluate the given string, and choose the first matching "case"
77 statement inside of the current block. If the string is sur‐
78 rounded by double quotes, it is expanded as described in the
79 DATA TYPES section, below.
80 No statement other than "case" can appear in a "switch" block.
82 switch "string" {
84 ...
85 }
86 case
88 Define a static string to match a parent "switch" statement.
89 The strings given here are not expanded as is done with the par‐
90 ent "switch" statement.
91 A "case" statement cannot appear outside of a "switch" block.
93 case string {
95 ...
96 }
97 A default entry can be defined by omitting the static string.
99 This entry will be used if no other "case" entry matches. Only
100 one default entry can exist in a "switch" section.
101 case {
103 ...
104 }
105 update
107 Update a particular attribute list, based on the attributes
108 given in the current block.
109 update <list> {
111 attribute = value
112 ...
113 }
114 The <list> can be one of "request", "reply", "proxy-request",
116 "proxy-reply", "coa", "disconnect", or "control". The "control"
117 list is the list of attributes maintainted internally by the
118 server that controls how the server processes the request. Any
119 attribute that does not go in a packet on the network will gen‐
120 erally be placed in the "control" list.
121 For backwards compatibility with older versions, "check" is
123 accepted as a synonym for "control". The use of "check" is dep‐
124 recated, and will be removed in a future release.
125 For EAP methods with tunneled authentication sessions (i.e. PEAP
127 and EAP-TTLS), the inner tunnel session can also reference
128 "outer.request", "outer.reply", and "outer.control". Those ref‐
129 erences allow you to address the relevant list in the outer tun‐
130 nel session.
131 The "coa" and "disconnect" sections can only be used when the
133 server receives an Access-Request or Accounting-Request. Use
134 "request" and "reply" instead of "coa" when the server receives
135 a CoA-Request or Disconnect-Request packet.
136 Adding one or more attributes to either of the "coa" or "discon‐
138 nect" list causes server to originate a CoA-Request or Discon‐
139 nect-Request packet. That packet is sent when the current
140 Access-Request or Accounting-Request has been finished, and a
141 reply sent to the NAS. See raddb/sites-available/originate-coa
142 for additional information.
143 The only contents permitted in an "update" section are
145 attributes and values. The contents of the "update" section are
146 described in the ATTRIBUTES section below.
147 redundant
149 This section contains a simple list of modules. The first mod‐
150 ule is called when the section is being processed. If the first
151 module succeeds in its operation, then the server stops process‐
152 ing the section, and returns to the parent section.
153 If, however, the module fails, then the next module in the list
155 is tried, as described above. The processing continues until
156 one module succeeds, or until the list has been exhausted.
157 Redundant sections can contain only a list of modules, and can‐
159 not contain keywords that perform conditional operations (if,
160 else, etc) or update an attribute list.
161 redundant {
163 sql1 # try this
164 sql2 # try this only if sql1 fails.
165 ...
166 }
167 load-balance
169 This section contains a simple list of modules. When the sec‐
170 tion is entered, one module is chosen at random to process the
171 request. All of the modules in the list should be the same type
172 (e.g. ldap or sql). All of the modules in the list should
173 behave identically, otherwise the load-balance section will
174 return different results for the same request.
175 Load-balance sections can contain only a list of modules, and
177 cannot contain keywords that perform conditional operations (if,
178 else, etc) or update an attribute list.
179 load-balance {
181 ldap1 # 50% of requests go here
182 ldap2 # 50% of requests go here
183 }
184 In general, we recommend using "redundant-load-balance" instead
186 of "load-balance".
187 redundant-load-balance
189 This section contains a simple list of modules. When the sec‐
190 tion is entered, one module is chosen at random to process the
191 request. If that module succeeds, then the server stops pro‐
192 cessing the section. If, however, the module fails, then one of
193 the remaining modules is chosen at random to process the
194 request. This process repeats until one module succeeds, or
195 until the list has been exhausted.
196 All of the modules in the list should be the same type (e.g.
198 ldap or sql). All of the modules in the list should behave
199 identically, otherwise the load-balance section will return dif‐
200 ferent results for the same request.
201 Load-balance sections can contain only a list of modules, and
203 cannot contain keywords that perform conditional operations (if,
204 else, etc) or update an attribute list.
205 redundant-load-balance {
207 ldap1 # 50%, unless ldap2 is down, then 100%
208 ldap2 # 50%, unless ldap1 is down, then 100%
209 }
210
212 The conditions are similar to C conditions in syntax, though quoted
213 strings are supported, as with the Unix shell.
214 Simple conditions
216 (foo)
217 Evalutes to true if 'foo' is a non-empty string (single quotes,
219 double quotes, or back-quoted). Also evaluates to true if 'foo'
220 is a non-zero number. Note that the language is poorly typed,
221 so the string "0000" can be interpreted as a numerical zero.
222 This issue can be avoided by comparings strings to an empty
223 string, rather than by evaluating the string by itself.
224 If the word 'foo' is not a quoted string, then it can be taken
226 as a reference to a named attribute. See "Referencing attribute
227 lists", below, for examples of attribute references. The condi‐
228 tion evaluates to true if the named attribute exists.
229 Otherwise, if the word 'foo' is not a quoted string, and is not
231 an attribute reference, then it is interpreted as a reference to
232 a module return code. The condition evaluates to true if the
233 most recent module return code matches the name given here.
234 Valid module return codes are given in MODULE RETURN CODES,
235 below.
236 Negation
238 (!foo)
239 Evalutes to true if 'foo' evaluates to false, and vice-versa.
241 Short-circuit operators
243 (foo || bar)
244 (foo && bar)
245 "&&" and "||" are short-circuit operators. "&&" evaluates the
247 first condition, and evaluates the second condition if and only
248 if the result of the first condition is true. "||" is similar,
249 but executes the second command if and only if the result of the
250 first condition is false.
251 Comparisons
253 (foo == bar)
254 Compares 'foo' to 'bar', and evaluates to true if the comparison
256 holds true. Valid comparison operators are "==", "!=", "<",
257 "<=", ">", ">=", "=~", and "!~", all with their usual meanings.
258 Invalid comparison operators are ":=" and "=".
259 Conditions may be nested to any depth, subject only to line length lim‐
261 itations (8192 bytes).
262
264 There are only a few data types supported in the language. Reference
265 to attributes, numbers, and strings. Any data type can appear in
266 stand-alone condition, in which case they are evaluated as described in
267 "Simple conditions", above. They can also appear (with some exceptions
268 noted below) on the left-hand or on the right-hand side of a compari‐
269 son.
270 numbers
272 Numbers are composed of decimal digits. Floating point, hex,
273 and octal numbers are not supported. The maximum value for a
274 number is machine-dependent, but is usually 32-bits, including
275 one bit for a sign value.
276 word
278 Text that is not enclosed in quotes is interpreted differently
279 depending on where it occurs in a condition. On the left hand
280 side of a condition, it is interpreted as a reference to an
281 attribute. On the right hand side, it is interpreted as a sim‐
282 ple string, in the same manner as a single-quoted string.
283 Using attribute references permits limited type-specific compar‐
285 isons, as seen in the examples below.
286 if (User-Name == "bob") {
288 ...
289 if (Framed-IP-Address > 127.0.0.1) {
290 ...
291 if (Service-Type == Login-User) {
292 "strings"
294 Double-quoted strings are expanded by inserting the value of any
295 variables (see VARIABLES, below) before being evaluated. If the
296 result is a number it is evaluated in a numerical context.
297 String length is limited by line-length, usually about 8000
299 characters. A double quote character can be used in a string
300 via the normal back-slash escaping method. ("like \"this\" !")
301 'strings'
303 Single-quoted strings are evaluated as-is. Their values are not
304 expanded as with double-quoted strings above, and they are not
305 interpreted as attribute references.
306 `strings`
308 Back-quoted strings are evaluated by expanding the contents of
309 the string, as described above for double-quoted strings. The
310 resulting command given inside of the string in a sub-shell, and
311 taking the output as a string. This behavior is much the same
312 as that of Unix shells.
313 Note that for security reasons, the input string is split into
315 command and arguments before variable expansion is done.
316 For performance reasons, we suggest that the use of back-quoted
318 strings be kept to a minimum. Executing external programs is
319 relatively expensive, and executing a large number of programs
320 for every request can quickly use all of the CPU time in a
321 server. If you believe that you need to execute many programs,
322 we suggest finding alternative ways to achieve the same result.
323 In some cases, using a real language may be sufficient.
324 /regex/i
326 These strings are valid only on the right-hand side of a compar‐
327 ison, and then only when the comparison operator is "=~" or
328 "!~". They are regular expressions, as implemented by the local
329 regular expression library on the system. This is usually Posix
330 regular expressions.
331 The trailing 'i' is optional, and indicates that the regular
333 expression match should be done in a case-insensitive fashion.
334 If the comparison operator is "=~", then parantheses in the reg‐
336 ular expression will define variables containing the matching
337 text, as described below in the VARIABLES section.
338
340 Run-time variables are referenced using the following syntax
341 %{Variable-Name}
343 Note that unlike C, there is no way to declare variables, or to refer
345 to them outside of a string context. All references to variables MUST
346 be contained inside of a double-quoted or back-quoted string.
347 Many potential variables are defined in the dictionaries that accompany
349 the server. These definitions define only the name and type, and do
350 not define the value of the variable. When the server receives a
351 packet, it uses the packet contents to look up entries in the dictio‐
352 nary, and instantiates variables with a name taken from the dictionar‐
353 ies, and a value taken from the packet contents. This process means
354 that if a variable does not exist, it is usually because it was not
355 mentioned in a packet that the server received.
356 Once the variable is instantiated, it is added to an appropriate
358 attribute list, as described below. In many cases, attributes and
359 variables are inter-changeble, and are often talked about that way.
360 However, variables can also refer to run-time calls to modules, which
361 may perform operations like SQL SELECTs, and which may return the
362 result as the value of the variable.
363 Referencing attribute lists
365 Attribute lists may be referenced via the following syntax
366 %{<list>:Attribute-Name}
368 Where <list> is one of "request", "reply", "control", "proxy-
370 request", "proxy-reply", or "outer.request", "outer.reply",
371 "outer.control", "outer.proxy-request", or "outer.proxy-reply".
372 just as with the "update" section, above. The "<list>:" prefix
373 is optional, and if omitted, is assumed to refer to the
374 "request" list.
375 When a variable is encountered, the given list is examined for
377 an attribute of the given name. If found, the variable refer‐
378 ence in the string is replaced with the value of that attribute.
379 Some examples are:
380 %{User-Name}
382 %{request:User-Name} # same as above
383 %{reply:User-Name}
384 %{outer.request:User-Name} # from inside of a TTLS/PEAP
385 tunnel
386 Results of regular expression matches
388 If a regular expression match has previously been performed,
389 then the special variable %{0} will contain a copy of the input
390 string. The variables %{1} through %{8} will contain the sub‐
391 string matches, starting from the left-most parantheses, and
392 onwards. If there are more than 8 parantheses, the additional
393 results will not be placed into any variables.
394 Obtaining results from databases
396 It is useful to query a database for some information, and to
397 use the result in a condition. The following syntax will call a
398 module, pass it the given string, and replace the variable ref‐
399 erence with the resulting string returned from the module.
400 %{module: string ...}
402 The syntax of the string is module-specific. Please read the
404 module documentation for additional details.
405 Conditional Syntax
407 Conditional syntax similar to that used in Unix shells may also
408 be used.
409 %{%{Foo}:-bar}
411 If %{Foo} has a value, returns that value.
412 Otherwise, returns literal string "bar".
413 %{%{Foo}:-%{Bar}}
415 If %{Foo} has a value, returns that value.
416 Otherwise, returns the expansion of %{Bar}.
417 These conditional expansions can be nested to almost any
419 depth, such as with %{%{One}:-%{%{Two}:-%{Three}}}
420 String lengths and arrays
422 Similar to a Unix shell, there are ways to reference string
423 lenths, and the second or more instance of an attribute in a
424 list. If you need this functionality, we recommend using a real
425 language.
426 %{#string}
428 The number of characters in %{string}. If %{string} is
429 not set, then the length is not set.
430 e.g. %{#Junk-junk:-foo} will yeild the string "foo".
432 %{Attribute-Name#}
434 Will print the integer value of the attribute, rather
435 than a decoded VALUE or date. This feature applies only
436 to attributes of type "date", "integer", "byte", and
437 "short". It has no effect on any other attributes. It
438 is used when the numerical value is needed (e.g. Unix
439 seconds), rather than a humanly-readable string.
440 e.g. If a request contains "Service-Type = Login-User",
442 the expansion of %{Service-Type#} will yeild "1".
443 %{Attribute-Name[index]}
445 Reference the N'th occurance of the given attribute. The
446 syntax %{<list>:Attribute-Name[index]} may also be used.
447 The indexes start at zero. This feature is NOT available
448 for non-attribute dynamic translations, like %{sql:...}.
449 For example, %{User-Name[0]} is the same as %{User-Name}
451 The variable %{Cisco-AVPair[2]} will reference the value
453 of the THIRD Cisco-AVPair attribute (if it exists) in the
454 request packet,
455 %{Attribute-Name[#]}
457 Returns the total number of attributes of that name in
458 the relevant attribute list. The number will usually be
459 between 0 and 200.
460 For most requests, %{request:User-Name[#]} == 1
462 %{Attribute-Name[*]}
464 Expands to a single string, with the value of each array
465 member separated by a newline.
466 %{#Attribute-Name[index]}
468 Expands to the length of the string %{Attribute-
469 Name[index]}.
470
472 The attribute lists described above may be edited by listing one or
473 more attributes in an "update" section. Once the attributes have been
474 defined, they may be referenced as described above in the VARIABLES
475 section.
476 The following syntax defines attributes in an "update" section. Each
478 attribute and value has to be all on one line in the configuration
479 file. There is no need for commas or semi-colons after the value.
480 Attribute-Name = value
482 Attribute names
484 The Attribute-Name must be a name previously defined in a dic‐
485 tionary. If an undefined name is used, the server will return
486 an error, and will not start.
487 Operators
489 The operator used to assign the value of the attribute may be
490 one of the following, with the given meaning.
491 = Add the attribute to the list, if and only if an
493 attribute of the same name is not already present in that
494 list.
495 := Add the attribute to the list. If any attribute of the
497 same name is already present in that list, its value is
498 replaced with the value of the current attribute.
499 += Add the attribute to the tail of the list, even if
501 attributes of the same name are already present in the
502 list.
503 Enforcement and Filtering Operators
505 The following operators may also be used in addition to the ones
506 listed above. Their function is to perform enforcement or fil‐
507 tering on attributes in a list.
508 -= Remove all matching attributes from the list. Both the
510 attribute name and value have to match in order for the
511 attribute to be removed from the list.
512 == Keep all matching attributes. Both the attribute name
514 and value have to match in order for the attribute to
515 remain in the list.
516 Note that this operator is very different than the '='
518 operator listed above!
519 <= Keep all attributes having values less than, or equal to,
521 the value given here. Any larger value is replaced by
522 the value given here. If no attribute exists, it is
523 added with the value given here, as with "+=".
524 This operator is valid only for attributes of integer
526 type.
527 >= Keep all attributes having values greater than, or equal
529 to, the value given here. Any larger value is replaced
530 by the value given here. If no attribute exists, it is
531 added with the value given here, as with "+=".
532 This operator is valid only for attributes of integer
534 type.
535 !* Delete all occurances of the named attribute, no matter
537 what the value.
538 Values
540 The format of the value is attribute-specific, and is usually a
541 string, integer, IP address, etc. Prior to the attribute being
542 instantiated, the value may be expanded as described above in
543 the DATA TYPES section, above. This flexibility means that, for
544 example, you can assign an IP address value to an attribute by
545 specifying the IP address directly, or by having the address
546 returned from a database query, or by having the address
547 returned as the output of a program that is executed.
548 When string values are finally assigned to a variable, they can
550 have a maximum length of 253 characters. This limit is due in
551 part to both protocol and internal server requirements. That
552 is, the strings in the language can be nearly 8k in length, say
553 for a long SQL query. However, the output of that SQL query
554 should be no more than 253 characters in length.
555
557 Other keywords in the language are taken from the names of modules
558 loaded by the server. These keywords are dependent on both the mod‐
559 ules, and the local configuration.
560 Some use keywords that are defined in the default configuration file
562 are:
563 fail Cause the request to be treated as if a database failure had
565 occurred.
566 noop Do nothing. This also serves as an instruction to the config‐
568 urable failover tracking that nothing was done in the current
569 section.
570 ok Instructs the server that the request was processed properly.
572 This keyword can be used to over-ride earlier failures, if the
573 local administrator determines that the faiures are not cata‐
574 strophic.
575 reject Causes the request to be immediately rejected
577
579 When a module is called, it returns one of the following codes to
580 "unlang", with the following meaning.
581 notfound information was not found
583 noop the module did nothing
584 ok the module succeeded
585 updated the module updated the request
586 fail the module failed
587 reject the module rejected the request
588 userlock the user was locked out
589 invalid the configuration was invalid
590 handled the module has handled the request itself
591 These return codes can be tested for in a condition, as described above
593 in the CONDITIONS section.
594 See also the file doc/configurable_failover for additional methods of
596 trapping and modifying module return codes.
597
599 /etc/raddb/radiusd.conf
600
602 radiusd.conf(5), dictionary(5)
603
605 Alan DeKok <aland@deployingradius.com>
606 19 May 2010 unlang(5)