3 All code in this server was written for this project.
5 The server is mostly compatible with livingston radiusd-2.01
6 (no menus or s/key support though) but with more feautures, such as:
8 o Can limit the maximum number of simultaneous logins on a per-user basis!
9 o Multiple DEFAULT entries, that can optionally fall-through.
10 o In fact, every entry can fall-through
11 o Deny/permit access based on huntgroup users dials into
12 o Set certain parameters (such as static IP address) based on huntgroup
13 o Extra "hints" file that can select SLIP/PPP/rlogin based on
14 username pattern (Puser or user.ppp is PPP, plain "user" is rlogin etc).
15 o Can execute an external program when user has authenticated (for example
16 to run a sendmail queue).
17 o Can use `$INCLUDE filename' in radiusd.conf, users, and dictionary files
18 o Can act as a proxy server, relaying requests to a remote server
19 o Supports Vendor-Specific attributes
20 o Supports many different plug-in modules for authentication,
21 authorization, and accounting.
22 o No good documentation at all, just like the original radiusd 1.16!
24 Work on real manual pages is progressing slowly. For a large part you
25 can use the documentation of the Livingston 2.01 server. Just remember
26 that using Prefix and Suffix in both the "users" and the (FreeRadius
27 specific) "hints" file will give unpredictable results. Well actually
28 it will result in Prefix and Suffix probably not working in the "users"
29 file if you already stripped them off in the "hints" file.
33 See the INSTALL file, in the parent directory.
35 3. CONFIGURATION FILES
37 For every file there is a fully commented example file included, that
38 explains what is does, and how to use it. Read those sample files too!
40 Again, many of the configuration files are ONLY documented in the
41 comments included in the files. Reading the configuration files is
42 REQUIRED to fully understand how to create complex configurations of
47 Make sure the clients (portmasters, Linux with portslave etc) are set up to
48 use the host radiusd is running on as authentication and accounting host.
49 Configure these clients to use a "radius secret password". For every client,
50 also enter this "secret password" into the file /etc/raddb/clients.
51 See also the manual page for clients(5).
55 Every NAS (Network Access Server, also known as terminal server) should have
56 an entry in this file with an abbreviated name and the type of NAS it
57 is. Currently FreeRadius supports the following NAS types:
59 Terminal Server Type in naslist
61 3Com/USR Hiper Arc Total Control usrhiper
62 3Com/USR NetServer netserver
63 3Com/USR TotalControl tc
64 Ascend Max 4000 family max40xx
65 Cisco Access Server family cisco
66 Cistron PortSlave portslave
67 Computone PowerRack computone
68 Cyclades PathRAS pathras
69 Livingston PortMaster livingston
70 Multitech CommPlete Server multitech
71 Patton 2800 family patton
73 Usually this is the same list as in the "clients" file, but not every
74 NAS is a client and not every client is a NAS (this will start to make
75 sense if you use radius proxy servers).
79 If ``checkrad'' needs to login on your terminal server to check who
80 is online on a certain port (i.e. it's not possible to use SNMP or
81 finger) you need to define a loginname and password here.
83 This is normally ONLY needed for USR/3Com Total Control, NetServer and
84 Cyclades PathRAS terminal servers!
88 Customize the /etc/raddb/hints file. This file is used to give users a
89 different login type based on a prefix/suffix of their loginname. For
90 example, logging in as "user" may result in a rlogin session to a Unix
91 system, and logging in as "Puser" could start a PPP session.
95 This is the /etc/raddb/huntgroups file. Here you can define different
96 huntgroups. These can be used to:
98 - restrict access to certain huntgroups to certain users/groups of
99 users (define this in the huntgroups file itself)
100 - match a loginname with a huntgroup in /etc/raddb/users. One use
101 for this is to give a user a static IP address based on the
102 huntgroup / Point of Presence (s)he dials in to.
106 With the original RADIUS server, every user had to be defined in this
107 file. There could be one default entry, where you could for example
108 define that a user not in the radius file would be checked agains the
109 UNIX password file and on succesfull login would get a PPP connection.
111 In the new style file, you can define multiple DEFAULT entries. All
112 entries are processed in the order as they appear in the users file.
113 If an entry matches the username, radiusd will stop scanning the users
114 file unless the attribute "Fall-Through = Yes" is set.
116 You can uses spaces in usernames by escaping them with \ or by using
117 quotes. For example, "joe user" or joe\ user.
119 The FreeRadius server does not trim any spaces from a username received
120 from the portmaster (livingston does, in perl notation, $user =~ s/\s+.*//;)
122 3g. NEW RADIUS ATTRIBUTES (to be used in the USERS file).
126 Simultaneous-Use integer Max. number of concurrent logins
127 Fall-Through integer Yes/No
128 Exec-Program string program to execute after authentication
129 Exec-Program-Wait string ditto, but wait for program to finish
130 before sending back auth. reply
131 Login-Time string Defines when user may login.
132 Current-Time string Allows you to perform time-based
133 checks when a request is received.
135 Exec-Program can take arguments. You can use variables in the
136 arguments, which are automatically expanded by the server. See
137 'doc/variables.txt' for more information.
139 For example, use the following entry for someone who has BSMTP (queued
140 SMTP) service. "brunq" is the program that runs the SMTP queue.
142 robert Service-Type = Framed-User
143 Exec-Program = "/usr/local/sbin/brunq -h %f delta",
146 The output from Exec-Program-Wait is parsed by the radius server. If
147 it looks like Attribute/Value pairs, they are decoded and added to the
148 reply sent to the NAS. This way, you can for example set Session-Timeout.
150 For backwards compatibility, if the output doesn't look like valid
151 radius A/V pairs, the output is taken as a message and added to the
152 reply sent to the NAS as Port-Message.
154 If Exec-Program-Wait returns a non-zero exit status, access will be
155 denied to the user. With a zero-exit status, access is granted.
157 Login-Time defines the time span a user may login to the system. The
158 format of a so-called time string is like the format used by UUCP.
159 A time string may be a list of simple time strings separated by "|" or ",".
161 Each simple time string must begin with a day definition. That can be just
162 one day, multiple days, or a range of days separated by a hyphen. A
163 day is Mo, Tu, We, Th, Fr, Sa or Su, or Wk for Mo-Fr. "Any" or "Al"
166 After that a range of hours follows in hhmm-hhmm format.
168 For example, "Wk2305-0855,Sa,Su2305-1655".
170 Radiusd calculates the number of seconds left in the time span, and
171 sets the Session-Timeout to that number of seconds. So if someones
172 Login-Time is "Al0800-1800" and she logs in at 17:30, Session-Timeout
173 is set to 1800 seconds so that she is kicked off at 18:00.
179 In this file the currently logged in users are held. The program "radwho"
180 reads this file and gives you a summary. Rogue sessions can be deleted
181 from this file with the "radzap" program.
185 This file is "wtmp" compatible and keeps a history of all radius logins/
186 logouts. This file can be read with the "last" program, and other Unix
187 accounting programs (such as "ac" and "sac") can be used to produce a
190 4c. /var/log/radius.log
192 All RADIUS informational. diagnostic and error messages are logged in
193 this file. If radiusd has been started with the "-y" flag, all logins
194 attempts will be logged in this file. For failed logins, the wrong password
195 will also be logged. With the "-z" flag, the passwords for successful
196 logins will be logged as well. That's pretty dangerous though in case
197 anyone unpriviliged ever manages to get access to this file!
199 4d. /var/log/radacct/<terminal_server>/detail
201 This is the original radius logfile, as written by all the livingston
202 radius servers. It's only created if the directory /var/log/radacct exists.
203 The <terminal_server> name is the short name if one is defined in
206 For more configuration options on the detail file please see
207 README.rlm_detail as it expands upon this greatly.
209 5. MORE INFO, SUPPORT
211 We know that the documentation provided is sparse. However it is not in
212 the scope of the radius server to provide a guide as to how terminal
213 servers works and how the RADIUS protocol works and is used.
215 The latest version of FreeRadius is always available through
216 anonymous CVS from cvs.freeradius.org - for more info, see
217 <URL: http://www.freeradius.org/>
219 There are two GNU Mailman mailing lists hosted by Cistron Internet Services:
222 http://lists.cistron.nl/archives/freeradius-users/
224 and a 'developers only' list, at
226 http://lists.cistron.nl/archives/freeradius-devel/
230 The files in other directories are:
232 debian/ Files to build a radiusd-freeradius Debian Linux package
234 dialup_admin/ A PHP web front-end to manage an SQL database associated
237 doc/ Various snippets of documentation
238 doc/rfc/ Copies of the RFC's. If you have Perl, do a 'make' in
239 that directory, and look at the HTML output.
241 libltdl/ Libtool platform independent library system.
243 man/ Unix Manual pages for the server, configuration files,
244 and associated utilities.
246 mibs/ SNMP Mibs for the server.
248 raddb/ Sample configuration files for the server.
250 redhat/ Additional files for a RedHat Linux system.
252 scripts/ Sample scripts for startup and maintenance
255 src/main source code for the daemon and associated utilities
256 src/lib source code for the RADIUS library
257 src/include header files
258 src/modules dynamic plug-in modules
260 src/billing Some scripts and configuration files to assist in billing,
261 Currently mostly VoIP related.
263 suse/ Aditional files for a SuSE (UnitedLinux) system.
265 todo/ TODO list and assorted files.
268 If you have ANY problems, concerns, or surprises when running the
269 server, then run it in debugging mode, as root, from the command line:
273 It will produce a large number of messages. The answers to many
274 questions, and the solution to many problems, can usually be found in
277 For further details, see:
279 http://www.freeradius.org/faq/
281 and the 'bugs' file, in this directory.