\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename radius.info
@settitle GNU radius
@c %**end of header
@setchapternewpage odd

@dircategory GNU radius
@direntry
* Radius: (radius).     The GNU radius
@end direntry

@include version.texi

@c **************************************************************************
@c Please remember to specify the edition, version numbers and date in
@c *three* places: 1. First ifinfo section, 2. Title page, 3. Top node
@ifinfo
This file documents the GNU radius

Published by the Free Software Foundation
59 Temple Place, Suite 330
Boston, MA  02111-1307 USA

Copyright @copyright{} 1999 Sergey Poznyakoff
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU
General Public License'' are included exactly as in the original, and
rovided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``The GNU Manifesto'',
``Distribution'' and ``GNU General Public License'' may be included in a
translation approved by the Free Software Foundation instead of in the
original English.
@end ifinfo

@settitle GNU Radius Manual

@iftex
@shorttitlepage GNU Radius Manual
@end iftex
@titlepage
@sp 6
@center @titlefont{GNU Radius Manual}
@sp 4
2@center for Radius version @value{VERSION}
@sp5
@sp 1
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU
General Public License'' are included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``The GNU Manifesto'',
``Distribution'' and ``GNU General Public License'' may be included in a
translation approved by the Free Software Foundation instead of in the
original English.
@author Sergey Poznyakoff
@end titlepage

@node Top, Distrib, , (dir)

@ifinfo
@top The GNU Radius

Radius is a suite of programs for performing user authentication
and accounting using RADIUS protocol.

This Info file documents the version @value{VERSION} of the package.

@end ifinfo

@comment *******************************************************************
@menu
* Distrib::             How to get the radius distribution.
* Copying::             The GNU General Public License gives you permission
                        to redistribute the program on certyain terms.
* Intro::               An introduction to radius concepts.
* Glossary::            The glossary.

The radius daemon
* Operation::           How radius operates.
* Naming conventions::  Conventins abount naming files and directories.
* Invocation::          How to start the daemon.
* Configuration files:: Radius configuration files.
* Authentication::      How the users are authenticated
* Accounting::          Accounting methods.
* Logging::             What gets logged and where.
* Debugging::           An extensive logging information.

Client programs
* Client Overview::     General concepts.
* client.config::       General configuration options.
* client.shadow::       A list of radius servers to connect to.

The checkrad program
* Checkrad Overview::   Purpose of checkrad.
* checkrad.conf::       Configuring checkrad.

Controlling who and when was logged in
* Radwho::              Show who is logged in by radius now.
* Radlast::             Show the history of logins by radius.
* Raduse::              Monitor the users in real time.

Maintenance commands
* Radzap::              Modify the login records.
* Radgrep::             Quickly find the login record.
* Radping::             Ping the remote machine by the username.
* Radauth::             Check if a user can be authenticated.
* Radtest::             Test the functionality of the radius daemon.
* Radctl::              Radctl monitor.
* Radctl.sh::           Alternative ways to communicate with radius daemon.
* Builddbm::            Create DBM version of the @file{raddb/users} file.

Radius Attributes
* Attribute list::      Some frequently used attributes.

Reporting Bugs
* Bugs::                How to report a bug

Indices
* Program Index::       Index of programs.
* Attribute Index::     Index of RADIUS attributes.
* Concept Index::       Index of concepts.

@end menu

@ignore
Enable this when necessary
@detailmenu
@end detailmenu
@end ignore

@comment *******************************************************************
@node Distrib, Copying, Top, Top
@unnumbered Distribution

GNU Radius is @dfn{free software}; this means that everyone is free to
use it and free to redistribute it on certain conditions.  GNU Radius is
not in the public domain; it is copyrighted and there are restrictions
on its distribution, but these restrictions are designed to permit
everything that a good cooperating citizen would want to do.  What is
not allowed is to try to prevent others from further sharing any version
of GNU Radius that they might get from you.  The precise conditions are
found in the GNU General Public License that comes with Radius and also
appears following this section.

One way to get a copy of GNU Radius is from someone else who has it.  You
need not ask for our permission to do so, or tell any one else; just
copy it.  If you have access to the Internet, you can get the latest
distribution version of GNU Radius by anonymous FTP. It is available at
@url{ftp://ftp.gnu.org/pub/gnu/gnu-radius}


@comment *******************************************************************
@node Copying, Intro, Distrib, Top
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991

@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo

@enumerate 0
@item
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The ``Program'', below,
refers to any such program or work, and a ``work based on the Program''
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term ``modification''.)  Each licensee is addressed as ``you''.

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

@item
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

@item
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.

@item
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

@item
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
@end enumerate

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

@item
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

@item
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

@item
Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
@end enumerate

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

@item
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

@item
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

@item
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c' 
for details.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than @samp{show w} and
@samp{show c}; they could even be mouse-clicks or menu items---whatever
suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here is a sample; alter the names:

@smallexample
@group
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written 
by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end group
@end smallexample

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

@comment *******************************************************************
@node Intro, Glossary, Copying, Top
@unnumbered Introduction to Radius

Radius is a system serving for authentication and accounting. The name
RADIUS (all capitals) stands for Remote Authentication in Dial-In User
Service and is usually used as the underlying protocol name.

Historically, radius servers were used as a means to authenticate the user
coming from a dial-in connection, but GNU Radius is much more than an
authentication system: it is an advanced, customizable and extensible system
for controlling access to the network.

It is @dfn{advanced}, because it allows for authentication, accounting and
monitoring of the user connections.

It is @dfn{customizable}, because you can fine-tune it to suit your needs.

It is @dfn{extensible}, because its functions can be extended beyond
simple customization.

GNU Radius includes radius server program capable of serving authentication
and accounting requests, and a set of accompanying programs designed to
monitor the activity of the server and analize the information it provides.

@comment *******************************************************************
@node Glossary, Operation, Intro, Top
@unnumbered Radius Glossary

Throughout this document the following terms are used:

@table @asis

@item RADIUS
(All capitals) The Remote Authentication in Dial-In User Service
protocol as described in RFC 2138, 2865 and 2866.

@cindex NAS
@cindex Network Access Server
@item NAS
NAS stands for Network Access Server. It is a computer or a special device
designed to provide access to the network. For example, it can be a
computer connected to the network and equipped with several modems. Such
NAS would allow the user connecting to one of its modems to access the
network. 

@cindex Service
@item Service
A service, such as PPP, SLIP, telnet, etc., provided to a user by the NAS.

@cindex Session
@item Session
Every single instance of a service. Session starts when the service was
first provided and ends when the service is ended. A user may have multiple
sessions active simultaneously if he is allowed to.

@cindex Session ID
@item Session ID
Session Identifier. A string of characters uniquely identifying the session.

@cindex A/V pair
@cindex Attribute
@cindex Attribute-Value pair
@item A/V pair
Stands for Attribute-Value pair @ref{Attributes}. 

@cindex Dial-In user
@cindex Dial-Up user
@item Dial-In or Dial-Up user
A user connecting to a service through the modem line.

@item User Database
A database in which Radius server keeps information about users, their
authentication information, etc.

@item User's Profile
A record in the User Database describing a particular user. User's
Profile keeps the authentication and authorization information for
that user, i.e. it contains data describing how this user should
be authenticated as well as which services he is allowed to be
provided and parameters of these services.

@end table

@comment *******************************************************************
@node Operation, Naming conventions, Glossary, Top
@chapter  How Radius operates.
@cindex NAS
@cindex Network Access Server

The main purpose of Radius is to centralize authentication of users coming
from various network stations. It's primary usage is for dial-in users,
though it can be used to authenticate any kind of connection.

Radius uses the Client/Server model. The main server keeps the centralized
user database. Each user's profile in this database determines which services
are allowed for this particular user.

The Network Access Server (NAS in short) is a machine that actually provides
a service for the user. It can do so, e.g. by running a pool of modems the
users can connect to. Otherwise, it can be a machine connected to the network
and allowing some form of remote access, like telnet or ssh. It can even be
a workstation allowing console logins to it. Whichever service it provides
the NAS sends the request to the central Radius server in order to determine
whether the user trying to access the service is allowed to do so. Such
request carries information about user's login name, password, NAS
identifier (such as its IP address), etc.

On receiving such request Radius server consults its user database on
whether the user should be allowed access. If so, the server responds with
the parameters of the service, such as connection speed, framed IP address,
etc. If the user is not allowed to access the service, the server sends
back the negative response.

If the server needs some additional information in order to process the
request, it asks such information from the NAS. Thus, for example, if
the user is allowed to use several services, he can be asked which one of
them he wishes to use, etc.

The Radius server can also be configured to accept accounting information.
When NAS receives the positive Radius response, it initiates the connection
and sends the accounting start request to the Radius accounting server. On
ending the connection the accounting stop request is sent. The NAS can also
notify the server about other events, such as system shutdown or startup.

@menu
* Packets::                     Radius packets.
* Attributes::                  Attributes.
* User Profile::                How the user information is stored.
* Processing the request::      How Radius processes incoming requests.
* Realms::                      Co-operation between multiple Radiuses.
@end menu

@comment *L2****************************************************************
@node Packets, Attributes, Operation, Operation
@chapter Radius packets
@cindex Packet

The term @dfn{packet} means both the authentication/accounting request
from NAS to a Radius server and the response that the server sends back
to the NAS.

Each packet contains the following fields

@table @samp

@item Code
The code field identifies the type of the request. 

@item Identifier
The number in the range 0-255 used to match the request with the reply.

@item Length
The length of the packet

@item Authenticator
The 16-byte hash value used to authenticate the packet.

@item Attributes

The list of attribute/value pairs carrying actual information about the
request. 

@end table

@menu
* Authentication requests::
* Accounting requests::
@end menu

@comment **L3***************************************************************
@node Authentication requests, Accounting requests, , Packets
@chapter Authentication requests
@cindex Authentication requests
@cindex requests, authentication

A NAS sends authentication requests (packets with code Access-Request)
to a RADIUS server when any particular user is trying to connect to that
NAS. Such requests convey information used to determine whether a user
is allowed access to the NAS, and any special services requested for
that user.

An Access-Request must contain a @code{User-Name} attribute
@ref{User-Name}. It should contain either a @code{NAS-IP-Address}
attribute or @code{NAS-Identifier} attribute, or both of them.
It also must contain either a @code{Password} attribute or @code{CHAP-Password}
attribute. These attributes are passed encoded using a method based
on the RSA Message Digest Algorithm MD5.

The Access-Request should contain a @code{NAS-Port} or @code{NAS-Port-Type}
attribute or both unless the type of access being requested does
not involve a port or the NAS does not distinguish among its
ports.

Upon receiving Access-Request packet for a particular user and
authenticating that user, Radius server replies to the NAS that
has sent the packet with either of the following packets:

@itemize @bullet
@item Access-Accept
@item Access-Reject
@item Access-Challenge
@end itemize

Radius replies with Access-Accept packet when it has successfully
authenticated the user. Such reply packet provides specific
configuration information necessary to begin delivery of service to
the user.

Radius replies with Access-Reject packet when it was unable to
authenticate the user. Such packet may contain a descriptive
text encapsulated in one or more @code{Reply-Message} attributes.
The NAS may display this text along with its response to the
user.

Radius replies with Access-Challenge packet when it desires to
obtain more information from the user in order to determine its
authenticity or to determine the kind of service to be provided
to the user.

An Access-Challenge packet may include one or more @code{Reply-Message}
attributes, and may also include a single @code{State} attribute, or
none. No other Attributes are permitted in an Access-Challenge.

On receipt of an Access-Challenge, the Identifier field is matched
with a pending Access-Request.  Additionally, the Response Authenticator
field must contain the correct response for the  pending Access-Request.
Radius discards invalid packets and issues appropriate log message.

If the NAS does not support challenge/response, it treats an
Access-Challenge as though it had received an Access-Reject instead.
Otherwise, upon receipt of a valid Access-Challenge the NAS prompts the
user for a response, possibly displaying the text message provided in
@code{Reply-Message} attributes of the request. It then sends its
original Access-Request with a new request ID and Request Authenticator,
with the @code{Password} attribute replaced by the encrypted user's
response, and including the @code{State} attribute from the
Access-Challenge, if any. 

@comment **L3***************************************************************
@node Accounting requests, , Authentication requests, Packets
@chapter Accounting requests
@cindex Accounting requests
@cindex requests, accounting

Accounting-Request packets are sent from a NAS to a Radius server
to allow for accounting of a service provided to a user.

Upon receipt of an Accounting-Request, the server attempts to record
the accounting packet @ref{Accounting}, and if it succeeds in doing
so it replies with an Accounting-Response packet. Otherwise it sends
no reply, which then causes the NAS to retransmit its request within
a preconfigured interval of time. Such retransmits will continue until
either the server responds with an Accounting-Response packet or a
preconfigured number of retransmits is reached, whichever occurs first.

Any attribute valid in an Access-Request or Access-Accept packet
is also valid in an Accounting-Request packet, except the following
attributes, which are never present in an Accounting-Request packet:

@itemize @bullet
@item User-Password
@item CHAP-Password
@item Reply-Message
@item State
@end itemize

Either @code{NAS-IP-Address} or @code{NAS-Identifier} must be present in an
Accounting-Request.  It should contain a @code{NAS-Port} or
@code{NAS-Port-Type} attribute or both unless the service does not involve a
port or the NAS does not distinguish among its ports.

If the Accounting-Request packet includes a Framed-IP-Address,
that attribute MUST contain the actual IP address of the user.


@comment *L2****************************************************************
@node Attributes, User Profile, Packets, Operation
@chapter Attributes
@cindex Attribute
@cindex Attribute-Value pair
@cindex A/V pair

The information in the Radius packets is stored as a list of
@dfn{Attribute-Value pairs}. Each such pair consists of an
@dfn{Attribute number} and @dfn{Attribute value}. The @dfn{Attribute number}
identifies the type of information the pair carries and the
@dfn{Attribute Value} keeps the actual data.

The attribute value can be of either of the following types:

@itemize @bullet
@item Integer
@item IP-number
@item String
@end itemize

For convenience, the attributes and the values of some frequently used
integer attributes are also given names. For example, attribute 6 is
called @dfn{Service-Type}. Its values are: 

@itemize @bullet
@item 1         Login-User                
@item 2         Framed-User               
@item 3         Callback-Login-User       
@item 4         Callback-Framed-User      
@item 5         Outbound-User             
@item 6         Administrative-User       
@end itemize

The symbolic names are assigned to attributes and values in the dictionary
file @ref{dictionary,,dictionary file}.

The attribute numbers range from 1 to 255. The attributes with the numbers
greater than 255 are used internally by the sever and cannot be sent to
the NAS.

The special attribute 26 @dfn{Vendor-Specific} is available to allow
vendors of the NAS hardware or software to support their own extended
attributes. @ref{Vendor-Specific,, Vendor-Specific attribute}.

@ref{Attribute list}.


@comment *L2****************************************************************
@node User Profile, Processing the request, Attributes, Operation
@chapter User Profile

