configure.texi

gnu 的radius服务器很好用的

@c This is part of the Radius manual.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c Written by Sergey Poznyakoff
@c See file radius.texi for copying conditions.
@comment *******************************************************************
@node Configuration Files, Request Comparison, Invocation, Top
@chapter Radius Configuration Files
@cindex Radiusd configuration files
@cindex Configuration files (radiusd)

At startup, GNU Radius obtains the information vital for its
functioning from a number of configuration files. These are normally
found in @value{RADDB} directory, which is defined at configuration
time, although their location can be specified at runtime. In the
discussion below we will refer to this directory by @file{raddb}.
@xref{Naming Conventions}.

Each configuration file is responsible for a certain part of the
GNU Radius functionality. The following table lists all configuration
files along with a brief description of their purposes.

@table @file
@item config
Determines the runtime defaults for @command{radiusd}, such
as the IP address and ports to listen on, the sizes of the request
queues, configuration of the SNMP subsystem, fine-tuning of the
extension languages, etc.

@item clients
Lists the shared secret belonging to each @NAS{}. It is
crucial for the normal request processing that each @NAS{} have an
entry in this file. The requests from @NAS{}es that are not listed
in @file{clients} will be ignored, as well as those from the @NAS{}es
that have a wrong value for the shared secret configured in this file.

@item naslist
Defines the types for the known @NAS{}es. Its information is
used mainly when performing multiple login checking
(@pxref{Multiple Login Checking}).

@item nastypes
Declares the known @NAS{} types. The symbolic type names,
declared in this file can be used in @file{naslist}.

@item dictionary
Defines the symbolic names for radius attributes and attribute
values. Only the names declared in this file may be used in the files
@file{users}, @file{hints} and @file{huntgroups}.

@item huntgroups
Contains special rules that process the incoming requests
basing on the @NAS{} IP and port number they come from. These can also
be used as a kind of @dfn{access control list}.

@item hints
Defines the matching rules that modify the incoming
request depending on the user name and its credentials.

@item users
Contains the individual users' profiles.

@item realms
Defines the Radius realms and the servers that are
responsible for them.

@item access.deny
A list of usernames that should not be allowed access via Radius.

@item sqlserver
Contains the configuration for the @sc{sql} system. This includes the
type of @sc{sql} interface used, the IP and port number of the server
and the definition of the @sc{sql} requests used by @command{radiusd}.

@item rewrite
Contains the source code of functions in Rewrite extension language.

@item menus
A subdirectory containing the authentication menus. 
@end table

The rest of this chapter describes each of these files in detail.

@menu
* config file::         Run-time configuration options.
* dictionary file::     Radius dictionary.
* clients file::        Clients lists the @NAS{}es that are allowed to
                        communicate with radius.
* naslist file::        The naslist file keeps general information about
                        the @NAS{}es.
* nastypes file::       Information about how to query the @NAS{}es about
                        active user sessions.
* hints file::          Important user information that is common for the
                        users whose names match some pattern.
* huntgroups file::     Group users by the @NAS{} (and, possibly, a port
                        number) they come from.
* realms file::         Communication with remote radius servers
* users file::          User profile.
* access.deny file::    List of users which are denied access.
* sqlserver file::      SQL server configuration.
* rewrite file::        Rewrite functions allow to change the input
                        packets.
* menus directory::     Menus allow user to select the type of
                        service.
* Macro Substitution::  Macros which are expanded by the actual
                        attribute values.      
@end menu

@comment *L2****************************************************************
@node config file
@section Run-Time Configuration Options --- @file{raddb/config}
@cindex Radiusd configuration
@cindex @file{raddb/config} file

At startup @command{radiusd} obtains its configuration values from three
places. The basic configuration is kept in the executable module
itself.  These values are overridden by those obtained from
@file{raddb/config} file. Finally, the options obtained from the
command line override the first two sets of options.

When re-reading of the configuration is initiated either by
@code{SIGHUP} signal or by SNMP channel any changes in the config file
take precedence over command line arguments, since @file{raddb/config} is
the only way to change configuration of the running program.

