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.96 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 certain terms. * Intro:: An introduction to radius concepts. * Glossary:: The glossary. The radius daemon * Naming Conventions:: Conventions about naming files and directories. * Operation:: How radius operates. * 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. * Extensions:: Extending radiusd. * Utility Programs:: * Client Package:: Radius Attributes * Attribute List:: Some frequently used attributes. Reporting Bugs and getting information * Bugs:: How to report a bug. * Info:: Where to get info about GNU radius. Indices * Program Index:: Index of programs. * Keyword Index:: Index of keywords. * Example Index:: Index of examples. * Variable Index:: Index of variables. * 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 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 acronym RADIUS stands for Remote Authentication in Dial-In User Service and usually denotes 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. GNU Radius has several built-in authentication and accounting methods. When these methods are not enough, it allows administrator to implement any new method he deems convenient. 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 analyze the information it provides. File: radius.info, Node: Glossary, Next: Naming Conventions, 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: Naming Conventions, Next: Operation, Prev: Glossary, 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 log 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. By default these are: Directory Short Name Default location Configuration directory raddb /usr/local/etc/raddb Log directory radlog /var/log Accounting directory radacct /var/log/radacct These location may differ depending on your local site configuration. 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 `/usr/local/etc/raddb/sqlserver'. If necessary, locations of these directories can be overridden 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: Operation, Next: Invocation, Prev: Naming Conventions, Up: Top How Radius Operates ******************* The main purpose of Radius is to centralize authentication of users coming from various network stations. Its primary usage is for dial-in users, though it can be used for any kind of network 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 retrieves from its database a profile corresponding to the user's login name. The profile basically consists of two parts: a checklist used for authentication and a reply list used for authorization. The server checks the authenticity of the user using first part of the retrieved profile. If this check succeeds, it uses second part of the profile to authorize the user, i.e. to determine which service he should be provided. Then, the server responds with the parameters of the service, such as connection speed, framed IP address, etc. If any of the described checks had failed, the server sends the negative response. If the server needs some additional information in order to process the request, it asks the NAS to supply such information. 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. When NAS receives the positive authentication response, it initiates the connection. The NAS can be configured to notify Radius server about such events as session start, session stop or changing some parameters during the session. It can also notify the server about other events, such as NAS shutdown or startup. This is called "accounting" and the radius server responsible for processing this information is called an "accounting server". * Menu: * Attributes:: Attributes. * Requests:: Radius requests. * Matching Rule:: Rules for request processing. * Request processing:: How Radius processes incoming requests. File: radius.info, Node: Attributes, Next: Requests, Up: Operation Attributes ========== The information the Radius requests carry is stored as a list of "Attribute-Value pairs". Each pair consists of "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 Value part of an attribute can contain the data of one of the following types: Integer A 32-bit unsigned integer value. IP-number An IPv4 IP-number. String A character string up to 253 characters long. For convenience, the attributes and the values of some frequently used integer attributes are given symbolic names. These names are assigned to attributes and values in the dictionary file *Note 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, "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. Each attribute has a set of properties associated with it. The properties are: "usage flags" These flags determine usage of the attribute in configuration files `huntgroups', `hints' and `users'. "propagation" When a radius server functions in proxy mode, it uses the "propagation" bit to determine which attributes from the reply packet should be passed back to the requesting NAS (*note Proxy Service::). "additivity" Some configuration rules may cause addition of new A/V pairs to the incoming request. Before addition of a new pair, `radiusd' scans the request to see if it already contains a pair with the same attribute. If it does, the value of "additivity" determines the further actions: None The old pair is retained in the request, the new pair is not added to it. Replace The old pair is retained in the request, but its value is replaced with that of the new pair. Append The new pair is appended to the end of the pair list. The attributes are declared in `raddb/dictionary' file. For a detailed description of it, *Note ATTRIBUTE::. For information about particular attributes, *Note Attribute List::. File: radius.info, Node: Requests, Next: Matching Rule, Prev: Attributes, Up: Operation Radius Requests =============== The term "request" means both the authentication/accounting request from NAS to a Radius server and the response that the server sends back to the NAS. Each request 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 request 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: Requests Authentication Requests ----------------------- A NAS sends authentication requests (packets with code Access-Request) to a RADIUS server when a 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: Requests 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. There are five types of accounting packets, which differ by the value of `Acct-Status-Type' attribute. These are: "Session Start Packet." The session start packet is sent after the user has successfully passed the authentication and has started to receive the requested service. It must contain at least following attributes: * Acct-Status-Type = Start * User-Name * Acct-Session-Id * NAS-IP-Address * NAS-Port-Id "Session Stop Packet." The Session Stop Packet is sent after the user has disconnected. It conveys the information about the duration of the session, number of octets transferred, etc. It must contain at least the following attributes: * Acct-Status-Type = Stop * User-Name * NAS-IP-Address * Acct-Session-Id The last three of them are used to find the corresponding "Session Start Packet". "Keepalive Packet" The keepalive packet is sent by the NAS when it obtains some new information about the user's session, e.g. it has determined its IP address or has changed the connection speed, etc. The packet must contain at least following attributes: * Acct-Status-Type = Alive * User-Name * NAS-IP-Address * Acct-Session-Id "Accounting Off Packet" By sending this packet NAS requests that radius mark all sessions registered from this NAS as finished. Receiving this packet usually means that the NAS is to be shut down, or is about to change its configuration in a way that requires all currently opened sessions to be shut down. The packet must contain at least the following attributes: * Acct-Status-Type = Accounting-Off * NAS-IP-Address "Accounting On Packet" By sending this packet, the NAS informs radius that it is ready to accept the incoming connections. Usually this packet is sent after startup, or after a major reconfiguration of the NAS. It must contain at least the following attributes: * Acct-Status-Type = Accounting-Off * NAS-IP-Address File: radius.info, Node: Matching Rule, Next: Request processing, Prev: Requests, Up: Operation Matching Rule ============= A record in the radius database describing a particular rule for matching an incoming request is called a "Matching Rule". Each such rule defines an action to be taken when the match occurs. The "Matching Rule" consists of three distinct parts: "Label" This is used to identify the rule. The special usernames `DEFAULT' and `BEGIN' are reserved. These will be described in detail below. "Left-Hand Side (LHS)" The list of attribute-value pairs used for matching the profile against an incoming request. "Right-Hand Side (RHS)" The list of attribute-value pairs that define the action to be taken if the request matches LHS. The following radius configuration files keep data in a "Matching Rule" format: `hints', `huntgroups' and `users'. Although they keep data in similar format, the rules that are used to match incoming requests against contents of these files differ from file to file. The following section describes these rules in detail. File: radius.info, Node: Request processing, Prev: Matching Rule, Up: Operation Processing Requests =================== Upon receiving a request Radius applies to it a number of checks to determine whether the request comes from an authorized source. If these checks succeed, the request is processed and answered. 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 file::). If no match is found, the request is rejected. 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 user-name hints. "User-name hints" are special rules that modify the request depending on user name and his credentials. These rules allow to divide users into distinct groups, each group having its own authentication and/or accounting methods. The user-name hints are stored in `raddb/hints' (*note hints file::). Process huntgroup rules. "Huntgroup rules" allow to segregate incoming requests depending on the NAS and/or port number they came from. These rules are stored in `raddb/huntgroups' (*note huntgroups file::). Determine whether the request must be proxied to another radius server The requests pertaining to another realm are immediately forwarded to the remote radius server for further processing. *Note Proxying::, for the description of this process. Process individual user profiles. This step applies only to authentication requests. * Menu: * Proxying:: * Hints:: * Huntgroups:: * User Profiles:: File: radius.info, Node: Proxying, Next: Hints, Up: Request processing Proxying -------- "Proxying" is a mode of operation when a radius server forwards an incoming requests from a NAS to another radius server, waits for the latter to reply, and forwards the reply back to the requesting NAS. A common use for such operation mode is to provide "roaming" between several Internet Service Providers (ISPs). Roaming permits the ISPs to share their resources, allowing each other's users to connect to other party's equipment. Thus, users traveling outside the area of one ISP's coverage are still able to access their services through another ISP. * Menu: * Proxy Service:: * Realms:: File: radius.info, Node: Proxy Service, Next: Realms, Up: Proxying Proxy Service ............. Suppose the ISP `Local' has a roaming arrangement with the ISP `Remote'. When the user of `Remote' dials in to the NAS of `Local', the NAS sends the authentication request to `Local' radius server. The server then determines that this is a roaming user, stores a copy of the request in its internal queue, and forwards the request to `Remote' radius server for processing. Thus, `Local' radius acts as a client for `Remote' radius. When `Remote' radius responds, the `Local' receives the response, and passes it back to the NAS. The copy of the request from the server's queue serves to determine which NAS originated the request. Before passing the request back to the NAS, radius removes from it the information, specific for `Remote' site, such as `Framed-IP-Address', `Framed-Netmask', etc. Only the attributes marked with `propagate' flag (*note Attributes::) are passed back to the NAS. After removing site-specific attributes, `Local' radius passes the request through its user profiles (*note User Profiles::) to insert any local site-specific information that might be needed. Finally, it passes the reply back to the NAS. The accounting requests are processed in the similar manner, except that no attribute filtering takes place, as the accounting responces do not carry any A/V pairs. This example illustrates the simplest "proxy chain", consisting of only two servers. The proxy chains may consist of several servers. In our example, the `Remote' radius server may also act as a proxy and forward the request to still another radius server, etc. _Note_, that when the accounting request passes through a chain of forwarding servers, the accounting records are stored on all servers in the chain. File: radius.info, Node: Realms, Prev: Proxy Service, Up: Proxying Realms ...... Radius server determines which server a request must be forwarded to by request's "authentication realm". There are three kinds of realms: 1. A "Named Realm" is the part of a user name following the `at sign' (`@'). For example, if the user name is `jsmith@this.net', then `this.net' is the realm. The named realms can be cascaded, e.g. a request with user name `jsmith@this.net@remote.net' will first be forwarded to the radius server of realm `remote.net', which in turn will forward it to `this.net'. 2. A "Default Realm" defines the server to which the requests for realms, not mentioned explicitly in the configuration, are forwarded. 3. An "Empty Realm" defines the server to which the requests _without_ explicit named realm are forwarded. If the configuration does not define the empty realm, such requests are processed by the server itself. GNU Radius keeps the information about the realms it serves in configuration file `raddb/realms' (*note realms file::). File: radius.info, Node: Hints, Next: Huntgroups, Prev: Proxying, Up: Request processing Hints ----- "User-name hints" are special rules that modify the incoming request depending on user name and his credentials. Hints are stored as a list of "Matching Rules" (*note Matching Rule::). Upon receiving a request, `radiusd' scans the hints entries sequentially, comparing each rule's "Label" with the value of `User-Name' attribute from the request. If they coincide, then `radiusd' appends the contents of the rule's RHS to the request pair-list. Both user names must match exactly in order for a hint to take effect, unless the hint's checklist contains either `Prefix' or `Suffix' attribute. The special name `DEFAULT' or `DEFAULT%d' (where %d denotes any decimal number), used as hint's "Label" match any username. The two special attributes, `Prefix' and `Suffix', may be used in LHS to restrict the match to a specified part of a user-name. Both are string attributes. The `Prefix' instructs radius to accept the hint only if the username begins with the given prefix. Similarly, `Suffix' instructs radius to accept the hint only if the username ends with the given suffix. A hint may contain both `Prefix' and `Suffix' attributes. In addition to these two attributes, a hint's LHS may contain `User-ID' and `Group' attributes. The following attributes, when used in a hint's RHS have special meaning. They are not appended to the request pair-list. Instead, they are removed after completing their function: `Fall-Through' If this attribute is present, and is set to `Yes', `radiusd' continues scanning the hints, after processing current entry. This allows for applying several hints to a single packet. `Rewrite-Function' If this attribute is present, the specified rewrite function is invoked. `Replace-User-Name' The value of this attribute is expanded (*note Macro Substitution::), and replaces the value of `User-Name' attribute from the request. The hints rules are defined in `raddb/hints' file (*note hints file::). File: radius.info, Node: Huntgroups, Next: User Profiles, Prev: Hints, Up: Request processing Huntgroups ---------- Huntgroups are special rules, that allow to alter processing of incoming requests, depending on NAS IP address and port number they come from. The rules are stored as a list of "Matching Rules" (*note Matching Rule::). Upon receiving a request, `radiusd' scans this list sequentially until it finds an entry, such that the conditions set forth in its LHS are matched by the request. If such an entry is found, `radiusd' verifies that the request meet the conditions described by RHS. If it does not, the request is rejected. In short, a huntgroup requires that any request matching its LHS must match also its RHS. The "Label" part of the rule is not used in comparisons, instead it is used to label huntgroups. All entries with the same label form a single huntgroup. The special attribute `Huntgroup-Name' can be used to request a match against a particular huntgroup (*note Huntgroup-Name::). The huntgroups rules are defined in `raddb/huntgroups' file (*note huntgroups file::). File: radius.info, Node: User Profiles, Prev: Huntgroups, Up: Request processing User Profiles ------------- "User Profiles" are the per-user matching rules (*note Matching Rule::). Any incoming authentication request is compared with the "User Profiles" after it has passed both "Hints" and "Huntgroups". `Radiusd' selects from the "User Profiles" those rules, whose "Label" matches the value of `User-Name' attribute from the incoming request. The selected profiles form the list of authentication rules for the request. In order for a profile to be selected, its label must either coincide literally with the `User-Name' value, or it must be one of special labels `DEFAULT' and `BEGIN'. The rules in the authentication list are ordered as follows: first go all the profiles with `BEGIN' label, they are followed by the profiles, whose labels match the `User-Name' literally, and, finally, these are followed by rules labeled with `DEFAULT'. (1) Within each of the three sub-lists the rules preserve the order in which they appear in `raddb/users' file. Once the list is constructed, it is scanned sequentially until the rule is found, whose LHS matches the incoming request. If no such rule is found, then the authentication fails. Otherwise, the contents of its RHS is appended to "Reply List" being constructed. If the RHS of the matched rule contains attribute `Fall-Through' with the value `Yes', the matching continues. When the list is exhausted, the authentication result is sent back to the NAS along with the A/V pairs collected in the "Reply List". The user profiles are defined in `raddb/users' file (*note users file::). ---------- Footnotes ---------- (1) For compatibility with other implementations of radius, GNU Radius treats profile labels in the form `DEFAULT%d', where `%d' represents a decimal number, in the same way it treats `DEFAULT' labels. The same applies to `BEGIN' labels. File: radius.info, Node: Invocation, Next: Configuration Files, Prev: Operation, 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 Whenever a command line options has its equivalent in config file the use of this equivalent should be preferred (*note config file::). 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::. Config file equivalent: `auth { detail yes; };'. `-a DIR' `--acct-directory DIR' Specify accounting directory. Config file equivalent: `option { acct-dir DIR; };'. `-b' `--dbm' Enable DBM support. Config file equivalent: `usedbm yes;'. `-d DIR' `--config-directory DIR' `--directory D' Specify alternate configuration directory. Default is `/usr/local/etc/raddb'. `-f' `--foreground' Stay in foreground. We recommend to use it for debugging purposes only. `-i IP' `--ip-address' Specifies the IP address `radiusd' will listen on. If this option is not specified, the program will listen on all IP addresses, assigned to the machine it runs on. Config file equivalent: `option { source-ip IP; };'. _Please note_, that `listen' statement in `raddb/config' provides a better control over IP addresses to listen on (*Note auth::, and *note acct::). `-L' `--license' Display GNU General Public License and exit. `-l DIR' `--logging-directory DIR' Specify alternate logging directory. Config file equivalent: `option { log-dir DIR; };'. `-mb' `--mode b' "Builddbm" mode. Builds a DBM version of a plaintext users database. *Note Builddbm::. `-mc' `--mode c' Check configuration files and exit. All errors are reported via usual log channels. `-mt' `--mode t' Test mode. In this mode `radiusd' starts an interactive interpreter which allows to test various aspects of its configuration. `-n' `--auth-only' Process only authentication requests. `-p PORTNO' `--port PORTNO' Listen the UDP port PORTNO. The accounting port is computed as PORTNO + 1. `-P DIR' `--pid-file-dir DIR' Specifies the alternate path for the pidfile. `-S' `--log-stripped-names' Log usernames stripped off any prefixes/suffixes. Config file equivalent: `auth { strip-names yes };'. `-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 compilation options. `-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:: Config file equivalent: logging { category debug { level DEBUG_LEVEL; }; }; `-y' `--log-auth' Log authentications. With this option enabled, Radius will log any authentication attempt into its logfile *Note Logging::. Config file equivalent: `logging { category auth { detail yes; }; }; '. `-z' `--log-auth-pass' Log passwords along with authentication information. _Do not use_ this option. It is _very_ insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes. Config file equivalent: logging { category auth { print-pass yes; }; }; *Note config file::. 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 /usr/local/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 file:: Run-time configuration options. * dictionary file:: Radius dictionary. * clients file:: Clients lists the NASes that are allowed to communicate with radius. * naslist file:: The naslist file keeps general information about the NASes. * nastypes file:: Information about how to query the NASes about active user sessions. * hints file:: Important user information that is common for the users whose names match some pattern. * huntgroups file:: Group users by the NAS (and, possibly, a port number) they come from. * realms file:: Communication with remote radius servers * users file:: User profile. * access.deny file:: List of users which are denied access. * sqlserver file:: SQL server configuration. * rewrite file:: Rewrite functions allow to change the input packets. * menus file:: 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 file, Next: dictionary file, Up: Configuration Files Run-Time Configuration Options -- `raddb/config' ================================================ `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 SNMP channel any changes in the config file take precedence over command line arguments, since `raddb/config' is the only way to change configuration of the running program. This chapter discusses the `raddb/config' file in detail. The `raddb/config' consists of statements and comments. Statements end with a semicolon. Many statements contain a block of sub-statements which also terminate with a semicolon. Comments can be written in shell, C, or C++ constructs, i.e. any of the following represent a valid comment: # A shell comment /* A C-style * multi-line comment */ // A C++-style comment These are the basic statements: * Menu: * option:: `Option' block: set the global program options. * logging:: Fine-tune the logging. * auth:: Configure authentication service. * acct:: Configure accounting service. * proxy:: Configure proxy service. * usedbm:: Enable the DBM feature. * snmp:: Configure SNMP service. * guile:: Configure Guile interface. * message:: Configure server reply messages. File: radius.info, Node: option, Next: logging, Up: config file `option' block -------------- Syntax: ------- option { [ source-ip NUMBER ; ] [ max-requests NUMBER ; ] [ exec-program-user STRING ; ] [ username-chars STRING ; ] [ log-dir STRING ; ] [ acct-dir STRING ; ] } ; Usage ----- The `option' block defines the global options to be used by `radiusd'. Numeric statements ------------------ `source-ip' Sets the source IP address. When this statement is not present, the IP address of the first available network interface on the machine will be used as source. `max-requests' Sets the maximum number of the requests in queue. String statements ----------------- `exec-program-user' Sets effective user id for the programs executed as a result of `Exec-Program' and `Exec-Program-Wait'. The effective group id will be retrieved from the `/etc/passwd' entry for the given user. `username-chars' Determines characters that are valid within a username. The alphanumeric characters are always allowed in a username, it is not necessary to specify them in this statement. By default the following characters are allowed in a username: `.-_!@#$%^&\/"'. `log-dir' Specifies the logging directory. `acct-dir' Specifies the accounting directory. File: radius.info, Node: logging, Next: auth, Prev: option, Up: config file `logging' block --------------- Syntax: ------- logging { [ category category_spec { [ channel channel_name ; ] [ print-auth BOOL ; ] [ print-pass BOOL ; ] [ print-failed-pass BOOL ; ] [ level DEBUG_LEVEL ; ] } ; ] [ channel channel_name { ( file STRING ; | syslog facility . priority ; ) [ print-pid BOOL ; ] [ print-category BOOL ; ] [ print-cons BOOL ; ] [ print-level BOOL ; ] [ print-priority BOOL ; ] }; ] } ; Usage ----- The `logging' statement describes the course followed by `radiusd''s logging information. * Menu: * category:: `category' statement. * channel:: `channel' statement. * logging example:: Example of the `logging' statement. File: radius.info, Node: category, Next: channel, Up: logging `category' statement .................... Each line of logging information generated by `radiusd' has an associated "category". The `logging' statement allows each category of output to be controlled independently of the others. The logging category is defined by "category name" and a "severity". "category name" determines what part of radiusd daemon is allowed to send its logging information to this channel. It can be any of `main', `auth', `acct', `proxy', `snmp'. "priority" determines the minimum priority of the messages displayed by this channel. The priorities in ascending order are: `debug', `info', `notice', `warn', `err', `crit', `alert', `emerg'. The full category specification, "category_spec", can take any of the following three forms: category_name Print the messages of given category. priority Print messages of all categories, abridged by given priority. If the priority is prefixed with `=', only messages with given priority will be displayed. If it is prefixed with `!', the messages with priority other than the specified will be displayed. Otherwise, the messages with priorities equal to or greater than the specified will be displayed. category_name . priority Print the messages of given category, abridged by given priority. The priority may be prefixed with either `=' or `!' as described above. Additional category options valid for `auth' category are: `print-auth' Log individual authentications. `print-pass' Include passwords for successful authentications. It is _very_ insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes. `print-failed-pass' Include passwords for failed authentications. File: radius.info, Node: channel, Next: logging example, Prev: category, Up: logging `channel' statement ................... Channels represent methods for recording logging information. Each channel has a unique name, and any categories which specify that name in a `channel' statement will use that channel. `radiusd' can write logging information to files or send it to syslog. The `file' statement sends the channel's output to the named file (*note Naming Conventions::). The `syslog' statement sends the channel's output to syslog with the specified facility and severity. Channel options modify the data flowing through the channel: `print-pid' Add the process ID of the process generating the logging information. `print-cons' Also send the logging information to the system console. `print-category' Add the category name to the logging information. `print-priority' `print-level' Add the priority name to the logging information. File: radius.info, Node: logging example, Prev: channel, Up: logging Example of the `logging' statement .................................. logging { channel default { file "radius.log"; print-category yes; print-priority yes; }; channel info { file "radius.info"; print-pid yes; print-cons yes; print-priority yes; }; channel notice { syslog auth.notice; }; category auth { print-auth yes; print-failed-pass yes; }; category notice { channel notice; }; category info { channel info; }; category debug { channel info; level radiusd=1,files; }; category *.!debug { channel default; }; }; File: radius.info, Node: auth, Next: acct, Prev: logging, Up: config file `auth' statement ---------------- Syntax: ------- auth { [ listen ADDR-LIST ; ] [ port NUMBER ; ] [ spawn BOOL ; ] [ max-requests NUMBER ; ] [ time-to-live NUMBER ; ] [ request-cleanup-delay NUMBER ; ] [ detail BOOL ; ] [ strip-names BOOL ; ] [ checkrad-assume-logged BOOL ; ] [ password-expire-warning NUMBER ; ] } ; Usage: ------ The `auth' statement configures the parameters of the authentication service. listen statement ---------------- This statement determines on which addresses radiusd will listen for incoming authentication requests. Its argument is a comma-separated list of items in the form IP:PORT-NUMBER. IP can be either an IP address in familiar "dotted-quad" notation or a hostname. :PORT-NUMBER part may be omitted, in which case the default authentication port is assumed. If the `listen' statement is omitted, radiusd will accept incoming requests from any interface on the machine. Numeric statements ------------------ `port' Sets the number of UDP port to listen on for the authentication requests. `max-requests' Sets the maximum number of authentication requests in the queue. Any surplus requests will be discarded. `time-to-live' Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue. `request-cleanup-delay' Sets the request cleanup delay in seconds, i.e. determines how long will the completed authentication request reside in the queue. `password-expire-warning' Sets the time interval for password expiration warning. If user's password expires within given number of seconds, radiusd will send a warning along with authentication-acknowledge response. Default is 0. Boolean statements ------------------ `spawn' Determines if `radiusd' should spawn a child to process the request. `detail' When set to true, `radiusd' will produce the detailed log of each received packet in the file `radacct/NASNAME/detail.auth'. (*note Naming Conventions::). `strip-names' Determines whether `radiusd' should strip any prefixes/suffixes off the username before logging. `checkrad-assume-logged' `radiusd' consults the value of this variable when the NAS does not responds to checkrad queries (*note Checking Simultaneous Logins::). If this variable is set to `yes', the daemon will proceed as if the NAS returned "yes", i.e. it will assume the user is logged in. Otherwise `radiusd' assumes the user _is not_ logged in. File: radius.info, Node: acct, Next: proxy, Prev: auth, Up: config file `acct' statement ---------------- Syntax: ------- acct { [ listen ADDR-LIST ; ] [ port NUMBER ; ] [ spawn BOOL ; ] [ detail BOOL; ] [ max-requests NUMBER ; ] [ time-to-live NUMBER ; ] [ request-cleanup-delay NUMBER ; ] } ; Usage: ------ The `acct' statement configures the parameters of the accounting service. listen statement ---------------- This statement determines on which addresses radiusd will listen for incoming accounting requests. Its argument is a comma-separated list of items in the form IP:PORT-NUMBER. IP can be either an IP address in familiar "dotted-quad" notation or a hostname. :PORT-NUMBER part may be omitted, in which case the default accounting port is assumed. If the `listen' statement is omitted, radiusd will accept incoming requests from any interface on the machine. Numeric statements ------------------ `port' Sets the port number to listen for the authentication requests. `max-requests' Sets the maximum number of accounting requests in the queue. Any surplus requests will be discarded. `time-to-live' Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue. `request-cleanup-delay' Sets the request cleanup delay in seconds, i.e. determines how long will the completed account request reside in the queue. Boolean statements ------------------ `spawn' Determines if `radiusd' should spawn a child to process the request. `detail' When set to `false', disables detailed accounting (*note Detailed Request Accounting::). File: radius.info, Node: proxy, Next: usedbm, Prev: acct, Up: config file `proxy' statement ----------------- Syntax: ------- proxy { [ max-requests NUMBER ; ] [ request-cleanup-delay NUMBER ; ] } ; Usage: ------ The `proxy' statement configures the parameters of the proxy service. Numeric statements ------------------ `max-requests' Sets the maximum number of accounting requests in the queue. Any surplus requests will be discarded. `request-cleanup-delay' Sets the request cleanup delay in seconds, i.e. determines how long will the completed account request reside in the queue. File: radius.info, Node: usedbm, Next: snmp, Prev: proxy, Up: config file `usedbm' statement ------------------ Syntax: ------- usedbm ( yes | no ) ; Usage ----- The `usedbm' statement determines whether the DBM support should be enabled. `no' Do not use DBM support at all. `yes' Use only the DBM database and ignore `raddb/users'. File: radius.info, Node: snmp, Next: guile, Prev: usedbm, Up: config file `snmp' statement ---------------- Syntax: ------- snmp { [ port PORTNO ; ] [ spawn BOOL ; ] [ max-requests NUMBER ; ] [ time-to-live NUMBER ; ] [ request-cleanup-delay NUMBER ; ] [ ident STRING ; ] [ community NAME ( rw | ro ) ; ] [ network NAME NETWORK [ NETWORK ... ] ; ] [ acl { [ allow NETWORK_NAME COMMUNITY_NAME ; ] [ deny NETWORK_NAME ; ] } ; ] }; Usage ----- The `snmp' statement configures the SNMP service. Numeric statements ------------------ `port' Sets the port number to listen for the SNMP requests. `max-requests' Sets the maximum number of SNMP requests in the queue. Any surplus requests will be discarded. `time-to-live' Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue. `request-cleanup-delay' Sets the request cleanup delay in seconds, i.e. determines how long will the completed SNMP request reside in the queue. Boolean statements ------------------ `spawn' Determines if `radiusd' should spawn a child to process the SNMP request. String statements ----------------- `ident' Sets the SNMP server identification string. Community and network definitions --------------------------------- `community NAME ( rw | ro )' Defines the community NAME as read-write (`rw') or read-only (`ro'). `network NAME NETWORK [ NETWORK ... ]' Groups several networks or hosts under one logical network name. Access-Control List definitions ------------------------------- `allow NETWORK_NAME COMMUNITY_NAME' allow hosts from the group NETWORK_NAME access to community COMMUNITY_NAME. `deny NETWORK_NAME' Deny access to SNMP service from any host in the group NETWORK_NAME. File: radius.info, Node: guile, Next: message, Prev: snmp, Up: config file `guile' statement ----------------- The `guile' statement allows to configure server interface with Guile. Syntax ------ guile { [ debug BOOL ; ] [ load-path STRING ; ] [ load STRING ; ] }; Usage ----- Boolean statements ------------------ `debug' When set to yes, enables debugging evaluator and backtraces on Guile scripts. String statements ----------------- `load-path' Add specified pathname to `%load-path' variable. `load' Load the specified source file on startup. For the detailed description of Guile extensions interface, *Note Guile::. File: radius.info, Node: message, Prev: guile, Up: config file `message' statement ------------------- The `message' statement allows to set up the messages that are returned to the user with authentication-response packets. Syntax ------ message { [ account-closed STRING ; ] [ password-expired STRING ; ] [ password-expire-warning STRING ; ] [ access-denied STRING ; ] [ realm-quota STRING ; ] [ multiple-login STRING ; ] [ second-login STRING ; ] [ timespan-violation STRING ; ] }; All variables in `message' block take a string argument. In STRING you can use the usual C backslash notation to represent non-printable characters. The use of %C{} and %R{} sequences is also allowed (*note Macro Substitution::). String statements ----------------- `account-closed' This message will be returned to the user whose account is administratively closed. `password-expired' This message will be returned to the user whose password has expired. `password-expire-warning' This is a warning message that will be returned along with an authentication-acknowledge packet for the user whose password will expire in less than N seconds. The value of N is set by `password-expire-warning' variable in `auth' block. *Note auth::. In this string, you can use the %R{Password-Expire-Days} substitution, to represent the actual number of _days_ left to the expiration date. The default is Password Will Expire in %R{Password-Expire-Days} Days\r\n `access-denied' This message is returned to the user who supplies an incorrect password or a not-existent user-name as his authentication credentials. `realm-quota' This message is returned when the user is trying to log in using a realm, and number of users that are currently logged in from this realm reaches maximum value. For a description of realms, *Note Realms::. `multiple-login' This message is returned to the user, who has logged in more than allowed number of times. For description of how to set the maximum number of concurrent logins, see *Note Simultaneous-Use::. `second-login' This is a special case of `multiple-login', which is used when the user's login limit is 1. `timespan-violation' This message is returned to the user who is trying to login outside of allowed time interval. For description of how to limit user's login time, see *Note Login-Time::. File: radius.info, Node: dictionary file, Next: clients file, Prev: config file, Up: Configuration Files Dictionary of Attributes -- `raddb/dictionary' ============================================== The dictionary file `raddb/dictionary' defines the symbolic names for radius attributes and their values (*note 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: NUMBER Denotes a decimal, octal or hexagesimal number. Usual C conventions are honored, i.e. if NUMBER starts with `0x' or `0X' it is read as a hex number, if it starts with `0' it is read as an octal number, otherwise it is read as a decimal one. TYPE Denotes an attribute type. These are valid attribute types: `string' A string type. `integer' An integer type. `ipaddr' IP address in a dotted-quad form. `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. There are following kinds of statements: * Menu: * Comment:: Introducing a comment line. * $INCLUDE:: Include a file. * VENDOR:: Define a vendor-id. * ATTRIBUTE:: Define an attribute translation. * VALUE:: Define a value translation. File: radius.info, Node: Comment, Next: $INCLUDE, Up: dictionary file Comments -------- Comments are introduced by a pound sign (`#'). Everything starting from the first occurrence of `#' up to the end of line is ignored. File: radius.info, Node: $INCLUDE, Next: VENDOR, Prev: Comment, Up: dictionary file $INCLUDE Statement ------------------ Syntax ------ $INCLUDE `filename' Usage ----- The `$INCLUDE' statement causes the contents of the file `filename' to be read in and processed. The file is looked up in the Radius database directory. *Note Configuration Files::. File: radius.info, Node: VENDOR, Next: ATTRIBUTE, Prev: $INCLUDE, Up: dictionary file VENDOR Statement ---------------- Syntax ------ VENDOR Vendor-Name NUMBER Usage ----- A `VENDOR' statement defines the symbolic name for a Vendor-Id. This name can subsequently be used in `ATTRIBUTE' statements to define Vendor-Specific attribute translations. *Note Vendor-Specific::. Example ------- VENDOR Livingston 307 File: radius.info, Node: ATTRIBUTE, Next: VALUE, Prev: VENDOR, Up: dictionary file ATTRIBUTE statement ------------------- Syntax ------ ATTRIBUTE NAME NUMBER TYPE [VENDOR [FLAGS]] Usage ----- The `ATTRIBUTE' statement defines the translation for an attribute. Its parts have the following meaning: NAME The attribute name. NUMBER The attribute ID (number). TYPE The attribute type. VENDOR Vendor name for vendor-specific attributes. For usual attributes this field is empty or contains a dash (`-'). FLAGS Flags, defining attribute properties (*note Attributes::). The "attribute property flags" consist of a sequence of letters, whose meaning is determined by the following rules: (1) 1. The attribute usage is described by three pairs of symbols, enclosed in square brackets. Each pair describes how the attribute can be used in each of three configuration files. The first pair corresponds to `raddb/users', the second one corresponds to `raddb/hints', and the third one corresponds to `raddb/huntgroups'. Within each pair, the letter `L' in first position means that the attribute is allowed in LHS of a rule. The letter `R' in second position means that the attribute is allowed in RHS of a rule. The absense of any of these letters is indicated by dash (`-'). Thus, the following usage specification: [L--RLR] means that the attribute may be used in LHS of a rule in `raddb/users', in RHS of a rule in `raddb/hints', and in both sides of a rule in `raddb/huntgroups'. 2. The attribute additivity is described by one of the following letters: = Additivity = Replace + Additivity = Append N Additivity = None 3. The presence of letter `P' in property flags raises the propagation bit. Example ------- ATTRIBUTE Service-Type 6 integer - [LR-RLR]=P This statement assigns the translation string `Service-Type' to the attribute number 6. It allows the use of this attribute in any part of matching rules, except in LHS of a `raddb/hints' rule. The additivity of `Service-Type' is set to `Replace'. The attribute will be propagated through the proxy chain. ---------- Footnotes ---------- (1) The FLAGS are optional for compatibility with previous versions of GNU Radius. If they are omitted, the default is `[LRLRLR]+' File: radius.info, Node: VALUE, Prev: ATTRIBUTE, Up: dictionary file VALUE Statement --------------- Syntax ------ VALUE Attribute-Translation Value-Translation NUMBER Usage ----- The `VALUE' statement assigns a translation string to a given value of an integer attribute. `Attribute-Translation' specifies the attribute and the `Value-Translation' specifies the name assigned to the value NUMBER of this attribute. Example ------- The following assigns the translation string `Login-User' to the value 1 of the attribute `Service-Type'. VALUE Service-Type Login-User 1 File: radius.info, Node: clients file, Next: naslist file, Prev: dictionary file, Up: Configuration Files Clients List -- `raddb/clients' =============================== The `raddb/clients' lists NASes which are allowed to make authentication requests. As usual, the `#' character introduces a comment. Each record in the file consists of two fields, separated by whitespace. The fields are: NAS name Specifies a hostname or IP address of the NAS. Key Lists the encryption key shared between the server and this NAS. * Menu: * Example: clients example. An example of clients file. File: radius.info, Node: clients example, Up: clients file Example of `clients' file ------------------------- # 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 File: radius.info, Node: naslist file, Next: nastypes file, Prev: clients file, Up: Configuration Files NAS List -- `raddb/naslist' =========================== The `raddb/naslist' file contains a list of NASes known to the Radius server. Each record in the file consist of three fields: NAS name Specifies a hostname or IP address of the NAS. The word `DEFAULT' may be used in this field to match any NAS. (1) 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. Type Specifies the type of this NAS. Using this value `radiusd' determines the way to query NAS about the presence of a given user on it (*note Checking Simultaneous Logins::). The two special types: `true' and `false', can be used to disable NAS querying. When the type field contains `true', `radiusd' assumes the user is logged in to the NAS, when it contains `false', `radiusd' assumes the user _is not_ logged in. Otherwise, the type is used as a link to `nastypes' entry (*note nastypes file::). Arguments Additional arguments describing the NAS. Multiple arguments must be separated by commas. No intervening whitespace is allowed in this field. There are two groups of nas arguments: "nas-specific" arguments and "nas-querying" arguments. "Nas-specific" arguments are used to modify a behavior of `radiusd' when sending or receiving the information to or from a particular NAS. "Nas-querying" arguments control the way `radiusd' queries a NAS for confirmation of a user's session (*note Checking Simultaneous Logins::). These arguments override the ones specified in `nastypes' and can thus be used to override the default values. The "nas-specific" arguments currently implemented are: broken_pass This is a boolean argument that controls the encryption of user passwords, longer than 16 octets. By default, `radiusd' uses method specified by RFC 2865. However some NASes, most notably MAX Ascend series, implement a broken method of encoding long passwords. This flag instructs `radiusd' to use broken method of password encryption for the given NAS. For the list of nas-querying arguments, *Note Full list of allowed arguments: nastypes file. * Menu: * Example: naslist example. Example of `naslist' file. ---------- Footnotes ---------- (1) Logins from DEFAULT NASes are not reported by213.130.0.5 `raduse', neither are they reflected in SNMP variables. File: radius.info, Node: naslist example, Up: naslist file Example of `naslist' file ------------------------- # 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 `true', `false' and # those defined in raddb/nastypes file. # NAS Name Short Name Type #---------------- ---------- ---- myhost.dom.ain myhost unix merlin merlin max 11.10.10.10 arthur livingston File: radius.info, Node: nastypes file, Next: hints file, Prev: naslist file, Up: Configuration Files NAS Types -- `raddb/nastypes' ============================= The `raddb/nastypes' file describes the ways to query NASes about active user sessions. * Menu: * Syntax: nastypes syntax. Syntax described. * Example: nastypes example. Example of nastypes file. * Predefined NAS Types:: NAS types defined in standard nastypes file. File: radius.info, Node: nastypes syntax, Next: nastypes example, Up: nastypes file Syntax of `raddb/nastypes' -------------------------- Syntax ====== Each record consists of three fields separated by any amount of whitespace. The fields are: Type Type of the NAS which is described in this record. Method Method to use to query a NAS of given type. Arguments Arguments to pass to this method. Each argument is a pair ARG=VALUE, where ARG is its name and VALUE is a value assigned to it. The list of predefined argument names follows. _Please note_, that no intervening whitespace is allowed in this field. Methods ======= Version 0.96 of GNU Radius supports two querying methods: finger and snmp. Arguments ========= In the discussion below N means numeric and S string value. The following arguments are predefined: Common for all methods ---------------------- function=S Specifies the check function to use with this method (*note Login Verification Functions::). This argument must be present. For description of how this function is applied, see *Note Checking Simultaneous Logins::. port=N Use port number N instead of the default for the given method. Method snmp ----------- password=S Use community S instead of the default. This argument must be present. retries=N Retry N times before giving up. timeout=N Timeout N seconds on each retry. Method finger ------------- timeout=N Give up if the NAS does not respond within N seconds. notcp tcp=0 Disable the use of T/TCP for hosts with a broken TCP implementation. arg=SUBST Send SUBST to finger, instead of username. SUBST must be one of "macro variables", described below. Macro variables --------------- The following macro-variables are recognized and substituted when encountered in the VALUE pair of an argument: `%u' Expands to username. `%s' Expands to session id. `%d' Expands to session id converted to decimal representation. `%p' Expands to port number. `%P' Expands to port number + 1. File: radius.info, Node: nastypes example, Next: Predefined NAS Types, Prev: nastypes syntax, Up: nastypes file Example of nastypes file. ------------------------- _Please note_, that in the following example the long lines are broken into several lines for readability. # Type Method Args # ---- ------ ---- unix finger function=check_unix max-f finger function=check_max_finger max snmp oid=.1.3.6.1.4.1.529.12.3.1.4.%d, function=check_snmp_u as5300-f finger function=check_as5300_finger as5300 snmp oid=.1.3.6.1.4.1.9.9.150.1.1.3.1.2.%d, function=check_snmp_u livingston snmp oid=.1.3.6.1.4.1.307.3.2.1.1.1.5.%P, function=check_snmp_s File: radius.info, Node: Predefined NAS Types, Prev: nastypes example, Up: nastypes file Standard NAS types ------------------ The `nastypes' shipped with version 0.96 of GNU Radius defines following NAS types: unix -- UNIX boxes running Finger This type suits for UNIX boxes running finger service able to return information about dial-up users active on them. To enable finger checking of a unix host add following to your `naslist' file: #Hostname Shortname Type #-------- --------- ---- nas.name T unix max-f -- MAX Ascend with Finger Use this type if you have MAX Ascend terminal server that answers finger queries. The `naslist' entry for such NAS will look like: #Hostname Shortname Type Flags #-------- --------- ---- ----- nas.name T max-f broken_pass _Please note_ the use of `broken_pass' flag. It is needed for most MAX Ascend servers (*note naslist file::). max -- MAX Ascend, answering SNMP Use this type if you have MAX Ascend terminal server that answers SNMP queries. The `naslist' entry for such NAS will look like: #Hostname Shortname Type Flags #-------- --------- ---- ----- nas.name T max-f broken_pass,community=COMM Replace COMM with your actual SNMP community name. as5300-f -- Cisco AS5300 running finger as5300 -- Cisco AS5300 answering SNMP livingston -- Livingston Portmaster Type `livingston' queries portmaster using SNMP. File: radius.info, Node: hints file, Next: huntgroups file, Prev: nastypes file, Up: Configuration Files Request Processing Hints -- `raddb/hints' ========================================= The `raddb/hints' file is used to modify the contents of the incoming request depending on the username. For a detailed description of this, *Note Hints::. The file contains data in "Matching Rule" format (*note Matching Rule::). The only attributes that can be used in the check list are: * `Suffix' * `Prefix' * `Group' * `User-ID' * Menu: * Example: hints example. An example of `hints' file. File: radius.info, Node: hints example, Up: hints file Example of `hints' file ----------------------- ## 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 ## and remove the suffix from the user name. DEFAULT Suffix = ".slip", Strip-User-Name = Yes Hint = "SLIP", Service-Type = Framed-User, Framed-Protocol = SLIP File: radius.info, Node: huntgroups file, Next: realms file, Prev: hints file, Up: Configuration Files Huntgroups -- `raddb/huntgroups' ================================ The `raddb/huntgroups' contains the definitions of the huntgroups. For a detailed description of huntgroup concept, *Note Huntgroups::. The file contains data in "Matching Rule" format (*note Matching Rule::). * Menu: * Example: huntgroups example. An example of the `huntgroups' file. File: radius.info, Node: huntgroups example, Up: huntgroups file Example of `huntgroups' file. ----------------------------- ## 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 File: radius.info, Node: realms file, Next: users file, Prev: huntgroups file, Up: Configuration Files List of Proxy Realms -- `raddb/realms' ====================================== The `raddb/realms' file lists remote Radius servers that are allowed to communicate with the local Radius server (*note Proxying::). Each record consists of up to three fields, separated by whitespace. Two of them are mandatory. The fields are: Realm name Specifies the name of the realm being defined, i.e. part of the login name after the `@' symbol. The special realm name `NOREALM' defines the empty realm, the name `DEFAULT' defines the default realm (*note Realms::). Remote server Specifies the remote server to which the requests for this realm should be forwarded. The syntax for this field is SERVERNAME[:AUTH-PORT[:ACCT-PORT]] Optional AUTH-PORT and ACCT-PORT are the authentication and accounting port numbers. If ACCT-PORT is omitted, it is computed as AUTH-PORT + 1. If AUTH-PORT is omitted, the default authentication port number is used. Flags (optional) The flags meaningful in `raddb/realms' are strip Boolean value. Controls whether the realm name should be stripped off the username before forwarding the request to the remote server. Setting `strip' enables stripping, setting `nostrip' disables it. Default is to always strip user names. quota=NUM Set maximum number of concurrent logins allowed from this realm to the given value (NUM). * Menu: * Example: realms example. An example of `realms' file. File: radius.info, Node: realms example, Up: realms file Example of `realms' file ------------------------ Example 1. ---------- # Realm Remote server[:port] flags #---------------- --------------------- -------- that.net radius.that.net nostrip dom.ain server.dom.ain:3000 strip,quota=20 Example 2. ---------- # Realm Remote server[:port] flags #---------------- --------------------- -------- NOREALM radius.server.net that.net radius.that.net nostrip dom.ain server.dom.ain:3000 strip,quota=20 File: radius.info, Node: users file, Next: access.deny file, Prev: realms file, Up: Configuration Files User Profiles -- `raddb/users' ============================== File `raddb/users' contains the list of "User Profiles". For a description of its purpose, *Note User Profiles::. * Menu: * Example: users example. An example of `users' file. File: radius.info, Node: users example, Up: users file Example of `users' file ----------------------- ## 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 SQL database. ## Users may log in at any time. They get PPP service. DEFAULT Suffix = ".ppp", Auth-Type = SQL, 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 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 ## Note the use of backslashes to split a long line. 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 `raddb/menus/menu1' file. gray Auth-Type = Pam Menu = menu1 File: radius.info, Node: access.deny file, Next: sqlserver file, Prev: users file, Up: Configuration Files List of Blocked Users -- `raddb/access.deny' ============================================ The `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 `#' character introduces an end-of-line comment. File: radius.info, Node: sqlserver file, Next: rewrite file, Prev: access.deny file, Up: Configuration Files SQL Configuration -- `raddb/sqlserver' ====================================== The `raddb/sqlserver' file configures the connection to SQL server. The file uses simple line-oriented `KEYWORD --- VALUE' format. Comments are introduced by `#' character. The `sqlserver' statements can logically be subdivided into following groups: "SQL Client Parameters", configuring the connection between SQL client and the server, "Authentication Server Parameters", "Authorization Parameters", and "Accounting server parameters". * Menu: * SQL Client Parameters:: * Authentication Server Parameters:: * Authorization Parameters:: * Accounting server parameters:: File: radius.info, Node: SQL Client Parameters, Next: Authentication Server Parameters, Up: sqlserver file SQL Client Parameters --------------------- These parameters configure various aspects of connection between SQL client and the server. `interface IFACE-TYPE' Specifies the SQL interface to use. Currently supported values for IFACE-TYPE are `mysql' and `postgres'. Depending on this, the default communication port number is set: it is 3306 for `interface mysql' and 5432 for `interface postgres'. Use of this statement is only meaningful when the package was configured with both `--with-mysql' and `--with-postgres' option. `server STRING' Specifies the hostname or IP address of the SQL server. `port NUMBER' Sets the SQL communicaton port number. It can be omitted if your server uses the default port. `login STRING' Sets the SQL user login name. `password PASSWORD' Sets the SQL user password. `keepopen BOOL' Specify whether `radiusd' should try to keep the connection open. When set to no (the default), `radiusd' will open new connection before the transaction and close it right after finishing it. We recommend setting `keepopen' to `yes' for heavily loaded servers, since opening the new connection can take a substantial amount of time and slow down the operation considerably. `idle_timeout 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. File: radius.info, Node: Authentication Server Parameters, Next: Authorization Parameters, Prev: SQL Client Parameters, Up: sqlserver file Authentication Server Parameters -------------------------------- These parameters configure the SQL authentication. The general syntax is: `doauth BOOL' When set to `yes', enables authentication via SQL. All `auth_' keywords are ignored if `doauth' is set to `no'. `auth_max_connections BOOL' Specifies the maximum number of authentication SQL connections to keep open. This parameter is ignored if `keepopen' is set to `no'. `auth_db STRING' Specifies the name of the database containing authentication information. `auth_query 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. `group_query STRING' Specifies the query that retrieves the list of user groups the user belongs to. This query is used when `Group' or `Group-Name' attribute appears in the LHS of a user's or hint's profile. Example of Authentication Server Parameters ------------------------------------------- Let's suppose the authentication information is kept in the tables `passwd' and `groups'. The `passwd' table contains user passwords. A user is allowed to have different passwords for different services. The table structure is: CREATE TABLE passwd ( user_name varchar(32) binary default '' not null, service char(16) default 'Framed-PPP' not null, password char(64) ); Additionally, the table `groups' contains information about user groups a particular user belongs to. Its structure is: CREATE TABLE groups ( user_name char(32) binary default '' not null, user_group char(32) ); The queries used to retrieve the information from these tables will then look like: auth_query SELECT password FROM passwd WHERE user_name = '%C{User-Name}' AND service = '%C{Auth-Data}' group_query SELECT user_group FROM groups WHERE user_name = '%C{User-Name}' It is supposed, that the information about the particular service a user is wishing to obtain, will be kept in `Auth-Data' attribute in LHS of a user's profile. File: radius.info, Node: Authorization Parameters, Next: Accounting server parameters, Prev: Authentication Server Parameters, Up: sqlserver file Authorization Parameters ------------------------ These parameters define queries used to retrieve the authorization information from the SQL database. All the queries refer to the authentication database. `check_attr_query STRING' This query must return a list of triplets: ATTR-NAME, ATTR-VALUE, OPCODE The query is executed before comparing the request with the profile entry. The values returned by the query are added to LHS of the entry. OPCODE here means one of valid operation codes: `=', `!=', `<', `>', `<=', `>='. `reply_attr_query STRING' This query must return pairs: ATTR-NAME, ATTR-VALUE The query is executed after a successful match, the values it returns are added to the RHS list of the matched entry, and are therefore returned to the NAS in the reply packet. Example of Authorization Parameters ----------------------------------- Suppose your attribute information is stored in a SQL table of the following structure: CREATE TABLE attrib ( user_name varchar(32) default '' not null, attr char(32) default '' not null, value char(128), op enum("=", "!=", "<", ">", "<=", ">=") default null ); Each row of the table contains the attribute-value pair for a given user. If `op' field is `NULL', the row describes LHS (check) pair. Otherwise, it describes a RHS (reply) pair. The authorization queries for this table will look as follows: check_attr_query SELECT attr,value,op \ FROM attrib \ WHERE user_name='%u' \ AND op IS NOT NULL reply_attr_query SELECT attr,value \ FROM attrib \ WHERE user_name='%u' \ AND op IS NULL Now, let's suppose the `raddb/users' contains only one entry: DEFAULT Auth-Type = SQL Service-Type = Framed-User And the `attrib' table contains following rows: user_name attr value op `jsmith' `NAS-IP-Address' `10.10.10.1' `=' `jsmith' `NAS-Port-Id' `20' `<=' `jsmith' `Framed-Protocol' `PPP' `NULL' `jsmith' `Framed-IP-Address' `10.10.10.11' `NULL' Then, when the user `jsmith' is trying to authenticate, the following happens: 1. Radius finds the matching entry (`DEFAULT') in the `raddb/users'. 2. It queries the database using the `check_attr_query'. The triplets it returns are then added to the LHS of the profile entry. Thus, the LHS will contain: Auth-Type = SQL, NAS-IP-Address = 10.10.10.1, NAS-Port-Id <= 20 3. Radius compares the incoming request with the LHS pairs thus obtained. If the comparison fails, it rejects the authentication. _Please note_, that the `Auth-Type' attributes itself triggers execution of `auth_query', described in the previous section. 4. After a successful authentication, Radius queries the database, using `reply_attr_query', and adds its return to the list of RHS pairs. The RHS pairs will then be: Service-Type = Framed-User, Framed-Protocol = PPP, Framed-IP-Address = 10.10.10.11 This list is returned to the NAS along with the authentication accept packet. Thus, this configuration allows the user `jsmith' to use only NAS 10.10.10.1, ports from 1 to 20 inclusive. If the user meets these conditions, he is allowed to use PPP service, and is assigned IP address `10.10.10.11'. File: radius.info, Node: Accounting server parameters, Prev: Authorization Parameters, Up: sqlserver file Accounting Parameters --------------------- To perform the SQL accounting `radiusd' needs to know the database where it is to store the accounting information. This information is supplied by the following statements: `doacct BOOL' When set to `yes' enables SQL accounting. All `acct_' keywords are ignored if `doacct' is set to `no'. `acct_db STRING' Specifies the name of the database where the accounting information is to be stored. `acct_max_connections NUMBER' Specifies the maximum number of accounting SQL connections to keep open. This parameter is ignored if `keepopen' is set to `no'. Further, `radiusd' needs to know which information it is to store into the database and when. Each of five accounting request types (*note Accounting Requests::) has a SQL query associated with it. Thus, when radius receives an accounting request, it determines the query to use by the value of `Acct-Status-Type' attribute. Following statemens define the accounting queries: `acct_start_query STRING' Specifies the SQL query to be used when "Session Start Packet" is received. Typically, this would be some `INSERT' statement (*note Queries::). `acct_stop_query STRING' Specifies the SQL query to be used when "Session Stop Packet" is received. Typically, this would be some `UPDATE' statement. `acct_stop_query STRING' Specifies the SQL query to be executed upon arrival of a "Keepalive Packet". Typically, this would be some `UPDATE' statement. `acct_nasup_query STRING' Specifies the SQL query to be used upon arrival of an "Accounting Off Packet". `acct_nasdown_query STRING' Specifies the SQL query to be used when a NAS sends "Accounting On Packet". None of these queries should return any values. * Menu: * Queries:: Writing SQL acounting query templates. File: radius.info, Node: Queries, Up: Accounting server parameters Writing SQL Accounting Query Templates ...................................... Let's suppose you have an accounting table of the following structure: 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) ); On receiving the "Session Start Packet" we would insert a record into this table with `status' set to 1. At this point the columns `acct_session_time', `acct_input_octets', `acct_output_octets' as well as `connect_term_reason' are unknown, so we will set them to 0: # 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}',\ '%C{Called-Station-Id}',\ '%C{Calling-Station-Id}') Then, when the "Session Stop Packet" request arrives we will look up the record having `status' = 1, `user_name' matching the value of `User-Name' attribute, and `acct_session_id' matching that of `Acct-Session-Id' attribute. Once the record is found, we will update it, setting 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 Thus, every record with `status' = 1 will represent the active session and every record with `status' = 2 will represent the finished and correctly closed record. The constructed `acct_stop_query' is then: # 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 \ AND acct_session_id='%C{Acct-Session-Id}' Upon receiving a "Keepalive Packet" we will update the information stored with `acct_start_query': acct_alive_query UPDATE calls \ SET acct_session_time=%C{Acct-Session-Time},\ acct_input_octets=%C{Acct-Input-Octets},\ acct_output_octets=%C{Acct-Output-Octets},\ framed_ip_address=%C{Framed-IP-Address} \ WHERE user_name='%C{User-Name}' \ AND status = 1 \ AND acct_session_id='%C{Acct-Session-Id}' 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 `acct_nasdown_query' so that it would set `status' column to 2 and update `acct_session_time' in all records having `status' = 1 and `nas_ip_address' equal to IP address of the NAS. Thus, all sessions on a given NAS will be closed correctly when it brought down. The `acct_session_time' can be computed as difference between the current time and the time stored in `event_date_time' column: # 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}' We have not covered only one case: when a NAS crashes, e.g. due to a power failure. In this case it does not have a time to send `Accounting-Off' request and all its records remain open. But when the power supply is restored, the NAS will send an "Accounting On packet", so we define a `acct_nasup_query' to set `status' column to 3 and update `acct_session_time' in all open records belonging to this NAS. Thus we will know that each record having `status' = 3 represents a crashed session. The query constructed will be: # Query to be used when a NAS goes up, i.e. when it sends # Accounting-On packet acct_nasup_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}' File: radius.info, Node: rewrite file, Next: menus file, Prev: sqlserver file, Up: Configuration Files Rewrite functions -- `raddb/rewrite' ==================================== The file `raddb/rewrite' contains definitions of Rewrite extension functions. For information regarding Rewrite extension language *Note Rewrite::. File: radius.info, Node: menus file, Next: Macro Substitution, Prev: rewrite file, Up: Configuration Files Login Menus -- `raddb/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 `--enable-livingston-menus' option. A user is presented a menu after it is authenticated if the RHS of his profile record consists of a single A/V pair in the form: Menu = The menu files are stored in directory `raddb/menus'. * Menu: * Syntax: menu syntax. A menu file syntax. * Example: menu example. An example of menu files. File: radius.info, Node: menu syntax, Next: menu example, Up: menus file A menu file syntax. ------------------- A menu file is a text file containing a menu declaration and any number of choice descriptions. The menus can be nested to an arbitrary depth. A comment is introduced by a `#' character. All characters from this one up to the end of line are discarded. The menu declaration is contained between the words `menu' and `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 `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. File: radius.info, Node: menu example, Prev: menu syntax, Up: menus file An example of menu files ------------------------ Single-Level Menu ================= Suppose the following file is stored under `raddb/menus/menu1': 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" Now, suppose the `raddb/users' contains the following profile entry: DEFAULT Auth-Type = System Menu = "menu1" and user `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 `Menu' attribute. Radius then sends Access-Challenge packet to the NAS with the text of the menu in it. The `jsmith' then sees on his terminal: *** Welcome EEE user! *** Please select an option: 1. Start CSLIP session 2. Start PPP session 3. Quit Option: He then enters `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: Service-Type = Framed-User, Framed-Protocol = PPP, Framed-IP-Address = 255.255.255.254, Termination-Menu = "menu1" The `Termination-Menu' in this list makes sure the same process will continue when `jsmith' logs out, i.e. he will be presented the same menu again until he enters choice `3' which will disconnect him. Nested menus ============ In this example, the `other' choice refers to the menu above. 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" File: radius.info, Node: Macro Substitution, Prev: menus file, Up: Configuration Files Macro Substitution ================== Some statements in the configuration files need to use the actual values of the attributes supplied with the request. These are: * `Exec-Program' and `Exec-Program-Wait' assignments in `users' database * SQL query templates in `sqlserver' In these statements the following macros are replaced by the value of corresponding attributes: `%Cnum' (num is a decimal number). This variable is replaced by the value of attribute number `num'. The attribute is looked up in the incoming request pairlist. `%C{attr-name}' This is replaced by the value of attribute named `attr-name'. The attribute is looked up in the incoming request pairlist. `%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. `%R{attr-name}' This is replaced by the value of attribute named `attr-name'. The attribute is looked up in the reply pairlist. `%D' This is replaced by current date/time (localtime). `%G' This is replaced by current date/time in GMT. The "`{}' form" allows to specify default value for the substitution. The default value will be used when no such attribute is encountered in the pairlist. The syntax for specifying the default value resembles that of shell environment variables. The substitution `%C{ATTR-NAME:-DEFVAL}' is expanded to the value of ATTR-NAME attribute, if it is present in the request pairlist, and to DEFVAL otherwise. For example: %C{Acct-Session-Time:-0} will return the value of Acct-Session-Time attribute or 0 if it doesn't exist in the request pairlist. The substitition `%C{ATTR-NAME:=DEFVAL}' is expanded to the value of ATTR-NAME attribute. If this attribute is not present in the request pairlist, it will be created and assigned the value DEFVAL. E.g.: %C{Acct-Session-Time:=0} The substitution `%C{ATTR-NAME:?MESSAGE}' is expanded to the value of ATTR-NAME attribute, if it is present. Otherwise the diagnostic message "ATTR-NAME: MESSAGE" is issued to the log error channel, and string "MESSAGE" is returned. The substitition `%C{ATTR-NAME:+RETVAL}' is expanded to empty string if the attribute ATTR-NAME is present in the referenced pairlist. Othervise it is expanded to RETVAL. You can also use the following shortcuts: `%p' Port number `%n' NAS IP address `%f' Framed IP address `%u' User name `%c' Callback-Number `%i' Calling-Station-Id `%t' MTU `%a' Protocol (SLIP/PPP) `%s' Speed (Connect-Info attribute) File: radius.info, Node: Authentication, Next: Accounting, Prev: Configuration Files, Up: Top Authentication ************** An "Authentication Type" specifies which credentials the user is required to supply in order to be authenticated and where the user's authentication data are stored. It is defined by the value of `Auth-Type' attribute in LHS of a `users' entry. * 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:: Authenticate using SQL. * PAM Auth:: Authenticate using PAM. * Custom Auth:: Defining Custom Authentication Types. * Checking Simultaneous Logins:: File: radius.info, Node: Accept Auth, Next: Reject Auth, Up: Authentication Accept Authentication Type ========================== "Accept" is the simplest authentication type. Users with this authentication type will be authenticated successfully without checking any credentials. Actually this means that only username is required for authentication. This authentication type is used for each `users' entry, whose LHS contains Auth-Type = Accept This authentication type can be used for guest accounts, e.g. the following profile in `users': guest Auth-Type = Accept, Password != "", Simultaneous-Use = 10 Service-Type = Framed-User, Framed-Protocol = PPP allows up to 10 simultaneous guest PPP accounts. To log in using such guest account it is sufficient to use username `guest' and any non-empty password. File: radius.info, Node: Reject Auth, Next: Local Password Auth, Prev: Accept Auth, Up: Authentication Reject Authentication Type ========================== The "Reject" authentication type causes the request to be rejected unconditionally. It can be used to disable a user account (For another method of disabling user accounts, *note access.deny file::). This authentication type is used for each `users' entry, whose LHS contains Auth-Type = Reject File: radius.info, Node: Local Password Auth, Next: Encrypted Password Auth, Prev: Reject Auth, Up: Authentication Local Password Authentication Type ================================== The "Local Password" authentication type allows to keep plaintext user passwords. Although the use of this authentication type is strongly discouraged for security reasons, this is the only authentication type that can be used with CHAP authentication. There are two ways of using this authentication type Specifying Passwords in users File. ----------------------------------- To keep the plaintext passwords in `users' file, the profile entry must follow this pattern: USER-NAME Auth-Type = Local, Password = PLAINTEXT The PLAINTEXT is the user's plaintext password. Obviously, USER-NAME may not be `DEFAULT' nor `BEGIN'. Specifying Passwords in SQL Database. ------------------------------------- USER-NAME Auth-Type = Local, Password-Location = SQL When the user is authenticated using such profile, its password is retrieved from the authentication database using `auth_query'. The configuration of SQL authentication is described in detail in *Note Authentication Server Parameters::. File: radius.info, Node: Encrypted Password Auth, Next: System Auth, Prev: Local Password Auth, Up: Authentication Encrypted Password Authentication Type ====================================== The "Encrypted Password" type allows to keep user's passwords encrypted via DES or MD5 algorythm. There are two ways of using this authentication type. Specifying Passwords in users File. ----------------------------------- USER-NAME Auth-Type = Crypt-Local, Password = CRYPT-PASS The `Crypt-Password' is a shortcut for the above notation: USER-NAME Crypt-Password = CRYPT-PASS Specifying Passwords in SQL Database. ------------------------------------- USER-NAME Auth-Type = Crypt-Local, Password-Location = SQL Using this profile, the user's password is retrieved from the authentication database using `auth_query'. The configuration of SQL authentication is described in detail on *Note Authentication Server Parameters::. The shortcut for this notation is `Auth-Type = SQL'. In any case, the passwords used with this authentication type must be either DES or MD5 hashed. File: radius.info, Node: System Auth, Next: SQL Auth, Prev: Encrypted Password Auth, Up: Authentication System Authentication Type ========================== The "System" authentication type requires that the user have a valid system account on the machine where the radius server is running. The use of this type is triggered by setting Auth-Type = System in the LHS of a `users' entry. File: radius.info, Node: SQL Auth, Next: PAM Auth, Prev: System Auth, Up: Authentication SQL Authentication Type ======================= Setting `Auth-Type = SQL' or `Auth-Type = Mysql' in the LHS of a `users' entry is a synonim for Auth-Type = Crypt-Local, Password-Location = SQL and is provided as a shortcut and for backward compatibility with previous versions of GNU Radius. For description of SQL authentication, *Note Encrypted Password Auth::. The configuration of SQL subsystem is described in *Note sqlserver file::. File: radius.info, Node: PAM Auth, Next: Custom Auth, Prev: SQL Auth, Up: Authentication PAM Authentication Type ======================= "PAM" authentication type indicates that a user should be authenticated using PAM (Pluggable Authentication Module) framework. The simplest way of usage is: Auth-Type = PAM Any user whose `users' profile contains the above, will be authenticated via PAM, using service name `radius'. If you wish to use another service name, set it using `Auth-Data' attribute, e.g.: Auth-Type = PAM, Auth-Data = PAM-SERVICE File: radius.info, Node: Custom Auth, Next: Checking Simultaneous Logins, Prev: PAM Auth, Up: Authentication Defining Custom Authentication Types ==================================== The are three ways to define custom authentication types: 1. Write a PAM module. 2. Use a Guile procedure. 3. Use an external program You can write a PAM module implementing the new authentication type. Then, specifying `Auth-Type = PAM' allows to apply it (*note PAM Auth::). Alternatively, you may write a Scheme procedure implementing the new authentication type. To apply it, use `Scheme-Procedure' attribute in RHS. The `Auth-Type = Accept' can be used in LHS if the whole authentication burden is to be passed to the Scheme procedure. For example, if one wrote a procedure `my-auth', to apply it to all users, one will place the following profile in his `users' file: DEFAULT Auth-Type = Accept Scheme-Procedure = "my-auth" For a discussion of how to write Scheme authentication procedures, *Note Authentication with Scheme::. The third way to implemement your own authentication method is using an external program. This is less effective than the methods described above, but may be necessary sometimes. To invoke the program, use the following statement in the RHS of `users' entry: Exec-Program-Wait = "PROGNAME ARGS" The PROGNAME must be the full path to the program, ARGS -- any arguments it needs. The usual substitutions may be used in ARGS to pass any request attributes to the program (*note Macro Substitution::). For a detailed description of `Exec-Program-Wait' attribute and an example of its use, *Note Exec-Program-Wait::. File: radius.info, Node: Checking Simultaneous Logins, Prev: Custom Auth, Up: Authentication Checking Simultaneous Logins ============================ The number of sessions a user can have open simultaneously can be restricted by setting `Simultaneous-Use' attribute in the user's profile LHS (*note Simultaneous-Use::). By default the number of simultaneous sessions is unlimited. When a user with limited number of simultaneous logins authenticates himself, Radius first counts the number of the sessions that are already opened by this user. If this number is equal to the value of `Simultaneous-Use' attribute the authentication request is rejected. T