extensions.texi

gnu 的radius服务器很好用的

@c This is part of the Radius manual.
@c Copyright (C) 1999,2000,2001,2002,2003 Free Software Foundation, Inc.
@c Written by Sergey Poznyakoff
@c See file radius.texi for copying conditions.
@comment *******************************************************************
@node Extensions, Utility Programs, Problem Tracking, Top
@chapter Extensions
@cindex Extensions

The use of extension language allows extending 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.

@menu
* Filters::         Using external filter programs.
* Rewrite::         The built-in extension language.
* Guile::           Using Scheme.       
@end menu

@comment *L1****************************************************************
@node Filters
@section Filters
@cindex Filters

The simplest way to extend the functionality of Radius is to use filters.
A filter is an external program that communicates with Radius via
its standard input and output channels.

@menu
* Getting Acquainted with Filters::
* Declaring the Filter::
* Invoking the Filter from a User Profile::
* Adding Reply Attributes::
* Accounting Filters::
* Invoking Accounting Filter::
@end menu

@node Getting Acquainted with Filters
@subsection Getting Acquainted with Filters

Suppose we wish to implement an authentication method based on the
user name and the user's calling station @acronym{ID}. We have a
database of user names with valid @acronym{ID}s, and the new
method should authenticate a user only if the combination
@{@var{user_name}, @var{id}@} is found in this database.

We write a filter program that reads its standard input line by line.
Each input line must consist of exactly two words: the user name
and the calling station @acronym{ID}. For each input line, the
program prints @code{0} if the @{@var{user_name}, @var{id}@} is found in the
database and @code{1} otherwise. Let's suppose for the sake of example
that the database is a plaintext file and the filter is written in
a shell programming language. Then it will look like

@smallexample
#! /bin/sh

DB=/var/db/userlist

while read NAME CLID
do
    if grep "$1:$2" $DB; then
        echo "0"
    else
        echo "1"
    fi
done
@end smallexample

@node Declaring the Filter
@subsection Declaring the Filter

Here is how this filter is declared in the @file{raddb/config} file:

@smallexample
filters @{
    filter check_clid @{
        exec-path "/usr/libexec/myfilter";
        error-log "myfilter.log";
        auth @{
            input-format "%C@{User-Name@}
            %C@{Calling-Station-Id@}";
            wait-reply yes;
        @};
    @};        
@};                        
@end smallexample       

Let's analyze this declaration line by line:

