0. WARNING! A number of things have changed since release 1.6.5: a) dictionary files Make sure you are using the latest version of the dictionary files. Due to stricter checks in 1.6.5, a bug in the dictionary file of all previous versions was discovered (the Strip-User-Name VALUE definitions for `Yes' and `No' were missing). If you are using this attribute in the 'hints' file, you need to install the new dictionary files or the server will refuse to start with a message like: Unknown value "No" for attribute Strip-User-Name /etc/raddb/hints[28]: Parse error (check) for entry DEFAULT In 1.6.7, the location of the dictionary files has also changed. The dictionary files are now located under /usr/local/share/radius for a standard install, or perhaps under /usr/share/radiusd-cistron if you're using a vendor package. The upgrade procedure should take care of this for you automatically. b) -a accounting_directory The the behaviour of the "-a accounting_directory" command line option has changed slightly. If you used -a accounting_directory/ with a trailing slash to consolidate all logfiles into accounting_directory/detail instead of accounting_directory/NAS/detail then you need to use -F detail instead - read the radiusd(8rad) manual page for details on those options. c) stricter syntax checking of "users" file. An entry in the users file cannot end with a trailing comma (,) on the last line of the entry anymore - all lines must have comma's except the last one. This is due to changes in the parses. d) Updated redback dictionary In the dictionary.redback file, all underscores have been changed to hyphens ("_" -> "-"). Fix your "users" file if you use those. Also, support for 64-bit integers was added. 1. INTRO This is version 1.6 of the Cistron Radius daemon. It was originally based on radius-1.16 by Livingston Enterprises, available from ftp.livingston.com. Not much (if any) of the original code is left by now. The current code is licensed under the GNU GPL. The server is mostly compatible with livingston radiusd-2.01 (no menus or s/key support though) but with more features, such as: o Can limit max. number of simultaneous logins on a per-user basis. o Multiple DEFAULT entries, that can optionally fall-through. o In fact, every entry can fall-through. Entries are process in order. o "Users" file can be built as DBM file for really large installs. o Deny/permit access based on huntgroup (nas/port) users dials into o Set certain parameters (such as static IP address) based on huntgroup o Extra "hints" file that can select SLIP/PPP/rlogin based on username pattern (Puser or user.ppp is PPP, plain "user" is rlogin etc). o Can execute an external program when user has authenticated (for example to run a sendmail queue). o Can use `$INCLUDE filename' in users and dictionary files o Can act as a proxy server, relaying requests to a remote server o Supports Vendor-Specific attributes and tagged (tunnel) attributes o Can replicate accounting information between multiple servers o No good documentation at all, just like the original radiusd 1.16! Work on real manual pages is progressing slowly. For a large part you can use the documentation of the Livingston 2.01 server. Just remember that using Prefix and Suffix in both the "users" and the (cistron-radiusd specific) "hints" file will give unpredictable results. Well actually it will result in Prefix and Suffix probably not working in the "users" file if you already stripped them off in the "hints" file. The Livington internet site had a lot of information on radius online. Unfortunately Livingston, and the site, don't exist anymore but there's a copy of the site still at http://portmasters.com/www.livingston.com/ Especially worth a read is the "RADIUS for Unix administrators guide" HTML: http://portmasters.com/tech/docs/radius/1185title.html PDF: http://portmasters.com/tech/docs/pdf/radius.pdf Command line flags for radiusd (the server) and all utilities are actually documented (!) in the included Unix manual pages. 2. COMPILE If you don't have a pre-installed binary package, but just unpacked the source and want to compile and install the server, read the INSTALL document. 3. USAGE You can use "radwho" at any time to find out who's logged in. If you want, you can install "radwho" as /usr/local/sbin/in.fingerd, and call it from /etc/inetd.conf instead of your normal fingerd. You can use last -f /var/log/radwtmp to get last info on all users, however the accounting data stored in Unix wtmp file format isn't 100% reliable, and also very slow to process if the radwtmp file grows larger. It's better to turn off radwtmp processing (-w command line option) and only use the detail files in /var/log/radacct for accounting purposes. 4. CONFIGURATION FILES For every file there is a fully commented example file included, that explains what is does and how to use it. Read those sample files too! 4a. CLIENTS Make sure the clients (portmasters, Linux with portslave etc) are set up to use the host radiusd is running on as authentication and accounting host. Configure these clients to use a "radius secret password". For every client, also enter this "secret password" into the file /etc/raddb/clients. See also the manual page for clients(5rad). 4b. NASLIST Every NAS (Network Access Server, also known as terminal server) should have an entry in this file with an abbreviated name and the type of NAS it is (Cisco, Livingston or Portslave). Usually this is the same list as in the "clients" file, but not every NAS is a client and not every client is a NAS (this will start to make sense if you use radius proxy servers). Since version 1.6.4, the defaults in the "naslist" file will be just fine for most installations, unless you want to control simultaneous-use (see also README.simul). 4c. NASPASSWD If ``checkrad'' needs to login on your terminal server to check who is online on a certain port (i.e. it's not possible to use SNMP or finger) you need to define a loginname and password here. This is normally ONLY needed for USR/3Com Total Control terminal servers! 4c. HINTS Customize the /etc/raddb/hints file. This file is used to give users a different login type based on a prefix/suffix of their loginname. For example, logging in as "user" may result in a rlogin session to a Unix system, and logging in as "Puser" could start a PPP session. 4d. HUNTGROUPS This is the /etc/raddb/huntgroups file. Here you can define different huntgroups. These can be used to: - restrict access to certain huntgroups to certain users/groups of users (define this in the huntgroups file itself) - match a loginname with a huntgroup in /etc/raddb/users. One use for this is to give a user a static IP address based on the huntgroup / Point of Presence (s)he dials in to. 4e. USERS With the original RADIUS server, every user had to be defined in this file. There could be one default entry, where you could for example define that a user not in the radius file would be checked agains the UNIX password file and on succesfull login would get a PPP connection. In the new style file, you can define multiple DEFAULT entries. All entries are processed in the order as they appear in the users file. If an entry matches the username, radiusd will stop scanning the users file unless the attribute "Fall-Through = Yes" is set. You can uses spaces in usernames by escaping them with \ or by using quotes. For example, "joe user" or joe\ user. The Cistron Radiusd does not trim any spaces from a username received from the portmaster (livingston does, in perl notation, $user =~ s/\s+.*//;) 4f. NEW RADIUS ATTRIBUTES (to be used in the USERS file). Name Type Descr. ---- ---- ------ Simultaneous-Use integer Max. number of concurrent logins Fall-Through integer Yes/No Exec-Program string program to execute after authentication Exec-Program-Wait string ditto, but wait for program to finish before sending back auth. reply Login-Time string Defines when user may login. Exec-Program can take arguments. You can use macros in the arguments: Taken from the original request: %p Port number %n NAS IP address %u User name %a Protocol (SLIP/PPP) %s Speed (connect string - eg "28800/V42.BIS") %i Calling Station ID Taken from the reply as defined thusfar: %f Framed IP address %c Callback-Number %t MTU For example, use the following entry for someone who has BSMTP (queued SMTP) service. "brunq" is the program that runs the SMTP queue. robert Service-Type = Framed-User Exec-Program = "/usr/local/sbin/brunq -h %f delta", Fall-Through = Yes Note that this example only works if the user "robert" has been assigned a static IP address - the %f parameter is taken from the _reply_ attributes. Most NASes do not send the dynamic IP address they are going to assign the user along in the access- request, so there is no way for the radius server to know it. The output from Exec-Program-Wait is parsed by the radius server. If it looks like Attribute/Value pairs, they are decoded and added to the reply sent to the NAS. This way, you can for example set Session-Timeout. For backwards compatibility, if the output doesn't look like valid radius A/V pairs, the output is taken as a message and added to the reply sent to the NAS as Port-Message. If Exec-Program-Wait returns a non-zero exit status, access will be denied to the user. With a zero-exit status, access is granted. Login-Time defines the time span a user may login to the system. The format of a so-called time string is like the format used by UUCP. A time string may be a list of simple time strings separated by "|" or ",". Each simple time string must begin with a day definition. That can be just one day, multiple days, or a range of days separated by a hyphen. A day is Mo, Tu, We, Th, Fr, Sa or Su, or Wk for Mo-Fr. "Any" or "Al" means all days. After that a range of hours follows in hhmm-hhmm format. For example, "Wk2305-0855,Sa,Su2305-1655". Radiusd calculates the number of seconds left in the time span, and sets the Session-Timeout to that number of seconds. So if someones Login-Time is "Al0800-1800" and she logs in at 17:30, Session-Timeout is set to 1800 seconds so that she is kicked off at 18:00. 5. LOG FILES 5a. /var/log/radutmp In this file the currently logged in users are held. The program "radwho" reads this file and gives you a summary. Rogue sessions can be deleted from this file with the "radzap" program. 5b. /var/log/radwtmp This file is "wtmp" compatible and keeps a history of all radius logins/ logouts. This file can be read with the "last" program, and other Unix accounting programs (such as "ac" and "sac") can be used to produce a summary. However you should NOT send bills based on this file. It is not really accurate. If you do usage-based billing, base it on the "Stop" records in the "detail" file(s). And beware of duplicate stop records. 5c. /var/log/radius.log All RADIUS informational. diagnostic and error messages are logged in this file. If radiusd has been started with the "-y" flag, all logins attempts will be logged in this file. For failed logins, the wrong password will also be logged. With the "-z" flag, the passwords for successful logins will be logged as well. That's pretty dangerous though in case anyone unpriviliged ever manages to get access to this file! 5d. /var/log/radacct//detail This is the original radius logfile, as written by all the livingston radius servers. It's only created if the directory /var/log/radacct exists. The name is found by checking the following in order: o the "shortname" as defined for this NAS in /etc/raddb/naslist o the DEFAULT "shortname" found in /etc/raddb/naslist o the name found in the DNS for the IP address of the terminal server o the IP address of the terminal server You can change this using the -F command line option to the server, see the manpage of radiusd(8). 6. MORE INFO, SUPPORT You're reading this file - read it again ;). Then read all the other README.* files as well. The FAQ is also included as FAQ.txt, and it's available on the web as http://www.radius.cistron.nl/faq/ I know that the documentation provided is sparse. However it is not in the scope of the radius server to provide a guide as to how terminal servers works and how the RADIUS protocol works and is used. Unfortunately I do not have too much time myself to answer all questions that might arise through email - you can always try sending me email, ofcourse, but I cannot guarantee a reply, depends on how much time I have. The latest released version of Cistron Radius is always available from http://www.radius.cistron.nl/ There is a MailMan mailing list hosted by XS4ALL. You can subscribe, unsubscribe and browse the archives all from a webinterface at http://lists.cistron.nl/mailman/listinfo/cistron-radius If you don't have access to a browser, you can subscribe by mail. Send a message with "help" in the body to cistron-radius-request@lists.cistron.nl. Then, of course, for general RADIUS questions, especially if you are using Livingston / Lucent RABU equipment, there is the portmaster-radius mailing list. Send mail to portmaster-radius-request@portmasters.com to find out how to subscribe. 7. FREERADIUS In August 1999 the Cistron Radius server source was forked into Cistron Radius and FreeRadius. FreeRadius started out as a cleanup and rewrite, but has since become a seperate project with seperate goals. Cistron Radius will not get any new existing features, it's purely in maintenance mode. FreeRadius is under active development. FreeRadius is production quality at the time of this writing and you should probably use FreeRadius instead of Cistron Radius. It has features such as SQL and LDAP support, EAP support, loadable modules, etc. There's an O'Reilly title called 'radius' which is mainly about FreeRadius. Check out the website at http://www.freeradius.org/ and/or the mailinglist at http://lists.freeradius.org/mailman/listinfo/freeradius-users $Id: README,v 1.22 2006/02/08 17:05:52 miquels Exp $