table of contents
unlang(5) | FreeRADIUS Processing un-language | unlang(5) |
NAME¶
unlang - FreeRADIUS Processing un-languageDESCRIPTION¶
FreeRADIUS supports a simple processing language in its configuration files. We call it an "un-language" because the intention is NOT to create yet another programming language. If you need something more complicated than what is described here, we suggest using the Perl or Python modules rlm_perl, or rlm_python. The goal of the language is to allow simple policies to be written with minimal effort. Those policies are then applied when a request is being processed. Requests are processed through virtual servers (including the default one), in the sections titled "authorize", "authenticate", "post-auth", "preacct", "accounting", "pre-proxy", "post-proxy", and "session". These policies cannot be used in any other part of the configuration files, such as module or client configuration.KEYWORDS¶
The keywords for the language are a combination of pre-defined keywords, and references to loadable module names. We document only the pre-defined keywords here. Subject to a few limitations described below, any keyword can appear in any context. The language consists of a series of entries, each one one line. Each entry begins with a keyword. Entries are organized into lists. Processing of the language is line by line, from the start of the list to the end. Actions are executed per-keyword.- module-name
- A reference to the named module. When processing reaches this point, the pre-compiled module is called. The module may succeed or fail, and will return a status to "unlang" if so. This status can be tested in a condition. See the "Simple Conditions" text in the CONDITIONS section, and MODULE RETURN CODES, below.
chap # call the CHAP modulesql # call the SQL module...
- if
-
if (condition) {...}
- else
-
else {...}
- elsif
-
elsif (condition) {...}
- switch
-
switch "string" {...}
- case
-
case string {...}
case {...}
- update
-
update <list> {attribute = value...}
- redundant
- This section contains a simple list of modules. The first module is called when the section is being processed. If the first module succeeds in its operation, then the server stops processing the section, and returns to the parent section. If, however, the module fails, then the next module in the list is tried, as described above. The processing continues until one module succeeds, or until the list has been exhausted. Redundant sections can contain only a list of modules, and cannot contain keywords that perform conditional operations (if, else, etc) or update an attribute list.
redundant {sql1 # try thissql2 # try this only if sql1 fails....}
- load-balance
- This section contains a simple list of modules. When the section is entered, one module is chosen at random to process the request. All of the modules in the list should be the same type (e.g. ldap or sql). All of the modules in the list should behave identically, otherwise the load-balance section will return different results for the same request. Load-balance sections can contain only a list of modules, and cannot contain keywords that perform conditional operations (if, else, etc) or update an attribute list.
load-balance {ldap1 # 50% of requests go hereldap2 # 50% of requests go here}
- redundant-load-balance
- This section contains a simple list of modules. When the section is entered, one module is chosen at random to process the request. If that module succeeds, then the server stops processing the section. If, however, the module fails, then one of the remaining modules is chosen at random to process the request. This process repeats until one module succeeds, or until the list has been exhausted. All of the modules in the list should be the same type (e.g. ldap or sql). All of the modules in the list should behave identically, otherwise the load-balance section will return different results for the same request. Load-balance sections can contain only a list of modules, and cannot contain keywords that perform conditional operations (if, else, etc) or update an attribute list.
redundant-load-balance {ldap1 # 50%, unless ldap2 is down, then 100%ldap2 # 50%, unless ldap1 is down, then 100%}
CONDITIONS¶
The conditions are similar to C conditions in syntax, though quoted strings are supported, as with the Unix shell.- Simple
- conditions
(foo)
- Negation
(!foo)
(foo || bar)(foo && bar)
- Comparisons
(foo == bar)
DATA TYPES¶
There are only a few data types supported in the language. Reference to attributes, numbers, and strings. Any data type can appear in stand-alone condition, in which case they are evaluated as described in "Simple conditions", above. They can also appear (with some exceptions noted below) on the left-hand or on the right-hand side of a comparison.- numbers
- Numbers are composed of decimal digits. Floating point, hex, and octal numbers are not supported. The maximum value for a number is machine-dependent, but is usually 32-bits, including one bit for a sign value.
Text that is not enclosed in quotes is interpreted
differently depending on where it occurs in a condition. On the left hand side
of a condition, it is interpreted as a reference to an attribute. On the right
hand side, it is interpreted as a simple string, in the same manner as a
single-quoted string.
Using attribute references permits limited type-specific comparisons, as seen in
the examples below.
if (User-Name == "bob") {...if (Framed-IP-Address > 127.0.0.1) {...if (Service-Type == Login-User) {
- "strings"
Double-quoted strings are expanded by inserting the value
of any variables (see VARIABLES, below) before being evaluated. If the result
is a number it is evaluated in a numerical context.
String length is limited by line-length, usually about 8000 characters. A double
quote character can be used in a string via the normal back-slash escaping
method. ("like \"this\" !")
- 'strings'
- Single-quoted strings are evaluated as-is. Their values are not expanded as with double-quoted strings above, and they are not interpreted as attribute references.
- `strings`
- Back-quoted strings are evaluated by expanding the contents of the string, as described above for double-quoted strings. The resulting command given inside of the string in a sub-shell, and taking the output as a string. This behavior is much the same as that of Unix shells. Note that for security reasons, the input string is split into command and arguments before variable expansion is done. For performance reasons, we suggest that the use of back-quoted strings be kept to a minimum. Executing external programs is relatively expensive, and executing a large number of programs for every request can quickly use all of the CPU time in a server. If you believe that you need to execute many programs, we suggest finding alternative ways to achieve the same result. In some cases, using a real language may be sufficient.
- /regex/i
- These strings are valid only on the right-hand side of a comparison, and then only when the comparison operator is "=~" or "!~". They are regular expressions, as implemented by the local regular expression library on the system. This is usually Posix regular expressions. The trailing 'i' is optional, and indicates that the regular expression match should be done in a case-insensitive fashion. If the comparison operator is "=~", then parantheses in the regular expression will define variables containing the matching text, as described below in the VARIABLES section.
VARIABLES¶
Run-time variables are referenced using the following syntax%{Variable-Name}
Attribute lists may be referenced via the following
syntax
Where <list> is one of "request", "reply",
"control", "proxy-request", "proxy-reply", or
"outer.request", "outer.reply", "outer.control",
"outer.proxy-request", or "outer.proxy-reply". just as
with the "update" section, above. The "<list>:"
prefix is optional, and if omitted, is assumed to refer to the
"request" list.
When a variable is encountered, the given list is examined for an attribute of
the given name. If found, the variable reference in the string is replaced
with the value of that attribute. Some examples are:
Results of regular expression matches
%{<list>:Attribute-Name}
%{User-Name}%{request:User-Name} # same as above%{reply:User-Name}%{outer.request:User-Name} # from inside of a TTLS/PEAP tunnel
If a regular expression match has previously been
performed, then the special variable %{0} will contain a copy of the input
string. The variables %{1} through %{8} will contain the substring matches,
starting from the left-most parantheses, and onwards. If there are more than 8
parantheses, the additional results will not be placed into any
variables.
Obtaining results from databases
It is useful to query a database for some information,
and to use the result in a condition. The following syntax will call a module,
pass it the given string, and replace the variable reference with the
resulting string returned from the module.
The syntax of the string is module-specific. Please read the module
documentation for additional details.
Conditional Syntax
%{module: string ...}
Conditional syntax similar to that used in Unix shells
may also be used.
String lengths and arrays
- %{%{Foo}:-bar}
- If %{Foo} has a value, returns that value.
- %{%{Foo}:-%{Bar}}
- If %{Foo} has a value, returns that value.
Similar to a Unix shell, there are ways to reference
string lenths, and the second or more instance of an attribute in a list. If
you need this functionality, we recommend using a real language.
- %{#string}
- The number of characters in %{string}. If %{string} is not set, then the length is not set. e.g. %{#Junk-junk:-foo} will yeild the string "foo".
- %{Attribute-Name#}
- Will print the integer value of the attribute, rather than a decoded VALUE or date. This feature applies only to attributes of type "date", "integer", "byte", and "short". It has no effect on any other attributes. It is used when the numerical value is needed (e.g. Unix seconds), rather than a humanly-readable string. e.g. If a request contains "Service-Type = Login-User", the expansion of %{Service-Type#} will yeild "1".
- %{Attribute-Name[index]}
- Reference the N'th occurance of the given attribute. The syntax %{<list>:Attribute-Name[index]} may also be used. The indexes start at zero. This feature is NOT available for non-attribute dynamic translations, like %{sql:...}. For example, %{User-Name[0]} is the same as %{User-Name} The variable %{Cisco-AVPair[2]} will reference the value of the THIRD Cisco-AVPair attribute (if it exists) in the request packet,
- %{Attribute-Name[#]}
- Returns the total number of attributes of that name in the relevant attribute list. The number will usually be between 0 and 200. For most requests, %{request:User-Name[#]} == 1
- %{Attribute-Name[*]}
- Expands to a single string, with the value of each array member separated by a newline.
- %{#Attribute-Name[index]}
- Expands to the length of the string %{Attribute-Name[index]}.
ATTRIBUTES¶
The attribute lists described above may be edited by listing one or more attributes in an "update" section. Once the attributes have been defined, they may be referenced as described above in the VARIABLES section. The following syntax defines attributes in an "update" section. Each attribute and value has to be all on one line in the configuration file. There is no need for commas or semi-colons after the value.Attribute-Name = value
The Attribute-Name must be a name previously defined in a
dictionary. If an undefined name is used, the server will return an error, and
will not start.
- Operators
- The operator used to assign the value of the attribute may be one of the following, with the given meaning.
- =
- Add the attribute to the list, if and only if an attribute of the same name is not already present in that list.
- :=
- Add the attribute to the list. If any attribute of the same name is already present in that list, its value is replaced with the value of the current attribute.
- +=
- Add the attribute to the tail of the list, even if attributes of the same name are already present in the list.
The following operators may also be used in addition to
the ones listed above. Their function is to perform enforcement or filtering
on attributes in a list.
- -=
- Remove all matching attributes from the list. Both the attribute name and value have to match in order for the attribute to be removed from the list.
- ==
- Keep all matching attributes. Both the attribute name and value have to match in order for the attribute to remain in the list. Note that this operator is very different than the '=' operator listed above!
- <=
- Keep all attributes having values less than, or equal to, the value given here. Any larger value is replaced by the value given here. If no attribute exists, it is added with the value given here, as with "+=". This operator is valid only for attributes of integer type.
- >=
- Keep all attributes having values greater than, or equal to, the value given here. Any larger value is replaced by the value given here. If no attribute exists, it is added with the value given here, as with "+=". This operator is valid only for attributes of integer type.
- !*
- Delete all occurances of the named attribute, no matter what the value.
- Values
-
OTHER KEYWORDS¶
Other keywords in the language are taken from the names of modules loaded by the server. These keywords are dependent on both the modules, and the local configuration. Some use keywords that are defined in the default configuration file are:- fail
- Cause the request to be treated as if a database failure had occurred.
- noop
- Do nothing. This also serves as an instruction to the configurable failover tracking that nothing was done in the current section.
- ok
- Instructs the server that the request was processed properly. This keyword can be used to over-ride earlier failures, if the local administrator determines that the faiures are not catastrophic.
- reject
- Causes the request to be immediately rejected
MODULE RETURN CODES¶
When a module is called, it returns one of the following codes to "unlang", with the following meaning.notfound information was not foundnoop the module did nothingok the module succeededupdated the module updated the requestfail the module failedreject the module rejected the requestuserlock the user was locked outinvalid the configuration was invalidhandled the module has handled the request itself
FILES¶
/etc/raddb/radiusd.confSEE ALSO¶
radiusd.conf(5), dictionary(5)AUTHOR¶
Alan DeKok <aland@deployingradius.com>19 May 2010 |