The GNU Radius ************** GNU Radius is a suite of programs for performing user authentication and accounting using RADIUS protocol. This Info file documents the version 1.6 of the package. Introduction to Radius ********************** GNU Radius is a software package that provides authentication and accounting services. The acronym RADIUS stands for "Remote Authentication Dial In User Service" and (in that form) 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 the administrator to implement any new method she deems convenient. The GNU Radius package includes the server program, `radiusd', which responds to authentication and accounting requests, and a set of accompanying programs designed to monitor the activity of the server and analyze the information it provides. Overview ======== To illustrate what GNU Radius does, let's consider an imaginary internet service provider. Our provider has two "network access servers" (NASes for short)--i.e., two pieces of equipment which directly accept users' connections--and a core router that connects the ISP's internal network with the Internet backbone. When a user connects to a NAS, the server must verify that the user is actually registered and that the credentials she has supplied are correct. This first step is called "authentication". Upon authenticating the user, the NAS must determine which services the user is permitted to use and to what extent the user may use them. This second step is called "authorization". When the first two stages have been successfully completed, the NAS takes the third step and establishes the connection between the user and the main server. This connection is called a "user session". For the purposes of "accounting", the NAS remembers the exact time of the start of the session. When the session is terminated, the duration of the session and the number of bytes transferred are recorded as well. All three tasks can be accomplished by the use of user and accounting databases on each terminal server. However, this is not convenient, and it is error-prone in that the maintenance of separate databases for the same users is not a trivial task. What is worse, as the number of terminal servers grows, this maintenance problem becomes more difficult. How Does RADIUS Perform These Tasks? ------------------------------------ RADIUS allows an administrator to keep authentication and accounting data in a single place, no matter how many network access servers are actually present. Using RADIUS, NASes instead communicate with this central server to perform authentication and accounting, thus easing the burden on the system administrator. Let's return to our imaginary ISP. Suppose it runs a RADIUS daemon on its central server. Each NAS runs "client software" to communicate with the RADIUS server by sending "radius packets". An average user session life cycle looks as follows. A user connects to the nearest NAS and supplies his login and password. The NAS forms an authentication request and sends it to the RADIUS server. The RADIUS server verifies the user's credentials and finds them sufficient. It then retrieves the user's authorization information from its database, packages it into an "acknowledgement packet", and then sends it back to the NAS The NAS receives the acknowledgement packet and starts the user session. The information brought with the packet tells the NAS to establish a connection between the core router and the user, and to assign the user a certain IP address. Having established the session, the NAS informs the RADIUS server by sending it an "accounting start packet". The server acknowledges the receipt of the accounting packet. Now suppose that after some time the user decides to break the connection. The NAS notices this and terminates the user's session. The NAS then sends an "accounting stop packet" to the RADIUS server to mark this event. Again, the server acknowledges the receipt of the packet. RADIUS Attributes ----------------- "Attributes" are means of passing the information between the NAS and the server. Basically, an attribute is an integer number that identifies some piece of information. A set of "properties" are associated with each attribute, specifying the way to interpret the attribute. The most important property is the "data type", which declares the type of data that the attribute identifies ("character string", "integer number", "IP address", or "raw binary data"). The information to be transmitted with the request is packaged in a set of "attribute-value pairs" (or A/V pairs for short). Such pairs consist of attribute numbers and the associated data. RADIUS Packets -------------- There exist two basic kinds of RADIUS packets: authentication and accounting packets. Each of them is subdivided into "requests" and "replies". "Authentication requests" are sent from the NAS to the RADIUS server and contain the information necessary to check the identity of the user. The minimum set of data in such packets consists of the user login name, user password, and NAS IP or identifier. "Authentication replies" are sent by the RADIUS server and contain the reply code and a set of additional attributes. According to their reply code the authentication replies are subdivided into "authentication acknowledgements", "authentication rejections", and "authentication challenges". An authentication acknowledgement packet is sent to the NAS if the credentials supplied with the authentication request were correct. This kind of packet tells the NAS to establish a normal user session. The additional attributes in such packets carry the "authorization data", i.e., they determine which kind of service the user is to be provided. An authentication rejection is sent to the NAS if the authentication has failed. This packet forbids the NAS to provide any service to the user. The additional attributes may carry descriptive text to be displayed as an explanation to the user for the failure of his request. Finally, an authentication challenge packet is sent to the NAS if the supplied credentials did not suffice to establish the authenticity of the user. This means that the dialog between the NAS and the RADIUS server continues. As the RADIUS server asks for additional authentication credentials, the NAS acts as a liaison, passing server requests to the user and sending user replies back to the server. Such a dialog ends when the RADIUS server sends either an acknowledgement packet or a rejection packet. An "accounting request" is sent to the server when the NAS wishes to report some event in the user session: the start of the session, session termination, etc. The attributes carry the actual information about the event. For each accounting request that has been received and successfully processed, the RADIUS server sends back an "accounting acknowledgement". This packet carries no attributes, but simply informs the NAS that the information it had sent was received. Occasionally, a RADIUS server may fail to receive incoming requests or may fail to process them due to high server load. In order to prevent such requests from being lost, the NAS retransmits the request if no response from the server is received within a predefined interval of time (a "timeout" interval). Usually the NAS is configured in such a way that it continues retransmitting failed requests until either it receives a reply from the server or a predefined number of "retries" are exhausted, whichever occurs first. Furthermore, a NAS may be configured to communicate with a set of "backup" RADIUS servers. In this case it applies the described process to each server from the set, until one of them responds or the set is exhausted. 1 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::). "Data directory" A directory where shared data files are stored, such as `Rewrite' or `Scheme' source files. The default locations of these directories are determined at compile time. Usually 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 Data directory `datadir' /usr/local/share/radius/1.6 These locations may differ depending on your local site configuration. Throughout this document we will refer to these directories by their short names. For example, when we say: ... this information is contained in file `raddb/sqlserver' we actually mean `/usr/local/etc/raddb/sqlserver'. To get the default directory names that your version of Radius was compiled with, run `radiusd --version'. Locations of these directories may be overridden by specifying the appropriate command line options. For example, any program from the GNU Radius package accepts the command line option `-d' or `--directory', which introduces the configuration directory path. 2 How Radius Operates ********************* The main purpose of GNU Radius is to centralize authentication of users coming from various network stations, pursuant to the RADIUS specification. Its primary usage is for dial-in users, though it can be used for any kind of network connection. 2.1 Attributes ============== Information carried by RADIUS requests is stored as a list of "attribute-value pairs". Each pair consists of an "attribute number" and an "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 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::). Attribute numbers range from 1 to 255. Attributes with numbers greater than 255 are used internally by the server and cannot be sent to the NAS. The "vendor-specific" attribute number 26 is special, allowing 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 the usage of the attribute in the configuration files `huntgroups', `hints', and `users'. "Propagation" When a RADIUS server functions in proxy mode, it uses the "propagation flag" 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 the addition of new A/V pairs to the incoming request. Before the 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 the "additivity" determines the following additional 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. Attributes are declared in the `raddb/dictionary' file. For a detailed description, see *note ATTRIBUTE::. For information about particular attributes, see *note Attribute List::. 2.2 RADIUS Requests =================== The term "request" refers to both the authentication/accounting request packet from a NAS to a RADIUS server and the response packet 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. 2.2.1 Authentication Requests ----------------------------- A NAS sends authentication requests (packets with code field set to 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 whether any special services are requested for that user. An Access-Request must contain a `User-Name' attribute *note User-Name::. This packet should contain a `NAS-IP-Address' attribute, a `NAS-Identifier' attribute, or both. It also must contain either a `User-Password' attribute or a `CHAP-Password' attribute. These attributes are passed after being 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 an Access-Request packet for a particular user and authenticating that user, the RADIUS server replies to the NAS that has sent the packet with any one of the following packets: * Access-Accept * Access-Reject * Access-Challenge GNU Radius replies with an Access-Accept packet when it has successfully authenticated the user. Such a reply packet provides the configuration information necessary to begin delivery of service to the user. GNU Radius replies with an Access-Reject packet when it is unable to authenticate the user. Such a 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. GNU Radius replies with an Access-Challenge packet when it needs to obtain more information from the user in order to determine the user's 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 it may or may not include a single `State' attribute. No other attributes are permitted in an Access-Challenge packet. Upon 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. In the event of an invalid packet, GNU Radius discards the offending packet and issues the 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 the `Reply-Message' attributes of the request. It then sends its original Access-Request with a new request ID and request authenticator, along with the `User-Password' attribute replaced by the encrypted user's response, and including the `State' attribute from the Access-Challenge, if any. 2.2.2 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 packet, the server attempts to record it (*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 any Accounting-Request packet: * `User-Password' * `CHAP-Password' * `Reply-Message' * `State' Either a `NAS-IP-Address' or a `NAS-Identifier' must be present in an Accounting-Request packet. It should contain either a `NAS-Port' or a `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 of the user. There are five types of accounting packets, differentiated by the value of the `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 or has changed the connection speed. The packet must contain at least the following attributes: * `Acct-Status-Type = Alive' * `User-Name' * `NAS-IP-Address' * `Acct-Session-Id' "Accounting-Off Packet" By sending this packet, the NAS requests that `radiusd' mark all sessions registered from this particular 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 closed. 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 `radiusd' 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-On' * `NAS-IP-Address' 2.3 Matching Rule ================= A record in the GNU 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 GNU Radius configuration files keep data in a matching rule format: `hints', `huntgroups', and `users'. Although they keep data in a similar format, the rules that are used to match incoming requests against the contents of these files differ from file to file. The following section describes these rules in detail. 2.4 Processing Requests ======================= Upon receiving a request, `radiusd' 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 the `User-Name' attribute, it is not processed. Check if the NAS is allowed to speak. The source IP 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 `User-Password' attribute. Process user-name hints. "User-name hints" are special rules that modify the request depending on the user's name and her credentials. These rules allow an administrator 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 an administrator 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. 2.4.1 Checking for Duplicate Requests ------------------------------------- As described above (*note Operation::), a NAS may decide to retransmit the request under certain circumstances. This behavior ensures that no requests are lost. For example, consider the following scenario: 1. The NAS sends a request to the server. 2. The server processes it and sends back the reply. 3. The reply is lost due to a network outage, or the load average of the NAS is too high and it drops the response. 4. The NAS retransmits the request. Thus the RADIUS server will receive and process the same request twice. This probably won't do any harm if the request in question is an authentication one, but for accounting requests it will lead to duplicate accounting. To avoid such an undesirable effect, `radiusd' keeps a queue of received requests. When an incoming request arrives, `radiusd' first scans the request queue to see if the request is a duplicate. If so, it drops the request; otherwise, it inserts the request into the queue for processing. After the request is completed, it will still reside in the queue for a preconfigured interval of time (*note auth::, parameter `request-cleanup-delay'). By default, `radiusd' considers two requests to be equal if the following conditions are met: 1. Both requests come from the same NAS. 2. They are of the same type. 3. The request identifier is the same for both requests. 4. The request authenticator is the same for both requests. Additionally, `radiusd' may be configured to take into account the contents of both requests. This may be necessary, since some NASes modify the request authenticator or request identifier before retransmitting the request, so the method described above fails to recognize the request as a duplicate. This "extended comparison" is described in detail in *note Extended Comparison::. 2.4.2 Proxying -------------- "Proxying" is a mode of operation where a RADIUS server forwards incoming requests from a NAS to another RADIUS server, waits for the latter to reply, and then 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 ISPs to share their resources, allowing each party'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. 2.4.2.1 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 the `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 the `Remote' RADIUS server for processing. Thus, the `Local' RADIUS server acts as a client for the `Remote' RADIUS server. When the `Remote' RADIUS server responds, the `Local' RADIUS server receives the response, and passes it back to the NAS. The copy of the request from the server's queue determines which NAS originated the request. Before passing the request back to the NAS, the server removes information specific to the `Remote' site, such as `Framed-IP-Address', `Framed-Netmask', etc. Only the attributes marked with a `propagation' flag (*note Attributes::) are passed back to the NAS. After removing site-specific attributes, the `Local' RADIUS server 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. Proxied accounting requests are processed in a similar manner, except that no attribute filtering takes place, as accounting responses do not carry any A/V pairs. This example illustrates only the simplest "proxy chain", consisting of two servers; real-life proxy chains may consist of several servers. For example, our `Remote' RADIUS server might also act as a proxy, forwarding the request to yet another RADIUS server, and so on. Note that when the accounting request passes through a chain of forwarding servers, the accounting records are _stored on all servers in the chain_. 2.4.2.2 Realms .............. GNU Radius determines which server a request must be forwarded to by the 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 the 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_ explicitly named realms are forwarded. If the configuration does not define an empty realm, such requests are processed by the server itself. GNU Radius keeps the information about the realms it serves in the `raddb/realms' configuration file (*note realms file::). 2.4.3 Hints ----------- "User-name hints" are special rules that modify the incoming request depending on the user name and its credentials. Hints are stored as a list of "matching rules" (*note Matching Rule::). Upon receiving a request, `radiusd' scans the hint entries sequentially, comparing each rule's label with the value of the `User-Name' attribute from the request. If they coincide, then `radiusd' appends the contents of the rule's RHS to the request's pair list. The two user names must match exactly in order for a hint to take effect, unless the hint's checklist contains either the `Prefix' or the `Suffix' attribute. The special name `DEFAULT' or `DEFAULT%D' (where %D denotes any decimal number), used as a hint's label, matches any user name. 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 `radiusd' to accept the hint only if the user name begins with the given prefix. Similarly, `Suffix' instructs `radiusd' to accept the hint only if the user name 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 the current entry. This allows `radiusd' to apply 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 the `User-Name' attribute from the request. Hint rules are defined in the `raddb/hints' file (*note hints file::). 2.4.4 Huntgroups ---------------- Huntgroups are special rules that allow an administrator to provide alternate processing of certain incoming requests depending on the NAS IP and port number they come from. These 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 meets 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::). Huntgroup rules are defined in the `raddb/huntgroups' file (*note huntgroups file::). 2.4.5 User Profiles ------------------- "User profiles" are _per-user_ matching rules (*note Matching Rule::). All incoming authentication requests are compared with the user profiles after they have passed both hints and huntgroups. `radiusd' selects the user profiles whose label matches the value of the `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 be one of the special labels, `DEFAULT' or `BEGIN'. Rules in an authentication list are ordered as follows: first go all the profiles with the `BEGIN' label, followed by the profiles whose labels match the `User-Name' literally, followed finally by the rules labeled with the `DEFAULT'. (1) Within each of the three sublists, the rules preserve the order in which they appear in the `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, the authentication fails. Otherwise, the contents of its RHS are appended to the reply list being constructed. If the RHS of the matched rule contains the 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. User profiles are defined in the `raddb/users' file (*note users file::). ---------- Footnotes ---------- (1) For compatibility with other radius implementations, 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. 3 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; };'. 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. `-n' `--do-not-resolve' Do not resolve IP addresses for diagnostic output. This can reduce the amount of network traffic and speed up the server. Config file equivalent: `option { resolve no };'. `-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 log file *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::. 4 Radius Configuration Files **************************** At startup, GNU Radius obtains the information vital for its functioning from a number of configuration files. These 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::. Each configuration file is responsible for a certain part of the GNU Radius functionality. The following table lists all configuration files along with a brief description of their purposes. `config' Determines the runtime defaults for `radiusd', such as the IP address and ports to listen on, the sizes of the request queues, configuration of the SNMP subsystem, fine-tuning of the extension languages, etc. `clients' Lists the shared secret belonging to each NAS. It is crucial for the normal request processing that each NAS have an entry in this file. The requests from NASes that are not listed in `clients' will be ignored, as well as those from the NASes that have a wrong value for the shared secret configured in this file. `naslist' Defines the types for the known NASes. Its information is used mainly when performing multiple login checking (*note Multiple Login Checking::). `nastypes' Declares the known NAS types. The symbolic type names, declared in this file can be used in `naslist'. `dictionary' Defines the symbolic names for radius attributes and attribute values. Only the names declared in this file may be used in the files `users', `hints' and `huntgroups'. `huntgroups' Contains special rules that process the incoming requests basing on the NAS IP and port number they come from. These can also be used as a kind of "access control list". `hints' Defines the matching rules that modify the incoming request depending on the user name and its credentials. `users' Contains the individual users' profiles. `realms' Defines the Radius realms and the servers that are responsible for them. `access.deny' A list of usernames that should not be allowed access via Radius. `sqlserver' Contains the configuration for the SQL system. This includes the type of SQL interface used, the IP and port number of the server and the definition of the SQL requests used by `radiusd'. `rewrite' Contains the source code of functions in Rewrite extension language. `menus' A subdirectory containing the authentication menus. The rest of this chapter describes each of these files in detail. 4.1 Run-Time Configuration Options -- `raddb/config' ==================================================== At startup `radiusd' obtains its configuration values from three places. The basic configuration is kept in the executable module itself. These values are overridden by those obtained from `raddb/config' file. Finally, the options obtained from the command line override the first two sets of options. When re-reading of the configuration is initiated either by `SIGHUP' signal or by SNMP channel any changes in the config file take precedence over command line arguments, since `raddb/config' is the only way to change configuration of the running program. This chapter discusses the `raddb/config' file in detail. The `raddb/config' consists of statements and comments. Statements end with a semicolon. Many statements contain a block of sub-statements which also terminate with a semicolon. Comments can be written in shell, C, or C++ constructs, i.e. any of the following represent a valid comment: # A shell comment /* A C-style * multi-line comment */ // A C++-style comment These are the basic statements: 4.1.1 `option' block -------------------- Syntax: ------- option { source-ip NUMBER ; max-requests NUMBER ; radiusd-user STRING ; exec-program-user STRING ; username-chars STRING ; log-dir STRING ; acct-dir STRING ; resolve BOOL ; max-processes NUMBER ; process-idle-timeout NUMBER ; master-read-timeout NUMBER ; master-write-timeout NUMBER ; } ; Usage ----- The `option' block defines the global options to be used by `radiusd'. Boolean statements ------------------ `resolve' Determines whether radius should resolve the IP addresses for diagnostic output. Specifying `resolve no' speeds up the server and reduces the network traffic. 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. `max-processes' Sets the maximum number of child processes. The default value is 16. If you plan to raise this value, make sure you have enough file descriptors available, as each child occupies four descriptors for its input/output channels. `process-idle-timeout' Sets the maximum idle time for child processes. A child terminates if it does not receive any requests from the main process within this number of seconds. By default, this parameter is 3600 seconds (one hour). `master-read-timeout' `master-write-timeout' These two values set the timeout values for the interprocess input/output operations in the main server process. More specifically, `master-read-timeout' sets the maximum number of seconds the main process will wait for the answer from the subprocess, and `master-write-timeout' sets the maximum number of seconds the main process will wait for the subprocess's comunication channel to become ready for input. By default, no timeouts are imposed. String statements ----------------- `radiusd-user' Instructs `radiusd' to drop root privileges and to switch to the real user and group IDs of the given user after becoming daemon. Notice the following implications of this statement: 1. All configuration files must be readable for this user. 2. Authentication type `System' (*note System Auth::) requires root privileges, so it cannot be used with `radiusd-user'. Any `raddb/users' profiles using this authentication type will be discarded. 3. Authentication type `PAM' (*note PAM Auth::) may require root provileges. It is reported to always require root privileges on some systems (notably on Solaris). 4. `exec-program-user' statement (see below) is ignored when used with `radiusd-user'. `exec-program-user' Sets the privileges for the programs executed as a result of `Exec-Program' and `Exec-Program-Wait'. The real user and group ids will be retrieved from the `/etc/passwd' entry for the given user. `username-chars' Determines characters that are valid within a username. The alphanumeric characters are always allowed in a username, it is not necessary to specify them in this statement. By default the following characters are allowed in a username: `.-_!@#$%^&\/"'. The `username-chars' statement overrides this default, thus setting: username-chars ":" will restrict the set of allowed characters to the alphanumeric characters and colon. If you wish to expand the default character set, you will have to explicitly specify it in the `username-chars' argument, as shown in the example below: username-chars ".-_!@#$%^&\\/\":" (Notice the use of escape character `\'). `log-dir' Specifies the logging directory. `acct-dir' Specifies the accounting directory. 4.1.2 `logging' block --------------------- Syntax: ------- logging { prefix-hook STRING ; suffix-hook STRING ; category category_spec { channel channel_name ; print-auth BOOL ; print-pass BOOL ; print-failed-pass BOOL ; level DEBUG_LEVEL ; } ; channel channel_name { file STRING ; syslog FACILITY . PRIORITY [TAG] ; print-pid BOOL ; print-category BOOL ; print-cons BOOL ; print-level BOOL ; print-priority BOOL ; print-tid BOOL; print-milliseconds BOOL; prefix-hook STRING ; suffix-hook STRING ; }; } ; Usage ----- The `logging' statement describes the course followed by `radiusd''s logging information. The parts of this statement are discussed below. 4.1.2.1 Logging hooks ..................... Most diagnostic messages displayed by `radiusd' describe some events that occured while processig a certain incoming request. By default they contain only a short summary of the event. "Logging hooks" are means of controlling actual amount of information displayed in such messages. They allow you to add to the message being displayed any relevant information from the incoming request that caused the message to appear. A "hook" is a special Rewrite function that takes three arguments and returns a string. There are two kinds of logging hooks: "prefix" and "suffix". Return value from the prefix hook function will be displayed before the actual log message, that of the suffix hook function will be displayed after the message. Furthermore, there may be "global" and "channel-specific hooks". Global hooks apply to all categories, unless overridden by category-specific hooks. Global prefix hook is enabled by `prefix-hook' statement appearing in the `logging' block. Global suffix hook is enabled by `suffix-hook' statement. Both statements take as their argument the name of corresponding Rewrite function. For detailed information about writing logging hooks, *Note Logging Hook Functions::. 4.1.2.2 `category' statement ............................ Each line of logging information generated by `radiusd' has an associated "category". The `logging' statement allows each category of output to be controlled independently of the others. The logging category is defined by "category name" and a "severity". "category name" determines what part of radiusd daemon is allowed to send its logging information to this channel. It can be any of `main', `auth', `acct', `proxy', `snmp'. "priority" determines the minimum priority of the messages displayed by this channel. The priorities in ascending order are: `debug', `info', `notice', `warn', `err', `crit', `alert', `emerg'. The full category specification, denoted by the `category_spec' in the above section, can take any of the following three forms: 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. The dot (`.') separates the priority from the category name, it may be surrounded by any amount of whitespace. Additional category options valid for `auth' category are: `print-auth' Log individual authentications. `print-pass' Include passwords for successful authentications. It is _very_ insecure, since all users' passwords will be echoed in the logfile. This option is provided only for debugging purposes. `print-failed-pass' Include passwords for failed authentications. 4.1.2.3 `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. Its optional last argument allows to alter default syslog tag. Channel options modify the data flowing through the channel: `print-pid' Add the process ID of the process generating the logging information. `print-cons' Also send the logging information to the system console. `print-category' Add the category name to the logging information. `print-priority' `print-level' Add the priority name to the logging information. `print-milliseconds' Print timestamp with milliseconds. `prefix-hook' Declares the name of Rewrite function used as logging prefix hook for that channel (*note hooks::). This overrides any global prefix hook. `suffix-hook' Declares the name of Rewrite function used as logging suffix hook for that channel (*note hooks::). This overrides any global suffix hook. 4.1.2.4 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; }; }; 4.1.3 `auth' statement ---------------------- Syntax: ------- auth { listen ( ADDR-LIST | no ); forward ADDR-LIST; port NUMBER ; max-requests NUMBER ; time-to-live NUMBER ; request-cleanup-delay NUMBER ; detail BOOL ; strip-names BOOL ; checkrad-assume-logged BOOL ; password-expire-warning NUMBER ; compare-atribute-flag CHARACTER ; trace-rules BOOL ; reject-malformed-names BOOL ; } ; 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. The special value `no' disables listening for authentication requests. The following example configures radius to listen for the incoming requests on the default authentication port on the address 10.10.10.1 and on port 1645 on address 10.10.11.2. listen 10.10.10.1, 10.10.11.2:1645; `forward' statement ------------------- This statement enables "forwarding" of the requests to the given set of servers. Forwarding is an experimental feature of GNU Radius, it differs from proxying in that the requests are sent to the remote server (or servers) _and_ processed locally. The remote server is not expected to reply. This mode is intended primarily for debugging purposes. It could also be useful in some very complex and unusual configurations. Numeric statements ------------------ `port' Sets the number of which UDP port to listen on for the authentication requests. `max-requests' Sets the maximum number of authentication requests in the queue. Any surplus requests will be discarded. `time-to-live' Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue. `request-cleanup-delay' Sets the request cleanup delay in seconds, i.e. determines how long will the completed authentication request reside in the queue. `password-expire-warning' Sets the time interval for password expiration warning. If user's password expires within given number of seconds, radiusd will send a warning along with authentication-acknowledge response. Default is 0. Boolean statements ------------------ `detail' When set to true, `radiusd' will produce the detailed log of each received packet in the file `radacct/NASNAME/detail.auth'. The format of such log files is identical to the format of detailed accounting files (*note Detailed Request Accounting::). `strip-names' Determines whether `radiusd' should strip any prefixes/suffixes off the username before logging. `checkrad-assume-logged' *Note mlc::, for the description of this setting. It is accepted in `auth' for compatibility with previous versions of GNU Radius. `trace-rules' Enables tracing of the configuration rules that were matched during processing of each received authentication request. *Note Rule Tracing::, for detailed information about this mode. `reject-malformed-names' Enables sending access-reject replies for the access-accept requests that contain an invalid value in `User-Name' attribute. By default such requests are discarded without answering. See the description of `username-chars' (*note username-chars: option.). Character statement ------------------- `compare-attribute-flag' The argument to this statement is a character from `1' through `9'. This statement modifies the request comparison method for authentication requests. *Note Extended Comparison::, for a detailed description of its usage. 4.1.4 `acct' statement ---------------------- Syntax: ------- acct { listen ( ADDR-LIST | no ); forward ADDR-LIST ; port NUMBER ; detail BOOL; system BOOL; max-requests NUMBER ; time-to-live NUMBER ; request-cleanup-delay NUMBER ; compare-atribute-flag CHARACTER ; trace-rules BOOL ; } ; 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. The special value `no' disables listening for accounting requests. The following example configures radius to listen for the incoming requests on the default accounting port on the address 10.10.10.1 and on port 1646 on address 10.10.11.2. listen 10.10.10.1, 10.10.11.2:1646; `forward' statement ------------------- This statement enables "forwarding" of the requests to the given set of servers. Forwarding is an experimental feature of GNU Radius, it differs from proxying in that the requests are sent to the remote server (or servers) _and_ processed locally. The remote server is not expected to reply. This mode is intended primarily for debugging purposes. It could also be useful in some very complex and unusual configurations. Numeric statements ------------------ `port' Sets the number of which port to listen for the authentication requests. `max-requests' Sets the maximum number of accounting requests in the queue. Any surplus requests will be discarded. `time-to-live' Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue. `request-cleanup-delay' Sets the request cleanup delay in seconds, i.e. determines how long will the completed account request reside in the queue. Boolean statements ------------------ `detail' When set to `no', disables detailed accounting (*note Detailed Request Accounting::). `system' When set to `no', disables system accounting (*note System Accounting::). Notice, that this will disable simultaneous use checking as well, unless you supply an alternative MLC method (currently SQL, *Note Multiple Login Checking::, for the detailed discussion of this). `trace-rules' Enables tracing of the configuration rules that were matched during processing of each received accounting request. *Note Rule Tracing::, for detailed information about this mode. Character statement ------------------- `compare-attribute-flag' The argument to this statement is a character from `1' through `9'. This statement modifies the request comparison method for authentication requests. *Note Extended Comparison::, for a detailed description of its usage. 4.1.5 `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'. 4.1.6 `snmp' statement ---------------------- Syntax: ------- snmp { port PORTNO ; listen ( ADDR-LIST | no ); max-requests NUMBER ; time-to-live NUMBER ; request-cleanup-delay NUMBER ; ident STRING ; community NAME ( rw | ro ) ; network NAME NETWORK [ NETWORK ... ] ; acl { allow NETWORK_NAME COMMUNITY_NAME ; deny NETWORK_NAME ; } ; storage { file FILENAME ; perms NUMBER ; max-nas-count NUMBER ; max-port-count NUMBER ; } ; }; Usage ----- The `snmp' statement configures the SNMP service. `listen' statement ------------------ The `listen' statement determines on which addresses radiusd will listen for incoming SNMP requests. The argument is a comma-separated list of items in the form IP:PORT-NUMBER. The IP can be either an IP address in familiar "dotted-quad" notation or a hostname. The :PORT-NUMBER part may be omitted, in which case the default SNMP port (161) is used. If the `listen' statement is omitted, radiusd will accept incoming requests from any interface on the machine. The special value `no' disables listening for SNMP requests. The following example configures radius to listen for the incoming SNMP requests on the default SNMP port on the address 10.10.10.1 and on port 4500 on address 10.10.11.2. listen 10.10.10.1, 10.10.11.2:4500; Numeric statements ------------------ `port' Sets the number of which port to listen for the SNMP requests. `max-requests' Sets the maximum number of SNMP requests in the queue. Any surplus requests will be discarded. `time-to-live' Sets the request time-to-live in seconds. The time-to-live is the time to wait for the completion of the request. If the request job isn't completed within this interval of time it is cleared, the corresponding child process killed and the request removed from the queue. `request-cleanup-delay' Sets the request cleanup delay in seconds, i.e. determines how long will the completed SNMP request reside in the queue. 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. Storage control --------------- GNU Radius stores the SNMP monitoring data in an area of shared memory mapped to an external file. This allows all subprocesses to share this information and to accumulate the statistics across invocations of the daemon. The `storage' statement controls the usage of the storage for the SNMP data. `file' Sets the file name for the SNMP storage file. Unless the filename begins with a `/' it is taken as relative to the current logging directory. `perms' Sets the access permissions for the storage file. _Notice_, that this statement does not interpret its argument as octal by default, so be sure to prefix it with `0' to use an octal value. `max-nas-count' Sets maximum number of NASes the storage file is able to handle. Default is 512. Raise this number if you see the following message in your log file: reached SNMP storage limit for the number of monitored NASes: increase max-nas-count `max-port-count' Sets maximum number of ports the storage file is able to handle. Default is 1024. Raise this number if you see the following message in your log file: reached SNMP storage limit for the number of monitored ports: increase max-port-count 4.1.7 `rewrite' statement. -------------------------- _(This message will disappear, once this node revised.)_ Syntax: ------- rewrite { stack-size NUMBER ; load-path STRING ; load STRING ; }; Numeric statements ------------------ `stack-size' Configures runtime stack size for Rewrite. The NUMBER is the size of stack in words. The default value is 4096. String statements ----------------- `load-path' Add specified pathname to the list of directories searched for rewrite files. `load' Loads the specified source file on startup. Unless STRING is an absolute pathname, it will be searched in directories set up by `load-path' statement. Loading ------- The default load path is ``RADDB':`DATADIR'/rewrite'. 4.1.8 `guile' statement ----------------------- _(This message will disappear, once this node revised.)_ The `guile' statement allows to configure server interface with Guile. Syntax ------ guile { debug BOOL ; load-path STRING ; load STRING ; load-module STRING [ STRING ... ] ; eval EXPRESSION [ EXPRESSION ... ] ; gc-interval NUMBER ; outfile STRING ; }; Usage ----- Boolean statements ------------------ `debug' When set to yes, enables debugging evaluator and backtraces on Guile scripts. Numeric statements ------------------ `gc-interval' Configures the forced garbage collections. By default the invocation of the garbage collector is run by the internal Guile mechanism. However, you may force Radius to trigger the garbage collection at fixed time intervals. The `gc-interval' statement sets such interval in seconds. For more information about Guile memory management system in general and garbage collections in particular, see *note Memory Management and Garbage Collection: (guile)Memory Management. String statements ----------------- `eval' Evaluates its argument as `Scheme' expression. `load-path' Adds specified pathname to `%load-path' variable. `load' Loads the specified source file on startup. `load-module' Loads the specified Scheme module on startup. This statement takes an arbitrary number of arguments. The first argument specifies the name of the module to load, the rest of arguments is passed to the "module initialization" funtion. Module initialization function is a function named `MODULE-init', where MODULE is the module name. Arguments are converted using usual `Guile' rules, except that the ones starting with a dash (`-') are converted to keyword arguments. `outfile' Redirects the standard output and standard error streams of the `Guile' functions to the given file. Unless the filename starts with `/', it is taken relative to the current logging directory. *Note Guile::, for a detailed description of Guile extensions interface. 4.1.9 `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, see *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::. 4.1.10 `filters' statement -------------------------- The `filters' statement configures user-defined external filters. *Note Filters::, for the detailed discussion of external filters. Syntax ------ filters { filter IDENT { exec-path PATH ; error-log FILENAME ; common BOOL [MAX-WAIT]; auth { input-format FMT ; wait-reply BOOL ; }; acct { input-format FMT ; wait-reply BOOL ; }; }; ... }; Each `filter' directive defines a new filter. The IDENT argument declares the name of the filter. This string must be used in `Exec-Program-Wait' or `Acct-Ext-Program' attributes to trigger invocation of this filter (*note Exec-Program-Wait::). Usage ----- exec-path PATH Absolute path to the filter program. error-log FILENAME Redirect error output from the filter program to FILENAME. If the FILENAME does not start with a slash, it is taken relative to the current logging directory (*note log-dir: option.). auth acct These compound statements define authentication and accounting parts of this filter. Any one of them may be missing. The two statements allowed within `auth' and `acct' blocks are: input-format FMT Format of the input line for this filter. Usually this string uses %C{} notations (*note Macro Substitution::). You can also use the return value from a `rewrite' function as input line to the filter. To do so, declare: input-format "=my_func()"; where MY_FUNC is the name of the rewrite function to invoke. The function must return string value. wait-reply BOOL If the filter prints a single line of output for each input line, set this to `yes'. Otherwise, if the filter produces no output, use `wait-reply no'. 4.1.11 `mlc' statement ---------------------- Syntax ------ mlc { method (system|sql); checkrad-assume-logged BOOL; }; Usage ----- `Mlc' statement configures multiple login checking subsystem (*note Multiple Login Checking::). method Sets the method of retrieving information about the currently open sessions. Currently two methods are implemented. Setting `method' to `system' will use system accounting database (*note System Accounting::). This is the default method. Setting it to `sql' will use SQL database. checkrad-assume-logged `radiusd' consults the value of this variable when the NAS does not responds to checkrad queries (*note Multiple Login Checking::). If this variable is set to `yes', the daemon will proceed as if the NAS returned "yes", i.e. it will assume the user is logged in. Otherwise `radiusd' assumes the user _is not_ logged in. 4.2 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. 4.2.1 Comments -------------- Comments are introduced by a pound sign (`#'). Everything starting from the first occurrence of `#' up to the end of line is ignored. 4.2.2 $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, unless its name starts with a slash. 4.2.3 VENDOR Statement ---------------------- Syntax ------ VENDOR VENDOR-NAME VENDOR-ID Usage ----- A `VENDOR' statement defines the symbolic name VENDOR-NAME for vendor identifier VENDOR-ID. This name can subsequently be used in `ATTRIBUTE' statements to define Vendor-Specific attribute translations. *Note Vendor-Specific::. Example ------- VENDOR Livingston 307 4.2.4 ATTRIBUTE statement ------------------------- Syntax ------ ATTRIBUTE NAME NUMBER TYPE [VENDOR] [FLAGS] Usage ----- The `ATTRIBUTE' statement defines the internal representation of an attribute: its symbolic name, data type and syntactical usage. 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 (`-'). The latter usage is for compatibility with previos version of GNU Radius 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 absence 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. 4. Letter `l' (lower-case ell) enables logging the given attribute in detail file (*note Detailed Request Accounting::). This is meaningful only for internal attributes, i.e. the ones whose decimal value is greater than 255 (*note Radius Internal Attributes::). By default such attributes do not appear in detailed logs. The flag `l' reverts this behavior. 5. Letter `E' marks attributes encrypted as described in RFC 2138. Currently these are User-Password and CHAP-Password. 6. Letter `T' marks attribute encrypted according to RFC 2868. 7. The characters from `1' to `9' denote nine user-defined flags (*note Extended Comparison::). Example ------- ATTRIBUTE Service-Type 6 integer - [LR-RLR]=P This statement declares that the attribute number 6 will be referred to by the symbolic name `Service-Type'. The attribute is of integer data type and it may be used 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]+' 4.2.5 Blocks of Vendor-Specific Attributes ------------------------------------------ Syntax ------ BEGIN VENDOR VENDOR-NAME [VENDOR-ID] ... END Usage ----- The `BEGIN' keyword marks start of the block of definitions of vendor-specific attributes. The block is terminated by `END' keyword, optionally followed by an arbitrary number of words, which are regarded as a comment. The block may contain any valid dictionary declarations, except other blocks: nesting of declaration blocks is not allowed. If VENDOR-ID is absent, the value of vendor ID is looked up in the internal table of vendors; therefore, it must be defined before `BEGIN' statement (*note VENDOR::). `BEGIN---END' block alters the handling of `ATTRIBUTE' statements within it. If `ATTRIBUTE' statement does not contain an explicit vendor-id specification, the value of VENDOR-ID is used instead. For compatibility with FreeRadius an alternative syntax is also supported: BEGIN-VENDOR VENDOR-NAME ... END-VENDOR VENDOR-NAME Such compatibility blocks must appear only ater the declaration of VENDOR-NAME (*note VENDOR::). Example ------- The following is the usual way of definig vendor-specific attributes: VENDOR Livingston 307 ATTRIBUTE LE-Terminate-Detail 2 string Livingston ATTRIBUTE LE-Advice-of-Charge 3 string Livingston The following two examples show the alternative ways: VENDOR Livingston 307 BEGIN VENDOR Livingston ATTRIBUTE LE-Terminate-Detail 2 string ATTRIBUTE LE-Advice-of-Charge 3 string END BEGIN VENDOR Livingston 307 ATTRIBUTE LE-Terminate-Detail 2 string ATTRIBUTE LE-Advice-of-Charge 3 string END These three examples are completely equivalent to each other. 4.2.6 ALIAS statement --------------------- Syntax ------ ALIAS NAME ALT-NAME Usage ----- The `ALIAS' statement defines an altenative name ALT-NAME for attribute NAME. The latter should already be defined, otherwise an error occurs. Example ------- ALIAS User-Password Password 4.2.7 PROPERTY statement ------------------------ Syntax ------ PROPERTY NAME FLAGS PROPERTY NAME +FLAGS [-FLAGS ...] Usage ----- The `PROPERTY' statement redefines property flags for attribute NAME. The attribute must be defined, otherwise an error occurs. The `PROPERTY' statement has two forms. In first form, it takes a single argument, representing new property flags for the attribute. In its second form it takes any number of arguments, each of them preceeded by `+' sign, inidicating addition of properties, or by `-' sign, indicating removal of these. *Note ATTRIBUTE::, for the discussion of attribute property flags. Example ------- The following example defines that the attribute `User-Password' may be used only on left-hand side of a `raddb/users' entry, and that it is transmitted in encrypted form. PROPERTY User-Password [L-----]E Next example illustrates adding and removing attribute properties: PROPERTY My-Attrib +P -= it adds propagation bit (`P') and removes `replace' additivity from `My-Attrib' attribute. 4.2.8 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 4.3 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. If the set of NASes share the same encryption key, there are two ways to list it in `raddb/clients'. First, if these NASes lie in a single network, you can specify this network address in `NAS name' field, e.g.: 10.10.10.0/27 seCRet Notice also that specifying full netmask after the `/' character is also allowed, so that the above example could also be written as follows: 10.10.10.0/255.255.255.224 seCRet Otherwise, the keyword DEFAULT may be used as `NAS name'. This notation will match any IP address, so it should be used with caution. 4.3.1 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 4.4 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 the following four fields, the first two being mandatory, the last two being optional: NAS name Specifies either a hostname or IP address for a single NAS or a CIDR net block address for a set of NASes. 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 Multiple Login Checking::). 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::). If this field is not present `true' is assumed. 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 Multiple Login Checking::). 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. compare-auth-flag=FLAG Instructs radius to use attributes marked with a given user-defined flag when comparing authentication requests. It overrides `compare-attribute-flag' (*note auth::) for this particular NAS. *Note Extended Comparison::, for a detailed description of its usage. compare-acct-flag=FLAG Instructs radius to use attributes marked with a given user-defined flag when comparing accounting requests. It overrides `compare-attribute-flag' (*note acct::) for this particular NAS. *Note Extended Comparison::, for a detailed description of its usage. *Note Checking Duplicates::, for general description of request comparison methods. For the list of nas-querying arguments, *Note Full list of allowed arguments: nastypes file. ---------- Footnotes ---------- (1) Logins from DEFAULT NASes are not reflected in SNMP variables. 4.4.1 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 4.5 NAS Types -- `raddb/nastypes' ================================= The `raddb/nastypes' file describes the ways to query NASes about active user sessions. 4.5.1 Syntax of `raddb/nastypes' -------------------------------- _(This message will disappear, once this node revised.)_ 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. Note, that no intervening whitespace is allowed in this field. Methods ======= Version 1.6 of GNU Radius supports following querying methods: finger, snmp, external and guile. . 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 Multiple Login Checking::. 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. 4.5.2 Example of nastypes file. ------------------------------- 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 4.5.3 Standard NAS types ------------------------ The `nastypes' shipped with version 1.6 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 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. 4.6 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::). Notice, that versions of GNU Radius up to 1.0 allowed to use only a subset of attributes in the check list of a `hints' entry, namely: * `Suffix' * `Prefix' * `Group' * `User-ID' This requirement has been removed in version 1.0. 4.6.1 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 4.7 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::). 4.7.1 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 4.8 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. There are three special forms of this field. The name `NOREALM' defines the empty realm, i.e. lines marked with this name will match user names without any realm suffix. The name `DEFAULT' defines the default realm (*note Realms::). The lines with this realm name will match any user name, not matched by any other line in `raddb/realms'. Remote server list A comma-separated list of remote servers to which the requests for this realm should be forwarded. Each item in the list 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. The servers from this list are tried in turn until any of them replies or the list is exhausted, whichever occurs first. The timeout value and number of retries for each server are set via `timeout' and `retry' flags (see below). There may be cases where you would wish a particular realm to be served by the server itself. It is tempting to write # _Wrong!_ realm.name localhost however, this will not work. The special form of the server list is provided for this case. It is the word `LOCAL'. The correct configuration line for the above case will thus be: # Use this to declare a locally handled realm realm.nam LOCAL Flags (optional) The flags meaningful in `raddb/realms' are ignorecase Boolean value. When set, enables case-insensitive comparison of realm names. For example, if a realm were defined as myrealm.net remote.server.net:1812 ignorecase then user name `user@MyREAlm.NeT' will match this definition. 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). timeout Number of seconds to wait for reply from the remote server before retransmitting the request. retries Number of attempts to connect a server. If the server does not respond after the last attempt, the next server from the list is tried. auth Proxy only authentication requests. acct Proxy only accounting requests. 4.8.1 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 remote.net srv1.remote.net,srv2.remote.net 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 4.9 User Profiles -- `raddb/users' ================================== File `raddb/users' contains the list of "User Profiles". *Note User Profiles::, for a description of its purpose. 4.9.1 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 4.10 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. 4.11 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". 4.11.1 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 communication 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. 4.11.2 Authentication Server Parameters --------------------------------------- _(This message will disappear, once this node revised.)_ 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_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. `auth_success_query STRING' This query is executed when an authentication succeeds. *Note Auth Probing::, for the detailed discussion of its purpose. `auth_failure_query STRING' This query is executed upon an authentication failure. *Note Auth Probing::, for the detailed discussion of its purpose. 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. 4.11.3 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 RHS (reply) pair. Otherwise, it describes a LHS (check) 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. 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'. 4.11.4 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. 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 statements 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. Three queries are designed for use by multiple login checking mechanism (*note Multiple Login Checking::): `mlc_user_query STRING' A query retrieving a list of sessions currently opened by the given user. `mlc_realm_query STRING' A query to retrieve a list of sessions currently open for the given realm. `mlc_stop_query STRING' A query to mark given record as "hung". 4.11.4.1 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}' If you plan to use SQL database for multiple login checking (*note Multiple Login Checking::), you will have to supply at least two additional queries for retrieving the information about currently active sessions for a given user and realm (*note Retrieving Session Data::). Each of these queries must return a list consisting of 5-element tuples: USER-NAME, NAS-IP-ADDRESS, NAS-PORT-ID, ACCT-SESSION-ID For example, in our setup these queries will be: mlc_user_query SELECT user_name,nas_ip_address,\ nas_port_id,acct_session_id \ FROM calls \ WHERE user_name='%C{User-Name}' \ AND status = 1 mlc_realm_query SELECT user_name,nas_ip_address,\ nas_port_id,acct_session_id \ FROM calls \ WHERE realm_name='%C{Realm-Name}' While performing multiple login checking `radiusd' will eventually need to close "hung" records, i.e. such records that are marked as open in the database (`status=1', in our setup), but are actually not active (*Note Verifying Active Sessions::, for the description of why it may be necessary). It will by default use `acct_stop_query' for that, but it has a drawback that hung records will be marked as if they were closed correctly. This may not be suitable for accounting purposes. The special query `mlc_stop_query' is provided to override `acct_stop_query'. If we mark hung records with `status=4', then the `mlc_stop_query' will look as follows: mlc_stop_query UPDATE calls \ SET status=4,\ acct_session_time=unix_timestamp(now())-\ unix_timestamp(event_date_time) \ WHERE user_name='%C{User-Name}' \ AND status = 1 \ AND acct_session_id='%C{Acct-Session-Id}' 4.12 Rewrite functions -- `raddb/rewrite' ========================================= The file `raddb/rewrite' contains definitions of Rewrite extension functions. For information regarding Rewrite extension language *Note Rewrite::. 4.13 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'. 4.13.1 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. 4.13.2 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" 4.14 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 exact substitution procedure varies depending on the type of the attribute referenced by macro. If the attribute is of string or date type, `radiusd' first checks if the resulting substitution should be quoted. It does so by looking at the character immediately preceeding `%'. If it is a single or double quote, then `radiusd' assumes the macro must be quoted and replaces it by an appropriately modified attribute value. The purpose of the modification is to ensure that no characters within the expanded string would conflict with the quoting characters. In particular, `radiusd' searches the attribute value for any of the characters `\', `'', `"' and prepends a `\' to any occurrence of these. For example, suppose that attribute `NAS-Identifier' has the value `A "new" host'. Then: nasid=%C{NAS-Identifier} ==> nasid=A "new" host nasid="%C{NAS-Identifier}" ==> nasid="A \"new\" host" nasid=%\C{NAS-Identifier} ==> nasid=A \"new\" host The last example illustrates the use of backslash character to force string quoting in the absense of explicit quotation marks. If an integer attribute reference is quoted, `radiusd' looks up the string translation of its value in the dictionary (*note VALUE::) and uses this string as a replacement. If no translation is found, the numeric value is used. The following example assumes that the value of `Acct-Terminate-Cause' attribute is 10: reason=%C{Acct-Terminate-Cause} ==> reason=10 reason='%C{Acct-Terminate-Cause}' ==> reason='NAS-Request' reason=%\C{Acct-Terminate-Cause} ==> reason=NAS-Request Again, a backslash after percent sign can be used to force dictionary lookup. 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 substitution `%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 substitution `%C{ATTR-NAME:+RETVAL}' is expanded to empty string if the attribute ATTR-NAME is present in the referenced pairlist. Otherwise 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) 5 Request Comparison Methods **************************** The basic notions about comparison of the incoming requests and why it is necessary were given in *note Checking Duplicates::. This chapter concentrates on extended methods of request comparison and on the configuration issues. 5.1 Extended Comparison ======================= The default comparison method may fail to recognize duplicate requests. if the originating NAS has modified the request authenticator or request identifier before retransmitting the request. If you happen to use such NASes, you will have to enable "extended request comparison" to compensate for their deficiencies. The extended request comparison consists in comparing the _contents_ of both requests. However, blindly comparing each A/V pair from both requests won't work, since many attributes do change their values between successive retransmits. Therefore, `radiusd' uses only "comparable attribute", i.e. a user-defined subset of such attributes that can safely be used in comparison. Thus, extended request comparison works as follows: 1. The comparable attributes are extracted from each request. They form two sorted "attribute lists". 2. If lengths of both lists differ, the requests are considered different. 3. Otherwise, the value of each A/V pair from the first list is compared against that of the corresponding A/V pair from the second list. If at least one A/V pair differs, then the requests are considered different. _Notice_, that values of `Password' and `CHAP-Password' are decoded prior to comparison. To use the extended comparison, follow the procedure below: 1. Select user-defined attribute properties. The syntax of dictionary file allows for nine user-defined properties, denoted by characters `1' through `9'. You should select one of them to mark comparable attributes for authentication and another one to mark those for accounting. It is strongly suggested that you use `PROPERTY' statement in your main dictionary file (*note PROPERTY::), instead of modifying `ATTRIBUTE' statements in the underlying dictionary files. *Note ATTRIBUTE::, for detailed description of attribute property flags. 2. To enable the extended comparison for requests coming from any NAS, declare extended comparison flags in `raddb/config'. To enable the extended comparison for authentication requests, add to your `auth' block the statement compare-attribute-flag FLAG; The FLAG is the same symbol you used in the dictionary to mark comparable attributes for authentication. To enable the extended comparison for accounting requests, insert `compare-attribute-flag' statement into the `acct' block. 3. To enable the extended comparison for requests coming from selected NASes, declare extended comparison flags in `raddb/naslist'. Add the following statement to the declaration of those NASes, that require using the extended comparison (in flags column): compare-auth-flag=FLAG,compare-acct-flag=FLAG *Note naslist file::, for a description of naslist file syntax. 5.1.1 An example of extended comparison configuration ----------------------------------------------------- In this example configuration, the user-defined flag `1' marks authentication comparable attributes, and the flag `2' marks the accounting comparable attributes. `raddb/dictionary' ------------------ PROPERTY User-Name +12 PROPERTY Password +1 PROPERTY NAS-Port-Id +12 PROPERTY State +1 PROPERTY Called-Station-Id +12 PROPERTY Calling-Station-Id +12 PROPERTY Acct-Status-Type +2 PROPERTY Acct-Session-Id +2 PROPERTY Acct-Session-Time +2 `raddb/config' -------------- auth { max-requests 127; request-cleanup-delay 2; compare-at