This is Info file radius.info, produced by Makeinfo version 1.68 from
the input file radius.texinfo.

INFO-DIR-SECTION GNU radius
START-INFO-DIR-ENTRY
* Radius: (radius).     The GNU radius
END-INFO-DIR-ENTRY

   This file documents the GNU radius

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

   Copyright (C) 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.

   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.


File: radius.info,  Node: Top,  Next: Distrib,  Up: (dir)

The GNU Radius
**************

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

   This Info file documents the version 0.92 of the package.

* 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 `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.


File: radius.info,  Node: Distrib,  Next: Copying,  Prev: Top,  Up: Top

Distribution
************

   GNU Radius is "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 `ftp://ftp.gnu.org/pub/gnu/gnu-radius'


File: radius.info,  Node: Copying,  Next: Intro,  Prev: Distrib,  Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 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.

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.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. 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.

  1. 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.

  2. 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:

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

       b. 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.

       c. 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.)

     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.

  3. 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:

       a. 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,

       b. 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,

       c. 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.)

     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.

  4. 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.

  5. 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.

  6. 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.

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

  8. 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.

  9. 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.

 10. 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.

                                NO WARRANTY

 11. 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.

 12. 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 OF TERMS AND CONDITIONS

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.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  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.

   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:

     Gnomovision version 69, Copyright (C) 19YY 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.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `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:

     Yoyodyne, Inc., hereby disclaims all copyright
     interest in the program `Gnomovision'
     (which makes passes at compilers) written
     by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   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.


File: radius.info,  Node: Intro,  Next: Glossary,  Prev: Copying,  Up: Top

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 "advanced", because it allows for authentication, accounting
and monitoring of the user connections.

   It is "customizable", because you can fine-tune it to suit your
needs.

   It is "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.


File: radius.info,  Node: Glossary,  Next: Operation,  Prev: Intro,  Up: Top

Radius Glossary
***************

   Throughout this document the following terms are used:

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

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.

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

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.

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

A/V pair
     Stands for Attribute-Value pair *Note Attributes::.

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

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

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.


File: radius.info,  Node: Operation,  Next: Naming conventions,  Prev: Glossary,  Up: Top

How Radius operates.
********************

   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.


File: radius.info,  Node: Packets,  Next: Attributes,  Prev: Operation,  Up: Operation

Radius packets
**************

   The term "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

`Code'
     The code field identifies the type of the request.

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

`Length'
     The length of the packet

`Authenticator'
     The 16-byte hash value used to authenticate the packet.

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

* Menu:

* Authentication requests::
* Accounting requests::


File: radius.info,  Node: Authentication requests,  Next: Accounting requests,  Up: Packets

Authentication requests
***********************

   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 `User-Name' attribute *Note
User-Name::. It should contain either a `NAS-IP-Address' attribute or
`NAS-Identifier' attribute, or both of them.  It also must contain
either a `Password' attribute or `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 `NAS-Port' or `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:

   * Access-Accept

   * Access-Reject

   * Access-Challenge

   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 `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 `Reply-Message'
attributes, and may also include a single `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
`Reply-Message' attributes of the request. It then sends its original
Access-Request with a new request ID and Request Authenticator, with
the `Password' attribute replaced by the encrypted user's response, and
including the `State' attribute from the Access-Challenge, if any.


File: radius.info,  Node: Accounting requests,  Prev: Authentication requests,  Up: Packets

Accounting requests
*******************

   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 *Note 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:

   * User-Password

   * CHAP-Password

   * Reply-Message

   * State

   Either `NAS-IP-Address' or `NAS-Identifier' must be present in an
Accounting-Request.  It should contain a `NAS-Port' or `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.


File: radius.info,  Node: Attributes,  Next: User Profile,  Prev: Packets,  Up: Operation

Attributes
**********

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

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

   * Integer

   * IP-number

   * String

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

   * 1         Login-User

   * 2         Framed-User

   * 3         Callback-Login-User

   * 4         Callback-Framed-User

   * 5         Outbound-User

   * 6         Administrative-User

   The symbolic names are assigned to attributes and values in the
