extensions.texi

gnu 的radius服务器很好用的

@end deftypefn

@deftypefn Function string request_code_string (integer @var{code})
Converts integer RADIUS request code to its textual representation as
per RFC 3575. This function is useful in logging hooks (@pxref{hooks}).

@smallexample
request_code_string(4) @result{} "Accounting-Request"
@end smallexample
@end deftypefn

@subheading Native Language Support

The native language support is provided via the functions described
below. These functions are interfaces to GNU @code{gettext} library.
For the information about general concepts and principles of
Native Language Support, please refer to
@ref{Top,GNU @code{gettext} utilities,gettext,gettext,GNU @code{gettext} utilities}.

The default current textual domain is @samp{radius}.

@deftypefn Function string textdomain (string @var{domain})
Sets the new value for the current textual domain. This domain is used by
the functions @code{gettext} and @code{ngettext}.
Returns the name of the previously used domain. 
@end deftypefn

@deftypefn Function string gettext (string @var{msgid})
@deftypefnx Function string _ (string @var{msgid})
The function returns the translation of the string @var{msgid} if it
is available in the current domain. If it is not available, the
argument itself is returned.

The second form of this function provides a traditional shortcut
notation.

For a detailed description of the GNU @code{gettext} interface, 
refer to @ref{Interface to gettext,,,gettext,GNU @code{gettext} utilities}.
@end deftypefn

@deftypefn Function string dgettext (string @var{domain}, string @var{msgid})
Returns the translation of the string @var{msgid} if it
is available in the domain @var{domain}. If it is not available, the
argument itself is returned.
@end deftypefn

@deftypefn Function string ngettext (string @var{msgid_singular}, string @var{msgid_plural}, integer @var{number})
The @code{ngettext} function is used to translate the messages that
have singular and plural forms. The @var{msgid_singular} parameter
must contain the singular form of the string to be converted. It is
also used as the key for the search in the catalog. The
@code{msgid_plural} parameter is the plural form.  The parameter
@var{number} is used to determine the plural form. If no message
catalog is found @var{msgid_singular} is returned if
@code{@var{number} == 1}, otherwise @var{msgid_plural}.

For a detailed description of the GNU @code{gettext} interface for the
plural translation, 
refer to @ref{Plural forms,,Additional functions for plural forms,gettext,GNU @code{gettext} utilities}.

@end deftypefn

@deftypefn Function string dngettext (string @var{domain}, string @var{msg_sing}, string @var{msg_plur}, integer @var{number})
Similar to @code{ngettext}, but searches translation in the given @var{domain}.
@end deftypefn

@subheading Request Accessors

The following functions are used to read some internal fields of a
@RADIUS{} request.

@deftypefn Function Integer request_source_ip ()
Returns source @IP{} of the currently processed request. This function
can be used to add @attr{NAS-IP-Address} attribute to the requests
lacking one, e.g.:

@smallexample
integer
restore_nas_ip()
@{
        if (!*%[NAS-IP-Address])
                %[NAS-IP-Address] = request_source_ip();
        return 0;
@}
@end smallexample
@end deftypefn

@deftypefn Function Integer request_source_port ()
Returns the source @sc{udp} port.
@end deftypefn

@deftypefn Function Integer request_id ()
Returns the request identifier.
@end deftypefn

@deftypefn Function Integer request_code ()
Returns the request code.
@end deftypefn

@comment *L1****************************************************************
@node Guile
@section Guile
@cindex Guile

