 |
Index for
Section 5 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
ENGINE.CONFIG(5)
NAME
engine.config - RADIUS Local Authorization Server
SYNOPSIS
../raddb/engine.config
DESCRIPTION
The engine.config file resides in the Interlink AAA Server configuration
directory (named .../raddb somewhere). It contains keyword-value entries,
one-per-line, which allow the user to override compiled-in default values
in the Interlink AAA Server. The engine.config file may be used for
performance tuning, debugging or specifying of defaults which would
otherwise require code changes and recompilation of the Interlink AAA
Server.
FILE SYNTAX
Comments are indicated by leading pound sign ('#') characters. All such
comment lines are ignored, as are lines entirely made up of blanks. All
lines are counted for the purpose of reporting errors, warnings, or
changes.
Each line in the engine.config configuration file is formatted as a
<variable> = <value> tuple, that is:
default_reply_holdtime = 6
even when that format isn't very appropriate. A hostname prefix (such as is
used in the clients(5) file) also may be allowed. For example:
radserver1.myisp.net/default_reply_holdtime = 6
radserver2.myisp.net/default_reply_holdtime = 0
Note: The hostname here is the hostname returned by the hostname(1)
command, not the fully-qualified DNS name.
Note: processing of this file terminates when "end" is encountered.
Note: Any whitespace characters (blanks and tabs) surrounding the equal
sign ("=") character are ignored, as is leading whitespace. Trailing
whitespace MAY be significant!
Most changes to configuration values are reported. The old and new values
are reported, although not necessarily in a way that can be used to feed
back into the engine.config file itself.
The engine.config file is read in during initialization time, and whenever
the server receives an INT or HUP signal.
The engine.config file has a maximum input line length of 255 characters.
NO checking is done to insure that a configuration statement has exceeded
this limit.
FUNCTIONAL GROUPING OF FEATURES
The following items are useful for general server performance tuning:
· default_reply_holdtime
· global_acct_q.limit
· global_auth_q.limit
The following items are useful for configuration specific performance
tuning (i.e., UNIX passwords, Kerberos, etc.):
· aatv.proc_max
The following items are useful for responding to network faults, DNS
problems, and other issues outside the direct control of the server
operator:
· aatv.proc_max
· dns_address_aging
· dns_address_window
The following items are useful for tracing the behaviour of the server in
order to determine where an external fault might lie:
· log_forwarding
· packet_log
· reply_check
The following items are useful for diagnosing load related issues with the
server by providing additional information using the radcheck(8) command:
· radcheck=+packets
· radcheck=+queues
DETAILED DESCRIPTION OF CONFIGURATION ITEMS
Configuration Item Related Config Example
aatv.direct none aatv.direct=FILE
Override the compiled in type of an AATV to be of type AA_DIRECT.
This is VERY dangerous, especially for socket type AATVs, or AATVs
that depend on the forked environment to be "reset" for every fork.
But, it is useful for debugging some AA_FORK type AATVs or even
AA_FREPLY type AATVs without disabling forking in the server with the
"-s" option.
Configuration Item Related Config Example
aatv.forking none aatv.forking=UNIX-PW
Override the compiled in type of an AATV to be of type AA_FORK. This
is VERY dangerous, especially for AA_SOCKET or AA_DIRECT type AATVs
that depend on sharing the address space with the main process.
Configuration Item Related Config Example
aatv.forkreply none aatv.forkreply=MKERB
aatv.forkreply=AKERB
aatv.forkreply=TAC_PLUS
Override the compiled in type of an AATV to be of type AA_FREPLY.
This is VERY dangerous, especially for socket type AATVs, or AATVs
that depend on the forked environment to be "reset" for every fork.
This is useful for converting an AA_FORK type AATV into an AA_FREPLY
type AATV for testing or addtional error messages being returned to
the user (i.e., convert the AKERB or MKERB AATVs from type AA_FORK to
AA_FREPLY to pass error messages back to the NAS/user or client RADIUS
server).
Configuration Item Related Config Example
aatv.socket none none
Override the compiled in type of an AATV to be of type AA_SOCKET.
This is VERY dangerous, as most of the socket type AATVs have a socket
in the AATV header and this doesn't do anything to put a socket there.
This was included for completeness, not because it had any useful
purpose.
Configuration Item Related Config Example
aatv.proc_max aatv.proc_max=UNIX-PW 8
none - See also
"radcheck =
+queues"
aatv.proc_max=AKERB 8
Set the maximum simultaneous number of processes for an AA_FORK or
AA_FREPLY type AATV. This value is normally compiled into the header
of a forking type AATV.
This is a performance enhancing feature intended to prevent a UNIX
platform from being consumed by too many simultaneously forked
processes.
The default value of zero means that NO maximum is applied.
When a maximum value is set, the AAA server keeps track of the number
of outstanding child processes for the specified AATV. When that
limit is exceeded, the authentication (or accounting) request is
queued on the AATV until the current number of child processes drops
below the maximum. NOTE: an authentication or accounting request CAN
time-out from this state if the child processes take too long to
respond!
Setting this value to one allows only one simultaneous child process
at a time (for the specified AATV), which may solve certain timing
issues involving AATVs that communicate with external databases, etc.,
while still allowing the normal AAA engine functions of duplicate
detection, queueing and timeouts to occur (i.e., try using this first
instead of 'aatv.direct' on a forking type AATV).
Information suitable for tailoring this value may be found from the
radcheck(8) command. Each forking-type AATV is listed by radcheck(8)
one per line.
Tailoring of this value should be influenced by the "total" and
"holding" values reported on a per-request basis.
Configuration Item Related Config Example
avpair_checking avpair_checking=on
none - Server needs
to be compiled with
AVPAIR_CHECKING
enabled
avpair_checking=off
This is a feature to assist developers. It enables a simple check of
each internal attribute value pair in many circumstances throughout
the Interlink AAA Server. If a corrupted attribute value pair is
detected, the server crashes with a core dump. See also the "cwd"
configuration item and version prefixing.
Configuration Item Related Config Example
default_reply_holdtime default_reply_holdtime=0
"clients" file
"reply_holdtime =
<seconds>"
See also the TTL
and TTL_SLICE AATVs
for related
configuration
options.
default_reply_holdtime=6
Specify the number of seconds to hold on to a request after it has
been replied to by the REPLY AATV in the finite state machine (FSM)
table. This should be two times the default retransmission period of
the NASes involved. This value is applied if no 'reply_holdtime' is
specified for a particular NAS client. This does NOT apply to packets
that are forwarded to a client in the clients(5) file.
A value of zero invokes special behaviour whereby the REPLY AATV does
NOT change the hold time for a request. This would cause all received
authentication or accounting requests to be held for the full TTL
(time-to-live), no matter if the request took a short time to process
before being replied to.
NOTE: Using the special value of zero, or using a hold time greatly in
excess of the retransmission policy of a NAS may cause the
authentication and accounting queues to grow too large. See
'global_acct_q.limit' and 'global_auth_q.limit' below.
The TTL AATV and TIMEOUT AATVs may be used to modify the TTL of a
request. The default TTL of a received request is 30 seconds.
The TTL of a request is normally reset to the ttlslice value when a
duplicate request is received, except after the the request has been
replied to. The TTL_SLICE AATV may be used to reset the default
ttlslice value.
Tailoring of this value should be influenced by the "total" and
"holding" values reported on a per-request basis.
Configuration Item Related Config Example
default_retry_limit default_retry_limit=8
See also
'default_seqch_limit',
and the AATVs
RETRY_LIMIT,
SEQCH_LIMIT, FAIL
and WAIT.
default_retry_limit=0
Limit the maximum number of retransmissions allowed before a RETRY
event occurs. A RETRY event is similar to a TIMEOUT event and should
be caught by the built-in (default) FSM table. If the value is zero,
the default, then no limits are imposed. The purpose of this is to
catch an authentication request and perform some action when a certain
number of retransmissions from a NAS occur.
In particular, it may be useful to have a primary authentication
server deny access (using the FAIL AATV) before a backup server starts
to authenticate, allowing the backup server to backup just the primary
and not the whole AAA system.
Configuration Item Related Config Example
default_seqch_limit See above default_seqch_limit=3
default_seqch_limit=0
Consider reply-vector and reply-id changes when counting
retransmissions. When the limit is exceeded, cause a RETRY event to
occur on the request which should be handled by the built-in (default)
FSM table.
Configuration Item Related Config Example
dns_address_aging dns_address_aging=5400
dns_address_window
- See also
'dns_refresh_floor'
and
'dns_refresh_window'
The default value is one hour. DNS entries in the clients(5) file are
refreshed periodically. There is a designed in randomness to the
aging process so that all the client entries don't expire at once.
The 'dns_address_aging' value is used to set the base-value, to which
zero, 15, 30 or 45 minutes is added.
Configuration Item Related Config Example
dns_address_window dns_address_window=300
dns_address_aging -
See also
'dns_refresh_floor'
and
'dns_refresh_window'
The default value is 60 seconds. When a DNS entry in the clients(5)
file expires (needs refreshing), all other client entries that might
be refreshed within this window are refreshed, too.
DNS entries are refreshed by forking a process that calls the
gethostbyname(3) library function for all entries that need
refreshing, and then passing the results back via UDP datagrams. This
serves to limit the amount of forking which occurs to support
refreshing of the clients(5) file entries.
Increasing this value means that less forking will occur for the same
number of client entries in the clients(5) file. That is, more
expired client entries will fit into a larger window. This may be
useful if DNS updates can take a long time, such as when the DNS
server for a particular client entry has gone bad or missing, or when
a single clients(5) file has a very large number of entries.
Configuration Item Related Config Example
dns_refresh_floor dns_refresh_floor=300
dns_refresh_window
- See also
'dns_address_aging'
and
'dns_address_window'
The default value is three (3) minutes. If a clients(5) file expires
(needs refreshing), all other clients that might be refreshed within
this window are refreshed, too.
DNS entries are refreshed by forking a process that calls the
gethostbyname(3) library function for all entries that need
refreshing, and then passing the results back via UDP datagrams. This
serves to limit the amount of forking that occurs to support
refreshing of the clients(5) file entries.
Increasing this value means that less forking will occur for the same
number of client entries in the clients(5) file. This may be useful
if DNS updates take a long time, such as when the DNS server has gone
bad or missing for a particular clients(5) file entry, or if there are
a large number of entries in a single clients(5) file.
Configuration Item Related Config Example
global_acct_q.limit none global_acct_q.limit=2400
Set the maximum number of simultaneous accounting requests to be
handled by the system. When this limit is exceeded, the requests are
dropped with a message in the logfile.
Configuration Item Related Config Example
global_acct_q.hold none global_acct_q.hold=300
For debugging purposes only. Enables holding of old requests for a
specific period of time after they've otherwise been freed from the
system. See also 'reply_check'. Specifies a value in seconds.
Configuration Item Related Config Example
global_auth_q.limit none global_auth_q.limit=1800
Set the maximum number of active authentication requests to be handled
by the system.
When this limit is exceeded, an Access-Reject reply is returned and a
message added to the logfile.
Note that when the authentication queue limit is exceeded, the server
stops responding to the radcheck(8) command.
Configuration Item Related Config Example
global_auth_q.hold none global_auth_q.hold=600
For debugging purposes only. Enables holding of old requests for a
specific period of time after they've otherwise been freed from the
system. See also 'reply_check'. Specifies a value in seconds.
Configuration Item Related Config Example
list_copy_limit none list_copy_limit=1024
For certain kinds of custom Interlink AAA Servers that accumuluate
attribute/value pairs or generate large responses. The default value
is 512. See also 'send_buffer_size'.
When this limit is exceeded, the Interlink AAA Server will crash with
a message in the logfile and a core-dump.
Configuration Item Related Config Example
log_forwarding none log_forwarding=on
log_forwarding=off
log_forwarding=+vector
log_forwarding=+digest
log_forwarding=+dump
log_forwarding=-vector
log_forwarding=-digest
log_forwarding=-dump
log_forwarding=clear
Turn on (or off) logging in the "logfile" when packets are forwarded
via RADIUS to another RADIUS or Interlink AAA Server. Also, turn on
(or off) logging of the forwarding vector, reply vector, or dumping of
the packet (in hexadecimal) in the logfile of the packet being
forwarded.
This allows finer detail when tracking problems, at the expense of
increased sizes of logfiles.
Configuration Item Related Config Example
log_generated_request none log_generated_request=on
log_generated_request=off
Turn on (or off) logging of internally generated packets when they are
created and when they reach their end-state.
This is used for certain custom Interlink AAA Servers that produce
accounting requests based on internal state transitions rather than on
an externally delivered request.
Configuration Item Related Config Example
merit_grandfather none merit_grandfather=on
This feature is available only if the server is compiled with the
MERIT_GRANDFATHER feature enabled. If on, it treats certain kinds of
authentication requests as Status-Server requests.
Configuration Item Related Config Example
monitor none monitor=on
monitor=off
monitor=reset
monitor=new
Turn on (or off) monitoring of the server's engine performance and
throughput. It does this by storing information in a shared memory
area for access by the radmon(8) performance monitor program. The
setting of this feature (to on or off) will take affect when the
server starts operation or when it receives a HUP signal.
Two options are available for modifying the monitoring behaviour.
These are reset and new. The former will zero the shared memory area
when the server starts or receives a HUP signal. In the latter case,
all information is deleted in the shared memory area when the server
receives a HUP signal.
Configuration Item Related Config Example
ourhostname none ourhostname=*
Change the internal hostname that the Interlink AAA Server believes
itself to be. This is useful for situations when a machine is being
configured at a different IP address than where it will final reside.
It is also useful for situations where a machine will be renamed and
some configurations need to be readied before the renaming. If no
hostname is given, or the special value '*' (without quotes), the
machine's true hostname will be set.
Configuration Item Related Config Example
packet_log packet_log=default
none - See also
'reply_check'
packet_log=clear (or none)
packet_log=+abort
packet_log=+both (or +comp)
packet_log=+current (or +cur)
packet_log=+original (or +orig)
packet_log=-abort
packet_log=-both (or -comp)
packet_log=-current (or -cur)
packet_log=-original (or -orig)
When logging certain attributes in a request log (NAS-Identifier,
NAS-Port, User-Name, et. al.), a check MAY be made to see if the
current request matches the original request and to crash and core-
dump as a possible action.
This is useful for tracking situations where a remote RADIUS or
Interlink AAA Server is responding with incorrect values. Also, it
may be used to investigate if an AATV is corrupting the current
request.
The value of "default" means to set only +current and +original. The
value of "+current" (or +cur) means to report only from the modified
request. The value of "+original" (or +orig) means to report only
from the original request. The value of "+abort" means to crash and
core-dump if there is a mismatch.
Configuration Item Related Config Example
radcheck none radcheck=+packets
radcheck=+queues
radcheck=-packets
radcheck=-queues
Enable (or disable) certain reports produced by the radcheck(8)
command. New reports produced by the radcheck(8) command may now be
enbled or disabled with this option. Currently, only two classes of
reports are so affected. The plus ("+") character enables the report,
while the minus ("-") disables the report:
· +/-queues (default is +/enable)
This shows queue information such as: number of unique requests,
number of queue overflows, number of duplicate requests, for all of
the queues in the system (e.g., authentication and accounting).
If the number of accounting requests greatly exceeds the number of
authentication requests, then a NAS/network configuration error is
possible.
· +/-packets (default -/disabled)
Show statistics about the number of octets/packets received,
replied, forwarded, replies received, and redone. These counters
are reset on an INT or HUP signal.
Configuration Item Related Config Example
radius_log_fmt -l option none
Override the "-l" option to specify the logfile format string used.
Configuration Item Related Config Example
reply_check none reply_check=first
reply_check=all
reply_check=+abort
reply_check=+dump
reply_check=+ignore
reply_check=+verbose
reply_check=clear
reply_check=none
reply_check=Nas-Identifier
Specify which attributes to check on a reply from a forwarded request
to insure that they are the same as the forwarded request.
Besides specifying which attributes to check, it's possible to specify
the action to take when a mismatch occurs: ignore the reply, ignore
the mismatch or crash and core-dump.
Useful attributes to check are Nas-Identifier, Acct-Session-Id, Class,
User-Name.
Note: This feature might not work well in situations that communicate
with servers that are not derived from the Interlink AAA Server.
The value of "first" (default) means to check only the first match.
The value of "all" means to check all the attributes for matches. The
value of "+abort" means to crash and core-dump if a check fails. The
value of "+dump" means to dump (log) the offending packet (in
hexadecimal).
Configuration Item Related Config Example
send_buffer_size none send_buffer_size=1472
Decrease the send buffer size. The current size is 16K (16536).
Limiting the send_buffer_size to be the UDP MTU for the network will
prevent excessively large packets from being forwarded (or replied to)
in certain circumstances.
This configuration item serves only a debugging function for certain
custom Interlink AAA Servers which might transmit very large packets,
and helps to debug code intended to prevent an excessively large
packet from corrupting the server.
Configuration Item Related Config Example
send_proxy_action none send_proxy_action=off
When the Interlink AAA Server forwards an authentication or an
accounting request, it adds a Merit vendor specific attribute (VSA),
Proxy-Action, at the begining of the request, if this is "on". This
is the default behaviour for the Advanced Interlink AAA Servers.
This feature allows an Interlink Advanced AAA Server to act as a
backup server.
Configuration Item Related Config Example
users_file_maxlen none users_file_maxlen=1024
Set the maximum line length for reading the users(5), file and/or
realm files. The values may range from 1024 to 16534 characters per
line.
Configuration Item Related Config Example
year_2000 none year_2000=on
year_2000=off
y2k=on
y2k=off
Turn on and off the Year 2000 compatibility mode. Dates that were
formerly expressed with two digits will be expressed with four digits.
Note: This feature does NOT affect the logfile.
FILES
../raddb/engine.config
SEE ALSO
hostname(1), kill(1), gethostbyname(3), signal(3), clients(5), radcheck(8),
radiusd(8), radmon(8)
|
Index for
Section 5 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|