The use of extension language allows to extend the functionality of GNU Radius without having to modify its source code. The two extension languages supported are Rewrite and Scheme. Use of Rewrite is always enabled. Use of Scheme requires Guile version 1.4 or higher.
Rewrite is the GNU Radius extension language. Its name reflects the fact that it was originally designed to rewrite the broken request packets, so they could be processed as usual (see section Rewriting Incoming Requests). Beside this basic use, however, Rewrite functions are used in verifying the activity of user sessions (see section Checking Simultaneous Logins).
Rewrite syntax resembles that of C. Rewrite has two basic data types:
integer and string. It does not have global variables, all variables are
automatic. The only exception are the A/V pairs from the incoming request,
which are accessible to Rewrite functions via special notation
%[attr].
As an example, let's consider the following Rewrite function:
string
foo(integer i)
{
string rc;
if (i % 2)
rc = "odd";
else
rc = "even";
return "the number is " + rc;
}
The function takes an integer argument and returns string "the number is odd" or "the number is even", depending on the value of i. This illustrates the fact that in Rewrite the addition operator is defined on the string type. The result of such operation is the concatenation of operands.
Another example is a function that adds a prefix to the User-Name
attribute:
integer
px_add()
{
%[User-Name] = "pfx-" + %[User-Name];
return 0;
}
The function manipulates the contents of the incoming request, its return value has no special meaning.
A Rewrite function can be invoked in several ways, depending on its purpose. There are three major kinds of Rewrite functions:
The need of rewriting the incoming requests arises from the fact that
some NASes are very particular about the information they send with
the requests. There are cases when the information they send
is hardly usable or even just unusable. For example, a
Cisco AS5300 terminal server used as a voice over IP router packs
a lot of information into its Acct-Session-Id attribute. Though
the information stored there is otherwise relevant, it makes proper
accounting impossible since the Acct-Session-Id attributes
in the start and stop packets of the same session become different, and
thus Radius cannot determine the Session Start to which the given
Session Stop request corresponds (see section Acct-Session-Id).
In order to cope with such NASes, GNU Radius is able to invoke a Rewrite function upon arrival of the packet and before further processing it. This function can transform the packet so, that it obtains the form prescribed by RFCs and its further processing becomes possible.
For example, in the case of AS5300 router, a corresponding rewrite
function parses the Acct-Session-Id attribute, breaks it
down into fields, stores them into proper attributes, creating
them if necessary, and, finally replaces Acct-Session-Id with
its real value, which is the same for start and stop records
corresponding to a single session. Thus all the information that
came with the packet is preserved, but the packet itself is made
usable for proper accounting.
A special attribute, Rewrite-Function, is used to trigger
invocation of a Rewrite function. Its value is a name of the
function to be invoked.
When used in a `naslist' profile, the attribute causes the function
to be invoked when the incoming request matches the huntgroup
(see section Huntgroups). For example, to have a function fixup
invoked for each packet from the NAS 10.10.10.11, the
following huntgroup rule may be used:
DEFAULT NAS-IP-Address = 11.10.10.11
Rewrite-Function = "fixup"
The Rewrite-Function attribute may also be used in a `hints'
rule. In this case, it will invoke the function if the request matches
the rule (see section Hints). For example, this `hints' rule will
cause the function to be invoked for each request containing the username
starting with `P':
DEFAULT Prefix = "P"
Rewrite-Function = "fixup"
Please note, that in both cases the attribute can be used either in LHS or in RHS pairs of a rule.
The packet rewrite function must be declared as having no arguments, and returning integer value:
integer fixup()
{
}
The actual return value from such a function is ignored, the integer return type is just a matter of convention.
The following subsection present some examples of packet rewriting functions.
The examples found in this chapter are working functions that can be used with various existing NAS types. They are taken from the `rewrite' file contained in distribution of GNU Radius.
Some MAX Ascend terminal servers pack additional information
into NAS-Port-Id attribute. The port number is constructed as
XYYZZ, where X = 1 for digital, X = 2 for analog, YY is line number
(1 for first PRI/T1/E1, 2 for second, so on), and ZZ = channel number
(on the PRI or Channelized T1/E1).
The following rewrite functions are intended to compute the integer
port number in the range (1 .. portcnt), where portcnt
represents the real number of physical ports available on the NAS.
Such port number can be used, for example, with
Add-Port-To-IP-Address attribute (see section Add-Port-To-IP-Address).
/*
* decode MAX port number
* input: P -- The value of NAS-Port-Id attribute
* portcnt -- number of physical ports on the NAS
*/
integer
max_decode_port(integer P, integer portcnt)
{
if (P > 9999) {
integer s, l, c;
s = P / 10000;
l = (P - (10000 * s))/100;
c = P - ((10000 * s) + (100 * l));
return (c-1) + (l-1) * portcnt;
}
return P;
}
/*
* Interface function for MAX terminal server with 23 ports.
* Note that it saves the received NAS-Port-Id attribute in the
* Orig-NAS-Port-Id attribute. The latter must be defined somewhere
* in the dictionary
*/
integer
max_fixup()
{
%[Orig-NAS-Port-Id] = %[NAS-Port-Id]; # Preserve original data
%[NAS-Port-Id] = max_decode_port(%[NAS-Port-Id], 23);
return 0;
}
Cisco VOIP IOS encodes a lot of other information into its
Acct-Session-Id. The pieces of information are separated by
`/' character. The part of Acct-Session-Id up to first
`/' character is the actual session ID.
On the other hand, its accounting packets lack NAS-Port-Id,
though they may contain the vendor-specific pair with code 2
(vendor PEC 9), which is the string in the form `ISDN 9:D:999'
(`9' represents a decimal digit). The number after the last
`:' character can be used as a port number.
The following code parses Acct-Session-Id attribute and stores
the information it contains in various other attributes, generates
normal Acct-Session-Id and attempts to generate
NAS-Port-Id attribute.
/*
* The port rewriting function for Cisco AS5300 used for VoIP.
* This function is used to generate NAS-Port-Id pair on the basis
* of vendor-specific pair 2. If the latter is in the form
* "ISDN 9:D:999" (where each 9 represents a decimal digit), then
* the function returns the number after the last colon. This is
* used as a port number.
*/
integer
cisco_pid(string A)
{
if (A =~
".*\([0-9][0-9]*\):[A-Z0-9][A-Z0-9]*:\([0-9][0-9]*\)") {
return (integer)\2;
}
return -1;
}
/*
* This function parses the packed session id.
* The actual sid is the number before the first slash character.
* Other possibly relevant fields are also parsed out and saved
* in the Voip-* A/V pairs. The latter should be defined somewhere
* in the dictionary.
* Please note, that the regular expression in this example
* spans several lines for readability. It should be on one
* line in real file.
*/
string
cisco_sid(string S)
{
if (S =~ "\(.[^/]*\)/[^/]*/[^/]*/\([^/]*\)/\([^/]*\)/
\([^/]*\)/\([^/]*\)/\([^/]*\)/\([^/]*\)
/\([^/]*\).*") {
%[Voip-Connection-ID] = \2;
%[Voip-Call-Leg-Type] = \3;
%[Voip-Connection-Type] = \4;
%[Voip-Connect-Time] = \5;
%[Voip-Disconnect-Time] = \6;
%[Voip-Disconnect-Cause] = \7;
%[Voip-Remote-IP] = \8;
return \1;
}
return S;
}
/*
* Normalize cisco AS5300 packets
*/
integer
cisco_fixup()
{
integer pid;
if ((pid = cisco_pid(%[Cisco-PRI-Circuit])) != -1) {
if (*%[NAS-Port-Id])
%[Orig-NAS-Port-Id] = %[NAS-Port-Id];
%[NAS-Port-Id] = pid;
}
if (*%[Acct-Session-Id]) {
%[Orig-Acct-Session-Id] = %[Acct-Session-Id];
%[Acct-Session-Id] = cisco_sid(%[Acct-Session-Id]);
}
return 0;
}
Users coming from Windows NT machines often authenticate themselves as
`NT_DOMAIN\username'. The following function selects the username part
and stores it in the User-Name attribute:
integer
login_nt(string uname)
{
integer i;
if ((i = index(uname, '\\')) != -1)
return substr(uname, i+1, -1);
return uname;
}
integer
nt_rewrite()
{
%[Orig-User-Name] = %[User-Name];
%[User-Name] = login_nt(%[User-Name]);
return 0;
}
A login verification function is invoked to process the output from the
NAS. This process is described in section Checking Simultaneous Logins.
The function to be invoked for given NAS is defined by
function flag in `raddb/nastypes' or `raddb/naslist'
files (see section NAS Types -- `raddb/nastypes'). It must be defined as follows:
integer check(string str, string name, integer pid, string sid)
{
}
Its arguments are:
finger, this is the string
of output received from the NAS with trailing newline stripped off. If
the query method is snmp, this is the received variable value
converted to its string representation.
The function should return non-0 if its arguments match user's session and 0 otherwise.
As an example, let's consider the function for analyzing a line line of output from a standard UNIX finger service. In each line of finger output the first field contains username, the third field --- tty number (Port ID), and the seventh field contains session ID. The function must return 1 if the three fields match the input user name, port and session IDs.
integer
check_unix(string str, string name, integer pid, string sid)
{
return field(str, 1) == name
&& field(str, 3) == pid
&& field(str, 7) == sid;
}
Next example is a function to analyze a line of output from an SNMP query returning a user name. This function must return 1 if entire input line matches the user name.
integer
check_username(string str, string name, integer pid, string sid)
{
return str == name;
}
These are the functions, used to create RADIUS reply attributes. An attribute creation function can take any number of arguments. The type of its return is determined by the type of RADIUS attribute the value will be assigned to. To invoke the function, write its name in the A/V pair of RHS in `raddb/users' file, e.g.:
DEFAULT Auth-Type = SQL
Service-Type = Framed-User,
Framed-IP-Address = "=get_ip_addr(10.10.10.1)"
The function get_ip_addr will be invoked after successful
authentication and it will be passed IP address 10.10.10.1 as its
argument. An example of a useful function, that can be invoked this
way:
integer
get_ip_address(integer base)
{
return base + %[NAS-Port-Id] - %[NAS-Port-Id]/16;
}
There are only two data types: integer and string,
the two being coercible to each other in the sense that a string
can be coerced to an integer if it contains a valid ASCII representation
of a decimal, octal or hex number, and the integer can always be coerced
to a string, the result of such coercion being the ASCII string with
decimal representation of the number.
A symbol is a lexical token. The following symbols are recognized:
Rewrite-Function attribute. It is kept as an associative array,
whose entries can be accessed using the following syntax:
`%[' attribute-name `]'
Thus notation returns the value of the attribute attribute-name.
attribute-name should be a valid Radius dictionary name
(see section Dictionary of Attributes -- `raddb/dictionary').
`\number'
refers to the contents of parenthesized group number number
obtained as a result of the last executed `=~' command.
The regexp group reference has always string data type. E.g.
string
basename(string arg)
{
if (arg =~ ".*/\(.*\)\..*")
return \1;
else
return arg;
}
This function strips from arg all leading components up to the
last slash character, and all trailing components after the last dot
character. It returns arg unaltered, if it does not contain
slashes and dots. Roughly, it is analogous to the system basename
utility.
A valid identifier is a string of characters meeting the following requirements:
The Rewrite function is declared as follows:
type function-name (parameter-list)
where type specifies the return type of the function, function-name declares the symbolic name of the function and parameter-list declares the formal parameters to the function. It is a comma-separated list of declarations in the form:
type parm-name
type being the parameter type, and parm-name being its symbolic name. Both function-name and parm-name should be valid identifiers.
There are no global variables in Rewrite. All variables are local. The local variables are declared right after the opening curly brace (`{') and before any executable statements. The declaration syntax is:
type ident_list ;
Here ident_list is either a valid Rewrite identifier, or a comma- separated list of such identifiers. Please note that, unlike in C, no assignments are allowed in variable declarations.
The Rewrite statements are: expressions, assignments, conditional statements and return statements. A statement is terminated by semicolon.
An expression is:
The type coercion is like a type cast in C. Its syntax is
`(' type `)' ident
the result of type coercion is as follows:
| type | Variable type | Resulting conversion |
| integer | integer | No conversion. This results in the same integer value. |
| integer | string | If the string value of the variable is a valid ASCII representation | of the integer number (either decimal, octal or hex) it is converted to the integer, otherwise the result of the conversion is undefined.
| string | integer | The ASCII representation (in decimal) of the integer number. |
| string | string | No conversion. This results in the same string value. |
An assignment is:
ident = expression ;
The variable ident is assigned the value of expression.
These take the form:
ident ( arg-list )
where ident is the identifier representing the function, arg-list is a comma-separated list of expressions supplying actual arguments to the function. The function ident references can be either a compiled function or a built-in function.
Please note that, unlike in C, the mismatch between the number of actual arguments and number of formal parameters in the compiled function declaration is not an error but rather a warning.
The following built-in functions are provided:
info. Returns 0.
The function is intended for debugging purposes.
All character positions in strings are counted from 0.
The name Guile stands for GNU's Ubiquitous Intelligent Language for Extensions. It provides the Scheme interpreter conforming to R4RS language specification. This section describes use of Guile as an extension language for GNU Radius. It assumes that the reader is sufficiently familiar with the Scheme language. Please, refer to section `Top' in Revised(4) Report on the Algorithmic Language Scheme, for the information about the language. If you wish to know more about the Guile, See section `Overview' in The Guile Reference Manual.
Scheme procedures can be called for processing both authentication
and accounting requests. The invocation of a scheme procedure for an
authentication request is triggered by Scheme-Procedure
attribute, the invocation for an accounting request is triggered
by Scheme-Acct-Procedure attribute. The following sections
address these issues in more detail.
A/V pair lists are the main object scheme functions operate upon. Scheme is extremely convenient for representation of such objects. A Radius A/V pair is represented by a Scheme pair, e.g.
Session-Timeout = 10
is represented in Guile as
(cons "Session-Timeout" 10)
The CAR of the pair can contain either the attribute dictionary name, or the attribute number. Thus, the above pair may also be written in Scheme as
(cons 27 10)
(Session-Timeout corresponds to attribute number 27).
Lists of A/V pairs are represented by Scheme lists. For example, the following Radius pair list
User-Name = "jsmith",
Password = "guessme",
NAS-IP-Address = 10.10.10.1,
NAS-Port-Id = 10
is written in Scheme as:
(list
(cons "User-Name" "jsmith")
(cons "Password" "guessme")
(cons "NAS-IP-Address" "10.10.10.1")
(cons "NAS-Port-Id" 10))
The Scheme procedure used for authentication must be declared as follows:
The function return value determines whether the authentication will
succeed. The function must return either a boolean value or a pair.
The return of #t causes authentication to succeed. The return
of #f causes it to fail.
If the function wishes to add something to the reply A/V pairs, it should return a pair in the form:
(cons return-code list)
Where return-code is a boolean value of the same meaning as described above. The list is a list of A/V pairs to be added to the reply list. For example, the following function will always deny the authentication, returning appropriate message to the user:
(define (decline-auth request-list check-list reply-list)
(cons #f
(list
(cons "Reply-Message"
"\r\nSorry, you are not allowed to log in\r\n"))))
As a more constructive example, let's consider a function that allows the authentication only if a user name is found in its internal database.
(define staff-data
(list
(list "scheme"
(cons
(list (cons "NAS-IP-Address" "127.0.0.1"))
(list (cons "Framed-MTU" "8096")))
(cons
'()
(list (cons "Framed-MTU" "256"))))))
(define (auth req check reply)
(let* ((username (assoc "User-Name" req))
(reqlist (assoc username req))
(reply-list '()))
(if username
(let ((user-data (assoc (cdr username) staff-data)))
(rad-log L_INFO (format #f "~A" user-data))
(if user-data
(call-with-current-continuation
(lambda (xx)
(for-each
(lambda (pair)
(cond
((avl-match? req (car pair))
(set! reply-list (avl-merge
reply-list
(cdr pair)))
(xx #t))))
(cdr user-data))
#f)))))
(cons
#t
reply-list)))
To trigger the invocation of the Scheme authentication function, assign
its name to Scheme-Procedure attribute in RHS of a
corresponding `raddb/users' profile. E.g.:
DEFAULT Auth-Type = SQL
Scheme-Procedure = "auth"
The Scheme accounting procedure must be declared as follows:
The function must return a boolean value. The accounting succeeds only
if it returned #t.
Here is an example of Scheme accounting function. The function dumps the contents of the incoming request to a file:
(define radius-acct-file "/var/log/acct/radius")
(define (acct req)
(call-with-output-file radius-acct-file
(lambda (port)
(for-each (lambda (pair)
(display (car pair) port)
(display "=" port)
(display (cdr pair) port)
(newline port))
req)
(newline port)))
#t)
#t if all pairs from list are present in target.
#f if
no such name was found in the dictionary.
A dictionary entry is a list in the form:
rad-log-open.
Return value: return of the corresponding Rewrite call, translated to the Scheme data type.
(car arglist) is interpreted as a name of the Rewrite
function to execute, and (cdr arglist) as a list of
arguments to be passed to it.
Return value: return of the corresponding Rewrite call, translated to the Scheme data type.
openlog() call.
syslog() call.
closelog() call.
NAS-Port-Id attribute.
Calling-Station-Id attribute from the request.
Go to the first, previous, next, last section, table of contents.