The name Guile stands for @dfn{GNU's Ubiquitous Intelligent Language for
Extensions}. It provides a Scheme interpreter conforming to the 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. For information about
the language, refer to
@ref{Top,,,r4rs,Revised(4) Report on the Algorithmic Language Scheme}.
For more information about Guile, see @ref{Top,,Overview,guile,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 the @attr{Scheme-Procedure}
attribute; the invocation for an accounting request is triggered
by the @attr{Scheme-Acct-Procedure} attribute. The following sections
address these issues in more detail.

@menu
* Data Representation::
* Authentication with Scheme::
* Accounting with Scheme::
* Radius-Specific Functions::
@end menu

@comment **L2***************************************************************
@node Data Representation
@subsection Data Representation
@cindex Guile, representation of Radius data

@AVP{} lists are the main object Scheme functions operate upon. Scheme
is extremely convenient for representation of such objects. A Radius @AVP{}
is represented by a Scheme pair; e.g.,

@smallexample
        Session-Timeout = 10
@end smallexample

@noindent
is represented in Guile as

@smalllisp
        (cons "Session-Timeout" 10)
@end smalllisp

The @code{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

@smalllisp
        (cons 27 10)
@end smalllisp

@noindent
(because @attr{Session-Timeout} corresponds to attribute number 27).

Lists of @AVP{}s are represented by Scheme lists. For example,
the Radius pair list

@smallexample
@group
        User-Name = "jsmith",
                User-Password = "guessme",
                NAS-IP-Address = 10.10.10.1,
                NAS-Port-Id = 10
@end group
@end smallexample

@noindent
is written in Scheme as

@smalllisp
@group
        (list
          (cons "User-Name" "jsmith")
          (cons "User-Password" "guessme")
          (cons "NAS-IP-Address" "10.10.10.1")
          (cons "NAS-Port-Id" 10))
@end group
@end smalllisp
        
@comment **L2***************************************************************
@node Authentication with Scheme
@subsection Authentication with Scheme
@cindex Authentication with Scheme

The Scheme procedure used for authentication must be declared as
follows:

@deffn {Function Template} auth-function request-list check-list reply-list
Its arguments are:
@table @var
@item request-list
The list of @AVP{}s from the incoming request
@item check-list
The list of @AVP{}s from the @LHS{} of the profile entry that matched
the request
@item reply-list
The list of @AVP{}s from the @RHS{} of the profile entry that matched
the request
@end table
@end deffn

The function return value determines whether the authentication will
succeed. The function must return either a boolean value or a pair.
The return of @code{#t} causes authentication to succeed. The return
of @code{#f} causes it to fail.

For a function to add something to the reply @AVP{}s, it
should return a pair in the form

@smalllisp
    (cons @var{return-code} @var{list})
@end smalllisp

@noindent
where @var{return-code} is a boolean value of the same meaning as
described above. @var{list} is a list of @AVP{}s to be added
to the reply list. For example, the following function will always
deny the authentication, returning an appropriate message to the user:

@exindex Scheme authentication function
@smalllisp
@group
(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"))))
@end group
@end smalllisp

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:

@smalllisp
@group
(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)))
@end group
@end smalllisp

To trigger the invocation of the Scheme authentication function, assign
its name to the @attr{Scheme-Procedure} attribute in the @RHS{} of a
corresponding @file{raddb/users} profile. For example:

@exindex Invoking Scheme authentication function
@exindex Scheme authentication function, invocation
@smallexample
@group
DEFAULT Auth-Type = SQL
        Scheme-Procedure = "auth"
@end group
@end smallexample

@comment **L2***************************************************************
@node Accounting with Scheme
@subsection Accounting with Scheme
@cindex Accounting with Scheme

The Scheme accounting procedure must be declared as follows:

@deffn {Function Template} acct-function-name request-list
Its argument is:
@table @var
@item request-list
The list of @AVP{}s from the incoming request
@end table
@end deffn

The function must return a boolean value. The accounting succeeds only
if it has returned @code{#t}.

Here is an example of a Scheme accounting function. The function dumps
the contents of the incoming request to a file:

@exindex Scheme accounting function
@smalllisp
@group
(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)
@end group
@end smalllisp

@comment **L2***************************************************************
@node Radius-Specific Functions
@subsection Radius-Specific Functions
@cindex Radius-Specific Scheme Functions

@deffn {Scheme Function} avl-delete av-list attr
Delete from @var{av-list} the pairs with attribute @var{attr}.
@end deffn

@deffn {Scheme Function} avl-merge dst src
Merge @var{src} into @var{dst}.
@end deffn

@deffn {Scheme Function} avl-match? target list
Return @code{#t} if all pairs from @var{list} are present in @var{target}.
@end deffn

@deffn {Scheme Function} rad-dict-name->attr name
Return a dictionary entry for the given attribute @var{name} or @code{#f} if
no such name was found in the dictionary.

A dictionary entry is a list in the form

@deffn {Scheme List} dict-entry name-string attr-number type-number vendor

@noindent
where the arguments are as follows:

@table @var
@item name-string
The attribute name
@item value-number
The attribute number
@item type-number
The attribute type
@item vendor
The vendor @acronym{PEC}, if the attribute is a vendor-specific one,
or @code{#f} otherwise.
@end table
@end deffn
@end deffn

@deffn {Scheme Function} rad-dict-value->name attr value
Returns the dictionary name of the given @var{value} for an integer-type
attribute @var{attr}, which can be either an attribute number
or its dictionary name.
@end deffn

@deffn {Scheme Function} rad-dict-name->value attr value
Convert a symbolic attribute value name into its integer representation.
@end deffn

@deffn {Scheme Function} rad-dict-pec->vendor pec
Convert a @acronym{PEC} to the vendor name.
@end deffn

@deffn {Scheme Function} rad-log-open prio
Open Radius logging to the severity level @var{prio}.
@end deffn

@deffn {Scheme Function} rad-log-close
Close a Radius logging channel opened by a previous call to @code{rad-log-open}.
@end deffn

@deffn {Scheme Function} rad-rewrite-execute-string string
Interpret @var{string} as an invocation of a function in Rewrite language and
execute it.

Return value: return of the corresponding Rewrite call, translated to
the Scheme data type.
@end deffn

@deffn {Scheme Function} rad-rewrite-execute arglist
Execute a Rewrite language function.
@code{(car @var{arglist})} is interpreted as a name of the Rewrite
function to execute, and @code{(cdr @var{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.
@end deffn

@deffn {Scheme Function} rad-openlog ident option facility
Scheme interface to the system @code{openlog()} call.
@end deffn

@deffn {Scheme Function} rad-syslog prio text
Scheme interface to the system @code{syslog()} call.
@end deffn

@deffn {Scheme Function} rad-closelog
Scheme interface to the system @code{closelog()} call.
@end deffn

@deffn {Scheme Function} rad-utmp-putent status delay list radutmp_file radwtmp_file
Write the supplied data into the radutmp file. If @var{radwtmp_file} is not nil,
the constructed entry is also appended to @var{wtmp_file}.

@var{list} is:

@deffn {Scheme List} utmp-entry user-name orig-name port-id port-type session-id caller-id framed-ip nas-ip proto

@table @var
@item user-name
The user name
@item orig-name
The original user name from the request
@item port-id
The value of the @attr{NAS-Port-Id} attribute
@item port-type
A number or character indicating the port type
@item session-id
The session @sc{id}
@item caller-id
The value of the @attr{Calling-Station-Id} attribute from the request
@item framed-ip
The framed IP assigned to the user
@item nas-ip
The @NAS{} IP
@item proto
A number or character indicating the type of the connection
@end table
@end deffn
@end deffn