This chapter discusses the @file{raddb/config} file in detail.

The @file{raddb/config} consists of statements and comments.
Statements end with a semicolon. Many statements contain a block
of sub-statements which also terminate with a semicolon.

Comments can be written in shell, C, or C++ constructs, i.e. any
of the following represent a valid comment:

@smallexample
# A shell comment
/* A C-style
 * multi-line comment
 */
// A C++-style comment
@end smallexample

These are the basic statements:
@menu
* option::      @code{Option} block: set the global program options.
* logging::     Fine-tune the logging.
* auth::        Configure authentication service.
* acct::        Configure accounting service.
* usedbm::      Enable the DBM feature.
* snmp::        Configure SNMP service.
* rewrite::     Configure Rewrite interface.
* guile::       Configure Guile interface.
* message::     Configure server reply messages.
* filters::     Configure authentication and accounting filters.
* mlc::         Configure multiple login checking.
@end menu

@comment **L3***************************************************************
@node option
@subsection @code{option} block
@cindex Run-time options (radiusd)
@kwindex option
@kwindex source-ip
@kwindex max-requests
@kwindex max-processes
@kwindex process-idle-timeout
@kwindex master-read-timeout
@kwindex master-write-timeout
@kwindex radiusd-user
@kwindex exec-program-user 
@kwindex username-chars
@kwindex log-dir
@kwindex acct-dir
@kwindex resolve

@subheading Syntax:

@smallexample
option @{
        source-ip @var{number} ; 
        max-requests @var{number} ; 
        radiusd-user @var{string} ; 
        exec-program-user @var{string} ; 
        username-chars @var{string} ; 
        log-dir @var{string} ; 
        acct-dir @var{string} ; 
        resolve @var{bool} ; 
        max-processes @var{number} ; 
        process-idle-timeout @var{number} ; 
        master-read-timeout @var{number} ; 
        master-write-timeout @var{number} ; 
@} ;
@end smallexample

@subheading Usage

The @code{option} block defines the global options to be used by @command{radiusd}.

@subheading Boolean statements

@table @code

@item resolve
Determines whether radius should resolve the IP addresses for diagnostic
output. Specifying @code{resolve no} speeds up the server and reduces
the network traffic.

@end table

@subheading Numeric statements

@table @code

@item source-ip
Sets the source @IP{}. When this statement is not present, the
@IP{} of the first available network interface on the machine
will be used as source.

@item max-requests
Sets the maximum number of the requests in queue.

@item max-processes
Sets the maximum number of child processes. The default value is
16. If you plan to raise this value, make sure you have enough
file descriptors available, as each child occupies four descriptors
for its input/output channels.

@item process-idle-timeout
Sets the maximum idle time for child processes. A child terminates
if it does not receive any requests from the main process within this
number of seconds. By default, this parameter is 3600 seconds
(one hour).

@item master-read-timeout
@itemx master-write-timeout
These two values set the timeout values for the interprocess input/output
operations in the main server process. More specifically,
@code{master-read-timeout} sets the maximum number of seconds the main
process will wait for the answer from the subprocess, and
@code{master-write-timeout} sets the maximum number of seconds the main
process will wait for the subprocess's comunication channel to become
ready for input. By default, no timeouts are imposed.

@end table

@subheading String statements
@table @code
@item radiusd-user
Instructs @command{radiusd} to drop root privileges and to switch to
the real user and group IDs of the given user after becoming 
daemon. Notice the following implications of this statement:

@enumerate 1
@item All configuration files must be readable for this user.
@item Authentication type @code{System} (@pxref{System Auth}) requires
root privileges, so it cannot be used with @code{radiusd-user}. Any
@file{raddb/users} profiles using this authentication type will be
discarded.
@item Authentication type @code{PAM} (@pxref{PAM Auth}) may require root
provileges. It is reported to always require root privileges on some
systems (notably on Solaris).
@item @code{exec-program-user} statement (see below) is ignored when
used with @code{radiusd-user}.
@end enumerate

