-.TH unlang 5 "12 Jun 2007" "" "FreeRADIUS Processing un-language"
+.\" # DS - begin display
+.de DS
+.RS
+.nf
+.sp
+..
+.\" # DE - end display
+.de DE
+.fi
+.RE
+.sp
+..
+.TH unlang 5 "01 Jul 2008" "" "FreeRADIUS Processing un-language"
.SH NAME
unlang \- FreeRADIUS Processing un\-language
.SH DESCRIPTION
.br
Evaluate the given string, and choose the first matching "case"
statement inside of the current block. If the string is surrounded by
-double quotes, it is expanded as described below in the STRINGS AND
-VARIABLES section.
+double quotes, it is expanded as described in the DATA TYPES section,
+below.
No statement other than "case" can appear in a "switch" block.
For EAP methods with tunneled authentication sessions (i.e. PEAP and
EAP-TTLS), the inner tunnel session can also reference
"outer.request", "outer.reply", and "outer.control". Those references
-will update the relevant list in the outer tunnel session.
+allow you to address the relevant list in the outer tunnel session.
The only contents permitted in an "update" section are attributes and
values. The contents of the "update" section are described in the
or update an attribute list.
.DS
- redundant load-balance {
+ redundant-load-balance {
.br
ldap1 # 50%, unless ldap2 is down, then 100%
.br
Evalutes to true if 'foo' is a non-empty string (single quotes, double
quotes, or back-quoted). Also evaluates to true if 'foo' is a
-non-zero number. Note that the language is not typed, so the string
-"0000" can be interpreted as a numerical zero. This issue can be
-avoided by comparings strings to an empty string, rather than by
+non-zero number. Note that the language is poorly typed, so the
+string "0000" can be interpreted as a numerical zero. This issue can
+be avoided by comparings strings to an empty string, rather than by
evaluating the string by itself.
-If the text is not quoted, then it is used as a test for one of the
-module return codes. The condition evaluates to true if the most
-recent module return code matches the name given here. Valid module
-return codes are given in MODULE RETURN CODES, below.
+If the word 'foo' is not a quoted string, then it can be taken as a
+reference to a named attribute. See "Referencing attribute lists",
+below, for examples of attribute references. The condition evaluates
+to true if the named attribute exists.
+
+Otherwise, if the word 'foo' is not a quoted string, and is not an
+attribute reference, then it is interpreted as a reference to a module
+return code. The condition evaluates to true if the most recent
+module return code matches the name given here. Valid module return
+codes are given in MODULE RETURN CODES, below.
.IP Negation
.DS
(!foo)
.PP
Conditions may be nested to any depth, subject only to line length
limitations (8192 bytes).
-.SH STRINGS AND NUMBERS
-Strings and numbers can appear as stand-alone conditions, 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.
+.SH 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.
.IP 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.
.PP
-"strings"
+word
+.RS
+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.
+
+.DS
+ if (User-Name == "bob") {
+.br
+ ...
+.br
+ if (Framed-IP-Address > 127.0.0.1) {
+.br
+ ...
+.br
+ if (Service-Type == Login-User) {
+.DE
+.RE
+.IP "strings"
.RS
Double-quoted strings are expanded by inserting the value of any
variables (see VARIABLES, below) before being evaluated. If
String length is limited by line-length, usually about 8000
characters. A double quote character (") can be used in a string via
-the normal escaping method. ("like \\"this\\" !")
+the normal back-slash escaping method. ("like \\"this\\" !")
.RE
.IP 'strings'
-Single-quoted strings are evaluated as-is.
-
+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.
.IP `strings`
Back-quoted strings are evaluated by expanding the contents of the
string, as described above for double-quoted strings. The resulting
%{<list>:Attribute-Name}
.DE
-Where <list> is one of "request", "reply", "proxy-request",
-"proxy-reply", "control", "outer.request", "outer.reply", or
-"outer.control", as described above in the documentation for the
-"update" section. The "<list>:" prefix is optional, and if omitted,
-is assumed to refer to the "request" list.
+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
%{request:User-Name} # same as above
.br
%{reply:User-Name}
+.br
+ %{outer.reqest:User-Name} # from inside of a TTLS/PEAP tunnel
.DE
.RE
.PP
to the value given here. If there is no attribute of the same name in
the list, the attribute is added with the given value, is with "+=".
If an attribute in the list exists, and has value less than given
-here, it's value is unchanged. If an attribute in the exists, and has
-value greater than given here, it's value is replaced with the value
-given here.
+here, it's value is unchanged. If an attribute in the list exists,
+and has a value greater than given here, then that value is replaced
+with the one given here.
This operator is valid only for attributes of integer type.
.IP >=
equal to the value given here. If there is no attribute of the same
name in the list, the attribute is added with the given value, is with
"+=". If an attribute in the list exists, and has value greater than
-given here, it's value is unchanged. If an attribute in the exists,
-and has value less than given here, it's value is replaced with the
-value given here.
+given here, it's value is unchanged. If an attribute in the list
+exists, and has value less than given here, then that value is
+replaced with the one given here.
This operator is valid only for attributes of integer type.
.RE
.br
The format of the value is attribute-specific, and is usually a
string, integer, IP address, etc. Prior to the attribute being
-instantiated, the value is handled as described above in the STRINGS
-AND NUMBERS section. This flexibility means that, for example, you
+instantiated, the value may be expanded as described above in the DATA
+TYPES section, above. This flexibility means that, for example, you
can assign an IP address value to an attribute by specifying the IP
address directly, or by having the address returned from a database
query, or by having the address returned as the output of a program
Some use keywords that are defined in the default configuration file
are:
.IP fail
-Cause the request to be treated as if a database failure had occured.
+Cause the request to be treated as if a database failure had occurred.
.IP noop
Do nothing. This also serves as an instruction to the configurable
failover tracking that nothing was done in the current section.