table of contents
other versions
- wheezy 2.1.12+dfsg-1.2
- wheezy-backports 2.2.5+dfsg-0.1~bpo70+1
- jessie 2.2.5+dfsg-0.2
- testing 3.0.12+dfsg-5
- unstable 3.0.12+dfsg-5
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.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.- 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.
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 {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.
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.
- /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.
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.
- %{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.
- %{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:...}.
- %{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.
- %{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.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.
- <=
- 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 "+=".
- >=
- 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 "+=".
- !*
- 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.- 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 |