@item exec-program-user
Sets the privileges for the programs executed as a result of
@attr{Exec-Program} and @attr{Exec-Program-Wait}. The real user
and group ids will be retrieved from the @file{/etc/passwd} entry
for the given user.

@item username-chars
Determines characters that are valid within a username. The alphanumeric
characters are always allowed in a username, it is not necessary to
specify them in this statement. By default the following characters
are allowed in a username: @samp{.-_!@@#$%^&\/"}. The
@code{username-chars} statement overrides this default, thus setting:

@smallexample
username-chars ":"
@end smallexample

@noindent
will restrict the set of allowed characters to the alphanumeric
characters and colon. If you wish to expand the default character
set, you will have to explicitly specify it in the
@code{username-chars} argument, as shown in the example below:

@smallexample
username-chars ".-_!@@#$%^&\\/\":"
@end smallexample

@noindent
(Notice the use of escape character @samp{\}).

@item log-dir
Specifies the logging directory.

@item acct-dir 
Specifies the accounting directory.

@end table

@comment **L3***************************************************************
@node logging
@subsection @code{logging} block
@cindex Logging, @file{config} statement
@kwindex logging

@subheading Syntax:

@smallexample
logging @{
        prefix-hook @var{string} ; 
        suffix-hook @var{string} ; 
        category category_spec @{
                channel channel_name ; 
                print-auth @var{bool} ; 
                print-pass @var{bool} ; 
                print-failed-pass @var{bool} ; 
                level @var{debug_level} ; 
        @} ; 
        channel channel_name @{
                file @var{string} ;
                syslog facility . priority ; 
                print-pid @var{bool} ; 
                print-category @var{bool} ; 
                print-cons @var{bool} ; 
                print-level @var{bool} ; 
                print-priority @var{bool} ; 
                print-tid @var{bool}; 
                print-milliseconds @var{bool}; 
                prefix-hook @var{string} ; 
                suffix-hook @var{string} ; 
        @}; 
@} ;

@end smallexample

@subheading Usage

The @code{logging} statement describes the course followed by
@command{radiusd}'s logging information.

The parts of this statement are discussed below.

@menu
* hooks::            Logging hooks
* category::         @code{category} statement.
* channel::          @code{channel} statement.
* logging example::  Example of the @code{logging} statement.
@end menu

@comment **L4***************************************************************
@node hooks
@subsubsection Logging hooks
@cindex Logging hook
@kwindex prefix-hook
@kwindex suffix-hook

Most diagnostic messages displayed by @command{radiusd} describe
some events that occured while processig a certain incoming request.
By default they contain only a short summary of the event.
@dfn{Logging hooks} are means of controlling actual amount of
information displayed in such messages. They allow you to add to the
message being displayed any relevant information from the incoming
request that caused the message to appear.

A @dfn{hook} is a special Rewrite function that takes three arguments
and returns a string. There are two kinds of logging hooks: @dfn{prefix}
and @dfn{suffix}. Return value from the prefix hook function will
be displayed before the actual log message, that of the suffix hook
function will be displayed after the message.

Furthermore, there may be @dfn{global} and @dfn{channel-specific
hooks}. Global hooks apply to all categories, unless overridden by
category-specific hooks. Global prefix hook is enabled by
@code{prefix-hook} statement appearing in the @code{logging} block.
Global suffix hook is enabled by @code{suffix-hook} statement.
Both statements take as their argument the name of corresponding
Rewrite function.

For detailed information about writing logging hooks,
@xref{Logging Hook Functions}.

@comment **L4***************************************************************
@node category
@subsubsection @code{category} statement
@cindex Logging category
@kwindex category
@kwindex channel
@kwindex print-auth
@kwindex print-pass
@kwindex print-failed-pass
@kwindex level

Each line of logging information generated by @command{radiusd} has an
associated @dfn{category}.  The @code{logging} statement allows each
category of output to be controlled independently of the others.
The logging category is defined by @dfn{category name} and a
@dfn{severity}. @dfn{category name} determines what part of radiusd
daemon is allowed to send its logging information to this channel.
It can be any of @code{main}, @code{auth}, @code{acct}, @code{proxy},