The user profile information is stored in the files @file{users},
@file{hints} and @file{huntgroups} in the radius database directory
(raddb, @ref{Naming conventions}. These files follow the same syntax.

@subheading Comments
A pound sign (@samp{#}) causes the rest of line to be ignored.

@subheading File inclusion
A statement in the form

@example
$INCLUDE filename
@end example

causes the contents of the file named @samp{filename} to be included.

@subheading Records
A file consists of records. Each record takes the form:

@example
NAME    CHECK-PAIRS     REPLY-PAIRS
@end example

The parts of a record are separated by any amount of whitespace.
The parts are:

@table @var

@item NAME
The username consists of up to 32 alphanumeric characters,
underscores (@samp{_}), dashes (@samp{-}) or dots (@samp{.}).
The special username @samp{DEFAULT} or @samp{DEFAULT%d}, where
%d stands for a decimal number, is used to indicate the default entry,
i.e. the entry that is used if no other entry is matched. Such entries
are processed in the order they appear in the file.

@item CHECK-PAIRS
A @dfn{list} of check-pairs, i.e. the A/V pairs that should be present
in the request in order for entry to be matched.

@item REPLY-PAIRS
A @dfn{list} of reply-pairs, i.e. the A/V pairs that the server replies
with if the entry is matched.

@end table

A term @dfn{list} used above means the comma-separated list of A/V
pairs  @xref{Attributes} or the word @code{NULL} to specify the empty
list. Each pair in the list follows the syntax:

@example
ATTRIBUTE-NAME  OP      VALUE
@end example

@noindent
where
@table @var
@item ATTRIBUTE-NAME
is a name of attribute as specified in the dictionary file @ref{dictionary,,Dictionary file}.

@item OP
is one of the following operation codes:

@itemize @bullet
@item @samp{=}
@item @samp{!=}
@item @samp{<}
@item @samp{<=}
@item @samp{>}
@item @samp{>=}
@end itemize

@item VALUE
Specifies the attribute value. The value syntax is:

@table @var

@item INTEGER
The decimal integer number

@item IP-ADDRESS
Either the dotted-quad notation or a decimal integer.

@item STRING
A string of characters enclosed in double-quotes (@samp{"}).

@item DATE
A date in the format: "MON DD CCYY", where MON is the usual three-character
abbreviation, DD is day of month (1-31), CCYY is the year, including the
century.

@end table

@end table

@menu
* Matching rules::      How the record is matched.
@end menu

@comment **L3***************************************************************
@node Matching rules, , User Profile, User Profile
@chapter Packet Matching Rules
@cindex Packet matching rules

When Radius is attempting to find the record in its database that
matches given request packet @ref{Packets}, it uses the following rules:

@table @asis

@item 1. Match the username
If the username from the packet does not match the one in the record,
the record does not match. @emph{Please note} that the special usernames
@code{DEFAULT} or @code{DEFAULT%d} (%d means any decimal number) match
any username.

@item 2. Determine the authentication type and verify the user's authentity. 

@item 3. Compaire check-pair list with pairlist from the request
While compairing any internal A/V pairs contained in check-pairs
are ignored. 

The internal A/V pairs are those with the attribute number greater than 255,
which server uses for its own purposes, such as @code{Auth-Type},
@code{Simultaneous-Logins}, etc.

The order of attributes in both list does not matter when comparing.

The comparison procedure can roughly be described as follows:

For each pair from the check-pairs find a pair in the request packet
having the same attribute. If no such pair is found, the comparison
fails. Otherwise, compare the values from both attributes as if the
the request pair value were at the left side from the comparison
operator of the check pair.

This may seem a bit complicated. Lets consider an example. Suppose the
check pair is:

@example
NAS-Port-Id <= 20
@end example

and the request pair is:

@example
NAS-Port-Id = 10
@end example

Then Radius will perform the following comparison:

@example
10 <= 20
@end example

which will, of course, succeed.

@item 4. If match fails try to match next record.

@item 5. Otherwise stop and return the reply pairs from the record.

@end table

@comment *L2****************************************************************
@node Processing the request, Realms, User Profile, Operation

@chapter Processing the request
@cindex Request processing
@cindex Processing the request

Upon receiving the request Radius applies to it a number of checks to
determine whether the request comes from the authorized source. If these
checks succeed, the request is processed and responded. Otherwise, the
request is dropped and corresponding error message is issued @ref{Logging}.

The following checks are performed:

@table @asis

@item Check if the username is supplied
If the packet lacks @code{User-Name} attribute it is not processed

@item Check if the NAS is allowed to speak
The source IP address of the machine that sent the packet is looked
up in the @file{clients} file @ref{clients}. If no match is found,
the request is not processed. 

@item Compute the encryption key
Using the data from the packet and the shared key value from the @file{clients}
file, Radius computes the MD5 encryption key that will be used to decrypt
the value of the @code{Password} attribute.

@item Process @file{hints} file.
Radius matches the packet against the contents of @file{hints} file
using the following rules:

Rule 1. Match the username
If the username from the packet does not match the one in the record,
the record does not match. @emph{Please note} that the special usernames
@code{DEFAULT} or @code{DEFAULT%d} (%d means any decimal number) match
any username.

Rule 2. Modify the attributes.

If the reply-pairs contain @code{Strip-User-Name} attribute and its
value is @code{Yes} (1), then any prefixes/suffixes are stripped off
the value of @code{User-Name} attribute.

If the reply-pairs contain the @code{Rewrite-Function} attribute, the
function specified in the value of this attribute is applied @ref{rewrite}.

If the reply pairs contain @code{Fall-Through} attribute and its value is
@code{Yes} (1) then Radius switches to the next record and goes back to
the rule 1. Otherwise the matching process stops and returns the reply pairs
from the record.

@xref{hints}

@end table

@comment *L2****************************************************************
@node Realms, , Processing the request, Operation
@chapter Realms
@cindex Realms

We call a @dfn{realm} a community of users served by a single Radius
server. Several such servers can co-operate with each other thus allowing
users from a particular @dfn{realm} to be authorized using another
@dfn{realm}'s server.

Let's illustrate this concept. Suppose an ISP has its affiliates in two
different cities, and each of these affiliates is using its own Radius
server. Let's call the affiliates @dfn{A} and @dfn{B} and let's call
the corresponding servers @dfn{radius.a} and @dfn{radius.b}. If the
user of affiliate @dfn{A} moves to city @dfn{B} he is no longer able
to use the service provided by @dfn{radius.a}, neither is he able to
use the service provided by @dfn{radius.b} because he is not in the
users database of the latter. To solve this situation, both Radius
servers should be able to share their database information with each
other. This is done by a very simple means: if user @samp{foo}
connects to the equipment of the @dfn{B} and authenticates itself as
@samp{foo@@A} then Radius server @dfn{radius.b} knows that the
user belongs to another realm and passes the request to server
@dfn{radius.a}. When the latter responds, server @dfn{radius.a} 
simply passes the response back to NAS. In other words @dfn{radius.a}
server acts as a proxy between the NAS to which the user is trying
to connect and the Radius server which is responsible for authenticating
the user.

@comment *******************************************************************
@node Naming conventions, Invocation, Operation, Top
@chapter Naming conventions.
@cindex naming conventions

This chapter describes file naming conventions used throughout this
document.

Programs from the GNU Radius package use the following directories
to store various configuration and log files:

@table @dfn
@item Configuration or database directory
A directory where all configuration files are stored.

@item Log directory
A directory where @code{radiusd} stores its radius files.

@item Accounting directory
A directory where @code{radiusd} stores accounting detail files
@ref{Detailed Request Accounting}.

@end table

The default locations of these directories are determined at compile
time. These are:

@include config.texi
@multitable @columnfractions .40 .15 .45
@item Directory @tab Short Name @tab Default location 

@item Configuration directory
@cindex Configuration directory
@cindex @file{raddb}
@tab raddb
@tab @value{RADDB}

@item Log directory
@cindex Log directory
@cindex @file{radlog}
@tab raddb
@tab @value{RADLOG}

@item Accounting directory
@cindex Accounting directory
@cindex radacct
@tab radacct
@tab @value{RADACCT}

@end multitable

Throughout this document we will refer to these directories by their
short names, e.g. saying

@example
... this information is contained in file @file{raddb/sqlserver} 
@end example

@noindent
we actually mean @file{@value{RADDB}/sqlserver}.

If necessary, locations of these directories can be overidden by
specifying appropriate command line options to a program. For
example, any program from the GNU Radius package accepts command
line option @code{-d} or @code{--directory}, which introduces
the configuration directory path. 


@comment *******************************************************************
@node Invocation, Configuration files, Naming conventions, Top
@chapter How to start the daemon.
@cindex Radius daemon invocation
@cindex Invoking the radius daemon
@pindex radiusd

When started @code{radiusd} uses the configuration values from the following
sources (in order of increasing precedence):

@itemize @bullet
@item Compiled-in defaults
@item @file{raddb/config} file.
@item Command line arguments
@end itemize

The following command line options are accepted:

@table @samp

@c ** -A option (radiusd)
@c ** --log-auth-detail (radiusd)
@item -A
@itemx --log-auth-detail
Enable detailed authentication logging. When this option is specified
each authentication request is logged to the file
@file{radacct/NASNAME/detail.auth}, where NASNAME is replaced by the
short name of the NAS from @file{raddb/naslist}
@ref{Naming conventions}.

@c ** -a option (radiusd)
@c ** --acct-directory (radiusd)
@item -a DIR
@itemx --acct-directory DIR
Specify accounting directory.

@c ** -c option (radiusd)
@c ** --check-config (radiusd)
@item -c
@itemx --check-config
Check configuration files and exit. All errors are reported via usual
log channels.

@c ** -b option (radiusd)
@c ** --dbm option (radiusd)
@item -b
@itemx --dbm
Enable DBM support. When used twice, allows to use both
@file{raddb/users} file and DBM database.

@c ** -d (radiusd)
@c ** --config-directory option (radiusd)
@item -d DIR
@itemx --config-directory DIR
Specify alternate configuration directory. Default is @file{@value{RADDB}}.

@c ** -f option (radiusd)
@c ** --foreground option (radiusd)
@item -f
@itemx --foreground
Stay in foreground. We recommend to use it for debugging purposes only.

@c ** -l option (radiusd)
@c ** --logging-directory option (radiusd)
@item -l DIR
@itemx --logging-directory DIR
Specify alternate logging directory. 

@c ** -n option (radiusd)
@c ** --auth-only option (radiusd)
@item -n
@itemx --auth-only
Process only authentication requests.

@c ** -p option (radiusd)
@c ** --port option (radiusd)
@item -p PORTNO
@itemx --port PORTNO
Listen the udp port PORTNO. The accounting port is computed as @var{PORTNO} + 1.

@c ** -S option (radiusd)
@c ** --log-stripped-names option (radiusd)
@item -S
@itemx --log-stripped-names
Log usernames stripped off any prefixes/suffixes.

@c ** -s option (radiusd)
@c ** --single-process option (radiusd)
@item -s
@itemx --single-process
Run in single process mode. This is for debugging purposes only. We strongly
recommend @emph{against} using this option. Use it only when absolutely
necessary.

@c ** -v option (radiusd)
@c ** --version option (radiusd)
@item -v
@itemx --version
Display program version and exit

@c ** -x option (radiusd)
@c ** --debug option (radiusd)
@item -x DEBUG_LEVEL
@itemx --debug DEBUG_LEVEL
Set debugging level. @var{DEBUG_LEVEL} is a comma-separated list of
assignments in the forms

@example
MODULE
MODULE = LEVEL
@end example

where @var{MODULE} is the module name or any non-ambiguous assignment
thereof, LEVEL is the debugging level in the range 0-100. @ref{Debugging}

@c ** -y option (radiusd)
@c ** --log-auth option (radiusd)
@item -y
@itemx --log-auth
Log authentications. With this option enabled, Radius will log any
authentication attempt into its logfile @ref{Logging}.

@item -z
@itemx --log-auth-pass
Log passwords along with authentication information. @emph{Do not use} this
option. It is @emph{very} unsecure, since all users' passwords will be
echoed in the logfile. This option is provided only for debugging purposes.

@end table


@comment *******************************************************************
@node Configuration files, Authentication, Invocation, Top
@chapter Radius configuration files
@cindex radiusd configuration files

This chapter describes the configuration files used by GNU Radius
package.

These files 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} @ref{Naming conventions}.

@menu
* config::              Run-time configuration options.
* dictionary::          Radius dictionary.
* clients::             Clients lists the NASes that are allowed to
                        communicate with radius.
* naslist::             The naslist file keeps general information about
                        the NASes.
* hints::               Important user information that is common for the
                        users whose names match some pattern.
* huntgroups::          Group users by the NAS (and, possibly, a port
                        number) they come from.
* realms::              Communication with remote radius servers
* users::               User profile.
* access.deny::         List of users which are denied access.
* sqlserver::           SQL server configuration.
* rewrite::             Rewrite functions allow to change the input
                        packets.
* menus::               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, dictionary, , Configuration files
@chapter  Run-time configuration options.
@cindex radiusd options
@cindex radiusd configuration
@cindex @file{raddb/config} file

@code{radiusd} uses the configuration values from the following
sources (in order of increasing precedence):

@enumerate 1
@item Compiled-in defaults
@item @file{raddb/config} file.
@item Command line arguments
@end enumerate

This order of precedence applies only on startup. When re-reading of
the configuration is initiated either by @var{SIGHUP} signal or by
a control channel @xref{Radctl} 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 radiusd configuration consists of statements and comments.
Statements end with a semicolon. Many statements contain a block
of substatements 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:

@example
# A shell comment
/* A C-style
 * multiline comment
 */
// A C++-style comment
@end example

These are the basic statements:
@menu
* option::      The @code{option} block sets the global program options.
* logging::     Fine-tune the logging.
* auth::        Configure authentication service.
* acct::        Configure accounting service.
* proxy::       Configure proxy service.
* notify::      Configure ttl service.
* usedbm::      Enable the DBM feature.
* snmp::        Configure SNMP service.
@end menu

@comment **L3***************************************************************
@node option, logging, , config
@chapter The @code{option} statement
@cindex option (raddb/config file)

@subheading Syntax:

@example
options @{
        [ usr2delay @var{number} ; ]
        [ max-requests @var{number} ; ]
        [ exec-program-user @var{string} ; ]
        [ exec-program-group @var{string} ; ]
@} ;
@end example

@subheading Usage

The options statement defines the global options to be used by @code{radiusd}.

@subheading Numeric statements

@table @code

@item usr2delay
Sets the delay time in seconds between receiving the @code{SIGUSR2} signal
and re-reading configuration.

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

@end table

@subheading String statements
@table @code
@item exec-program-user 
Sets effective user id for the programs executed as a result of
@code{Exec-Program} and @code{Exec-Program-Wait} to that of the
given username.

@item exec-program-group
Sets effective group id for the programs executed as a result of
@code{Exec-Program} and @code{Exec-Program-Wait} to that of the
given groupname.

@end table

@comment **L3***************************************************************
@node logging, auth, option, config
@chapter @code{logging} statement
@cindex logging statement (raddb/config file)

@subheading Syntax:

@example
logging @{
        [ channel channel_name @{
               (  file @var{string} ;
                | syslog facility . priority ; )
               [ option (pid, cons, level) ; ]
        @}; ]
        [ category category_name @{
                [ channel channel_name ; ]
                [ level level_list ; ]
        @} ; ]
@} ;

@end example

@comment **L3***************************************************************
@node auth, acct, logging, config
@chapter @code{auth} statement
@cindex auth statement (raddb/config)

@subheading Syntax:

@example
auth @{
        [ port @var{number} ; ]
        [ spawn @var{bool} ; ]
        [ max-requests @var{number} ; ]
        [ time-to-live @var{number} ; ]
        [ request-cleanup-delay @var{number} ; ]
        [ detail @var{bool} ; ]
        [ strip-names @var{bool} ; ]
        [ checkrad-assume-logged @var{bool} ; ]
@} ;
@end example

@subheading Usage:
The @code{auth} statement configures the parameter of the authentication
service.

@subheading Numeric statements

@table @code
@item port
Sets the port number to listen for the authentication requests.

@item max-requests
Sets the maximum number of authentication requests in the queue. Any
surplus requests will be discarded.

@item 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.

@item request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will
the completed authentication request reside in the queue.

@end table

@subheading Boolean statements

@table @code
@item spawn
Determines if @code{radiusd} should spawn a child to process the request.

@item detail
When set to true, @code{radiusd} will produce the detailed log of each
received packet in the file @file{radacct/NASNAME/detail.auth}
@ref{Naming conventions}.

@item strip-names
Determines whether @code{radiusd} should strip any prefixes/suffixes
off the username before logging.

@item checkrad-assume-logged
@code{radiusd} consults the value of this variable when @code{checkrad}
program returns ``don't know'' answer for a particular user
@ref{Checkrad Overview}.
If this variable is set to @code{yes}, the daemon will proceed as if
@code{checkrad} returned ``yes'', i.e. it will assume the user is logged in.
Otherwise @code{radiusd} assumes the user @emph{is} logged in.

@end table

@comment **L3***************************************************************
@node acct, proxy, auth, config
@chapter @code{acct} statement
@cindex acct statement (raddb/config)

@subheading Syntax:
@example
acct @{
        [ port @var{number} ; ]
        [ spawn @var{bool} ; ]
        [ max-requests @var{number} ; ]
        [ time-to-live @var{number} ; ]
        [ request-cleanup-delay @var{number} ; ]
@} ;
@end example

@subheading Usage:

The @code{acct} statement configures the parameters of the accounting
service.

@subheading Numeric statements

@table @code
@item port 
Sets the port number to listen for the authentication requests.

@item max-requests 
Sets the maximum number of accounting requests in the queue. Any
surplus requests will be discarded.

@item 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.

@item request-cleanup-delay 
Sets the request cleanup delay in seconds, i.e. determines how long will
the completed account request reside in the queue.

@end table

@subheading Boolean statements

@table @code
@item spawn 
Determines if @code{radiusd} should spawn a child to process the request.

@end table

@comment **L3***************************************************************
@node proxy, notify, acct, config
@chapter @code{proxy} statement
@cindex proxy statement (raddb/config)

@subheading Syntax:
@example
proxy @{
        [ max-requests @var{number} ; ]
        [ request-cleanup-delay @var{number} ; ]
@} ;
@end example

@subheading Usage:
The @code{proxy} statement configures the parameters of the proxy service.

@subheading Numeric statements

@table @code
@item max-requests
Sets the maximum number of accounting requests in the queue. Any
surplus requests will be discarded.

@item request-cleanup-delay
Sets the request cleanup delay in seconds, i.e. determines how long will
the completed account request reside in the queue.

@end table

@comment **L3***************************************************************
@node notify, usedbm, proxy, config
@chapter @code{notify} statement (raddb/config)
@cindex notify statement (raddb/config)

@subheading Syntax:
@example
notify @{
        [ host @var{ipaddr} ; ]
        [ port @var{portno} ; ]
        [ retry @var{number} ; ]
        [ delay @var{number} ; ]
@} ;

notify off ;
@end example

@subheading Usage
The @code{notify} statement configures the TTL notification service.

@subheading Disabling the service
The @code{notify off;} form of the statement disables the service.

@subheading Numeric statements

@table @code
@item port
Specify the port number to send the TTL notifications to.

@item retry
Specifies how many time @code{radiusd} should try to resend notifications
if the remote party doesn't respond.

@item delay
Specifies the delay in seconds between each two successive resends.

@end table

@subheading IP-Number statements

@table @code
@item host
Sets the hostname or IP address of the notification listener.

@end table

@comment **L3***************************************************************
@node usedbm, snmp, notify, config
@chapter @code{usedbm} statement
@cindex usedbm statement (raddb/config)

@subheading Syntax:
@example
usedbm ( never | only | also ) ;
@end example

@subheading Usage
The @code{usedbm} statement determines whether the DBM support should
be enabled.

@table @code
@item never
Do not use DBM support at all.

@item only
Use only the DBM database and ignore @file{raddb/users}.

@item also
Use both @file{raddb/users} and DBM.
@end table

@comment **L3***************************************************************
@node snmp, , usedbm, config
@chapter @code{snmp} statement (raddb/config)
@cindex snmp statement (raddb/config)

@subheading Syntax:
@example
snmp @{
        [ port @var{portno} ; ]
        [ spawn @var{bool} ; ]
        [ max-requests @var{number} ; ]
        [ time-to-live @var{number} ; ]
        [ request-cleanup-delay @var{number} ; ]
        [ ident @var{string} ; ]
        [ community @var{name} ( rw | ro ) ; ]
        [ network @var{name} @var{network} [ @var{network} ... ] ; ]
        [ acl @{
                [ allow @var{network_name} @var{community_name} ; ]
                [ deny @var{network_name} ; ]
        @} ; ]
@};
@end example

@subheading Usage
The @code{snmp} statement configures the SNMP service.

@subheading Numeric statements

@table @code
@item port
Sets the port number to listen for the SNMP requests.

@item max-requests
Sets the maximum number of SNMP requests in the queue. Any
surplus requests will be discarded.

@item 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.

@item request-cleanup-delay 
Sets the request cleanup delay in seconds, i.e. determines how long will
the completed SNMP request reside in the queue.

@end table

@subheading Boolean statements

@table @code
@item spawn
Determines if @code{radiusd} should spawn a child to process the SNMP
request.

@end table

@subheading String statements

@table @code
@item ident
Sets the SNMP server identification string.
@end table

@subheading Community and network definitions

@table @code
@item community @var{name} ( rw | ro )
Defines the community @var{name} as read-write (@code{rw}) or read-only
(@code{ro}).

@item network @var{name} @var{network} [ @var{network} ... ]
Groups several networks or hosts under one logical network name.

@end table

@subheading Access-Control List definitions

@table @code
@item allow @var{network_name} @var{community_name}
allow hosts from the group @var{network_name} access to community
@var{community_name}.

@item deny @var{NETWORK_NAME}
Deny access to SNMP service from any host in the group @var{network_name}.
@end table

@comment *L2****************************************************************
@node dictionary, clients, config            , Configuration files
@chapter Radius dictionary.
@cindex Radius dictionary
@cindex @file{dictionary} file

The dictionary file @file{raddb/dictionary} defines the symbolic names
for radius attributes and their values @ref{Attributes}. The file consists
of a series of statements. Each statement occupies one line.

In the detailed discussion below we use the following meta-syntactic
characters:

@table @var
@item number
Denotes a decimal, octal or hexagesimal number. Usual C conventions are
honored, i.e. if @var{number} starts with @samp{0x} or @samp{0X} it is
read as a hex number, if it starts with @samp{0} it is read as an
octal one, otherwise it is read as a decimal one.

@item type
Denotes an attribute type. These are valid attribute types

@table @code
@item string
A string type. 
@item integer
An integer type.
@item ipaddr
IP address in a dotted-quad form.
@item date
A date in the format: "MON DD CCYY", where MON is the usual three-character
abbreviation, DD is day of month (1-31), CCYY is the year, including the
century.

@end table

@end table

There are 6 kinds of statements:

@menu
* Comment::             Introducing a comment line.
* $INCLUDE::            Include a file.
* VENDOR::              Define a vendor-id.
* ATTRIBUTE::           Define an attribute translation.
* ATTRIB_NMC::          Another way to define vendor-specific attributes.
* VALUE::               Define a value translation.
@end menu

@comment **L3***************************************************************
@node Comment, $INCLUDE, dictionary, dictionary
@chapter Comments
Comments are introduced by a pound sign (@samp{#}). Everything starting from
the first occurence of @samp{#} up to the end of line is ignored.

@comment **L3***************************************************************
@node $INCLUDE, VENDOR, Comment, dictionary
@chapter Inclusion statements
@cindex $INCLUDE statement (dictionary)

@subheading Syntax
@example
$INCLUDE @file{filename}
@end example

@subheading Usage
The @code{$INCLUDE} statement causes the contents of the file @file{filename}
to be read in and processed. The file is looked up in the Radius database
directory @ref{Configuration files}.

@comment **L3***************************************************************
@node VENDOR, ATTRIBUTE, $INCLUDE, dictionary
@chapter Define the Vendor-Id translation
@cindex VENDOR statement (dictionary)

@subheading Syntax
@example
VENDOR  Vendor-Name     @var{number}
@end example 

@subheading Usage
A @code{VENDOR} statement defines the symbolic name for a Vendor-Id.
This name can subsequently be used in @code{ATTRIBUTE} statements
to define Vendor-Specific attribute translations @ref{Vendor-Specific}.

@subheading Example
@example
VENDOR		Livingston	307
@end example

@comment **L3***************************************************************
@node ATTRIBUTE, ATTRIB_NMC, VENDOR, dictionary
@chapter ATTRIBUTE statement
@cindex ATTRIBUTE statement (dictionary)
@subheading Syntax
@example
ATTRIBUTE       Attribute-Name          @var{number}  @var{type}
ATTRIBUTE       Attribute-Name          @var{number}  @var{type}    Vendor-Name
@end example

@subheading Usage
The @code{ATTRIBUTE} statement defines the translation for an attribute.
The second form of defines the vendor-specific attribute @xref{Vendor-Specific}.

@subheading Example

The following assigns the translation string @samp{Service-Type} to the
attribute number 6:

@example
ATTRIBUTE	Service-Type		6	integer
@end example

The following defines a vendor-specific attribute for vendor-id
@samp{Livingston}, defined in the previous chapter:

@example
ATTRIBUTE	LE-Terminate-Detail	2	string	Livingston
@end example

@comment **L3***************************************************************
@node ATTRIB_NMC, VALUE, ATTRIBUTE, dictionary
@chapter ATTRIB_NMC statement
@cindex ATTRIB_NMC statement (dictionary)
@subheading Syntax
@example
ATTRIB_NMC      Attribute-Name          @var{number}  @var{type}
@end example

@subheading Usage
This statement defines the translation for a USR vendor-specific attribute
(vendor PEC 429). The @code{ATTRIB_NMC} statement is provided for compatibility
with existing dictionaries.

@comment **L3***************************************************************
@node VALUE, , ATTRIB_NMC, dictionary
@cindex VALUE statement (dictionary)
@chapter ATTRIB_NMC statement

@subheading Syntax
@example
VALUE   Attribute-Translation       Value-Translation       @var{number}
@end example

@subheading Usage
The @code{VALUE} statement assigns a translation string to a given
value of an integer attribute. @code{Attribute-Translation} specifies
the attribute and the @code{Value-Translation} specifies the name
assigned to the value @var{number} of this attribute.

@subheading Example

The following assigns the translation string @samp{Login-User} to
the value 1 of the attribute @samp{Service-Type}.

@example
VALUE		Service-Type		Login-User		1
@end example

@comment *L2****************************************************************
@node clients, naslist, dictionary, Configuration files
@chapter clients list
@cindex @file{clients} file
@cindex @file{raddb/clients} file

The @file{raddb/clients} lists NASes which are allowed to make
authentication requests. As usual, the @samp{#} character introduces a
comment. Each record in the file consists of two fields, separated
by whitespace. The fields are:

@table @asis
@item NAS name
Specifies a hostname or IP address of the NAS.
@item Key
Lists the encryption key shared between the server and this NAS.
@end table

@menu
* Example: clients example.     An example of the clients file.
@end menu

@comment **L3***************************************************************
@node clients example, , clients, clients
@chapter An example of the clients file
@cindex @file{clients} file, an example

@example
# This is a list of clients which are allowed to make authentication 
# requests.
# Each record consists of two fields:
#	i.  Valid hostname.
#	ii. The shared encryption key for this hostname. 
#
#Client Name		Key
#----------------	-------------------
myhost.dom.ain          guessme         
merlin                  emrys           
11.10.10.10             secRet
@end example

@comment *L2****************************************************************
@node  naslist, hints, clients ,Configuration files
@chapter naslist
@cindex @file{naslist} file
@cindex @file{raddb/naslist} file

The @file{raddb/naslist} file contains a list of NASes known to the Radius
server. Each record in the file consist of three fields:

@table @asis
@item NAS name
Specifies a hostname or IP address of the NAS.
@item Short Name
This field defines a short name under which this NAS will be listed
in logfiles. The short name is also used as a name of the subdirectory
where the detailed logs are stored.
@item Type
Specifies the type of this NAS. Using this value @code{radiusd} determines
the way to query NAS about the presence of a given user on it
@ref{Checkrad Overview}, @ref{Checking Simultaneous Logins}.
This type should be listed in a @code{type} statement somewhere in
@file{checkrad.conf} file @ref{checkrad.conf}.
@end table

@menu
* Example: naslist example.     Example of @file{naslist} file.
@end menu

@comment **L3***************************************************************
@node naslist example, , naslist, naslist
@chapter Example of @file{naslist} file
@cindex @file{naslist} file, an example

@example
# @value{RADDB}/naslist: contains a list of Network Access Servers 
#
# Each record consists of following fields:
#
# 	i. 	A valid hostname or IP address for the client.
#	ii. 	The short name to use in the logfiles for this NAS.
#	iii.	Type of device. Valid values are those listed in 
#		@value{RADDB}/checkrad.conf file.

# NAS Name              Short Name      Type
#----------------       ----------      ----
myhost.dom.ain          myhost          unix
merlin                  merlin          max 
11.10.10.10             arthur          livingston
@end example


@comment *L2****************************************************************
@node hints, huntgroups, naslist, Configuration files
@chapter The @file{hints} configuration file.
@cindex Hints
@cindex @file{hints} file
@cindex @file{raddb/hints} file

The @file{raddb/hints} file is used to modify the contents of the incoming
request depending on the username.

The file contains data in @dfn{User Profile} format @ref{User Profile}. 

On receiving the incoming packet, Radius attempts to find a matching
record in the @file{hints} file using the procedure described below.
If the matching record is found, then the reply-pairs from this record are
appended to the end of the request's pairlist. Thus, these pairs will
further be used just as if NAS has sent them alog with the request.

@comment @xref{Examples of request processing:reqproc}

@menu
* Matching: hints matching.     The matching rules.
* Example: hints example.       An example of @file{hints} file.
@end menu

@comment **L3***************************************************************
@node hints matching, hints example, hints, hints
@chapter The hints matching rules
@cindex Hints
@cindex @file{hints}, matching rules
@cindex Matching rules for @file{hints}

Radius matches the packet against the contents of @file{hints} file
using the following rules:

@table @asis
@item Rule 1. Match the username
If the username from the packet does not match the one in the record,
the record does not match. @emph{Please note} that the special usernames
@code{DEFAULT} or @code{DEFAULT%d} (%d means any decimal number) match
any username.

@item Rule 2. Modify the attributes.

If the reply-pairs contain @code{Strip-User-Name} attribute and its
value is @code{Yes} (1), then any prefixes/suffixes are stripped off
the value of @code{User-Name} attribute.

If the reply-pairs contain the @code{Rewrite-Function} attribute, the
function specified in the value of this attribute is applied @ref{rewrite}.

If the reply pairs contain @code{Fall-Through} attribute and its value is
@code{Yes} (1) then Radius switches to the next record and goes back to
the rule 1. Otherwise the matching process stops and returns the record
found.

@end table

@comment **L3***************************************************************
@node hints example, , hints matching, hints
@chapter An example of @file{hints} file
@cindex @file{hints} file, an example

@example
## If the username starts with `U', append the UUCP hint 
DEFAULT         Prefix = "U", Strip-User-Name = No      Hint = "UUCP"
## If the username ends with `.slip', append the SLIP service data
DEFAULT         Suffix = ".slip", Strip-User-Name = Yes
                Hint = "SLIP",
                   Service-Type = Framed-User,
                   Framed-Protocol = SLIP
@end example

@comment *L2****************************************************************
@node huntgroups, realms, hints, Configuration files
@chapter The @file{huntgroups} file
@cindex Huntgroups
@cindex @file{huntgroups} file
@cindex @file{raddb/huntgroups} file

The @file{raddb/huntgroups} file segregates the incoming requests by
the contents of the request pairlist.

The file contains data in @dfn{User Profile} format @ref{User Profile}. 

@menu
* Matching: huntgroups matching.       The matching rules.
* Example: huntgroups example.         An example of the @file{huntgroups} file.
@end menu

@comment **L3***************************************************************
@node huntgroups matching, huntgroups example, huntgroups, huntgroups
@chapter The huntgroup matching
@cindex @file{huntgroups}, matching rules
@cindex Matching rules for @file{huntgroups}

Radius matches the packet against the contents of @file{hints} file
using the following rules:

@table @asis

@item 1. Compare the @dfn{Effective checklist} with the request pairlist.

For each pair from the @dfn{Effective checklist} find a pair with the
same attribute from the request pairlist. If no such pair is found, the
comparison fails. Otherwise, compare the values from both attributes as
if the value from the supplied list were at the left side from the
comparison operator of the Effective checklist pair.

This may seem a bit complicated. Lets consider an example. Suppose the
check pair is:

@example
NAS-Port-Id <= 20
@end example

and the supplied pair is:

@example
NAS-Port-Id = 10
@end example

Then Radius will perform the following comparison:

@example
10 <= 20
@end example

which will, of course, succeed.

@item 2. Record matches
If the reply-pairs contain @code{Strip-User-Name} attribute and its
value is @code{Yes} (1), then any prefixes/suffixes are stripped off
the value of @code{User-Name} attribute.

If the reply-pairs contain the @code{Rewrite-Function} attribute, the
function specified in the value of this attribute is applied @ref{rewrite}.

If the reply pairs contain @code{Fall-Through} attribute and its value is
@code{Yes} (1) then Radius switches to the next record and goes back to
the rule 1. Otherwise the matching process stops and returns the reply pairs
from the record.
@end table

@comment **L3***************************************************************
@node huntgroups example, , huntgroups matching, huntgroups
@chapter An example of @file{huntgroups} file.
@cindex @file{huntgroups}, an example

@example
## The following lines define administrative user huntgroup and the commands
## it can use:
ROOT    NAS-IP-Address = 127.0.0.1, State = "getpid"            NULL
ROOT    NAS-IP-Address = 127.0.0.1, State = "get-m-stat"        NULL
ROOT	NAS-IP-Address = 127.0.0.1, State = "get-q-stat"        NULL

## This defines the packet rewriting function for the server 11.10.10.11
DEFAULT NAS-IP-Address = 11.10.10.11, Rewrite-Function = "max_fixup"
        NULL

@end example

@comment *L2****************************************************************
@node realms, users, huntgroups, Configuration files
@chapter The @file{realms} file
@cindex @file{realms} file
@cindex @file{raddb/realms} file

The @file{raddb/realms} file lists remote Radius servers that are allowed to
communicate with the local Radius server @ref{Realms}.

Each record consists of up to three fields, separated by whitespace.
Two of them are mandatory. The fields are:

@table @asis
@item Realm name
Specifies the name of the realm being defined, i.e. part of the login
name after the @samp{@@} symbol.

@item Remote server
Specifies the remote server to which the requests for this realm should
be forwarded. A port number can also be specified using syntax
@var{hostname}:@var{port}. In this case the accounting port is computed as
@var{port} + 1.

@item Flags (optional)
Only @code{nostrip} flag is currently allowed in this field. This flag
means that the realm name should not be stripped off the username when
logging.

@end table

@menu
* Example: realms example.      An example of @file{realms} file.
@end menu

@comment **L3***************************************************************
@node realms example, , realms, realms
@chapter An example of @file{realms} file
@cindex @file{realms}, an example

@example
# Realm                 Remote server[:port]            flags
#----------------       ---------------------           --------
that.net                radius.that.net                 nostrip
dom.ain                 server.dom.ain:3000
@end example

@comment *L2****************************************************************
@node users, access.deny, realms, Configuration files
@chapter The @file{users} file
@cindex @file{users} file
@cindex @file{raddb/users} file

File @file{raddb/users} contains the database of Radius users.
@ref{User Profile} for a description of its syntax.

Each record in the file describes a user's profile. When trying
to find a match for an input request, @code{radiusd} uses the
following algorythm:

@heading Matching rules

@table @asis
@item 1. Match the username
If the username from the packet does not match the one in the record,
the record does not match. @emph{Please note} that the special usernames
@code{DEFAULT} or @code{DEFAULT%d} (%d means any decimal number) match
any username.

@item 2. Determine the authentication type and verify the user
The value of the @code{Auth-Type} attribute determines how the user
is authenticated @ref{Auth-Type}.

@item 3. Delete from the check-pair list A/V pairs internal to the server
The internal A/V pairs are those with the attribute number greater than 255
and the attributes from the following list:

@itemize @minus
       	@item Expiration
	@item Password
@end itemize

We will call the list thus generated an @dfn{Effective checklist}.

@item 4. Compare the @dfn{Effective checklist} with the supplied pairlist.
For each pair from the @dfn{Effective checklist} find a pair with the
same attribute from the supplied pairlist. If no such pair is found, the
comparison fails. Otherwise, compare the values from both attributes as
if the value from the supplied list were at the left side from the
comparison operator of the Effective checklist pair.

This may seem a bit complicated. Lets consider an example. Suppose the
check pair is:

@example
NAS-Port-Id <= 20
@end example

@noindent
and the supplied pair is:

@example
NAS-Port-Id = 10
@end example

@noindent
Then Radius will perform the following comparison:

@example
10 <= 20
@end example

@noindent
which will, of course, succeed.

@item 5. Process special reply attributes

If the reply-pairs contain @code{Strip-User-Name} attribute and its
value is @code{Yes} (1), then any prefixes/suffixes are stripped off
the value of @code{User-Name} attribute.

If the reply-pairs contain the @code{Rewrite-Function} attribute, the
function specified in the value of this attribute is applied @ref{rewrite}.

If the reply pairs contain @code{Fall-Through} attribute and its value is
@code{Yes} (1) then Radius switches to the next record and goes back to
the rule 1. Otherwise the matching process stops and returns the reply pairs
from the record.
@end table

@xref{Attribute list,,Special attributes}.

@menu
* Example: users example.       An example of @file{users} file.
@end menu

@comment **L3***************************************************************
@node users example, , , users
@chapter Example of @file{users} file
@cindex @file{users} file, an example

@example

## Administrative user
## His permissions are defined by huntgroup ROOT in the @file{huntgroups} file
ROOT    Auth-Type = Crypt-Local,
                Password = "$1$6wvmr$vucm4HQa7vIp6vFpAy3qm.",
                Huntgroup-Name = "ROOT"
        Service-Type = RADIUS-Administrative-User

## The following entry is matched when the user appends ``.ppp'' to his
## username when logging in.
## The suffix is removed from the user name, then the password is
## looked up in the mysql database.
## Users may log in at any time. They get PPP service.
DEFAULT Suffix = ".ppp",
                Auth-Type = Mysql,
                Login-Time = "Al",
                Simultaneous-Use = 1,
                Strip-User-Name = Yes
	Service-Type = Framed-User,
                Framed-Protocol = PPP

## This is for SLIP users.
## This entry is matched when the auth request matches ``SLIP'' hint
## @ref{huntgroups example}
DEFAULT Hint = "SLIP",
                Auth-Type = Mysql
        Service-Type = Framed-User
                Framed-Protocol = SLIP

## The following authenticates users using system passwd files.
## The users are allowed to log in from 7:55 to 23:05 on any weekday,
## except the weekend, and from 07:55 to 12:00 on sunday.
## Only one login is allowed per user.
## The program telauth is used to further check the authentication
## information and provide the reply pairs
DEFAULT Auth-Type = System,
                Login-Time = "Wk0755-2305,Su0755-1200",
                Simultaneous-Use = 1
        Exec-Program-Wait = "/usr/local/sbin/telauth %C@{User-Name@} %C@{Calling-Station-Id@} %C@{NAS-IP-Address@} %C@{NAS-Port-Id@}"

## This particular user is authenticated via PAM. He is presented a
## choice from @file{@value{RADDB}/menus/menu1} file.
gray    Auth-Type = Pam
        Menu = menu1

@end example

@comment *L2****************************************************************
@node access.deny, sqlserver, users, Configuration files
@chapter The @file{access.deny} file
@cindex @file{access.deny} file
@cindex @file{raddb/access.deny} file

The @file{raddb/access.deny} file contains a list of user names which are
not allowed to log in via Radius. Each user name is listed on a
separate line. As usual, the @samp{#} character introduces an end-of-line
comment.

@comment *L2****************************************************************
@node sqlserver, rewrite, access.deny, Configuration files
@chapter sqlserver
@cindex @file{sqlserver} file.
@cindex @file{raddb/sqlserver} file.

The @file{raddb/sqlserver} file configures the connection to SQL server.

The file uses simple line-oriented @samp{@var{KEYWORD} @var{VALUE}}
format. Comments are introduces by @samp{#} character.

@heading Syntax overview:

The @file{sqlserver} statements can logically be subdivided into
following groups:

@subheading 1. SQL client parameters
These specify the parameters for connecting to SQL server.
The keywords are as follows:

@table @code
@item server @var{string}
The name or IP address of the SQL server

@item port @var{number}
SQL port number

@item login @var{string}
The SQL user login name

@item password @var{password}
The password 
@end table

@subheading 2. Configuration parameters
These parameters set various aspects of the SQL engine:

@example
query_buffer_size @var{number}
keepopen @var{bool}
idle_timeout @var{number}
@end example

@table @code
@item query_buffer_size @var{number}
Set the size of SQL query expansion buffer. Default is 1024 bytes.

@item keepopen @var{bool}
Specify whether @code{radiusd} should try to keep the connection open.
When set to no (the default), @code{radiusd} will open new connection
before the transaction and close it right after finishing it.
We recommend setting @code{keepopen} to @code{yes} since opening a
new connection can take a substantial amount of time and slow down
the operation considerably.

@item idle_timeout @var{number}
Set idle timeout in seconds for an open SQL connection.
The connection is closed if it remains inactive longer that this amount
of time.

@end table

@subheading 3. Authentication server parameters
@example
doauth @var{bool}
auth_max_connections @var{bool}
auth_db @var{string}
auth_query @var{string}
@end example

@table @code
@item doauth @var{bool}
When set to @code{yes} enables authentication via SQL. All @code{auth_}
keywords are ignored if @code{doauth} is set to @code{no}.

@item auth_max_connections @var{bool}
Specifies the maximum number of authentication SQL connections to keep
open. This parameter is ignored if @code{keepopen} is set to @code{no}.

@item auth_db @var{string}
Specifies the name of the database containing authentication information.

@item auth_query @var{string}
Specifies the SQL query to be used to obtain user's password from the
database. The query should return exactly one string value --- the
password.
@end table

@subheading 4. Accounting parameters
@example
doacct @var{bool}
acct_max_connections @var{number}
acct_db @var{string}
acct_start_query @var{string}
acct_stop_query @var{string}
acct_nasup_query @var{string}
acct_nasdown_query @var{string}
@end example

@table @code
@item doacct @var{bool}
When set to @code{yes} enables SQL accounting. All @code{acct_}
keywords are ignored if @code{doacct} is set to @code{no}.

@item acct_max_connections @var{number}
Specifies the maximum number of accounting SQL connections to keep
open. This parameter is ignored if @code{keepopen} is set to @code{no}.

@item acct_db @var{string}
Specifies the name of the database where the accounting information is
to be stored.

@item acct_start_query @var{string}
Specifies the SQL query to be used when the @code{Start} accounting
packet is received. The query should not return any value. Typically,
this would be some @code{INSERT} statement @ref{Queries}.

@item acct_stop_query @var{string}
Specifies the SQL query to be used when the @code{Stop} accounting
packet is received. The query should not return any value. Typically,
this would be some @code{UPDATE} statement.

@item acct_nasup_query @var{string}
Specifies the SQL query to be used when a NAS sends
@code{Accounting-On} packet @ref{Accounting requests}. The query should
not return any value. 

@item acct_nasdown_query @var{string}
Specifies the SQL query to be used when a NAS sends
@code{Accounting-Off} packet @ref{Accounting requests}. The query should
not return any value. 

@end table

@menu
* Queries::                     Writing SQL query templates.
* Example: sqlserver example.   An example of @file{sqlserver} file.
@end menu

@comment **L3***************************************************************
@node Queries, sqlserver example, , sqlserver
@chapter Writing SQL query templates
@cindex SQL query templates
@cindex writing SQL query templates

The @code{radiusd} server sends SQL server a query on one of the
following events:

@table @asis

@item Authentication
SQL authentication is enabled @ref{SQL Auth} and a user
having @code{Auth-Type} of @code{Mysql} is being authenticated.

@item Accounting
SQL accounting is enabled @ref{SQL Accounting}, and the received request
has @code{Acct-Status-Type} attribute set to one of the following values:

@itemize @bullet
@item Start
@item Stop
@item Accounting-On
@item Accounting-Off
@end itemize

@end table

The queries to use for each of these types are set up in the file
@file{sqlserver}. This chapter describes in detail how to write such
queries.

@heading Autheniticaton

@subheading @code{auth_query} template.

This specifies a template for the query to use when authenticating a
user via SQL. This query will be used when authenticating a user which has

@example
Auth-Type = Mysql
@end example

@noindent
set in his profile @ref{users}. Radius expects this query to return
the MD5 encrypted password for the given user. When no such user
is found in the database, the query should return NULL. The
following statement

@example
auth_query select password from passwd where user_name='%u'
@end example

@noindent
is a valid query.

@heading Accounting

There are four templates:

@table @code
@item acct_start_query
A query to execute when receiving an accounting start request.
@item acct_stop_query
A query to execute when receiving an accounting start request.
@item acct_nasup_query
A query to execute when receiving an Accounting-On request.
@item acct_nasdown_query
A query to execute when receiving an Accounting-Off request.
@end table

Let's suppose we have an accounting table of the following structure:

@example
CREATE TABLE calls (
  status              int(3),
  user_name           char(32),
  Event_Date_Time     datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
  nas_ip_address      char(17),
  nas_port_id         int(6),
  acct_session_id     char(16) DEFAULT NOT NULL,
  acct_session_time   int(11),
  acct_input_octets   int(11),
  acct_output_octets  int(11),
  connect_term_reason int(4),
  framed_ip_address   char(17),
  called_station_id   char(32),
  calling_station_id  char(32),
  KEY name_sess (user_name,acct_session_id)
);
@end example

On receiving the @code{Start} record we would insert a record into this
table with @code{status} set to 1. At this point the columns
@code{acct_session_time}, @code{acct_input_octets},
@code{acct_output_octets} as well as @code{connect_term_reason} are
unknown, so we will set them to 0.

Then, when the @code{Stop} request arrives we will look up the record
having @code{status} = 1 and @code{user_name} and @code{acct_session_id}
coinciding with attributes @code{User-Name} and @code{Acct-Session-Id}
of the request and update it setting

@example
status = 2
acct_session_time = value of Acct-Session-Time attribute
acct_input_octets = value of Acct-Input-Octets attribute
acct_output_octets = value of Acct-Output-Octets attribute
connect_term_reason = value of Acct-Terminate-Cause attribute
@end example

@noindent
Thus every record with @code{status} = 1 will represent the active
session and every record with @code{status} = 2 will represent
the finished and correctly closed record.

Further, there may be times when it is necessary to bring some NAS
down. To correctly close the currently active sessions on this NAS
we will define a @code{acct_nasdown_query} so that it would
set @code{status} column to 2 and update @code{acct_session_time}
in all records having @code{status} = 1 and 
@code{nas_ip_address} equal to IP address of the NAS. Thus, all
sessions on a given NAS will be closed correctly even when it is
reloaded. The @code{acct_session_time} can be computed as difference
between the current time and the time stored in @code{event_date_time}
column.

We have not covered only one case: when a NAS is crashed, e.g. due to
a power failure. In this case it does not have a time to send
@code{Accounting-Off} request and all its records remain open. But when
the power supply is restored, the NAS will send an @code{Accounting-On}
request, so we define a @code{acct_nasup_query} to 
set @code{status} column to 3 and update @code{acct_session_time}
in all open records belonging to this NAS. Thus we will know that
each record having @code{status} = 3 represents a crashed session.

The next chapter illustrates such approach @ref{sqlserver example}. 

@comment **L3***************************************************************
@node sqlserver example, , Queries, sqlserver
@chapter An example of @file{sqlquery} file.

This example supposes you have the single database called RADIUS
with the following tables in it:

@subheading passwd
This table keeps authentication information. It is created as

@example
CREATE TABLE passwd(
  user_name           char(32),
  password            char(64),
  UNIQUE (user_name)
);
@end example

@subheading calls
This table accumulates user session statistics. Its structure is:

@example
CREATE TABLE calls (
  status              int(3),
  user_name           char(32),
  Event_Date_Time     datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
  nas_ip_address      char(17),
  nas_port_id         int(6),
  acct_session_id     char(16) DEFAULT NOT NULL,
  acct_session_time   int(11),
  acct_input_octets   int(11),
  acct_output_octets  int(11),
  connect_term_reason int(4),
  framed_ip_address   char(17),
  unused              int(1),
  called_station_id   char(32),
  calling_station_id  char(32),
  KEY name_sess (user_name,acct_session_id)
);
@end example

Assuming this the @file{sqlserver} could contain:

@example
######
## sqlserver configuration

## General settings
##
server localhost
port 3306
login radius
password password

# Size of SQL query expansion buffer. Default is 1024 bytes.
query_buffer_size 1024

keepopen yes
idle_timeout 14400


#########
## Authentication service
##

# Enable authentication via SQL
doauth yes

auth_max_connections 16
auth_db RADIUS
auth_query select password from passwd where user_name='%u'

#########
# Accounting-relevant settings

# Enable SQL accounting
doacct yes
acct_max_connections 16
acct_db RADIUS

# Query to be used on session start
acct_start_query     INSERT INTO calls \
                     VALUES(%C@{Acct-Status-Type@},\
                            '%u',\
                            '%G',\
                            '%C@{NAS-IP-Address@}',\
                            %C@{NAS-Port-Id@},\
                            '%C@{Acct-Session-Id@}',\
                            0,\
                            0,\
                            0,\
                            0,\
                            '%C@{Framed-IP-Address@}',\
                            0,\
                            '%C@{Called-Station-Id@}',\
                            '%C@{Calling-Station-Id@}')

# Query to be used on session end
acct_stop_query      UPDATE calls \
                     SET status=%C@{Acct-Status-Type@},\
                         acct_session_time=%C@{Acct-Session-Time@},\
                         acct_input_octets=%C@{Acct-Input-Octets@},\
                         acct_output_octets=%C@{Acct-Output-Octets@},\
                         connect_term_reason=%C@{Acct-Terminate-Cause@} \
                         WHERE user_name='%C@{User-Name@}' AND status = 1


# Query to be used when a NAS is brought up, i.e. when it sends 
# Accounting-On packet
# NOTE: It sets status 3 so that we can always tell which records
#       have been closed due to NAS hard reset.
acct_nasdup_query   \
    UPDATE calls \
       SET status=3,\
     acct_session_time=unix_timestamp(now())-unix_timestamp(event_date_time) \
    WHERE status=1 AND nas_ip_address='%C@{NAS-IP-Address@}'

# Query to be used when a NAS goes down, i.e. when it sends 
# Accounting-Off packet
acct_nasdown_query   \
    UPDATE calls \
       SET status=2,\
     acct_session_time=unix_timestamp(now())-unix_timestamp(event_date_time) \
    WHERE status=1 AND nas_ip_address='%C@{NAS-IP-Address@}'

## EOF
@end example

@comment *L2****************************************************************
@node rewrite, menus, sqlserver, Configuration files
@chapter The @file{rewrite} file
@cindex @file{rewrite} file
@cindex @file{raddb/rewrite} file

Some NASes are very particular about the information they send with
the requests. There are cases when the information they send
is hardly usable or even just unusable. For example, a
cisco AS5300 terminal server used as a voice over IP router packs
a lot of information into its @code{Acct-Session-Id} attribute. Though
the information stored there is otherwise relevant, it makes proper
accounting impossible since the @code{Acct-Session-Id} attributes
in the start and stop packets of the same session become different, and
thus Radius cannot determine which stop corresponds to which start
@ref{Acct-Session-Id}.

In order to cope with such NASes, GNU Radius provides a rewrite
feature which can be applied to incoming packet in order to normalize
it, i.e. to convert it to the form prescribed by RFCs and understandable
by Radius.

This is done by writing special functions, storing them in the
@file{raddb/rewrite} file and creating a huntgroup for the NAS
@ref{huntgroups}, which applies the function to any packet coming
from that NAS.

For example, in the case of AS5300 router, a corresponding rewrite
function parses the @code{Acct-Session-Id} attribute, selects
various fields from it, stores them in proper attributes, creating
them if necessary and, finally replaces @code{Acct-Session-Id} with
its real value, which is the same for start and stop records
corresponding to a single session. Thus all the information that
came with the packet is preserved, but the packet itself is made
usable for proper accounting.

@menu
* Syntax: rewrite syntax.       The syntax of rewrite functions.
* Usage: rewrite usage.         Applying rewrite functions to packets
                                coming from particular NAS.
* Examples: rewrite examples.   Examples of various rewrite functions.
@end menu

@comment **L3***************************************************************
@node rewrite syntax, rewrite usage, , rewrite
@chapter The syntax of rewrite functions.
@cindex rewrite, syntax

The syntax of rewrite functions resembles closely the C syntax.

@subheading Data types
There are only two datatypes: @code{integer} and @code{string}, 
the two being coercible to each other in the sense that a string
can be coerced to an integer if it contains a valid ASCII representation
of a decimal, octal or hex number, and the integer can always be coerced
to a string, the result of such coercion being the ASCII string with
decimal representation of the number.

@subheading Symbols
A symbol is a lexical token. The following symbols are recognized:

@table @asis
@item Arithmetical operators
These are @samp{+}, @samp{-}, @samp{*}, @samp{/} representing the basic
arithmetical operations and @samp{%} meaning remainder.

@item Comparison operators
These are: @samp{==}, @samp{!=}, @samp{<}, @samp{<=}, @samp{>},
@samp{>=} with the meaning equal to what they have in C, @samp{=~}
meaning ``matches a regular expression'' and @samp{!~} meaning
``does not match a regular expression''.

@item Unary operators.
These are: @samp{-} and @samp{+} for unary plus and minus,
@samp{!} for boolean negation and @samp{*} for testing the
existence of an attribute.

@item Boolean operators.
These are: @samp{&&} and @samp{||}.

@item Parentheses @samp{(} and @samp{)}
These are used to change the precedence of operators, to introduce
typecasts (type coercions), to declare functions and to pass actual
arguments to functions.

@item Curly braces (@samp{@{} and @samp{@}})
These are used to delimit blocks of code.

@item Numbers
Numbers follow usual C convention for integers.

@item Characters
These follow usual C convention for characters. A character is
represented internally by an integer keeping its ASCII code.

@item Quoted strings
These follow usual C conventions for strings.

@item Attribute values
This are represented either as

@example
@samp{%}@var{number}
@end example

@noindent
which returns the value of an attribute @var{number} from the request
packet, or

@example
@samp{%[}@var{attribute-name}@samp{]}
@end example

@noindent
which returns the value of an attribute @var{attribute-name} from the
request packet. @var{attribute-name} should be a valid Radius dictionary
name @ref{dictionary}.

@item Identifiers
Represent functions and variables. These are described in the next section.

@item Previous regexp match references
This are the tokens in the form:

@example
@samp{\}@var{number}
@end example

@noindent
This means the @var{number}th subexpression from the recent regexp
match. The match references are always string expressions.

@end table

@subheading Identifiers
A valid identifier is a string of characters meeting the following
requirements:

@enumerate 1
@item It starts with either a lower- or uppercase letter of the latin
alphabet or any of the following symbols: @samp{_}, @samp{$}.
@item It consists of alphanumeric characters, undersores(@samp{_}) and
dollar signs (@samp{$}).
@end enumerate

@subheading Function declarations
The function is declared as follows:

@example
@var{type} @var{function-name} (@var{parameter-list})
@end example

@noindent
where @var{type} specifies the return type of the function,
@var{function-name} declares the symbolic name of the function and
@var{parameter-list} declares the formal parameters to the function.
It is a comma-separated list of declarations in the form:

@example
@var{type} @var{parm-name}
@end example

@noindent
@var{type} being the parameter type, and @var{parm-name} being its
symbolic name. Both @var{function-name} and @var{parm-name} should
be valid identifiers.

@subheading Variable declarations

There is no global variables in rewrite code. All variables are local.
The local variables are declared right after the opening curly brace
(@samp{@{}) and before any executable statements. The declaration
takes form:

@example
@var{type} @var{ident_list} ;
@end example

@noindent
Here @var{ident_list} is a list of variable names. @emph{Please note}
that, unlike in C, no assignments are allowed in variable declarations.

@subheading Executable statements

These are: expressions, assignments, conditional statements and
return statements.

@subheading Expressions

An expression is either of the following:

@itemize @bullet
@item A variable identifier
@item A type coercion expression
@item An arithmetic expression
@item A boolean expression
@item An assignment
@item A function call
@end itemize

@subheading Type coercion
The type coercion is like a typecast in C. Its syntax is

@example
@samp{(} @var{type} @samp{)} @var{ident}
@end example

@noindent
the result of type coercion is as follows:

@multitable @columnfractions .20 .20 .60
@item @var{type} @tab Variable type @tab Resulting conversion

@item integer
@tab integer
@tab No conversion. This results in the same integer value.

@item integer
@tab string
@tab If the string value of the variable is a valid ASCII representation
of the integer number (either decimal, octal or hex) it is converted to
the integer, otherwise the result of the conversion is undefined.

@item string
@tab integer
@tab The ASCII representation (in decimal) of the integer number. 

@item string
@tab string
@tab No conversion. This results in the same string value.

@end multitable

@subheading Assignment
An assignment is:

@example
@var{ident} = @var{expression} ;
@end example

@noindent
The variable @var{ident} is assigned the value of @var{expression}.

@subheading Function calls
These take the form:

@example
@var{ident} ( @var{arg-list} )
@end example

@noindent
where @var{ident} is the identifier representing the function,
@var{arg-list} is a comma-separated list of expressions supplying
actual arguments to the function. The function @var{ident} 
references can be either a compiled function or a built-in
function.

@emph{Please note} that, unlike in C, the mismatch between the
number of actual arguments and number of formal parameters in the
compiled function declaration is not an error but rather a warning.

@subheading Built-in functions.
The following built-in functions are provided:

@table @asis
@item integer length(string s);
Returns the length of string @code{s}.

@item integer index(string s, integer c);
Returns the index of the first occurence of the character @code{c} in
the string @code{s}. Returns -1 if no such occurence is found.

@item integer rindex(string s, integer i);
Returns the index of the last occurence of the character @code{c} in
the string @code{s}. Returns -1 if no such occurence is found.

@item string substr(string s, integer start, integer length);
Returns the at most @code{length} substring of @code{s} starting at
position @code{start}.

@end table

All character positions in strings are counted from 0.

@comment **L3***************************************************************
@node rewrite usage, rewrite examples, rewrite syntax, rewrite
@chapter Applying rewrite functions.
@cindex rewrite, usage
@cindex rewrite, applying functions

To apply a rewrite function to packets coming from a particular NAS,
the name of the function should be listed in @code{Rewrite-Function}
attribute of the huntgroup for this NAS @ref{Rewrite-Function},
@ref{huntgroups}.

For example, suppose you need to apply function @code{max_fixup} to
all packets coming from NAS 11.10.10.11. Then you would write the
following in your @file{huntgroups} file:

@example
## This defines the packet rewriting function for the server 11.10.10.11
DEFAULT NAS-IP-Address = 11.10.10.11, Rewrite-Function = "max_fixup"
        NULL
@end example

The function @code{max_fixup} must be declared as:

@example
integer max_fixup()
@{
@}
@end example

@ref{huntgroups example}

@comment **L3***************************************************************
@node rewrite examples, , rewrite usage, rewrite
@chapter Examples of various rewrite functions.
@cindex rewrite, examples

The examples found in this chapter are working functions that can be
used with various existing NAS types. They are taken from the
@file{rewrite} file contained in distribution of GNU Radius.

@subheading 1. Port rewriting for MAX Ascend terminal servers

Some MAX Ascend terminal servers pack additional information
into @code{NAS-Port-Id} attribute. The port number is constructed as
as XYYZZ, where X = 1 for digital, X = 2 for analog, YY is line number
(1 for first PRI/T1/E1, 2 for second, so on), and ZZ = channel number
(on the PRI or Channelized T1/E1).

The following rewrite functions are intended to compute the integer
port number in the range (1 .. @var{portcnt}), where @var{portcnt}
represents the real number of physical ports available on the NAS.
Such port number can be used, for example, with
@code{Add-Port-To-IP-Address} attribute @ref{Add-Port-To-IP-Address}.

@example
/*
 * decode MAX port number
 * input: P        --  The value of NAS-Port-Id attribute
 *        portcnt  --  number of physical ports on the NAS
 */
integer
max_decode_port(integer P, integer portcnt)
@{
	if (P > 9999) @{
		integer s, l, c;

		s = P / 10000;
		l = (P - (10000 * s))/100; 
		c = P - ((10000 * s) + (100 * l)); 
		return (c-1) + (l-1) * portcnt;
	@}
	return P;
@}

/*
 * Interface function for MAX terminal server with 23 ports.
 * Note that it saves the received NAS-Port-Id attribute in the
 * Orig-NAS-Port-Id attribute. The latter must be defined somewhere
 * in the dictionary
 */
integer
max_fixup()
@{
        %[Orig-NAS-Port-Id] = %[NAS-Port-Id]; # Preserve original data
        %[NAS-Port-Id] = max_decode_port(%[NAS-Port-Id], 23);
        return 0;
@}
@end example

@subheading 2. Session ID parsing for Cisco AS 5300 series

Cisco AS 5300 with VoIP IOS encodes a lot of other information into its
@code{Acct-Session-Id}. The pieces of information are separated by
@samp{/} character. The part of @code{Acct-Session-Id} up to first
@samp{/} character is the actual session ID.

On the other hand, its accounting packets lack @code{NAS-Port-Id},
though they may contain the vendor-specific pair with code 2
(vendor PEC 9), which is the string in the form @samp{ISDN 9:D:999}
(@samp{9} represents a decimal digit). The number after the last
@samp{:} character can be used as a port number.

The following code parses @code{Acct-Session-Id} attribute and stores
the information it contains in various other attributes, generates
normal @code{Acct-Session-Id} and attempts to generate
@code{NAS-Port-Id} attribute.

@example
/* 
 * The port rewriting function for cisco AS5300 used for voip.
 * This function is used to generate NAS-Port-Id pair on the basis
 * of vendor-specific pair 2. If the latter is in the form 
 * "ISDN 9:D:999" (where each 9 represents a decimal digit), then 
 * the function returns the number after the last colon. This is
 * used as a port number.
 */
integer
cisco_pid(string A)
@{
        if (A =~ ".*\([0-9][0-9]*\):[A-Z0-9][A-Z0-9]*:\([0-9][0-9]*\)") @{
                return (integer)\2;
        @}
        return -1;
@}

/*
 * This function parses the packed session id.
 * The actual sid is the number before the first slash character.
 * Other possibly relevant fields are also parsed out and saved 
 * in the Voip-* A/V pairs. The latter should be defined somewhere
 * in the dictionary.
 */
string
cisco_sid(string S)
@{
        if (S =~ "\(.[^/]*\)/[^/]*/[^/]*/\([^/]*\)/\([^/]*\)/\([^/]*\)/\([^/]*\)/\([^/]*\)/\([^/]*\)/\([^/]*\).*") @{
                %[Voip-Connection-ID] = \2;
                %[Voip-Call-Leg-Type] = \3;
                %[Voip-Connection-Type] = \4;
                %[Voip-Connect-Time] = \5;
                %[Voip-Disconnect-Time] = \6;
                %[Voip-Disconnect-Cause] = \7;
                %[Voip-Remote-IP] = \8;
                return \1;
        @} 
	return S;
@}

/*
 * Normalize cisco AS5300 packets
 */
integer
cisco_fixup()
@{
        integer pid;

        if ((pid = cisco_pid(%[Cisco-PRI-Circuit])) != -1) @{
                if (*%[NAS-Port-Id])
                        %[Orig-NAS-Port-Id] = %[NAS-Port-Id];
                %[NAS-Port-Id] = pid;
        @}
        if (*%[Acct-Session-Id]) @{
                %[Orig-Acct-Session-Id] = %[Acct-Session-Id];
                %[Acct-Session-Id] = cisco_sid(%[Acct-Session-Id]);
        @}
        return 0;
@}
@end example

@subheading 3. Username rewriting for NT machines.

Users coming from Windows NT machines often authenticate themselves as
NT_DOMAIN\username. The following function selects the username part
and stores it in the @code{User-Name} attribute:

@example
integer
login_nt(string uname)
@{
        integer i;
	
        if ((i = index(uname, '\\')) != -1)
                return substr(uname, i+1, -1);
        return uname;
@}

integer
nt_rewrite()
@{
        %[Orig-User-Name] = %[User-Name];
        %[User-Name] = login_nt(%[User-Name]);
        return 0;
@}
@end example


@comment *L2****************************************************************
@node menus, Macro substitution, rewrite, Configuration files
@chapter menus
@cindex menus

The menus is a way to allow user the choice between various services
he could be provided. The menu functionality is enabled when Radius
is compiled with @code{--enable-livingston-menus} option.

A user is presented a menu after it is authenticated if the reply-pairs
of his profile record consist of a single A/V pair in the form:

@example
Menu = <menu-name>
@end example

@noindent

The menu files are stored in directory @file{raddb/menus}.

@menu
* Syntax:menu syntax.           A menu file syntax.
* Example:menu example.         An example of menu files.
@end menu

@comment ***L3**************************************************************
@node menu syntax, menu example,, menus
@chapter A menu file syntax.
@cindex  menu, syntax

A menu file is a text file containing a menu declaration and any number
of choice descriptions. It can be either a single-level menu or can
reference other menus.

A comment is introduced by a @samp{#} character. All characters from
this one up to the end of line are discarded.

The menu declaration is contained between the words @samp{menu} and
@samp{end}. Each of these must be the only word on a line and must
start in column 1. 

Choice descriptions follow the menu declaration. Each description
starts with a line containing choice identifier. A choice identifier
is an arbitrary word identifying this choice, or a word @samp{DEFAULT}.
It is followed by comma-separated list of A/V pairs which will be
returned to the server when a user selects this choice.

@comment ***L3**************************************************************
@node menu example,, menu syntax, menus
@chapter An example of menu files
@cindex menus, an example

@heading Single-Level Menu

Suppose the following file is stored under @file{raddb/menus/menu1}:

@example
menu
        *** Welcome EEE user! ***
Please select an option:

        1. Start CSLIP session
        2. Start PPP session
        3. Quit

        Option:
end
# CSLIP choice
# Framed-IP-Address of 255.255.255.254 indicates that the NAS should
# select an address for the user from its own IP pool.
1
        Service-Type = Framed-User,
        Framed-Protocol = SLIP,
        Framed-IP-Address = 255.255.255.254,
        Termination-Menu = "menu1"
# PPP choice
2
        Service-Type = Framed-User,
        Framed-Protocol = PPP,
        Framed-IP-Address = 255.255.255.254,
        Termination-Menu = "menu1"
# A special menu EXIT means abort the session
3
        Menu = "EXIT"
# Return to this menu if no valid choice have been entered 
DEFAULT
        Menu = "menu1"
@end example

Now, suppose the @file{raddb/users} contains the following
profile entry:

@example
DEFAULT Auth-Type = System
        Menu = "menu1"
@end example

@noindent
and user @samp{jsmith} has a valid system account and tries to log in
from some NAS. Upon authenticating the user, the Radius server sees that
his reply pairs contain the @code{Menu} attribute. Radius then sends
Access-Challenge packet to the NAS with the text of the menu in it.
The @samp{jsmith} then sees on his terminal:

@example
        *** Welcome EEE user! ***
Please select an option:

        1. Start CSLIP session
        2. Start PPP session
        3. Quit

        Option:
@end example
        
He then enters @samp{2}. The NAS sends the Access-Request packet to the
server, which sees that user wishes to use option 2 and replies to the
NAS with an Access-Accept packet containing the following attributes:

@example
        Service-Type = Framed-User,
        Framed-Protocol = PPP,
        Framed-IP-Address = 255.255.255.254,
        Termination-Menu = "menu1"
@end example

@noindent
The @code{Termination-Menu} in this list makes sure the same process
will continue when @samp{jsmith} logs out, i.e. he will be presented
the same menu again until he enters choice @samp{3} which will
disconnect him.


@heading Nested menus

In this example, the @samp{other} choice refers to the menu above.

@example
menu
        *** Welcome here! ***
Please enter an option:
        ppp     ---     Start PPP session
        telnet  ---     Begin guest login session
        other   ---     Select other option

        Enter your choice:
end
ppp
        Service-Type = Framed-User,
        Framed-Protocol = PPP
telnet
        Service-Type = Login-User,
        Login-IP-Host = 10.11.11.7,
        Login-Service = Telnet,
        Login-TCP-Port = 23
other
        Menu = "menu1"
DEFAULT
        menu = "menu2"
@end example

@comment *L2****************************************************************
@node Macro substitution, , menus, Configuration files
@chapter Substitution rules

Some statements in the configuration files need to use the actual
values of the attributes supplied with the request. These are:

@itemize @bullet
@item @code{Exec-Program} and @code{Exec-Program-Wait} assignments in @file{users} database
@item SQL query templates in @file{sqlserver}
@end itemize

In these statements the following macros are replaced by the value
of corresponding attributes:

@table @code
@item %Cnum
(num is a decimal number). This variable is replaced by the value of
attribute number `num'. The attribute is looked up in the check
pairlist.
@item %C@{attr-name@}
This is replaced by the value of attribute named `attr-name'. The
attribute is looked up in the check pairlist.
@item %Rnum
(num is a decimal number). This variable is replaced by the value of
attribute number `num'. The attribute is looked up in the reply
pairlist.
@item %R@{attr-name@}
This is replaced by the value of attribute named `attr-name'. The
attribute is looked up in the reply pairlist.
@item %D
This is replaced ny current date/time (localtime).
@item %G
This is replaced by current date/time in GMT.
@end table

You can also use the following shortcuts:

@table @code
@item %p
Port number
@item %n
NAS IP address
@item %f
Framed IP address
@item %u
User name
@item %c
Callback-Number
@item %i
Calling-Station-Id
@item %t
MTU
@item %a
Protocol (SLIP/PPP)
@item %s
Speed (Connect-Info attribute)
@end table

@comment *******************************************************************
@node Authentication, Accounting, Configuration files, Top

Several authentication types are supported. The use of a particular
authentication type for a given user is determined by the value
of @code{Auth-Type} attribute in his profile.

@menu
* Accept Auth::                   Accept unconditionally.
* Reject Auth::                   Reject unconditionally.
* Local Password Auth::           Authenticate using plaintext password.
* Encrypted Password Auth::       Authenticate using MD5 encrypted password.
* System Auth::                   Authenticate using system account.
* SQL Auth::                      Athenticate using SQL.
* PAM Auth::                      Authenticate using PAM.
* Checking Simultaneous Logins::  
@end menu

@comment *L2****************************************************************
@node Accept Auth, Reject Auth, , Authentication
@chapter Accept Authentication Type
@cindex Accept Authentication Type
@cindex guest accounts, setting up

@subheading Synopsis
@example
Auth-Type = Accept
@end example

@subheading Usage
When a user has the above string in his profile he will be authenticated
without any further checking. Actually this means that only username
is required for authentication.

This authentication type can be used for guest accounts, e.g. the
following profile in @file{users}:

@example
guest   Auth-Type = Accept,
                Password != "",
                Simultaneous-Use = 10
        Service-Type = Framed-User,
                Framed-Protocol = PPP
@end example

@noindent
allows up to 10 simultaneous guest PPP accounts. To log in using such
guest account it is sufficient to use username @samp{guest} and any
non-empty password.

@comment *L2****************************************************************
@node Reject Auth, Local Password Auth, Accept Auth, Authentication
@chapter Reject Authentication Type
@cindex Reject Authentication Type
@cindex disabling user accounts

@subheading Synopsis
@example
Auth-Type = Reject
@end example

@subheading Usage
The @code{Reject} authentication type causes the request to be rejected
unconditionally. It can be used to disable a user account @ref{access.deny}.

@comment *L2****************************************************************
@node Local Password Auth, Encrypted Password Auth, Reject Auth, Authentication
@chapter Local Password Authentication Type
@cindex Local Password Auth

@subheading Synopsis
@example
Auth-Type = Local,
Password = <plaintext password>
@end example

@subheading Usage
The @code{Password} attribute in user's profile contains the
@emph{plaintext} password. If this password and the one supplied by the
user coincide, then the user is authenticated.

We do not recommend the use of this authentication type, since keeping
plaintext passwords in @file{users} is very unsecure, even though the
file is owned by root and its permissions are 0600.

@comment *L2****************************************************************
@node Encrypted Password Auth, System Auth, Local Password Auth, Authentication
@chapter Encrypted Password Authentication Type
@cindex Encrypted Password Authentication Type

@subheading Synopsis
@example
Auth-Type = Crypt-Local,
Password = <MD5 hash>
@end example
@noindent
or

@example
Crypt-Password = <MD5 hash>
@end example

@subheading Usage

The @code{Password} attribute in user's profile contains the MD5 hash
of his password. The MD5 hash is computed over the password supplied
by the user, both hashes are compared and if they coincide, the user
is authenticated.

@comment *L2****************************************************************
@node System Auth, SQL Auth, Encrypted Password Auth, Authentication
@chapter System Authentication Type
@cindex System Authentication Type

@subheading Synopsis
@example
Auth-Type = System
@end example

When a user has the above string in his profile record, he will be
authenticated using system /etc/passwd (/etc/shadow) files, i.e.
to be authenticated he has to have a valid system account on the
machine where the radius server is running.

@comment *L2****************************************************************
@node SQL Auth, PAM Auth, System Auth, Authentication
@chapter SQL Authentication Type
@cindex SQL Authentication Type

@subheading Synopsis
@example
Auth-Type = Mysql
@end example

@subheading Usage
This authentication type means that the MD5 hash of his password is kept
in SQL database. To authenticate such user, @code{radiusd} will query
the database using @code{auth_query} from the @file{sqlserver} file.
It will then compute the MD5 hash over the supplied password and
compare it with the string returned by the query. If both strings
coincide, the user will be authenticated.

@xref{sqlserver}.
@xref{Queries,,Writing SQL query templates}.

@comment *L2****************************************************************
@node PAM Auth, Checking Simultaneous Logins, SQL Auth, Authentication
@chapter PAM Authentication Type
@cindex PAM Authentication Type

@subheading Synopsis
@example
Auth-Type = PAM
@end example
@noindent
or

@example
Auth-Type = PAM
PAM-Auth = <PAM service>
@end example

@subheading Usage

This authentication type indicates that a user should be authenticated
using PAM (Pluggable Authentication Module) framework. The value of
@code{PAM-Auth} attribute specifies the PAM service to be used. 
If it is not specified, @samp{radius} will be used. 

@comment *L2****************************************************************
@node Checking Simultaneous Logins, , PAM Auth, Authentication
@chapter Checking Simultaneous Logins
@cindex Checking Simultaneous Logins
@cindex simultaneous logins, checking for

The number of sessions a user can have open simultaneously can be
restricted by setting @code{Simultaneous-Use} attribute in the user's
profile check-pairs @ref{Simultaneous-Use}. By default the number
of simultaneous sessions is unlimited.

When a user with limited number of simultaneous logins authenticates
himself, Radius first sees how many sessions are already open for this user.
If this number is equal to the value of @code{Simultaneous-Use}
attribute the authentication request is rejected.

To determine the number of open sessions, Radius scans the
@file{radlog/radutmp} for any open entries marked with the
user's login name @ref{Unix Accounting}. Such entries are created
when Radius receives an Accounting-Request packet with
@code{Acct-Status-Type} attribute set to @code{Start}. An entry is
marked closed when a corresponding Accounting-Request packet arrives with
@code{Acct-Status-Type} attribute set to @code{Stop}.

Since an open entry might be a result of missing @code{Stop} packet,
Radius queries the NAS whether the session listed in the entry is
currently active. If the NAS replies positive, the session count
is incremented, if it replies negative, such entry is marked as
closed and is not counted. There may also be cases when the NAS
is unreachable due to some reasons. In such cases the Radius behaviour
is determined by the value of @code{checkrad-assume-logged} in
@file{config} file @ref{auth,,auth statement (raddb/config)}.
If the value is @code{yes}, Radius assumes the session is still
active and increases the session count, otherwise it proceeds as
if the NAS returned negative reply.

Usually, different NASes should be queried in different ways. It would
be unwise to make Radius server know all protocols for communicating
with every existing NAS type. Instead of querying NAS directly, Radius
calls external process @code{checkrad} and passes it all the information
necessary to query a particular NAS about a particular session
@ref{Checkrad Overview}. The @code{checkrad} program then performs
the actual work of querying and returns one of the following
exit codes:

@itemize @bullet
@item 0, when the NAS replies negative
@item 1, when the NAS replies positive
@item -1, when the NAS cannot be reached or some error occurs.
@end itemize

@code{checkrad} determines the way to query a given NAS by its type,
which radius passes to it along with other arguments
@ref{Checkrad Overview}. Radius knows the type from a corresponding
line in @file{naslist} file @ref{naslist}.

The NAS types @code{checkrad} knows about and ways of communicating
with them are fully configurable @ref{checkrad.conf,,Configuring checkrad}.

@comment *******************************************************************
@node Accounting, Logging, Authentication, Top
@chapter Accounting
@cindex Accounting Types

GNU Radius supports three types of accounting. By default Unix and
Detailed request ccounting types are always enabled. 

@menu
* Unix Accounting::                     Unix style utmp/wtmp accounting.
* Detailed Request Accounting::         Detailed requests.
* SQL Accounting::                      Accounting to SQL server.
@end menu

@comment *L2****************************************************************
@node Unix Accounting, Detailed Request Accounting, , Accounting
@chapter Unix Accounting
@cindex Unix Accounting

This accounting method is always enabled.

Radius keeps files @file{radutmp} and @file{radwtmp} in its logging
directory  and stores the accounting data there. The utilities
@code{radwho} and @code{radlast} can be used to list information about
users' sessions.

@xref{Naming conventions}.

@xref{Radwho}.

@xref{Radlast}.

@comment *L2****************************************************************
@node Detailed Request Accounting, SQL Accounting, Unix Accounting, Accounting
@chapter Detailed Request Accounting
@cindex Detailed Request Accounting

This accounting method is always enabled.

Radius stores the detailed information about accounting packets received
in files @file{radacct/@var{nasname}/detail} @ref{Naming conventions}, where
@var{nasname} means short nas name from the @file{raddb/naslist} file @ref{naslist}.

The information stored there includes the timestamp and detailed
dump of attributes from each packet, e.g.:

@example
Fri Dec 15 18:00:24 2000
	Acct-Session-Id = "2193976896017"
	User-Name = "e2"
	Acct-Status-Type = Start
	Acct-Authentic = RADIUS
	Service-Type = Framed-User
	Framed-Protocol = PPP
	Framed-IP-Address = 11.10.10.125
	Calling-Station-Id = "+15678023561"
	NAS-IP-Address = 11.10.10.11
	NAS-Port-Id = 8
	Acct-Delay-Time = 0
	Timestamp = 976896024
	Request-Authenticator = Unverified

Fri Dec 15 18:32:09 2000
	Acct-Session-Id = "2193976896017"
	User-Name = "e2"
	Acct-Status-Type = Stop
	Acct-Authentic = RADIUS
	Acct-Output-Octets = 5382
	Acct-Input-Octets = 7761
	Service-Type = Framed-User
	Framed-Protocol = PPP
	Framed-IP-Address = 11.10.10.125
	Acct-Session-Time = 1905
	NAS-IP-Address = 11.10.10.11
	NAS-Port-Id = 8
	Acct-Delay-Time = 0
	Timestamp = 976897929
	Request-Authenticator = Unverified
@end example

@comment *L2****************************************************************
@node SQL Accounting, , Detailed Request Accounting, Accounting
@chapter SQL Accounting
@cindex SQL Accounting

The SQL accounting method is enabled when Radius is configured with
@code{--enable-mysql} option and @file{sqlserver} file in its
configuration directory is properly set up @ref{sqlserver}.

This version of GNU Radius (@value{VERSION}) supports only MySQL
servers. Support for other SQL servers will be added in future
versions.

With this accounting method enabled, @code{radiusd} will store the
information about accounting requests in the configured SQL database.
The accounting method is fully configurable: the Radius administrator
defines both the types of requests to be accounted and the information
to be stored into the database. @ref{sqlserver}.

@comment *******************************************************************
@node Logging, Debugging, Accounting, Top
@chapter Logging
@cindex Logging

GNU Radius reports every event worth mentioning. The events are
segregated by their severity level. Radius discerns the following
levels (in order of increasing severity):

@table @code
@item Debug
The debug messages @ref{Debugging}.

@item Auth
Under this level every authentication attempt is logged. This is enabled
by setting
@example
level auth;
@end example
@noindent
in @code{category auth} statement of @file{config} file.

@item Proxy
Messages regarding proxy requests @ref{Realms}.

@item Info
Informational messages.

@item Notice
Normal, but significant conditions.

@item Warning
Warning conditions. These mean some deviations from normal work.

@item Error
Error conditions. Usually these require special attention.

@item CRIT
Critical conditions due to which Radius is no longer able to continue
working. These require urgent actions from the site administrator.

@end table

By default, all messages in all levels are output to file
@file{radlog/radius.log}. In addition, messages in level
@code{CRIT} are also duplicated to the system console. These defaults
can be overridden using @code{logging} statement in @file{raddb/config} file
@ref{logging,,logging statement}, @ref{Naming conventions}.


@comment *******************************************************************
@node Debugging, Client Overview, Logging, Top
@chapter Debugging
@cindex Debugging

GNU Radius provides extensive debugging features. These are enabled
either by @samp{-x} command option to the @code{radiusd}
@ref{Invocation}, or by @code{level} statement in debug category
@ref{logging,,logging statement}. Both cases require as an argument
a valid debug specification.

A debug specification sets the module for which the debugging should
be enabled and debugging level. The higher the level is, the more
detailed information is provided. The module name and level are
separated by an equal sign. If the level is omitted, the highest
possible level (100) is assumed. The module name may be abbreviated
to first N characters, in which case the first matching module is
selected. Several such specifications can be specified, in which case
they should be separated by a comma. For example, the following is a
valid debug specification:
@example
        proxy.c=10,files.c,config.y=1
@end example

@noindent
It sets debug level 10 for module @code{proxy.c}, level 100 for
@code{files.c}, and 1 for @code{config.y}.

The modules and debugging levels are subject to change from release
to release. 

@c The following describes shortly the debugging levels for this release
@c of GNU Radius (@value{VERSION}.

@c @include debug.texinfo

@comment *******************************************************************
@node Client Overview, client.config, Debugging, Top
@chapter Client Overview
@cindex Client Overview

Client programs are those which emulate the NAS. These are
@code{radtest} @ref{Radtest} and @code{radctl} @ref{Radctl}.

Since they have to connect to radius server, they should be provided
information about server's IP address, ports to connect to and the
shared secret key to use.

The two configuration files @file{raddb/client.config} and
@file{raddb/client.shadow} provide this information for the
client programs.

These configuration files are described in the following chapters.

@comment *******************************************************************
@node client.config, client.shadow, Client Overview, Top
@chapter client.config

The @file{client.config} file determines the configuration values for
client programs such as @code{radtest} and @code{radctl}.

@subheading Syntax
The syntax is quite simple: one statement per line, a statement consists
of a keyword and a value separated by whitespace.

Following keywords are recognized:

@table @code
@item timeout
Sets the timeout in seconds for connection to radius server.
@item retry
Determines how many times to retry connecting the server in case of failure.
Each subsequent	attempt takes place after sleeping the amount of time
specified by @code{timeout} statement.
@item server
The name of the Radius server to connect to. It is used as a lookup key
to client.shadow file, from where the corresponding server parameters are
obtained.
@end table

@subheading Example

@example
server local
timeout 3
retry 2
@end example

@comment *******************************************************************
@node client.shadow, Checkrad Overview, client.config, Top
@chapter client.shadow

This file contains IP addresses, port numbers and secret keys to
be used when connecting to Radius servers.

@subheading Syntax
The record for each server occupies one line. The format of the record is
somewhat similar to that of the system /etc/passwd file: it contains six
fields separated by colons. The fields are:

@enumerate 1
@item Server name
@item Server IP address or FQDN
@item Shared secret
@item Authentication port number
@item Accounting port number
@item Administrative portnumber
@end enumerate

@subheading Example

@example
local:localhost:guessme:1645:1646:5000
@end example

This line states that server @samp{local} has the hostname
@samp{localhost}. Its shared secret value is @samp{guessme},
authentication and accounting port numbers are 1645 and 1646
respectively, and the control channel is listening on port 5000.


@comment *******************************************************************
@node Checkrad Overview, checkrad.conf, client.shadow, Top
@chapter Checkrad Overview
@pindex checkrad

When Radius needs to query a particular NAS about the presence of a
given user, it calls the @code{checkrad} program and analizes its
exit code @ref{Checking Simultaneous Logins}.

The @code{checkrad} accepts the following command line options:

@table @samp
@item -d RADDB_DIR
Sets the name of radius configuration directory
@ref{Naming conventions}.

@item -h HOST
The IP address or domain name of the NAS to query.

@item -p PORT
The NAS port number the user seems to be in.

@item -t TYPE
The NAS type. This is used to determine the method of conversation
with the NAS.

@item -u USERNAME
Username to check.

@item -s SID
The session ID to check for.

@item -x DEBUG
The debug level.

@end table

The @code{checkrad} program exits with following exit codes:

@table @asis
@item 0
No session with the specified parameters was found to be active on the
NAS.

@item 1
The specified session is currently active on the NAS.

@item -1
@samp{Don't know}. This means that either NAS did not respond, or
@code{checkrad} was unable to parse its answer.
@end table

For example if @code{radiusd} needs to verify presence of user
@samp{foo} with session ID @samp{001} on port 23 of NAS @samp{myhost}
@ref{naslist example} it would run @code{checkrad} as follows:

@example
checkrad -t unix -h myhost.dom.ain -u foo -s 001 -p 23
@end example

@noindent

@comment *******************************************************************
@node checkrad.conf, Radwho, Checkrad Overview, Top
@chapter Configuring checkrad: @file{checkrad.conf} file
@cindex checkrad.conf
@cindex checkrad, configuring
@cindex Configuring checkrad.

The @file{raddb/checkrad.conf} file describes the ways to
communicate with NASes of different types and the way of parsing
their requests.

@subheading Syntax

The file follows simple @code{@var{keyword} @var{value}} oriented
syntax. Empty lines are ignored. The @samp{#} character introduces
an end-of-line comment.

The file consists of definition blocks. Each definition block starts
with a @code{type} keyword and continues up to the next @code{type}
keyword or to the end of file.

The definition block describes ways of communicating with the NAS of
given type.

@subheading Statements

@table @code
@item logfile @var{filename}
Specifies the filename to use for logging. Default is stderr.

@item debug @var{debug_spec}
Specifies debug level @ref{Debugging}.

@item type @var{type}
Introduces new definition block. @var{type} is a type of NAS which is
described by the block. Every NAS marked with this @var{type} in
@file{naslist} configuration file @ref{naslist} will be queried using
rules described in this block.

@item method @var{finger|snmp}
Specify the method to use while communicating with the NAS.

@item header @var{line} @var{header_string}
(Applies to @code{method finger}.) This statement describes the header
to be expected in the NAS reply.

The @var{line} argument specifies the response line number where
the header string should be present. Response lines are counted starting
from 1 and are separated from each other by a @code{\r\n} characters.

The @var{header_string} argument describes the format of a header line.
It is a string of header titles delimited by @samp{:}. If the string
starts with a punctuation character, this character is used as a
delimiter instead of a @samp{:}.

@item oid @var{oid_string}
(Applies to @samp{method snmp}.) This statement specifies the OID to
be queried when using SNMP method. The OID string can contain
@code{checkrad} metacharacters described below.

@item community @var{ident}
(Applies to @samp{method snmp}.) Specifies the community name to be
used while querying NAS.

@item match @var{match_definition}
Specifies the conditions to be met to identify the session as being
active. The format of @var{match_definition} string depends on query
method:

@table @code

@item finger
The comma-separated list of the statements in the form:

@example
@var{var}=@var{macro}
@end example

@noindent
where @var{var} is either a @code{$@var{number}} notation, meaning
@var{number}th column from the NAS output, or a name meaning the column
identified by this heading in the @code{header} statement. @var{macro}
is one of the @code{checkrad} macros.

For example, consider the usual UNIX finger output. It starts with a
header line saying:

@example
Login  Name   TTY   Idle    Login Time   Where
@end example

@noindent

then we could write the following rules:

@example
header 1 Login:Name:TTY:Idle:Login Time:Where
match Login=%u,TTY=%p
@end example

@noindent
the @code{header} string describes the headings to be found on the first
line of output, the @code{match} statements says that the value listed
in column 1 (heading @samp{Login}) must coincide with username and
column 3 (heading @samp{TTY}) must coincide with the NAS port number.

The same example can be rewritten as

@example
match $1=%u,$3=%p
@end example

@noindent
using column numbers instead of column names.

@item snmp
In this case @var{match_definition} should be a string containing
@code{checkrad} macros. For example, the following statement

@example
oid .1.3.6.1.4.1.307.3.2.1.1.1.5.%p
match %s
@end example

@noindent
tells @code{checkrad} that it should query the given oid, replacing
the @samp{%p} sequense by actual port number and expect a session
ID (@samp{%s}) in reply.

@end table

@end table

@subheading Macros

Following macros can be used in @code{match} and @code{oid} statements:

@table @code

@item %u
Expands to username as given by @code{-u} command line option.

@item %s
Expands to session id as given by @code{-s} command line option.

@item %d
Expands to session id converted to decimal representation.

@item %p
Expands to port number as given by @code{-p} command line option.

@item %P
Expands to port number + 1.

@end table

@menu
* Example:checkrad.conf example.         An example of checkrad configuration.
@end menu

@comment *******************************************************************
@node checkrad.conf example, , , checkrad.conf
@chapter An example of checkrad configuration
@cindex checkrad.conf, an example

@example
######
# Configuration file for checkrad 
# 
logfile "/var/log/checkrad.conf"

####
# How to query unix network access servers
# We suppose that unix boxes run fingerd service.
type unix
method finger
header 1 Login:Name:TTY:Idle:Login Time:Where
match Login=%u,TTY=%p,Where=%s

####
# Ascend MAX networks servers
# Field 2 is session_id (here we convert it to decimal),
# Field 9 is user name
# Port is not matched
type max
method finger
match $2=%d,$9=%u

####
# Cisco AS5300 terminal server
# No session_id in finger output. We match on username and port number.
type as5300
method finger
match $1=%p,$4=%u 

####
# Livingston terminal server
# Answers on SNMP queries
type livingston
method snmp
community public
oid .1.3.6.1.4.1.307.3.2.1.1.1.5.%P
match %s

@end example

@comment *******************************************************************
@node Radwho, Radlast, checkrad.conf, Top
@chapter Radwho
@pindex radwho

@code{Radwho} displays the list of users currently logged in by the
Radius server.

Default output information is made compatible with that of the standard
unix finger(1) utility. For each user the following information is
displayed: login name, name, connection protocol, NAS port, login date,
NAS name, assigned IP address or corresponding network name.

When used with @samp{-l} option, the long output format is used. In
this format the following information is output:

@table @samp
@item Login
Login name of the user
@item SessionID
Unique session ID assigned by the terminal server.
@item Proto
Connection prototype.
@item Port
Port number
@item When
Login date and time
@item From
The name of NAS that accepted the connection.
@item Location
Framed IP address or the corresponding network name.
@item Caller
Caller station ID ad reported by the NAS.
@item Duration
Duration of the session.
@end table

@menu
* Options: radwho options.      Command line options.
@end menu

@comment *L2****************************************************************
@node radwho options, , , Radwho
@chapter Radwho command line options
@cindex radwho, command line options

The following command line options can be used to modify the behaviour
of the program:

@table @samp
@item -A
@itemx --all
Display the information about logged-out users as well. The logged-out
users are shown with Proto field set to HUP.

@item -c
@itemx --calling-id
Display the calling station ID in the second column.

@item -d NAME
@itemx --directory NAME
Set the radius configuration directory name.

@item -D @{short|abbr|full@}
@itemx --date-formap @{short|abbr|full@}
Set the date representation. By default dates are output as
@code{DOW HH:MM}, where DOW means the day of week abbreviation,
HH and MM mean hours and minutes respectively. This corresponds to
option @samp{-D short}. Other available formats are:

@table @samp
@item abbr
Abbreviated date: MM/DD HH:MM, where MM is a two-digit month number,
DD --- a two-digit day of month.
@item full
Full data output, like this:

@example
Mon Dec 18 12:29:38 EET 2000
@end example

@end table

@item -e STRING
@itemx --empty STRING
Display any empty field as STRING. This is useful when the output of
@code{radwho} is fed to some analyzing program, as it helps to keep
the same number of columns on each line of output.

@item -F
@itemx --finger
Start in fingerd mode. In this mode @code{radwho} emulates the
behaviour of fingerd(8) utility. Use this option if starting
@code{radwho} from the /etc/inetd.conf line like this:

@example
finger  stream  tcp   nowait  nobody   /usr/sbin/radwho radwho -fL
@end example

@noindent
This mode is also enabled by default if @code{radwho} notices that its
name (argv[0]) is @samp{fingerd} or @samp{in.fingerd}.

@item -H
@itemx --no-header
Don't display header line.

@item -i
@itemx --session-id
Display session ID instead of GECOS in the second column.

@item -I @{smart|ip|nodomain@}
@itemx --ip-format @{smart|ip|nodomain@}
Change IP address representation. The meaning of the argument is as follows:

@table @samp
@item smart
Select the best representation. The following rules apply:

@enumerate 1
@item For a NAS use its short name from @file{naslist}. If there is no
short name, use its long name. If there is no long name either, go to
2.
@item Resolve IP address to FQDN.
@item If the IP cannot be resolved, use dotted-quad representation of
the IP
@end enumerate

@item ip
Display IP in dotted-quad form.

@item nodomain
If the IP can be resolved to a fully qualified domain name, use the
hostname part of it, i.e. any characters up to the first dot.
@end table

@item -u
@itemx --local-also
Display information about local users from the system @file{utmp} file.
May prove useful when running @code{radwho} as a finger daemon.

@item -n
@itemx --no-resolve
Do not resolve IP addresses. It is a synonim for -I ip.

@item -o FORMAT
@itemx --format FORMAT
Select customized output format. This can also be changed by setting
the value of environment variable @code{RADWHO_FORMAT}.
The format string is a comma-separated list of format specifications
in one of the following forms:

@table @asis
@item @var{field}
Output @var{field} with its default width, heading and alignment. The
field names and corresponding default values are discussed in detail below.
@item @var{field}:@var{width}
Output @var{field}, use column width @var{width}. If @var{width} starts
with @samp{+}, the field will be right-aligned, if it starts with
@samp{-}, the field will be left-aligned. Otherwise the default
alignment will be used
@item @var{field}:@var{width}:@var{heading}
The same as above, but also supplies the heading for the column
@end table

The field names are:

@table @code
@item login
Login name

@item orig
Original login name as supplied with the request.

@item port
NAS port number

@item sid
The Session ID

@item nas
The NAS name or IP address.

@item ip
Framed IP address assigned to the user, if it is provided framed
service.

@item proto
Connection protocol. Its possible values are:

@itemize @bullet
@item @samp{PPP} for a point-to-point link
@item @samp{SLIP} for a SLIP link
@item @samp{HUP} for closed session
@item @samp{shell} for shell user
@end itemize

@item date
Date/time when the session started

@item delay
Delay time @ref{Acct-Delay-Time}.

@item type
Entry type in decimal.

@item ptype
Port type. This is one of the following letters:

@multitable @columnfractions .15 .50
@item Type @tab Meaning
@item @samp{L}
@tab Local connection
@item @samp{R}
@tab Rlogin connection
@item @samp{S}
@tab SLIP connection
@item @samp{C}
@tab CSLIP connection
@item @samp{P}
@tab PPP connection
@item @samp{A}
@tab Auto PPP connection
@item @samp{E}
@tab Telnet session
@item @samp{T}
@tab ``Clear TCP'' connection
@item @samp{U}
@tab TCP login service
@item @samp{!}
@tab Console session
@item @samp{X}
@tab Shell
@end multitable

@item time
Total time of the session duration.

@item clid
The calling station ID.

@item uname
The GECOS field from local /etc/passwd, corresponding to the login name.
If the user does not have a local account, his login name is output.

@end table

@item -s
@itemx --secure
Run in secure mode. Queries without a user name are rejected.

@end table

@comment *******************************************************************
@node Radlast, Raduse, Radwho, Top
@chapter Radlast
@pindex radlast

The @code{radlast} utility lists sessions of specified users, NASes,
NAS ports and hosts, in reverse time order. By default, each line of output
contains the login name, NAS short name and port number from where the
session was conducted, host IP address or name, the start and stop
times for the session, and the duration of the session. If the session
is still continuing, @code{radlast} will so indicate.

When specified the @samp{-l} option, @code{radlast} produces long
output. It includes following fields:

@itemize @bullet
@item login name
@item NAS short name
@item port number
@item prototype
@item port type
@item Session ID
@item Caller ID
@item Framed IP address
@item Session Start Time
@item Session Stop Time
@item Duration of the Session
@end itemize


@menu
* Options: radlast options.      Command line options.
@end menu

@comment *******************************************************************
@node radlast options, , , Radlast
@chapter @code{radlast} command line options
@pindex @code{radlast}, options

Use following command line options to control the behaviour of
@code{radlast} utility:

@table @samp
@item -@var{number}
@itemx -c @var{number}
@itemx --count @var{number}
When given this option @code{radlast} will output at most this many
lines of information. 

@item -f
@itemx --file @var{name}
Read the specified file instead of the default @file{/var/log/radwtmp}.

@item -h @var{hostname}
@itemx --host @var{hostname}
Report the logins from given host. Host can be either a name or a
"dotted quad" internet address.

@item -n @var{shortname}
@itemx --nas @var{shortname}
Report the logins from given Network Access Server (NAS).

@item -l
@itemx --long-format
"Long" output format. Report all the information stored in
@file{radwtmp} file.

@item -p @var{number}
@itemx --port @var{number}
Report the logins on a given port. The port may be specified either fully or
abbreviated, e.g. @code{radlast -p 3} or @code{radlast -p S03}.

@item -s
@itemx --show-seconds
Report the duration of the login session in seconds instead of the
default days, hours and minutes.

@item -t
The same as @samp{-p}. This flag is provided for compatibility with last(1).

@item -w
@itemx --wide
Widen the duration field to show seconds as well as the default days,
hours and minutes.

@end table

If multiple arguments are given, the logical OR operation between them
is assumed, i.e. the information selected by each argument
is printed. This, however, does not apply to @code{-c} option. This option is
always combined with the rest of command line by logical AND.

The pseudo-user ~reboot logs in on every reboot of network access
server.

If @code{radlast} is interrupted, it indicates to what date the search
was progressed.

@comment *******************************************************************
@node Raduse, Radzap, Radlast, Top
@chapter Raduse
@pindex raduse

The @code{raduse} utility shows the usage of dialup lines in the
realtime.

@menu
* Display:raduse display.       What is displayed.
* Options:raduse options.       Command line options modify the default
                                display.
* Commands:raduse commands.     Interactive mode commands. 
@end menu

@comment *L2****************************************************************
@node raduse display, raduse options, , Raduse
@chapter Display
@cindex raduse display
@cindex display, raduse

At the top of output the summary information is displayed. It consists
of two lines. First line shows the statistic collection uptime and
current date/time. Second line shows total number of lines, number of
active lines, number of idle (inactive) lines and load percentage.

The dialup statistics is displayed in the area below. For each dialup
line three lines of data are shown.

First line shows the network access server name, port number on that
server, number of logins registered on this line, status of the line,
amount of time the line keeps the current status, and date and time
where the line has switched to the current status.

If the line is currently active, the status field displays login
name of the user logged in on this line. If the line is inactive, the
word @samp{[Idle]} is displayed.

Second and third lines display active and idle usage summary. They show
following data: total time the line is in the given state, maximum
amount of time in this state, and starting date and time when maximum
duration was perceived.

The example of default display:

@example
uptime    90+20:35         Sun Dec 17 12:21                                    
235 lines,  71 active, 164 idle. Pool load 0.30                                
                                                                               
                                                                               

max          001  2796 [idle]                 00:05 Sun Dec 17 12:16           
             43+00:17     1+22:39 Fri Sep 22 18:04 - 16:44                     
             47+20:22       06:25 Thu Oct 05 02:24 - 08:50                     
max          002  2877 [idle]                 00:09 Sun Dec 17 12:11           
             41+06:56       10:55 Sat Oct 28 21:20 - 07:15                     
             49+13:35       05:32 Mon Oct 02 00:33 - 06:05                     
max          003  3000 [idle]                 00:08 Sun Dec 17 12:12           
             39+14:42       19:44 Thu Nov 02 14:52 - 10:36                     
             50+11:22       07:29 Wed Oct 11 23:30 - 06:59                     
max          004  2829 jsmith                 00:05 Sun Dec 17 12:15           
             41+21:11     1+00:04 Sun Sep 24 12:17 - 12:21                     
             48+23:28       04:51 Sat Oct 07 03:42 - 08:33                     
max          005  2913 gray                   00:41 Sun Dec 17 11:40           
             40+12:01       15:24 Mon Dec 11 19:18 - 10:43                     
             50+08:03       11:58 Wed Nov 29 13:43 - 01:41                     
max          006  3014 roland                 00:39 Sun Dec 17 11:41           
             42+02:10       22:28 Sun Sep 24 13:46 - 12:15                     
             48+17:39       05:30 Fri Nov 24 01:57 - 07:28                     
max          007  2937 [idle]                 00:06 Sun Dec 17 12:15           
@end example

This default display can be altered using command line options or
interactive commands

@comment *L2****************************************************************
@node raduse options, raduse commands, raduse display, Raduse
@chapter Raduse Command Line Options
@cindex raduse, command line options

The following options modify the behaviour of @code{raduse}:

@table @samp
@item -b
@itemx --brief
Start up in brief mode. In this mode only first line of information for
each dialup line is displayed.
@item -d @var{count}
@itemx --display @var{count}
Show only count displays, then exit. A display is considered to be one
update of the screen.
@item -D
@itemx --dump
Dump the statistics database to the standard output and then
exit. This is for debugging purposes only.
@item -I
@itemx --no-idle-lines
Do not display idle lines. By default @code{raduse} displays all dialup
lines.
@item -i
@itemx --interactive
Use interactive mode. In this mode any input is immediately read for
processing. @ref{raduse commands} section for the description of
commands usable in interactive mode. After processing each command the
screen is updated immediately, no matter was the command understood or
not. This mode is the default when the standard output is an
intelligent terminal.
@item -n
@itemx -no-interactive
Use non-interactive mode.
@item -s @var{num}
@itemx --delay @var{num}
Specify delay in seconds between screen updates.
@item -w
@itemx --widen
Widen the time display fields to show the seconds.
@item -l
@item --list-nas
List the names and IP numbers of network access servers and then exit.
@item -h
@itemx --help
Display short usage summary.
@end table


@comment *L2****************************************************************
@node raduse commands, , raduse options, Raduse

The following commands are understood when @code{raduse} is in
interactive mode. Some commands require an argument. Such commands
are followed by the word @var{arg}. When @code{raduse} gets such command
it displays a prompt and waits for user to enter the necessary data.

After processing each command the screen is updated immediately,
no matter was the command understood or not.

@table @code
@item RET
Refresh the screen immediately
@item SPC
Refresh the screen immediately
@item C-l
Clear and redraw the display.
@item ^
(Caret) go to the first page.
@item b
Toggle brief display mode.
@item C-b
Move one page backwards.
@item C-f
Move one page forwards.
@item i
Toggle idle line display on or off.
@item j
Move one line forwards.
@item k
Move one line backwards.
@item G
Move to the last page.
@item $
Move to the last page.
@item q
Quit the program
@item s @var{arg}
Change the number of seconds to delay between screen updates. 
@item t @var{arg}
Display lines on a given Network Access Servers. The user is
prompted to input the NAS names. The names should be separated by
whitespace. The word @samp{all} returns to display of all NAS lines.
@end table

@comment *******************************************************************
@node Radzap, Radgrep, Raduse, Top
@chapter Radzap
@pindex radzap

@code{radzap} searches the Radius accounting database for matching login
records and closes them.

At least one of @samp{-n}, @samp{-p} options or username must be
specified. If they are used in conjunction, they are taken as if
joined by logical AND operation.

@samp{radzap} operates in two modes: silent and confirm. The silent
mode is enabeld by default. When run in this mode, radzap deletes
every record that matched the search conditions given.

In confirm mode @samp{radzap} will ask for a confirmation
before zapping each matching record. Every line beginning with a `y'
is taken as positive response, otherwise it is taken as negative
response.

The confirm mode is toggled by the command line option @samp{-c}.

@subheading Syntax

@example
radzap [options] [username]
@end example

@noindent
Options are:

@table @samp
@item -c
@itemx --confirm
Enable confirm mode. 
@item -q
@itemx --quiet
Disable confirm mode.
@item -h
@itemx --help
Display short help summary and exit.
@item -n @var{NAME}
@itemx --nas @var{NAME}
Specify NAS name to zap user from.
@item -p @var{PORT}
@itemx --port @var{PORT}
Specify the port number of the session to be zapped. The port number
can be specified either in its full form, i.e @code{radzap -p S02} or in
its short form, like @code{radzap -p 2}.

@end table

@comment *******************************************************************
@node Radgrep, Radping, Radzap, Top
@chapter Radgrep
@pindex radgrep

This utility allows to quickly lookup the user in the radius accounting
database using a regular expression match.

@code{radgrep} scans the output of @code{radwho} utility and outputs
only the lines that match given @code{grep} regular expressions.

@subheading Syntax
@code{radgrep} accepts two sets of options separated by @samp{--}
(double-dash) sign. First subset is passed as command line to
@code{radwho} utility. The second one is passed to @code{grep}.

@comment *******************************************************************
@node Radping, Radauth, Radgrep, Top
@chapter Radping
@pindex radping

This utility is a shell program that determines the user's
framed IP address and runs @code{ping} on that address.

@subheading Syntax
@example
radping @var{username}
radping -c @var{calling-station-id} 
@end example

The second way of invoking the program allows to use calling station
ID in order to indicate the user.

@comment *******************************************************************
@node Radauth, Radtest, Radping, Top
@chapter Radauth
@pindex radauth

The @code{radauth} utility sends the Radius server Access-Request
packet and displays the result it gets. It can be used to test the
configuration files. The usage is:

@example
raduse [options] username password
@end example

Actually the program is a wrapper that collects its arguments and calls
@code{radtest} @ref{Radtest} with the options collected and passes it
the following script ($LOGIN and $PASSWORD variables contain the username
and password):

@example
        auth_packet = @{
                User-Name = $LOGIN,
                Password = $PASSWD
	@};
        send auth 1 $auth_packet;
        expect 2 "rejected (" $REPLY_CODE \
                  "); Reply-Message = " $REPLY[Reply-Message];
	print "Authentity confirmed, reply pairs: " $REPLY;
@end example

The program determines which Radius server to use, the authentication
port number and shared secret following the procedure common for all client
programs @ref{Client Overview}. @ref{radtest usage} for a list of
accepted command line options.

@comment *******************************************************************
@node Radtest, Radctl, Radauth, Top
@chapter Radtest
@pindex radtest

@code{radtest} program is designed to test the functionality of
the Radius daemon. It sends the daemon arbitrary requests and
displays the replies it gets.

@menu
* Usage: radtest usage.         Invocation and command line options.
* Syntax: radtest syntax.       The input language syntax.
* Examples: radtest examples.   Examples of using @code{radtest}.
@end menu

@comment *L2****************************************************************
@node radtest usage, radtest syntax, , Radtest
@chapter Invocation and command line options.

The @code{radtest} is invoked using the following syntax:

@example
radtest [@var{options}] [@var{filename} ...]
@end example

When started without filename argument, @code{radtest} enters 
interactive mode. In this mode the user is allowed to input
arbitrary commands and execute them interactively. The program
prompts the user by @samp{> } characters.

If the filenames are supplied, @code{radtest} treats them as
names of the files containing scripts and executes these
files.

The variables used in scripts can be set from command line using this
syntax:

@example
@var{VARIABLE}=@var{VALUE}
@end example

@noindent
Note, that no spaces are allowed on either side of the equal sign.

Following options can be used to control the behaviour of
@code{radtest}.

@table @samp

@item -d @var{path}
@itemx --directory @var{path}
Specifies the directory where Radius startup files reside.

@item -x @var{debug_level}
@itemx --debug @var{debug_level}
Specifies the debugging level @ref{Debugging}.

@item -p @var{portno}
@itemx --port @var{portno}
Sets the port number to use when sending authentication requests.
@var{portno} can be either a decimal number or string representing a valid
service from @file{/etc/services}. Accounting port is computed as
@var{portno} + 1.

@item -q
@itemx --quick
Quick startup. When given this flag @code{radtest} does not process startup
files.

@item -r @var{number}
@itemx --retry @var{number}
Specifies how many times @code{radtest} should retry sending requests if
the server does not respond within the timeout interval.

@item -t @var{number}
@itemx --timeout @var{number}
Specifies the amount of time @code{radtest} should wait for the reply before
giving up.

@item -h
@itemx --help
Display short usage summary and exit.

@item -l
@itemx --license
Display the license and exit.

@item -v
@itemx --version
Display the version and exit.

@end table

@comment *L2****************************************************************
@node radtest syntax, radtest examples, radtest usage, Radtest
@chapter The input language syntax

The @code{radtest} program gets as its argument the filename of the test
script to run. Currently its syntax is very simple: It consists of
the statements of three kinds:

@enumerate 1
@item Assignment statements
@item Send statements
@item Expect statements
@end enumerate

Each statement is terminated by a semicolon. The statements are
discussed in detail below.

@subheading Expressions

The term @dfn{expression} in the discussion below means one of the
following:

@table @asis
@item 1. Dereferenced variable name.
This is the name of a previously defined variable with a @samp{$}
sign prepended to it, e.g: @code{$VAR}. In this case the resulting
value is that of the variable being dereferenced.	

@item 2. String enclosed in double quotes
E.g. @code{"a string"}

@item 3. Integer value

@item 4. IP address
IP addresses are specified in `dotted quad' notation,
e.g. @code{127.0.0.1}

@item 5. An A/V pair list.
A comma-separated list of A/V pairs. The whole list is enclosed
in curly braces. Each pair is represented by the following construct:

@example
		@var{dict_name} = @var{value}
@end example

@noindent
where @var{dict_name} is a valid radius dictionary name, i.e.
the name which is listed in @code{ATTRIBUTE} statement in one
of the radius dictionary files.

For example the following is a valid value-pair list:

@example
@{ NAS-Name = "localhost", NAS-IP-Address = 127.0.0.1,
   NAS-Port-Id = 1, User-Name = $name @}
@end example

@item 6. Concatenation
This means a concatenation of the two or more value-pair lists. The
sign for such concatenation is @samp{+}. For example, assuming

@example
a = @{ NAS-Name = "localhost,
       NAS-IP-Address = 127.0.0.1 @};
b = @{ NAS-Port-Id = 1, User-Name = $name @};
@end example

@noindent
the statement:

@example
		$a + $b
@end example
@noindent
would produce the same list as in the example above, except
that the @code{$name} will be already substituted by its value.

@item 7. Dictionary name
This means a valid radius dictionary value name, i.e. the name which
is listed in a @code{VALUE} statement in one of the radius
dictionary files.

@end table
	

@subheading An assignment statement

This statement assigns a value to a variable. Syntax is:

@example
@var{variable_name} = @var{expression} ;
@end example

@noindent
where @var{variable_name} is a name of a variable, @var{value} is its
value. The @samp{=} and @samp{;} are required. 

@subheading Send statement

This statement sends the packet to the radius server.

The syntax is:

@example
send auth @var{PACKET_CODE} @var{PAIRLIST}
send acct @var{PACKET_CODE} @var{PAIRLIST}
@end example

@noindent
where @var{PACKET_CODE} is the integer value of the radius packet code,
@var{PAIRLIST} is a value-pair list to be sent to the server.

The following statement:

@example
send auth 1 @{ User-Name = "hamlet", Password = "pwd",
               NAS-IP-Address = 127.0.0.1, NAS-Port-Id = 1 @} ;
@end example

@noindent
sends the radius authentication request (code 1) to authenticate the
user @samp{hamlet} with password @samp{pwd} coming from the port 1 on
the NAS 127.0.0.1.

The statement:

@example
send acct 4 @{ Acct-Status-Type = Start,
               Acct-Session-Id = "00" @} +
            @{ User-Name = "hamlet", Password = "pwd",
               NAS-IP-Address = 127.0.0.1, NAS-Port-Id = 1 @} ;
@end example
@noindent
sends the accounting record (code 4) for the above user, querying
server to mark the start of his session.

@subheading Expect statement

The expect statement follows the syntax:

@example
expect @var{CODE} ;
expect @var{CODE} @var{FAILURE_MESSAGE} ;
@end example

@noindent
where @var{CODE} is an integer number of the response packet to expect
from the radius server. If the server replies with this code, the
statement succeeds, otherwise it fails, prints the diagnostics on
stderr and @code{radtest} finishes its execution.

The @var{FAILURE_MESSAGE} is a string to display when the expect fails
instead of the standard message;

@comment *L2****************************************************************
@node radtest examples,              , radtest syntax, Radtest
@chapter Examples of @code{radtest} scripts

@subheading Authentication test

The following script sends the authentication request to the server

@example

auth_packet = @{ User-Name = $username, Password = $password,
		 NAS-Port-Id = $port,
		 NAS-Identifier = "localhost",
		 NAS-IP-Address = 127.0.0.1 @};

send auth 1 $auth_packet;
expect 2 "Returned " $REPLY_CODE ", Reply-Message = " $REPLY[Reply-Message] ;

## EOF
@end example

Before calling this script, the variables @code{username},
@code{password} and @code{port} must be assigned corresponding values.
If the above script is saved in the file @file{auth.t}, then it can
be run as:

@example
% radtest username=\"gray\" password=\"foo\" port=1 auth.t
@end example
@noindent
Note the use of quotes to assign string values and the use of escape
characters (@samp{\}) to prevent the quotes from being interpreted by
the shell.

@subheading Accounting test

@example

send acct 4 @{ User-Name = $username,
		Acct-Status-Type = $type,
		Acct-Session-Id = $sid,
		NAS-Port-Id = $port,
		NAS-Identifier = "localhost",
		NAS-IP-Address = 127.0.0.1 @};
expect 5;
@end example

This script can be run as:

@example
% radtest username=\"gray\" sid=\"abc\" port=1 type=Start acct.t
@end example
@noindent

to send a start request or as:

@example
% radtest username=\"gray\" sid=\"abc\" port=1 type=Stop acct.t
@end example
@noindent

to send a stop request.

@comment *******************************************************************
@node Radctl, Radctl.sh, Radtest, Top
@chapter Radctl
@pindex radctl

@code{radctl} is a control interface to @code{radiusd} daemon. It allows
user running it to query @code{radiusd} about various aspects of its
work and issue administrative commands to it. It is planned to replace
usual signal interface.

@menu
* Configuring:radctl configuration.     Configuring @code{radctl}.
* Invocation:radctl invocation.         How to invoke @code{radctl}.
* Commands:radctl commands.             Commands available. 
@end menu

@comment *L2****************************************************************
@node radctl configuration, radctl invocation, , Radctl
@chapter Configuring @code{radctl}.
@cindex configuring radctl
@cindex radctl, configuring

To configure Radius to use @code{radctl} control channel the following
actions must be performed:

@table @asis

@item Configure the port number to listen to.
The port number to listen to incoming control requests is set in
@code{cntl} statement in @file{config} file.

@item Create administrative huntgroup.
Since @code{radctl} interface provides some potentially dangerous
commands, we recommend to restrict its usage to some trusted
hosts. This can be done using huntgroups mechanism @ref{huntgroups}.
The administrative huntgroup definition should include the
trusted host IP address and name of a command which is allowed from
this host. The command name must be listed in @code{State} attribute.
See example below.

@item Create administrative user.
The administrative user profile should be created in the @file{users}
file. It should be restricted to administrative huntgroup.

@end table

@heading Example @code{radctl} configuration.

In the example below, we suppose that port 5000 is chosen as Radius
administrative port, administrative user name is ROOT, and he is
allowed to connect only from localhost. Then the following modifications
would be needed:

@subheading @file{config} file

@example
cntl @{
        port 5000;
@};
@end example

@subheading @file{huntgroups} file

@example
ROOT    NAS-IP-Address = 127.0.0.1, State = "getpid"            NULL
ROOT    NAS-IP-Address = 127.0.0.1, State = "get-m-stat"        NULL
ROOT    NAS-IP-Address = 127.0.0.1, State = "get-q-stat"        NULL
ROOT    NAS-IP-Address = 127.0.0.1, State = "reload"            NULL
ROOT    NAS-IP-Address = 127.0.0.1, State = "restart"           NULL
ROOT    NAS-IP-Address = 127.0.0.1, State = "shutdown"          NULL
ROOT    NAS-IP-Address = 127.0.0.1, State = "dumpdb"            NULL
@end example

@subheading @file{users}

@example
ROOT    Auth-Type = System,
                Huntgroup-Name = "ROOT"
        Service-Type = RADIUS-Administrative-User
@end example

@comment *L2****************************************************************
@node radctl invocation, radctl commands, radctl configuration, Radctl
@chapter How to invoke @code{radctl}.
@cindex radctl, invocation

Radctl understands following command line options:

@table @code
@item -d DIR
@itemx --directory DIR
Specifies the directory where client configuration files reside
@ref{Client Overview}.

@item -s HOST
@itemx --server HOST
Specifies the name of the server to connect to. @emph{Please note} that
this is not a domain name, but rather the name under which server is
listed in @file{client.shadow} file @ref{client.shadow}.

@item -u USERNAME
@itemx --user USERNAME 
Specifies the username. If started without this option, @code{radctl}
will prompt for the username.

@item -p PASSWORD
@itemx --password PASSWORD
Specifies the password to be used while connecting to the server. If
started without this option, @code{radctl} will prompt user for the
password.

@item -v
@itemx --verbose
Enable verbose mode. In verbose mode all conversation with the
Radius server is echoed on stderr.

@item -?
@itemx --help
Display short usage help and exit.
@end table

@comment *L2****************************************************************
@node radctl commands, , radctl invocation, Radctl
@chapter Radctl commands
@cindex radctl commands
@cindex commands, radctl

@subheading Internal commands

These commands modify the behaviour of radctl itself.

@table @code

@item -?
@itemx -help
Output short help information.

@item -q
@itemx -quit
Exit the program.

@item -s
@itemx -server
Set the name of radius server to query @ref{Client Overview}.

@item -v
@itemx -verbose
Toggle verbose mode on/off. When verbose mode is on, @code{radctl}
displays to stderr detailed log of its conversation with Radius
server.

@end table

@subheading Server commands

These are sent directly to the server:

@table @code
@item getpid
Output the PID of the master Radius process.

@item get-m-stat
Display detailed memory usage statistics.

@item get-q-stat
Display detailed queue statistics. Four fields are displayed for each
queue:
@enumerate 1
@item Queue number
@item Number of pending requests
@item Number of processed requests still residing in the queue
@item Total number of requests in queue
@end enumerate

@item dumpdb
Tells @code{radiusd} to dump its user database, i.e. the parsed
contents of files @file{hints}, @file{huntgroups} and @file{users}
to disk file. The filename is @file{radlog/radius.parse}
@ref{Naming conventions}.

@item reload @var{what}
Instructs the server to reload a particular part of its configuration.
The @var{what} part specifies which configuration file to reload:

@table @code
@item all
Reload all configuration files.

@item users
Reload the @file{users} file.

@item dict
Reload @file{dictionary} file. This implies reloading of @file{users},
@file{huntgroups} and @file{hints}.

@item huntgroups
Reload @file{huntgroups} file.

@item hints
Reload @file{hints} file.

@item clients
Reload @file{clients} file.

@item naslist
Reload @file{naslist} file.

@item realms
Reload @file{realms} file.

@item deny
Reload @file{access.deny} file.

@item sql
Reload @file{sqlserver} file.

@item rewrite
Reload @file{rewrite} file.

@end table

@item restart
Instructs Radius to flush all request queues and restart itself. In
order to use this command, the @code{radiusd} program should have
been started with its full pathname.

@item shutdown
Instructs Radius to flush all pending requests and shut down.

@end table


@comment *******************************************************************
@node Radctl.sh, Builddbm, Radctl, Top
@chapter Radctl.sh
@pindex radctl.sh

The @code{radctl.sh} utility provides the alternative way to communicate
with the radius server. It uses the signal mechanism in order to do so.
It is invoked as:

@example
radctl.sh @var{command}
@end example

The valid @var{command}s are as follows:

@table @code

@item start
If @code{radiusd} is not running already, it is started. The
rest of the command line arguments is passed as command line to the
server.

@item stop
Stops running @code{radiusd}.

@item restart
Stops the server and then starts it again. The rest of the arguments
is passed as command line to the server.

@item reload
Causes running @code{radiusd} server to re-read its configuration files.

@item dumpdb
Tells @code{radiusd} to dump its user hash table into the file
@file{/var/log/radius.parse}. This can be used for debugging the
configuration files.

@item status
@code{radiusd} reports its memory usage statistics. The information is
logged under @code{Info} log level.

@item which
Reports the information about running copy of @code{radiusd}.

@end table

@comment *******************************************************************
@node Builddbm, , Radctl.sh, Top
@chapter Builddbm
@pindex buildbm

@subheading Usage
@code{Builddbm} converts the plaintext Radius users database into
DBM files. Some versions of Radius daemon have used this to
speed up the access to the users database.

Howewer in this implementation things go the other way around.
The server reads entire plaintext database, converts it into internal
form and stores into hash table which provides for fast
access. Actually, using DBM version of the users database slows
down the access unless the machine which runs Radius daemon is
short of address space for the daemon to store the users database into.

@subheading Syntax
When used without arguments, @code{builddbm} utility attempts to
convert file @file{raddb/users} into @file{raddb/users.db} or
@file{raddb/users.pag}, @file{raddb/users.dir} pair, depending on the
version of DBM library used.

If used with one argument, the argument is taken as the name of the
plaintext database file to operate upon.

Use the following command line options to modify the operation of
@code{buildbm}:

@table @samp
@item -d @var{dir}
Specifies alternate directory for the Radius configuration
files. This defaults to @file{@value{raddb}}.

@item -i @var{filename}
Specifies alternate input file instead of default
@file{raddb/users}. The @samp{-i} option is provided
for compatibility with other versions of @code{builddm}. It can
safely be omitted.

@item -h
Outputs short usage summary and exits with 0 exit code.
@end table

@comment *******************************************************************


@include attributes.texinfo


@comment *******************************************************************
@node Bugs, , , Top
@chapter Reporting Bugs

It is possible you will encounter a bug in one of Radius programs. If this
happens we would like to hear about it. As the purpose of bug reporting
is to improve software, please be sure to include maximum information
when reporting a bug. The information needed is:

@itemize @bullet
@item Conditions under which the bug appears.
@item Version of the package you are using.
@item Compilation options used when configuring the package.
@item If the bug is found in @code{radiusd} daemon, run
@samp{radiusd -v} and include the output it produces.
@item Contents of radius configuration directory (@value{RADDB} or whatever
you have set it to while configuring).
@item Log messages produced.
@end itemize

Send your report to bug-gnu-radius@@gnu.org. Allow me a couple of
days to answer.


@comment *******************************************************************

@node Program Index, Attribute Index, , Top
@unnumbered Program Index
@printindex pg

@node Attribute Index, Concept Index, Program Index, Top
@unnumbered Attribute Index
@printindex vr

@node Concept Index, ,Attribute Index, Top
@unnumbered Concept Index
@printindex cp

@contents

@bye

Local Variables:
compile-command: "makeinfo --force radius.texinfo"
End:
