Hi, Chris. On Wed, Nov 28, 2001 at 01:42:02PM -0600, Chris Parker wrote: > However, in order to use it, I have to learn a whole new markup language. > > Irony of ironies, the documentation for JADE ( the editor recommended > on the docbook site ) sucks.
Ugh. That site must really suck, if it led you to believe jade is an editor. 'jade' is a renderer. It will render the DocBook SGML to any format that it has a backend for (usually HTML, PDF, and RTF). Docbook really is nice. Please try it. An excellent site is URL: http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html . Here's how useful DocBook is: O'Reilley's authors use Docbook (usually). ORA used jade on the very same source to render it to ROFF for the print-house and HTML for the webmonster. Both look really good. I'm becomming to grok the Buddha-nature of DSSSL (we use it at work), so feel free to ask me to make the rendering phase do what you want. Attached is the single-page HTML rendering of what I have so far. - chad -- Chad Miller <[EMAIL PROTECTED]> <url: http://web.chad.org/home/> ``Is it wrong to donate Kool-Aid to one's favorite kook organizations when The Comets come around?'' - C. M.Title: FreeRADIUS Operating Manual
Chapter 1. OverviewFreeRADIUS is an implementation of the RADIUS protocol. It aims to be a free, fast, robust, feature-rich server. Livingston's RADIUS server, the first decent free (libre) RADIUS server, is the basis of most RADIUS implementations today. From it grew many attempts at improvement and redesign. One of those reimplementations, Cistron's, became popular for its features and rapid development and it became a staple for those in the ISP business who were dissatisfied with other servers. Eventually, Cistron's server was well entrenched, and development and redesign issues begat The FreeRADIUS Project. Cistron's server is still in usage, but active development on it has ceased and been moved to development of FreeRADIUS The RADIUS protocol is a means of authentication and accounting sessions, usually of dialin users, but feasably of any kind of session. It does not address other concerns like billing, user organization, or data management. A RADIUS server listens on a network for authentication requests, and upon receipt of requests, either answers with a rejection or with confirmation and optional session attribute suggestions. Upon recipt of an accounting packet, it can store evidence of the session starting or terminating. 1.1. Compilation and InstallationThe FreeRADIUS server is written in the C programming language, and a POSIX environment with a ANSI C compiler and GNU Make is necessary to create an executable from source code. There are plenty of optional features of the server that require additional software to be installed for one to use those features. At present, The FreeRADIUS Project does not distribute binary packages; you might get some from your OS vendor or by asking the freeradius-users email list. All the components necessary to build a binary are freely available, though, so you should be able to build it yourself. One should get the server's source code by reading the instructions at http://www.freeradius.org/getting.html. The steps for compiling and installing from FreeRADIUS source (in an example ~/freeradius directory) should be something like... Example 1-1. Compiling and Installing FreeRADIUS foo:~/freeradius$ ./configure --help (browse the options) foo:~/freeradius$ ./configure [options] loading cache ./config.cache checking for gcc... gcc checking whether the C compiler (gcc ) works... yes checking whether the C compiler (gcc ) is a cross-compiler... no checking whether we are using GNU C... yes checking whether gcc accepts -g... yes checking how to run the C preprocessor... gcc -E [...] foo:~/freeradius$ make make[1]: Entering directory `/home/bar/freeradius' [...] foo:~/freeradius$ su Password: foo:~/freeradius# make install make[1]: Entering directory `/home/bar/freeradius' [...] 1.2. ExecutionThe server executable should be at sbin/radiusd after installation. When executed, parameters given on the command line should override any corresponding setting in the server's configuration file. The configuration file is described in Chapter 2. Execution parameters are each single letter ``short'' paremeters, some with words that specify values where appropriate.
radiusd [-a accounting directory] [-d configuration directory] [-l log location] [-i ip address] [-p port number] [-A] [-f] [-h] [-s] [-S] [-v] [-X] [-x] [-y] [-z] The -a option sets .... Chapter 2. Configuration Concepts and FilesAfter installation, the files that configure the server are typically installed under etc/raddb/, at some installion root. The root is usually at / (if installed with a FHS-compliant package) or /usr/local/ (if you install it yourself), unless you set prefix to something else when you ran the ./configure program before compiling. (See Section 1.1.) 2.1. Configuration Structure and ParsingAlmost every file in the configuration directory is in the same format. There are four kinds of ``things'' in the config files: Sections, Assignments, Directives, and Comments. The parser of the files is pretty simple, and doesn't allow more than one ``thing'' per line, so if you start a section, you can not put a comment on the same line, for instance. You can have any amount of whitespace before or after "things" in the config files, including entirely blank lines, so you should use indention to help visually group items. Comments are the easiest to understand; they are lines that begin with an octothorpe, #. Everything up to the end of that line is ignored by the parser. Assignments are variable names, followed by an equals-sign (=), followed by a value for that variable. Sections are used to group ``things'' together under a common name. They start with a word that tells the server what kind of Section it is. The server will need to refer to the Section by a name, and you can give one after the first word, or if you don't specify one, the server will assume the name is the same as the Section type. (Thus, foo foo is the same as foo.) After the Section's type and optional name is an opening brace ``{'', and on a later line is the brace' closing sister, ``}''. Example 2-1. Sections, Subsections, and Comments # this section has a type of "pigments" and an appropriate name of "dumbexample"
pigments dumbexample {
# This section has a name of "azure"
blue azure {
# Azure is nice
}
# This section has a name of "blue"
blue {
# (this comment intentionally left blank)
}
}
danube blue {
# This "blue" is distinct from the dumbexample "blue", above,
# as it's in another namespace. Another top-level "blue" wouldn't
# be allowed, now would another "blue" under "pigments".
}
Directives are single words that have some meaning for the server. These are pretty rare outside a few particular areas that are discussed in just a moment. One can mix Comments, Assignments, Directives, and Sections in any manner one wishes. The FreeRADIUS server cares about only five sections, when it starts up. If those five sections refer to other things (and they most certainly will!), then the server goes looking for the referenced information. The parser is "lazy" that way, in that if you have something misspelled, and if the server doesn't require it in order to run (perhaps it has a sane default value), then you will never hear a complaint from the server. It treats the config files as a bag full of information from which it can pull what it needs, rather than like a list of instructions (each of which would be important). If an entry isn't there, spelled as the server is expecting, then the server isn't alarmed. Think ``phone book'' rather than ``cooking recipe.''
What are the magical five sections that the server really cares about, and requires them in order to run? They are authorization, authentication, preaccounting, accounting, and session and they contain only Directives. These Directives are module names that piece together the flow of execution for the running server. Each module that is referenced in one of the five magical sections has to be the name of a subsection inside a section in the top-level, called ``modules''. What each of the five sections does will be described later, in Section 2.2.1. Because a lot can go into the configuration of a RADIUS server, there is a way to split out blocks of configuration into different files, and refer to them in the main etc/raddb/radiusd.conf file. One can use the $INCLUDE tag on an empty line to have the parser read that file as if it were part of the current file. The $INCLUDE tag is not recursive, though, so included files can not include others, and all $INCLUDE tags must occur in the etc/raddb/radiusd.conf file. Sure, there are a few other files in the etc/raddb/ directory that don't follow these guidelines, but their purporse and format will be described later, when the code that uses them is discussed. 2.2. Actual Sections and Variables2.2.1. Five Execution SectionsThere are five sections that the FreeRADIUS server cares about when starting up, the main five sections described below. When those are parsed, the information contained in them may induce the server to look in other parts of the config files for information on how to behave. Their contents directly translate into execution paths of the server. 2.2.1.1. The authorization SectionWhen the server receives an authentication request from a known client, it eventually intends to reply to it. Before the authorization section begins, the server takes the attribute-value pairs that the auth-request provides and builds a ``request-list'' from it. It also creates two empty lists, one that will contain attributes that it will use to decide if the user is allowed a session (a ``check-list'') and one that contains session attributes that it will send to the client (a ``reply-list'') if the session is allowed. The authorization section is a stage used to set up values in the check-list, in preparation for the next stage in processing the request, authentication. Execution passes through the authorization section until the end of the list of declarations, or when a module returns reject, ok, or handled. 2.2.2. Top-level VariablesThere are a lot of variables outside any section that set the behavior of the server:
2.2.3. Proxy SectionThe FreeRADIUS server can act as a proxy, accepting requests and making its own requests to another RADIUS server, on behalf of its client.
For realms, it's best to declare top-level realm sections for each realm to use. The secondary name of the section is the realm to be matched against. Example 2-2. Defining proxy realms realm isp2.com {
type = radius
authhost = 0.auth.radius.isp2.com:1645
accthost = 0.acct.radius.isp2.com:1646
secret = TheirKey
detailfile = /var/log/radacct/isp2/detail
nostrip
utmpfile = /var/log/radutmp-isp2
wtmpfile = /var/log/radwtmp-isp2
}
realm momandpop.com {
type = radius
authhost = LOCAL
accthost = LOCAL
secret = hi-mom
}
realm NULL {
type = radius
authhost = radius1.isp4.com:1645
accthost = radius2.isp4.com:1646
secret = isp4secret
}
realm DEFAULT {
type = radius
authhost = 0.auth.radius.isp2.com:1645
accthost = 0.acct.radius.isp2.com:1646
secret = TheirKey
detailfile = /var/log/radacct/isp2/detail
}
2.2.4. Thread Pool SectionIf you have thread pools compiled in to the server, then you should adjust the pool settings to your environment. The section is called thread, and it has several attributes.
2.2.5. Clients SectionThere should be several client sections, one for each client that should use the server. The secondary section name (the first being client) should be the IP address of the client, in dotted-quad notation. Within that section, several variables are useful:
2.2.6. Module SectionModules are independent pieces of code that are designed in the same spirit as the Unix toolkit, in that each thing does only a few things, but does them well. 2.2.6.1. acct_unique moduleApplicable Sections. accounting This module adds a (hopefully) unique session id to an accounting packet based on the RADIUS attributes listed in the module configuration's key value. Based on the attributes listed in the key, this module will concatenate the attribute name and value received in the accounting request packet, and then calculate a (unique) md5 digest value from that concatenated list of attributes. After generating the md5 digest value, it adds it to the accounting request packet received from the client. The resultant attribute created by this module is called Acct-Unique-Session-Id, and it's a useful bit of info to have inserted into your accounting log. Suggested Uses. Useful for keeping long-lasting accounting records, in which one can use the key as an index in some storage system, like an SQL server or detail logs. It's not an expensive operation, so use on a heavily-burdened server should not impact performance much.
2.2.6.2. always moduleApplicable Sections. authorize, authenticate, preaccounting, accounting, session Unconditionally handles requests a predetermined way. This modules is most useful for debugging the server, over anything else. The best way to accept requests unconditionally is though the files module's FOO attribute in its users file, as described in Appendix A. Suggested Uses. This should almost never be used.
2.2.6.3. attr_filter moduleApplicable Sections. authorize This modules is allowed only in the authorize section, and should be placed before use of a Realm module instance. This module exists for filtering certain attributes and values in received radius packets from remote proxied servers. It gives the proxier (us) a very flexible framework to filter the attributes that proxied servers send us in their replies. This makes sense in an out-sourced dialup situation, for example, where the client's proxy is permitted only certain values for setting the Idle-Timeout. Filter rules are defined and applied on a per-realm basis, where the realm can be anything you have defined via the rlm_realm module. Suggested Uses. Use this when you have upstream RADIUS servers controlled by one organization sending information through you to downstream RADIUS clients controlled by a different organization.
2.2.6.3.1. Format of the attrsfile fileThe file that defines the attribute filter rules is layed out and parsed very similar to the users file (See Appendix A). There are a couple main differences:
See the comments in the default 'attrs' file for examples and additional explanation. 2.2.6.4. attr_rewrite moduleApplicable Sections. authorize, authenticate, preaccounting, accounting, session In authentication and accounting requests, filters out some attributes, as useful to do when proxying to another server or massaging data from clients into a normalized or "standard" form.
2.2.6.5. counter moduleApplicable Sections. authorize, accounting In accounting, sums a user's usage in a GDBM DB. In authentication, creates an attribute in your check-list based on past usage, with which, you can later test to see if this new session is allowed or not. Suggested Uses. Use this to enforce a limit on usage of your RADIUS-protected resource, for accounts that aren't allowed unlimited usage.
2.2.6.6. detail moduleApplicable Sections. accounting Meaningless in authentication, but accounts to the traditional RADIUS ``detail'' file format. The placement of the file is very powerful, as it can be based on expansion of request attributes (see Appendix C).
2.2.6.8. example moduleApplicable Sections. (none) Useful only as an example for new module developers. Don't enable this in your server. 2.2.6.9. fastusers moduleApplicable Sections. authorize, authenticate, preaccounting, accounting Behaves identically to the files modules, as described in Section 2.2.6.10, with the exceptions that authentications are done in (nearly) constant time (rather than being ``Big-O of N''), and there are additional cache-related settings. Suggested Uses. Use of this is nice if you have a lot of users and have some source from which you can generate a users-style file from it. It's the successor to the slower files module.
2.2.6.10. files moduleApplicable Sections. authorize, preaccounting Authenticates users from a somewhat Livingstonesque, very Cistronlike ``users'' file. See Appendix A for information about the file format.
2.2.6.12. ldap moduleApplicable Sections. authorize, authenticate Authenticates users via a LDAP tree. Meaningless in accounting. Suggested Uses. This is an appealing way to authenticate users, but the code is not yet ready for use in an important environment. Feedback is welcome.
2.2.6.14. ns_mta_md5 moduleApplicable Sections. authenticate Suggested Uses. This is a rarely used module. Its use isn't discouraged, but not very well supported by developers.
2.2.6.15. pam moduleApplicable Sections. authenticate Authenticates to any PAM method that your system has available. Suggested Uses. This is an easy way to add a level of indirection to authentication and gain access to another realm of authentication methods. This is a powerful idea, if only a simple module.
2.2.6.16. preprocess moduleApplicable Sections. authorize, preaccounting A multipurpose module used in both authorization and preaccounting. It prepares a request structure to be handled by other modules.
2.2.6.17. radutmp moduleApplicable Sections. accounting, session Accounts users to a typical Unix ``utmp'' file. Meaningless in authentication. Suggested Uses. This is an ugly and discouraged way to account and session-limit. Use a detail file, or SQL DB instead.
2.2.6.18. realm moduleApplicable Sections. authorize, preaccounting In authorize and preaccounting, a single character may be a username/realm delimiter.
2.2.6.19. sql moduleApplicable Sections. authorize, authenticate, accounting Authenticates and accounts from and to a SQL server. Note that because this module involves several variables, its configuration is often split out to another file, and included into the configuration at runtime with $INCLUDE. See the etc/raddb/radiusd.conf file. Suggested Uses. This is a great way to account usage. If you already store user information in a DB, then it's also an excellent way to authenticate users.
2.2.6.20. unix moduleApplicable Sections. authenticate, accounting Auths out of the system password database, usually /etc/passwd. Accounts to utmp. Suggested Uses. If you store user information in your system password files only, then this is a good way to go about using that to auth users. (If you expect to grow past a few thousand accounts (especially more than 2**16), though, use a faster and more robust user database, like SQL or LDAP.)
Chapter 3. TroubleshootingUse the -X command-line argument. Blah blah. Use gdb. Stack trace. core-dumps=yes. Blah. Appendix A. Format of the users fileA request has initially an empty check list and an empty reply list attached to it. So each incoming authentication request has three attribute-value lists associated with it:
For every entry in the users file, the Username value-pair is compared to it. If an entry in the users-file matches, or if it is a DEFAULT entry, a check pair is created (call it ``tempcheck'') by adding the check list of the current users-file entry to the check list of the request. If an attribute is already present in the check list of the request, then it will not be changed. Then the request list is compared with the ``tempcheck'' list. If all items match (except for password-related items at this time!) then both of the following actions are taken: The reply list of the users-file entry is appended to the reply list of the request. The check list of the request is replaced by the ``tempcheck'' list. Then a check is made to see if the reply list contains an attribute-value pair of Fall-Through = yes. If not, we stop processing the users-file. If so, we continue with the users-file's next entry. Then after all this is done, the authentication information is filtered from the check list, the password of the user is checked, and we send an appropriate reply back to the client. Appendix B. Username Collision HandlingMany ISPs are acquiring other ISPs in local or remote areas. This causes problems with centralizing services such as RADIUS because of the overlap in usernames between ISPs. For example:
Currently, it only works when authenticating users via the following methods in FreeRADIUS:
The reason user collision cannot be implemented (efficiently) on a non-cached /etc/passwd file is because getpwnam() will always return the first user it finds with a matching username. Thus, if you're going to use the /etc/passwd file, you MUST set cache = yes in your etc/raddb/radiusd.conf. Or, you could always just put duplicate usernames in the 'users' files, but you should probably be caching anyway if you want a speedy server. B.1. AuthenticationIt currently works by using the password of the user to uniquely identify and authenticate them. Example:
If the user logs in with 'bleah' as the password, again, they'll be authenticated, but they will get the reply attributes associated with user 'foo' password 'bleah'. So, what happens if more than one user has the same username and the same password? It breaks! Well, ok, it doesn't really break, but those users will get the same reply attributes, causing grief for you. The code does not check for this; that is your job!
So the security minded among us are now agast. I'm not much for this method myself, but trust me, the corporate folks are gonna love it. And it's not inherently insecure as long as the passwords remain different. B.2. AccountingOk, so now, how can we tell in the accounting logs which user 'foo' logged in? Well, again, you have a little work to do. The code identifies the user via a unique value assigned to the 'Class' reply attribute in the users file. Example B-1. Collision in a users file foo Auth-Type := Local, Password == "bar"
Class = 0x0001
foo Auth-Type := Local, Password == "bleah"
Class = 0x0002
Now, you'd add other attributes as well, but let's just start with 'Class' by itself as a reply. When a user 'foo' logs in with password 'bar', the 'Class=0x0001' reply item gets sent back to the client they dialed into. The client then adds 'Class=0x0001' to the Accounting 'Start' packet it sends for that user, thus uniquely identifying this 'foo' in the your accounting logs. If the user 'foo' logs in with password 'bleah', you will get 'Class=0x0002' in your accounting logs. Now, again, you should note that it is *your job* to make sure the 'Class' values are different for each user. If you don't, I can assure you the phones will ring off the hook when users get their bills. Obviously, this method works only for users in your 'users' files. If you are using a cached passwd file, then the "Full name" field in the passwd file you cached will be passed back to the client as the value of 'Class'. Be sure they are set differently! In this case, "0x1001" will be passed as the value for the 'Class' attribute when the Auth-Accept packet gets sent back to the client, and then you should see 'Class=0x1001' for that user in your accounting logs. Once again, it is your job to ensure that these Class values are unique for each user. Appendix C. String TranslationString translation is a method of embedding logical tokens in strings that the server will expand to their actual values while handling a request. One might wish to set the Detail-module's logfile variable to include the token %s, so that when a request is handled, the name of the file that the detail-entry is written to has the NAS' IP address as part of the filename. In the design of the string translation code, one will see influences from the C language and from Korn Shell scripting.
Also available is limited parameter expansion, similar to Korn Shell's. The string ${Y} is the same as %Y. One may also use the ${parameter:-word} syntax to mean that if $parameter is unset, then instead substitute word (which is also subject to parameter expansion). A simple example of this is ${u:-(NoUser)}, and a complex one might be ${U:-${u:-(NoUser)}}. IndexA
C
I
N
P
S
U
|
