doc/README

   1 1. INTRO
   2
   3   All code in this server was written for this project.
   4
   5   The server is mostly compatible with livingston radiusd-2.01
   6   (no menus or s/key support though) but with more features, such as:
   7
   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!
  23
  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.
  30
  31 2. INSTALLATION
  32
  33    See the INSTALL file, in the parent directory.
  34
  35 3. CONFIGURATION FILES
  36
  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!
  39
  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
  43   the server.
  44
  45 3a. CLIENTS
  46
  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).
  52
  53 3b. NASLIST
  54
  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:
  58
  59   Terminal Server                       Type in naslist
  60
  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
  72
  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).
  76
  77 3c. NASPASSWD
  78
  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.
  82
  83   This is normally ONLY needed for USR/3Com Total Control, NetServer and
  84   Cyclades PathRAS terminal servers!
  85
  86 3d. HINTS
  87
  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.
  92
  93 3e. HUNTGROUPS
  94
  95   This is the /etc/raddb/huntgroups file. Here you can define different
  96   huntgroups. These can be used to:
  97
  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.
 103
 104 3f. USERS
 105
 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 successful login would get a PPP connection.
 110
 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.
 115
 116   You can uses spaces in usernames by escaping them with \ or by using
 117   quotes. For example, "joe user" or joe\ user.
 118
 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+.*//;)
 121
 122 3g. NEW RADIUS ATTRIBUTES (to be used in the USERS file).
 123
 124   Name                  Type            Descr.
 125   ----                  ----            ------
 126   Simultaneous-Use      integer         Max. number of concurrent logins
 127   Fall-Through          integer         Yes/No
 128   Login-Time            string          Defines when user may login.
 129   Current-Time          string          Allows you to perform time-based
 130                                         checks when a request is received.
 131
 132   Login-Time defines the time span a user may login to the system. The
 133   format of a so-called time string is like the format used by UUCP.
 134   A time string may be a list of simple time strings separated by "|" or ",".
 135
 136   Each simple time string must begin with a day definition. That can be just
 137   one day, multiple days, or a range of days separated by a hyphen. A
 138   day is Mo, Tu, We, Th, Fr, Sa or Su, or Wk for Mo-Fr. "Any" or "Al"
 139   means all days.
 140
 141   After that a range of hours follows in hhmm-hhmm format.
 142
 143   For example, "Wk2305-0855,Sa,Su2305-1655".
 144
 145   Radiusd calculates the number of seconds left in the time span, and
 146   sets the Session-Timeout to that number of seconds. So if someones
 147   Login-Time is "Al0800-1800" and she logs in at 17:30, Session-Timeout
 148   is set to 1800 seconds so that she is kicked off at 18:00.
 149
 150 4. LOG FILES
 151
 152 4a. /var/log/radutmp
 153
 154   In this file the currently logged in users are held. The program "radwho"
 155   reads this file and gives you a summary. Rogue sessions can be deleted
 156   from this file with the "radzap" program.
 157
 158 4b. /var/log/radwtmp
 159
 160   This file is "wtmp" compatible and keeps a history of all radius logins/
 161   logouts. This file can be read with the "last" program, and other Unix
 162   accounting programs (such as "ac" and "sac") can be used to produce a
 163   summary.
 164
 165 4c. /var/log/radius.log
 166
 167   All RADIUS informational. diagnostic and error messages are logged in
 168   this file.  If radiusd has been started with the "-y" flag, all logins
 169   attempts will be logged in this file. For failed logins, the wrong password
 170   will also be logged.  With the "-z" flag, the passwords for successful
 171   logins will be logged as well. That's pretty dangerous though in case
 172   anyone unpriviliged ever manages to get access to this file!
 173
 174 4d. /var/log/radacct/<terminal_server>/detail
 175
 176   This is the original radius logfile, as written by all the livingston
 177   radius servers. It's only created if the directory /var/log/radacct exists.
 178   The <terminal_server> name is the short name if one is defined in
 179   /etc/raddb/naslist.
 180
 181   For more configuration options on the detail file please see
 182   README.rlm_detail as it expands upon this greatly.
 183
 184 5.  MORE INFO, SUPPORT
 185
 186   We know that the documentation provided is sparse. However it is not in
 187   the scope of the radius server to provide a guide as to how terminal
 188   servers works and how the RADIUS protocol works and is used.
 189
 190   The latest version of FreeRadius is always available through
 191   anonymous CVS from cvs.freeradius.org - for more info, see
 192   <URL: http://www.freeradius.org/>
 193
 194   There are two GNU Mailman mailing lists hosted by Cistron Internet Services:
 195   a 'users' list, at:
 196
 197         http://lists.freeradius.org/pipermail/freeradius-users/
 198
 199   and a 'developers only' list, at
 200
 201         http://lists.freeradius.org/pipermail/freeradius-devel/
 202
 203 6.  OTHER INFORMATION
 204
 205   The files in other directories are:
 206
 207   debian/       Files to build a "freeradius" Debian Linux package.
 208
 209   dialup_admin/ A PHP web front-end to manage an SQL database associated
 210                 with the server.
 211
 212   doc/          Various snippets of documentation
 213   doc/rfc/      Copies of the RFC's.  If you have Perl, do a 'make' in
 214                 that directory, and look at the HTML output.
 215
 216   libltdl/      Libtool platform independent library system.
 217
 218   man/          Unix Manual pages for the server, configuration files,
 219                 and associated utilities.
 220
 221   mibs/         SNMP Mibs for the server.
 222
 223   raddb/        Sample configuration files for the server.
 224
 225   redhat/       Additional files for a RedHat Linux system.
 226
 227   scripts/      Sample scripts for startup and maintenance.
 228
 229   src/          Source code
 230   src/main      source code for the daemon and associated utilities
 231   src/lib       source code for the RADIUS library
 232   src/include   header files
 233   src/modules   dynamic plug-in modules
 234
 235   src/billing   Some scripts and configuration files to assist in billing,
 236                 Currently mostly VoIP related.
 237
 238   suse/         Aditional files for a SuSE (UnitedLinux) system.
 239
 240   todo/         TODO list and assorted files.
 241
 242
 243   If you have ANY problems, concerns, or surprises when running the
 244 server, then run it in debugging mode, as root, from the command line:
 245
 246 $ radiusd -X
 247
 248 It will produce a large number of messages.  The answers to many
 249 questions, and the solution to many problems, can usually be found in
 250 these messages.
 251
 252   For further details, see:
 253
 254   http://www.freeradius.org/faq/
 255
 256   and the 'bugs' file, in this directory.
 257
 258 $Date$