dictionary file *Note dictionary file: dictionary.

   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 "Vendor-Specific" is available to allow
vendors of the NAS hardware or software to support their own extended
attributes. *Note Vendor-Specific attribute: Vendor-Specific.

   *Note Attribute list::.


File: radius.info,  Node: User Profile,  Next: Processing the request,  Prev: Attributes,  Up: Operation

User Profile
************

   The user profile information is stored in the files `users', `hints'
and `huntgroups' in the radius database directory (raddb, *Note Naming
conventions::. These files follow the same syntax.

Comments
--------

   A pound sign (`#') causes the rest of line to be ignored.

File inclusion
--------------

   A statement in the form

     $INCLUDE filename

   causes the contents of the file named `filename' to be included.

Records
-------

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

     NAME    CHECK-PAIRS     REPLY-PAIRS

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

NAME
     The username consists of up to 32 alphanumeric characters,
     underscores (`_'), dashes (`-') or dots (`.').  The special
     username `DEFAULT' or `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.

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

REPLY-PAIRS
     A "list" of reply-pairs, i.e. the A/V pairs that the server replies
     with if the entry is matched.

   A term "list" used above means the comma-separated list of A/V pairs
*Note Attributes:: or the word `NULL' to specify the empty list. Each
pair in the list follows the syntax:

     ATTRIBUTE-NAME  OP      VALUE

where
ATTRIBUTE-NAME
     is a name of attribute as specified in the dictionary file *Note
     Dictionary file: dictionary.

OP
     is one of the following operation codes:

        * `='

        * `!='

        * `<'

        * `<='

        * `>'

        * `>='

VALUE
     Specifies the attribute value. The value syntax is:

    INTEGER
          The decimal integer number

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

    STRING
          A string of characters enclosed in double-quotes (`"').

    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.

* Menu:

* Matching rules::      How the record is matched.


File: radius.info,  Node: Matching rules,  Prev: User Profile,  Up: User Profile

Packet Matching Rules
*********************

   When Radius is attempting to find the record in its database that
matches given request packet *Note Packets::, it uses the following
rules:

1. Match the username
     If the username from the packet does not match the one in the
     record, the record does not match. *Please note* that the special
     usernames `DEFAULT' or `DEFAULT%d' (%d means any decimal number)
     match any username.

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

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
     `Auth-Type', `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:

          NAS-Port-Id <= 20

     and the request pair is:

          NAS-Port-Id = 10

     Then Radius will perform the following comparison:

          10 <= 20

     which will, of course, succeed.

4. If match fails try to match next record.

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

File: radius.info,  Node: Processing the request,  Next: Realms,  Prev: User Profile,  Up: Operation

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 *Note
Logging::.

   The following checks are performed:

Check if the username is supplied
     If the packet lacks `User-Name' attribute it is not processed

Check if the NAS is allowed to speak
     The source IP address of the machine that sent the packet is looked
     up in the `clients' file *Note clients::. If no match is found,
     the request is not processed.

Compute the encryption key
     Using the data from the packet and the shared key value from the
     `clients' file, Radius computes the MD5 encryption key that will
     be used to decrypt the value of the `Password' attribute.

Process `hints' file.
     Radius matches the packet against the contents of `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.
     *Please note* that the special usernames `DEFAULT' or `DEFAULT%d'
     (%d means any decimal number) match any username.

     Rule 2. Modify the attributes.

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

     If the reply-pairs contain the `Rewrite-Function' attribute, the
     function specified in the value of this attribute is applied *Note
     rewrite::.

     If the reply pairs contain `Fall-Through' attribute and its value
     is `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.

     *Note hints::


File: radius.info,  Node: Realms,  Prev: Processing the request,  Up: Operation

Realms
******

   We call a "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 "realm" to be authorized using another
"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 "A" and "B" and let's call the
corresponding servers "radius.a" and "radius.b". If the user of
affiliate "A" moves to city "B" he is no longer able to use the service
provided by "radius.a", neither is he able to use the service provided
by "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 `foo' connects to the equipment of the "B" and
authenticates itself as `foo@A' then Radius server "radius.b" knows
that the user belongs to another realm and passes the request to server
"radius.a". When the latter responds, server "radius.a" simply passes
the response back to NAS. In other words "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.


File: radius.info,  Node: Naming conventions,  Next: Invocation,  Prev: Operation,  Up: Top

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:

"Configuration or database directory"
     A directory where all configuration files are stored.

"Log directory"
     A directory where `radiusd' stores its radius files.

"Accounting directory"
     A directory where `radiusd' stores accounting detail files *Note
     Detailed Request Accounting::.

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

Directory                     Short Name  Default location                 
Configuration directory       raddb       /etc/raddb                       
Log directory                 raddb       /usr/adm                         
Accounting directory          radacct     /usr/adm/radacct                 

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

     ... this information is contained in file `raddb/sqlserver'

we actually mean `/etc/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
`-d' or `--directory', which introduces the configuration directory
path.


File: radius.info,  Node: Invocation,  Next: Configuration files,  Prev: Naming conventions,  Up: Top

How to start the daemon.
************************

   When started `radiusd' uses the configuration values from the
following sources (in order of increasing precedence):

   * Compiled-in defaults

   * `raddb/config' file.

   * Command line arguments

   The following command line options are accepted:

`-A'
`--log-auth-detail'
     Enable detailed authentication logging. When this option is
     specified each authentication request is logged to the file
     `radacct/NASNAME/detail.auth', where NASNAME is replaced by the
     short name of the NAS from `raddb/naslist' *Note Naming
     conventions::.

`-a DIR'
`--acct-directory DIR'
     Specify accounting directory.

`-c'
`--check-config'
     Check configuration files and exit. All errors are reported via
     usual log channels.

`-b'
`--dbm'
     Enable DBM support. When used twice, allows to use both
     `raddb/users' file and DBM database.

`-d DIR'
`--config-directory DIR'
     Specify alternate configuration directory. Default is `/etc/raddb'.

`-f'
`--foreground'
     Stay in foreground. We recommend to use it for debugging purposes
     only.

`-l DIR'
`--logging-directory DIR'
     Specify alternate logging directory.

`-n'
`--auth-only'
     Process only authentication requests.

`-p PORTNO'
`--port PORTNO'
     Listen the udp port PORTNO. The accounting port is computed as
     PORTNO + 1.

`-S'
`--log-stripped-names'
     Log usernames stripped off any prefixes/suffixes.

`-s'
`--single-process'
     Run in single process mode. This is for debugging purposes only.
     We strongly recommend *against* using this option. Use it only
     when absolutely necessary.

`-v'
`--version'
     Display program version and exit

`-x DEBUG_LEVEL'
`--debug DEBUG_LEVEL'
     Set debugging level. DEBUG_LEVEL is a comma-separated list of
     assignments in the forms

          MODULE
          MODULE = LEVEL

     where MODULE is the module name or any non-ambiguous assignment
     thereof, LEVEL is the debugging level in the range 0-100. *Note
     Debugging::

`-y'
`--log-auth'
     Log authentications. With this option enabled, Radius will log any
     authentication attempt into its logfile *Note Logging::.

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


File: radius.info,  Node: Configuration files,  Next: Authentication,  Prev: Invocation,  Up: Top

Radius configuration files
**************************

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

   These files are normally found in /etc/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
`raddb' *Note 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.


File: radius.info,  Node: config,  Next: dictionary,  Up: Configuration files

Run-time configuration options.
*******************************

   `radiusd' uses the configuration values from the following sources
(in order of increasing precedence):

  1. Compiled-in defaults

  2. `raddb/config' file.

  3. Command line arguments

   This order of precedence applies only on startup. When re-reading of
the configuration is initiated either by SIGHUP signal or by a control
channel *Note Radctl:: any changes in the config file take precedence
over command line arguments, since `raddb/config' is the only way to
change configuration of the running program.

   This chapter discusses the `raddb/config' file in detail.

   The 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:

     # A shell comment
     /* A C-style
      * multiline comment
      */
     // A C++-style comment

   These are the basic statements:

* Menu:

* option::      The `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.

