gradient.texi

gnu 的radius服务器很好用的

@c This is part of the Radius manual.
@c Copyright (C) 2004 Free Software Foundation, Inc.
@c Written by Sergey Poznyakoff
@c See file radius.texi for copying conditions.
@comment *******************************************************************
@chapter New Configuration Approach (draft)
@UNREVISED{}

This document presents a draft describing new approach for
processing @RADIUS{} requests. It is intended as a @dfn{request
for comments}, and, in the long run, as a guide for GNU Radius
developers. In its current state it is far from being complete.
Please check @url{http://www.gnu.org/@/software/@/radius/@/manual} for
updated versions. Feel free to send your comments and suggestions to
@email{bug-gnu-radius@@gnu.org}.

@menu
* Present State::             A brief description of Currently Used Approach
* Deficiencies::              Deficiencies of Current Operation Model
                              and Configuration Suite
* Solution::                  A Proposed Solution
* New Rewrite::               Changes to Rewrite Language
* Traditional Configuration:: Support for Traditional Configuration Files.
* New Configuration::         New Configuration Files
@end menu


@node Present State
@section A brief description of Currently Used Approach

When I started to write GNU Radius, back in 1998, I had two major aims.
The first and primary aim was to create a flexible and robust
system that would follow the principle of Jon Postel:

@quotation
Be liberal in what you accept and conservative in what you send.
@end quotation

This, I believe, is the main principle of any good software for
Internet.

The second aim was to be backward compatible with the implementations
that already existed back then. This seemed to be important (and the
time has proved it was), because it would allow users to easily switch
from older radius daemon to GNU Radius.

An important part of every complex program is its configuration
file. Traditional implementations of @RADIUS{} servers (beginning from
Livingston Radius) used a configuration suite consisting of several
files, usually located in @file{/etc/raddb} subdirectory. Its main
components were:

@table @file
@item dictionary
A file containing translations of symbolic names of radius attributes
and attribute values to their integer numbers as specified by
@RADIUS{} protocol.

@item hints
This file was intended to separate incoming requests in groups, based
on the form of their login name. Traditionally such separation
was performed basing on common @dfn{prefixes} and/or @dfn{suffixes}
of login names.

@item huntgroups
The purpose of this file was to separate incoming requests depending
on their source, i.e. on the @NAS{} that sent them and the port
number on that @NAS{}. It also served as a sort of simplified
@dfn{access control list}. 

@item users
This file contained a users database. It described criteria for
authentication and @dfn{reply pairs} to be sent back to requesting
@NAS{}es.
@end table

Among these files, the first two were used for requests of any kind,
whereas @file{users} was used only for @code{Access-Request} packets.
@FIXME-xref{request types}

Though this configuration system suffered from many inconsistencies,
the @dfn{second aim} required GNU Radius to use this approach.

To compensate for its deficiencies and to fulfill the @dfn{first aim},
this configuration system was extended, while preserving its main
functionality. A number of additional @dfn{internal attributes} were
added, that control @command{radiusd} behavior. A new language was
created whose main purpose was to modify incoming requests
(@pxref{Rewrite}). The support for @dfn{GNU's Ubiquitous Intelligent
Language for Extensions} (@pxref{Guile}) was added, that allowed to
further extend GNU Radius functionality.

The present operation model@footnote{@xref{Operation}.} of GNU Radius
and its configuration file system@footnote{@xref{Configuration
Files}.} emerged as a result of the two development aims described
above. Since 1998 up to present, GNU Radius users contributed a lot
of ideas and code to the further development of the system.

However, it became obvious that this system presents
strong obstacles to the further development. The next section
addresses its deficiencies.

@node Deficiencies
@section Deficiencies of Current Operation Model and Configuration Suite

The main deficiencies are inherited with the traditional configuration
file suite. The rules for processing each request are split among
three files, each of which is processed differently, despite of their
external similarity. The administrator has to keep in mind a set of
exotic rules when configuring the system@footnote{@file{Hints} is
processed for each request... Authentication requests first pass
@file{hints}, then @file{huntgroups}, then @file{users}... Accounting
requests use only @file{hints} and @file{huntgroups}...
@file{Huntgroups} entries may also be used (sometimes inadvertently) to
create @acronym{ACL} rules, etc, etc...}. When matching incoming
requests with configuration file entries (@dfn{LHS}, @pxref{Matching
Rule}), some attributes are taken verbatim, whereas others are used
to control @command{radiusd} behavior and to pass additional data to
other rules (@pxref{Radius Internal Attributes}). The things become even
more complicated when @RADIUS{} realms come into play (@pxref{Proxy
Service}). Some attributes are meaningful only if used in a certain
part of a certain configuration file rule.

So, while being a lot more flexible than the approach used by
other @RADIUS{} implementations, the current system is quite
difficult to maintain.

Another deficiency is little control over actions executed on
different events. For example, it is often asked how can one
block a user account after a predefined number of authentication
failures? Currently this can only be done by writing an external
authentication procedure (either in Scheme, using Guile, or as
a standalone executable, using @attr{Exec-Program-Wait}). The
proper solution would be to have a set of user-defined triggers
for every @RADIUS{} event (in this case, for authentication failure).

Another commonly asked question is how to make @command{radiusd}
execute several @acronym{SQL} queries when processing a request.
While GNU Radius is not supposed to compensate for deficiencies
of some @acronym{SQL} implementations that do not allow for
nested queries, such a feature could come quite handy.

@node Solution
@section Proposed Solution
@UNREVISED{}

Processing of incoming requests is controlled by
@dfn{request-processing program}. Request-processing program is a
list-like structure, consisting of @dfn{instructions}. 

@menu
* Instruction::        
* grad_instr_conditional::
* grad_instr_call::
* grad_instr_return::
* grad_instr_action::
* grad_instr_reply::
* grad_instr_proxy::
* grad_instr_forward::
@end menu

@node Instruction
@subsection Request-processing Instruction

@dfn{Request-processing program} consists of @dfn{instructions}. There
are seven basic instruction types:

@table @code
@item grad_instr_conditional_t
This instruction marks a branch point within the program.

@item grad_instr_call_t
Represents a @dfn{call} of a subprogram

@item grad_instr_action_t
Invokes a Rewrite @FIXME{or Scheme?} function

@item grad_instr_proxy_t
Proxies a request to the remote server

@item grad_instr_forward_t
Forwards a request to the remote server

@item grad_instr_reply_t
Replies back to the requesting @NAS{}.
@end table

Consequently, an instruction is defined as a union of the above node
types:

@deftp Instruction grad_instr_t
@smallexample
@group
enum grad_instr_type
@{
  grad_instr_conditional,
  grad_instr_call,
  grad_instr_return,
  grad_instr_action,
  grad_instr_reply,
  grad_instr_proxy,
  grad_instr_forward
@};

typedef struct grad_instr grad_instr_t;

struct grad_instr
@{
  enum grad_instr_type type;
  grad_instr_t *next;
  union
    @{
      grad_instr_conditional_t cond;
      grad_instr_call_t call;
      grad_instr_action_t action;
      grad_instr_reply_t reply;
      grad_instr_proxy_t proxy;
      grad_instr_forward_t forward;
    @} v;                                                             
@};
@end group
@end smallexample

@code{Type} member contains type of the instruction. The evaluator
uses @code{type} to determine which part of @code{union v}, holds
instruction-specific data.

@code{Next} points to the next instruction. The evaluator will
go to this instruction unless the present one changes the control
flow.

Finally, @code{v} contains instruction-specific data. These will
be discussed in the following subsections.
@end deftp

@node grad_instr_conditional
@subsection grad_instr_conditional
@UNREVISED{}

@deftp Instruction grad_instr_conditional_t cond iftrue iffalse
@smallexample
@group
struct grad_instr_conditional
@{
  grad_entry_point_t cond;  /* Entry point to the compiled
                               Rewrite condition */
  grad_instr_t *iftrue;     /* Points to the ``true'' branch  */
  grad_instr_t *iffalse;    /* Points to the ``false'' branch  */
@};
typedef struct grad_instr_conditional grad_instr_conditional_t;
@end group
@end smallexample

Instructions of type @code{grad_instr_conditional_t} indicate branching.
Upon encountering an @code{grad_instr_conditional_t}, the
engine executes a Rewrite expression pointed to by @code{cond}.
If the expression evaluates to @code{true}, execution branches to
instruction @code{iftrue}. Otherwise, if @code{iffalse} is not @code{NULL},
execution branches to that instruction. Otherwise, the control flow
passes to @code{grad_instr_t.next}, as described in the previous section.
@end deftp

@subheading RPL representation

@deffn {RPL defun} COND @var{expr} @var{if-true} [@var{if-false}]

@table @var
@item expr
Textual representation of Rewrite conditional expression or its entry
point.
@item if-true
RPL expression executed if @var{expr} evaluates to @code{t}.
@item if-true
Optional RPL expression that is executed if @var{expr} evaluates to
@code{nil}.
@end table
@end deffn

@subheading Example

@code{COND} with two arguments:

@smalllisp
@group
(COND "%[User-Name] ~= \"test-.*\""
      (REPLY Access-Reject ("Reply-Message" . "Test accounts disabled")))
@end group      
@end smalllisp

@noindent
@code{COND} with three arguments:

@smalllisp
@group
(COND "%[Hint] == "PPP" && authorize(PAM)"
      (REPLY Access-Accept
             ("Service-Type" . "Framed-User")
             ("Framed-Protocol" . "PPP"))
      (REPLY Access-Reject
             ("Reply-Message" . "Access Denied")))
@end group      
@end smalllisp

@node grad_instr_call
@subsection grad_instr_call
@UNREVISED{}

@deftp Instruction grad_instr_call_t entry
@smallexample
@group
struct grad_instr_call @{
       grad_instr_t *entry;    
@};
typedef struct grad_instr_call grad_instr_call_t;
@end group
@end smallexample