[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
At startup 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
‘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
SIGHUP
signal or by SNMP channel any changes in the config file
take precedence over command line arguments, since ‘raddb/config’ is
the only way to change configuration of the running program.
This chapter discusses the ‘raddb/config’ file in detail.
The ‘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:
# A shell comment /* A C-style * multi-line comment */ // A C++-style comment |
These are the basic statements:
4.1.1 option block | Option block: set the global program options.
| |
4.1.2 logging block | Fine-tune the logging. | |
4.1.3 auth statement | Configure authentication service. | |
4.1.4 acct statement | Configure accounting service. | |
4.1.5 usedbm statement | Enable the DBM feature. | |
4.1.6 snmp statement | Configure SNMP service. | |
4.1.7 rewrite statement. | Configure Rewrite interface. | |
4.1.8 guile statement | Configure Guile interface. | |
4.1.9 message statement | Configure server reply messages. | |
4.1.10 filters statement | Configure authentication and accounting filters. | |
4.1.11 mlc statement | Configure multiple login checking. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
option
block option { source-ip number ; max-requests number ; radiusd-user string ; exec-program-user string ; username-chars string ; log-dir string ; acct-dir string ; resolve bool ; max-processes number ; process-idle-timeout number ; master-read-timeout number ; master-write-timeout number ; } ; |
The option
block defines the global options to be used by radiusd
.
resolve
Determines whether radius should resolve the IP addresses for diagnostic
output. Specifying resolve no
speeds up the server and reduces
the network traffic.
source-ip
Sets the source IP address. When this statement is not present, the IP address of the first available network interface on the machine will be used as source.
max-requests
Sets the maximum number of the requests in queue.
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.
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).
master-read-timeout
master-write-timeout
These two values set the timeout values for the interprocess input/output
operations in the main server process. More specifically,
master-read-timeout
sets the maximum number of seconds the main
process will wait for the answer from the subprocess, and
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.
radiusd-user
Instructs 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:
System
(see section System Authentication Type) requires
root privileges, so it cannot be used with radiusd-user
. Any
‘raddb/users’ profiles using this authentication type will be
discarded.
PAM
(see section PAM Authentication Type) may require root
provileges. It is reported to always require root privileges on some
systems (notably on Solaris).
exec-program-user
statement (see below) is ignored when
used with radiusd-user
.
exec-program-user
Sets the privileges for the programs executed as a result of
Exec-Program
and Exec-Program-Wait
. The real user
and group ids will be retrieved from the ‘/etc/passwd’ entry
for the given user.
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: ‘.-_!@#$%^&\/"’. The
username-chars
statement overrides this default, thus setting:
username-chars ":" |
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
username-chars
argument, as shown in the example below:
username-chars ".-_!@#$%^&\\/\":" |
(Notice the use of escape character ‘\’).
log-dir
Specifies the logging directory.
acct-dir
Specifies the accounting directory.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
logging
block logging { prefix-hook string ; suffix-hook string ; category category_spec { channel channel_name ; print-auth bool ; print-pass bool ; print-failed-pass bool ; level debug_level ; } ; channel channel_name { file string ; syslog facility . priority [tag] ; print-pid bool ; print-category bool ; print-cons bool ; print-level bool ; print-priority bool ; print-tid bool; print-milliseconds bool; prefix-hook string ; suffix-hook string ; }; } ; |
The logging
statement describes the course followed by
radiusd
's logging information.
The parts of this statement are discussed below.
4.1.2.1 Logging hooks | ||
4.1.2.2 category statement | ||
4.1.2.3 channel statement | ||
4.1.2.4 Example of the logging statement |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Most diagnostic messages displayed by radiusd
describe
some events that occured while processig a certain incoming request.
By default they contain only a short summary of the event.
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 hook is a special Rewrite function that takes three arguments and returns a string. There are two kinds of logging hooks: prefix and 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 global and channel-specific
hooks. Global hooks apply to all categories, unless overridden by
category-specific hooks. Global prefix hook is enabled by
prefix-hook
statement appearing in the logging
block.
Global suffix hook is enabled by suffix-hook
statement.
Both statements take as their argument the name of corresponding
Rewrite function.
For detailed information about writing logging hooks, See section Logging Hook Functions.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
category
statement Each line of logging information generated by radiusd
has an
associated category. The logging
statement allows each
category of output to be controlled independently of the others.
The logging category is defined by category name and a
severity. category name determines what part of radiusd
daemon is allowed to send its logging information to this channel.
It can be any of main
, auth
, acct
, proxy
,
snmp
. priority determines the minimum priority of
the messages displayed by this channel. The priorities in ascending
order are: debug
, info
, notice
, warn
,
err
, crit
, alert
, emerg
.
The full category specification, denoted by the category_spec
in the above section, can take any of the following three forms:
Print the messages of given category.
Print messages of all categories, abridged by given priority. If the priority is prefixed with ‘=’, only messages with given priority will be displayed. If it is prefixed with ‘!’, the messages with priority other than the specified will be displayed. Otherwise, the messages with priorities equal to or greater than the specified will be displayed.
Print the messages of given category, abridged by given priority. The priority may be prefixed with either ‘=’ or ‘!’ as described above. The dot (‘.’) separates the priority from the category name, it may be surrounded by any amount of whitespace.
Additional category options valid for auth
category are:
print-auth
Log individual authentications.
print-pass
Include passwords for successful authentications. It is very insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes.
print-failed-pass
Include passwords for failed authentications.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
channel
statement Channels represent methods for recording logging information. Each
channel has a unique name, and any categories which specify that name in
a channel
statement will use that channel.
radiusd
can write logging information to files or send it to
syslog. The file
statement sends the channel's output to the
named file (see section Naming Conventions). The syslog
statement
sends the channel's output to syslog with the specified facility and
severity. Its optional last argument allows to alter default syslog
tag.
Channel options modify the data flowing through the channel:
print-pid
Add the process ID of the process generating the logging information.
print-cons
Also send the logging information to the system console.
print-category
Add the category name to the logging information.
print-priority
print-level
Add the priority name to the logging information.
print-milliseconds
Print timestamp with milliseconds.
prefix-hook
Declares the name of Rewrite function used as logging prefix hook for that channel (see section Logging hooks). This overrides any global prefix hook.
suffix-hook
Declares the name of Rewrite function used as logging suffix hook for that channel (see section Logging hooks). This overrides any global suffix hook.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
logging
statement logging { channel default { file "radius.log"; print-category yes; print-priority yes; }; channel info { file "radius.info"; print-pid yes; print-cons yes; print-priority yes; }; channel notice { syslog auth.notice; }; category auth { print-auth yes; print-failed-pass yes; }; category notice { channel notice; }; category info { channel info; }; category debug { channel info; level radiusd=1,files; }; category *.!debug { channel default; }; }; |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
auth
statement auth { listen ( addr-list | no ); forward addr-list; port number ; max-requests number ; time-to-live number ; request-cleanup-delay number ; detail bool ; strip-names bool ; checkrad-assume-logged bool ; password-expire-warning number ; compare-atribute-flag character ; trace-rules bool ; reject-malformed-names bool ; } ; |
The auth
statement configures the parameters of the authentication
service.
listen
statement This statement determines on which addresses radiusd will listen for incoming authentication requests. Its argument is a comma-separated list of items in the form ip:port-number. ip can be either an IP address in familiar “dotted-quad” notation or a hostname. :port-number part may be omitted, in which case the default authentication port is assumed.
If the listen
statement is omitted, radiusd will accept incoming
requests from any interface on the machine.
The special value no
disables listening for authentication
requests.
The following example configures radius to listen for the incoming requests on the default authentication port on the address 10.10.10.1 and on port 1645 on address 10.10.11.2.
listen 10.10.10.1, 10.10.11.2:1645; |
forward
statement This statement enables forwarding of the requests to the given set of servers. Forwarding is an experimental feature of GNU Radius, it differs from proxying in that the requests are sent to the remote server (or servers) and processed locally. The remote server is not expected to reply.
This mode is intended primarily for debugging purposes. It could also be useful in some very complex and unusual configurations.
port
Sets the number of which UDP port to listen on for the authentication requests.
max-requests
Sets the maximum number of authentication requests in the queue. Any surplus requests will be discarded.
time-to-live
Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.
request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will the completed authentication request reside in the queue.
password-expire-warning
Sets the time interval for password expiration warning. If user's password expires within given number of seconds, radiusd will send a warning along with authentication-acknowledge response. Default is 0.
detail
When set to true, radiusd
will produce the detailed log of each
received packet in the file ‘radacct/nasname/detail.auth’. The
format of such log files is identical to the format of detailed
accounting files (see section Detailed Request Accounting).
strip-names
Determines whether radiusd
should strip any prefixes/suffixes
off the username before logging.
checkrad-assume-logged
See section mlc
statement, for the description of this setting. It is accepted in
auth
for compatibility with previous versions of GNU Radius.
trace-rules
Enables tracing of the configuration rules that were matched during processing of each received authentication request. See section Rule Tracing, for detailed information about this mode.
reject-malformed-names
Enables sending access-reject replies for the access-accept requests
that contain an invalid value in User-Name
attribute. By default
such requests are discarded without answering. See the description of
username-chars
(see section Option statement).
compare-attribute-flag
The argument to this statement is a character from ‘1’ through ‘9’. This statement modifies the request comparison method for authentication requests. See section Extended Comparison, for a detailed description of its usage.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
acct
statement acct { listen ( addr-list | no ); forward addr-list ; port number ; detail bool; system bool; max-requests number ; time-to-live number ; request-cleanup-delay number ; compare-atribute-flag character ; trace-rules bool ; } ; |
The acct
statement configures the parameters of the accounting
service.
listen
statement This statement determines on which addresses radiusd will listen for incoming accounting requests. Its argument is a comma-separated list of items in the form ip:port-number. ip can be either an IP address in familiar “dotted-quad” notation or a hostname. :port-number part may be omitted, in which case the default accounting port is assumed.
If the listen
statement is omitted, radiusd will accept incoming
requests from any interface on the machine.
The special value no
disables listening for accounting
requests.
The following example configures radius to listen for the incoming requests on the default accounting port on the address 10.10.10.1 and on port 1646 on address 10.10.11.2.
listen 10.10.10.1, 10.10.11.2:1646; |
forward
statement This statement enables forwarding of the requests to the given set of servers. Forwarding is an experimental feature of GNU Radius, it differs from proxying in that the requests are sent to the remote server (or servers) and processed locally. The remote server is not expected to reply.
This mode is intended primarily for debugging purposes. It could also be useful in some very complex and unusual configurations.
port
Sets the number of which port to listen for the authentication requests.
max-requests
Sets the maximum number of accounting requests in the queue. Any surplus requests will be discarded.
time-to-live
Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.
request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will the completed account request reside in the queue.
detail
When set to no
, disables detailed accounting
(see section Detailed Request Accounting).
system
When set to no
, disables system accounting (see section System Accounting). Notice, that this will disable simultaneous use checking
as well, unless you supply an alternative MLC method (currently
SQL, See section Multiple Login Checking, for the detailed discussion
of this).
trace-rules
Enables tracing of the configuration rules that were matched during processing of each received accounting request. See section Rule Tracing, for detailed information about this mode.
compare-attribute-flag
The argument to this statement is a character from ‘1’ through ‘9’. This statement modifies the request comparison method for authentication requests. See section Extended Comparison, for a detailed description of its usage.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
usedbm
statement usedbm ( yes | no ) ; |
The usedbm
statement determines whether the DBM support should
be enabled.
no
Do not use DBM support at all.
yes
Use only the DBM database and ignore ‘raddb/users’.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
snmp
statement snmp { port portno ; listen ( addr-list | no ); max-requests number ; time-to-live number ; request-cleanup-delay number ; ident string ; community name ( rw | ro ) ; network name network [ network ... ] ; acl { allow network_name community_name ; deny network_name ; } ; storage { file filename ; perms number ; max-nas-count number ; max-port-count number ; } ; }; |
The snmp
statement configures the SNMP service.
listen
statement The listen
statement determines on which addresses radiusd will
listen for incoming SNMP requests. The argument is a comma-separated
list of items in the form ip:port-number. The ip can
be either an IP address in familiar “dotted-quad” notation or a
hostname. The :port-number part may be omitted, in which case the
default SNMP port (161) is used.
If the listen
statement is omitted, radiusd will accept incoming
requests from any interface on the machine.
The special value no
disables listening for SNMP requests.
The following example configures radius to listen for the incoming SNMP requests on the default SNMP port on the address 10.10.10.1 and on port 4500 on address 10.10.11.2.
listen 10.10.10.1, 10.10.11.2:4500; |
port
Sets the number of which port to listen for the SNMP requests.
max-requests
Sets the maximum number of SNMP requests in the queue. Any surplus requests will be discarded.
time-to-live
Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue.
request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will the completed SNMP request reside in the queue.
ident
Sets the SNMP server identification string.
community name ( rw | ro )
Defines the community name as read-write (rw
) or read-only
(ro
).
network name network [ network ... ]
Groups several networks or hosts under one logical network name.
allow network_name community_name
allow hosts from the group network_name access to community community_name.
deny NETWORK_NAME
Deny access to SNMP service from any host in the group network_name.
GNU Radius stores the SNMP monitoring data in an area of shared memory mapped to an external file. This allows all subprocesses to share this information and to accumulate the statistics across invocations of the daemon.
The storage
statement controls the usage of the storage for
the SNMP data.
file
Sets the file name for the SNMP storage file. Unless the filename begins with a ‘/’ it is taken as relative to the current logging directory.
perms
Sets the access permissions for the storage file. Notice, that this statement does not interpret its argument as octal by default, so be sure to prefix it with ‘0’ to use an octal value.
max-nas-count
Sets maximum number of NASes the storage file is able to handle. Default is 512. Raise this number if you see the following message in your log file:
|
max-port-count
Sets maximum number of ports the storage file is able to handle. Default is 1024. Raise this number if you see the following message in your log file:
|
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
rewrite
statement. (This message will disappear, once this node revised.)
rewrite { stack-size number ; load-path string ; load string ; }; |
stack-size
Configures runtime stack size for Rewrite. The number is the size of stack in words. The default value is 4096.
load-path
Add specified pathname to the list of directories searched for rewrite files.
load
Loads the specified source file on startup. Unless string is an
absolute pathname, it will be searched in directories set up by
load-path
statement.
The default load path is ‘RADDB’:‘DATADIR’/rewrite
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
guile
statement (This message will disappear, once this node revised.)
The guile
statement allows to configure server interface with
Guile.
guile { debug bool ; load-path string ; load string ; load-module string [ string ... ] ; eval expression [ expression ... ] ; gc-interval number ; outfile string ; }; |
debug
When set to yes, enables debugging evaluator and backtraces on Guile scripts.
gc-interval
Configures the forced garbage collections. By default the invocation
of the garbage collector is run by the internal Guile mechanism.
However, you may force Radius to trigger the garbage collection
at fixed time intervals. The gc-interval
statement sets
such interval in seconds.
For more information about Guile memory management system in general and garbage collections in particular, see (guile)Memory Management section `Memory Management and Garbage Collection' in The Guile Reference Manual.
eval
Evaluates its argument as Scheme
expression.
load-path
Adds specified pathname to %load-path
variable.
load
Loads the specified source file on startup.
load-module
Loads the specified Scheme module on startup. This statement takes an
arbitrary number of arguments. The first argument specifies the name
of the module to load, the rest of arguments is passed to the
module initialization funtion. Module initialization function
is a function named ‘module-init’, where module is
the module name. Arguments are converted using usual Guile
rules, except that the ones starting with a dash (‘-’) are
converted to keyword arguments.
outfile
Redirects the standard output and standard error streams of the Guile
functions to the given file. Unless the filename starts with ‘/’,
it is taken relative to the current logging directory.
See section Guile, for a detailed description of Guile extensions interface.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
message
statement The message
statement allows to set up the messages that are
returned to the user with authentication-response packets.
message { account-closed string ; password-expired string ; password-expire-warning string ; access-denied string ; realm-quota string ; multiple-login string ; second-login string ; timespan-violation string ; }; |
All variables in message
block take a string argument. In
string you can use the usual C backslash notation to represent
non-printable characters. The use of %C{} and %R{} sequences
is also allowed (see section Macro Substitution).
account-closed
This message will be returned to the user whose account is administratively closed.
password-expired
This message will be returned to the user whose password has expired.
password-expire-warning
This is a warning message that will be returned along with an
authentication-acknowledge packet for the user whose password will
expire in less than n seconds. The value of n is set by
password-expire-warning
variable in auth
block.
See section auth
statement. In this string, you can use the %R{Password-Expire-Days}
substitution, to represent the actual number of days left
to the expiration date. The default is
Password Will Expire in %R{Password-Expire-Days} Days\r\n |
access-denied
This message is returned to the user who supplies an incorrect password or a not-existent user-name as his authentication credentials.
realm-quota
This message is returned when the user is trying to log in using a realm, and number of users that are currently logged in from this realm reaches maximum value. For a description of realms, see Realms.
multiple-login
This message is returned to the user, who has logged in more than
allowed number of times. For description of how to set the maximum
number of concurrent logins, see Simultaneous-Use
.
second-login
This is a special case of multiple-login
, which is used when
the user's login limit is 1.
timespan-violation
This message is returned to the user who is trying to login outside of
allowed time interval. For description of how to limit user's login
time, see Login-Time
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
filters
statement The filters
statement configures user-defined external filters.
See section Filters, for the detailed discussion of external filters.
filters { filter ident { exec-path path ; error-log filename ; common bool [max-wait]; auth { input-format fmt ; wait-reply bool ; }; acct { input-format fmt ; wait-reply bool ; }; }; … }; |
Each filter
directive defines a new filter. The ident
argument declares the name of the filter. This string must be
used in Exec-Program-Wait
or Acct-Ext-Program
attributes
to trigger invocation of this filter (see section Exec-Program-Wait
).
Absolute path to the filter program.
Redirect error output from the filter program to filename. If the filename does not start with a slash, it is taken relative to the current logging directory (see section log-dir).
These compound statements define authentication and accounting
parts of this filter. Any one of them may be missing. The two
statements allowed within auth
and acct
blocks are:
Format of the input line for this filter. Usually this string uses %C{} notations (see section Macro Substitution).
You can also use the return value from a rewrite
function as
input line to the filter. To do so, declare:
input-format "=my_func()"; |
where my_func is the name of the rewrite function to invoke. The function must return string value.
If the filter prints a single line of output for each input line, set
this to yes
. Otherwise, if the filter produces no output, use
wait-reply no
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
mlc
statement mlc { method (system|sql); checkrad-assume-logged bool; }; |
Mlc
statement configures multiple login checking subsystem
(see section Multiple Login Checking).
Sets the method of retrieving information about the currently open
sessions. Currently two methods are implemented. Setting method
to system
will use system accounting database (see section System Accounting). This is the default method. Setting it to sql
will use SQL database.
radiusd
consults the value of this variable when the NAS
does not responds to checkrad queries (see section Multiple Login Checking).
If this variable is set to yes
, the daemon will proceed as if
the NAS returned “yes”, i.e. it will assume the user is logged in.
Otherwise radiusd
assumes the user is not logged in.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated by Sergey Poznyakoff on December, 6 2008 using texi2html 1.78.