@enumerate
@item @code{filters @{}

This keyword opens the filters declaration block. The block may
contain several declarations.

@item @code{filter check_clid @{}

This line starts the declaration of this particular filter and names it
@samp{check_clid}.

@item @code{exec-path "/usr/libexec/myfilter";}

This line tells @command{radiusd} where to find the executable image of
this filter.

@item @code{error-log "myfilter.log";}

The diagnostic output from this filter must be redirected to the file
@file{myfilter.log} in the current logging directory

@item @code{auth @{}

This filter will process authentication requests.

@item @code{input-format "%C@{User-Name@} %C@{Calling-Station-Id@}";}

Define the input line format for this filter. The %C@{@} expressions
will be replaced by the values of the corresponding attributes from
the incoming request (@pxref{Macro Substitution}).

@item @code{wait-reply yes;}

@code{radiusd} will wait for the reply from this filter to decide whether to
authenticate the user. 
@end enumerate
                
@node Invoking the Filter from a User Profile
@subsection Invoking the Filter from a User Profile

To invoke this filter from the user profile, specify its name prefixed
with @samp{|} in the value of @attr{Exec-Program-Wait} attribute,
like this:

@smallexample
DEFAULT Auth-Type = System,
                Simultaneous-Use = 1
        Exec-Program-Wait = "|check_clid"
@end smallexample

@node Adding Reply Attributes
@subsection Adding Reply Attributes

Apart from simply deciding whether to authenticate a user, the filter
can also modify the reply pairs. 

@smallexample
#! /bin/sh

DB=/var/db/userlist

while read NAME CLID
do
    if grep "$1:$2" $DB; then
        echo "0 Service-Type = Login, Session-Timeout = 1200"
    else
        echo "1 Reply-Message = 
              \"You are not authorized to log in\""
    fi
done
@end smallexample

@node Accounting Filters
@subsection Accounting Filters

Let's suppose we further modify our filter to also handle 
accounting requests. To discern between the authentication and
accounting requests we'll prefix each authentication request
with the word @samp{auth} and each accounting request with
the word @samp{acct}. Furthermore, the input line for accounting
requests will contain a timestamp.

Now, our filter program will look as follows:

@smallexample
#! /bin/sh

AUTH_DB=/var/db/userlist
ACCT_DB=/var/db/acct.db

while read CODE NAME CLID DATE
do
    case CODE
    auth)
        if grep "$1:$2" $DB; then
            echo "0 Service-Type = Login, \
                  Session-Timeout = 1200"
        else
            echo "1 Reply-Message = \
                  \"You are not authorized to log in\""
        fi
    acct)
        echo "$CODE $NAME $CLID $DATE" >> $ACCT_DB
done
@end smallexample

Its declaration in the @file{raddb/config} will also change:

@smallexample
filter check_clid @{
    exec-path "/usr/libexec/myfilter";
    error-log "myfilter.log";
    auth @{
        input-format "auth %C@{User-Name@} 
                      %C@{Calling-Station-Id@}";
        wait-reply yes;
    @};
    acct @{
        input-format "acct %C@{User-Name@} 
                      %C@{Calling-Station-Id@} %D";
        wait-reply no;
    @};
@};        
@end smallexample

@noindent
(The @code{input-format} lines are split for readability. Each of them
is actually one line).

@emph{Notice} @code{wait-reply no} in the @code{acct} statement. It
tells @command{radiusd} that it shouldn't wait for the response on
accounting requests from the filter. 

@node Invoking Accounting Filter
@subsection Invoking the Accounting Filter

To invoke the accounting filter, specify its name prefixed with a
vertical bar character as a value of @attr{Acct-Ext-Program} in our
@file{raddb/hints} file. For example:

@smallexample
DEFAULT NULL
        Acct-Ext-Program = "|check_clid:
@end smallexample        

@comment *L1****************************************************************
@node Rewrite
@section Rewrite
@cindex Rewrite

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 (@pxref{Rewriting Incoming
Requests}). Beside this basic use, however, Rewrite functions are used
to control various aspects of GNU Radius functionality, such as
verifying the activity of user sessions, controlling the amount of
information displayed in log messages, etc (@pxref{Interaction with Radius}).

@menu
* Syntax Overview::
* Quick Start::
* Interaction with Radius::
* Rewriting Incoming Requests::
* Login Verification Functions::
* Attribute Creation Functions::
* Logging Hook Functions::
* Full Syntax Description::
@end menu


@comment *L2****************************************************************
@node Syntax Overview
@subsection Syntax Overview
@cindex Rewrite, syntax overview

The syntax of Rewrite 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 exceptions are the @AVP{}s from the incoming request,
which are accessible to Rewrite functions via the special notation
@code{%[@var{attr}]}. 

@comment *L2****************************************************************
@node Quick Start
@subsection Quick Start
@cindex Rewrite, quick start introduction

As an example, let's consider the following Rewrite function:

@smallexample
@group
string
foo(integer i)
@{
    string rc;
    if (i % 2)
        rc = "odd";
    else
        rc = "even";
    return "the number is " + rc;
@}
@end group
@end smallexample

@noindent
The function takes an integer argument and returns the string
@samp{the number is odd} or @samp{the number is even}, depending on the
value of @code{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 @attr{User-Name}
attribute:

@smallexample
@group
integer
px_add()
@{
        %[User-Name] = "pfx-" + %[User-Name];
        return 0;
@}
@end group
@end smallexample

@noindent
This function manipulates the contents of the incoming request; its
return value has no special meaning.


@comment *L2****************************************************************
@node Interaction with Radius
@subsection Interaction with Radius
@cindex Rewrite, usage
@cindex Rewrite, applying functions

A Rewrite function can be invoked in several ways, depending on its
purpose. There are three major kinds of Rewrite functions:

@itemize @bullet
@item Functions used to rewrite the incoming requests.
@item Functions designed for simultaneous login verification.
@item Functions used to generate Radius attribute values.
@item Logging hooks.
@end itemize

@comment *L3****************************************************************
@node Rewriting Incoming Requests
@subsection Rewriting Incoming Requests
@cindex Rewriting incoming requests

The need for rewriting the incoming requests arises from the fact that
some @NAS{}es are very particular about the information they send with
the requests. There are cases when the information they send
is hardly usable or even completely unusable. For example, a
Cisco @sc{as5300} terminal server used as a voice-over IP router packs
a lot of information into its @attr{Acct-Session-Id} attribute. Though
the information stored there is otherwise relevant, it makes proper
accounting impossible, since the @attr{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 (@pxref{Acct-Session-Id}).

In order to cope with such @NAS{}es, GNU Radius is able to invoke
a Rewrite function upon arrival of the packet and before 
processing it further. This function can transform the packet so that
it obtains the form prescribed by @sc{rfc}s and its further processing
becomes possible.

For example, in the case of the @sc{as5300} router, a corresponding Rewrite
function parses the @attr{Acct-Session-Id} attribute; breaks it
down into fields; stores them into proper attributes, creating
them if necessary; and finally replaces @attr{Acct-Session-Id} with
its real value, which is the same for the 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, @attr{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 @file{naslist} profile, the attribute causes the function
to be invoked when the incoming request matches the huntgroup
(@pxref{Huntgroups}). For example, to have a function @code{fixup}
invoked for each packet from the @NAS{} @code{10.10.10.11}, the
following huntgroup rule may be used:

@smallexample
@group
DEFAULT  NAS-IP-Address = 11.10.10.11
         Rewrite-Function = "fixup"
@end group
@end smallexample

The @attr{Rewrite-Function} attribute may also be used in a @file{hints}
rule. In this case, it will invoke the function if the request matches
the rule (@pxref{Hints}). For example, this @file{hints} rule will
cause the function to be invoked for each request containing the user name
starting with @samp{P}:

@smallexample
@group
DEFAULT  Prefix = "P"
         Rewrite-Function = "fixup"
@end group
@end smallexample

@noindent
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 an integer value:

@smallexample
@group
integer fixup()
@{
@}
@end group
@end smallexample

@noindent
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 rewrite
functions.

@menu
* Example: Rewrite Examples.
@end menu

@comment **L3***************************************************************
@node Rewrite Examples
@subsubsection Examples of Various Rewrite Functions
@exindex Rewrite functions

The examples found in this chapter are working functions that can be
used with various existing @NAS{} types. They are taken from the
@file{rewrite} file contained in distribution of GNU Radius.

@subheading 1. Port rewriting for @sc{max a}scend terminal servers

Some @sc{max a}scend terminal servers pack additional information
into the @attr{NAS-Port-Id} attribute. The port number is constructed as
@var{XYYZZ}, where @var{X} = 1 for digital, @var{X} = 2 for analog,
@var{YY} is the line number
(1 for first PRI/T1/E1, 2 for second, and so on), and @var{ZZ} is the
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 .. @var{portcnt}), where @var{portcnt}
represents the real number of physical ports available on the @NAS{}.
Such a port number can be used, for example, to create a dynamic pool
of IP addresses (@pxref{Framed-IP-Address}).

@smallexample
@group
/*
 * decode MAX port number
 * input: P        --  The value of NAS-Port-Id attribute
 *        portcnt  --  number of physical ports on the NAS
 */