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
  23
  24 2. INSTALLATION
  25
  26    See the INSTALL file, in the parent directory.
  27
  28
  29 3. CONFIGURATION FILES
  30
  31   For every file there is a fully commented example file included, that
  32   explains what is does, and how to use it. Read those sample files too!
  33
  34   Again, many of the configuration files are ONLY documented in the
  35   comments included in the files.  Reading the configuration files is
  36   REQUIRED to fully understand how to create complex configurations of
  37   the server.
  38
  39 3a. CLIENTS
  40
  41   Make sure the clients (portmasters, Linux with portslave etc) are set up to
  42   use the host radiusd is running on as authentication and accounting host.
  43   Configure these clients to use a "radius secret password". For every client,
  44   also enter this "secret password" into the file /etc/raddb/clients.
  45   See also the manual page for clients(5).
  46
  47 3b. NASLIST
  48
  49   Every NAS (Network Access Server, also known as terminal server) should have
  50   an entry in this file with an abbreviated name and the type of NAS it
  51   is. Currently FreeRADIUS supports the following NAS types:
  52
  53   Terminal Server                       Type in naslist
  54
  55   3Com/USR Hiper Arc Total Control      usrhiper
  56   3Com/USR NetServer                    netserver
  57   3Com/USR TotalControl                 tc
  58   Ascend Max 4000 family                max40xx
  59   Cisco Access Server family            cisco
  60   Cistron PortSlave                     portslave
  61   Computone PowerRack                   computone
  62   Cyclades PathRAS                      pathras
  63   Livingston PortMaster                 livingston
  64   Multitech CommPlete Server            multitech
  65   Patton 2800 family                    patton
  66
  67   Usually this is the same list as in the "clients" file, but not every
  68   NAS is a client and not every client is a NAS (this will start to make
  69   sense if you use radius proxy servers).
  70
  71 3c. NASPASSWD
  72
  73   If ``checkrad'' needs to login on your terminal server to check who
  74   is online on a certain port (i.e. it's not possible to use SNMP or
  75   finger) you need to define a loginname and password here.
  76
  77   This is normally ONLY needed for USR/3Com Total Control, NetServer and
  78   Cyclades PathRAS terminal servers!
  79
  80 3d. HINTS
  81
  82   Customize the /etc/raddb/mods-config/preprocess/hints file. This file is
  83   used to give users different login type based on a prefix/suffix of their
  84   loginname. For example, logging in as "user" may result in a rlogin session
  85   to a Unix system, and logging in as "Puser" could start a PPP session.
  86
  87 3e. HUNTGROUPS
  88
  89   This is the /etc/raddb/mods-config/preprocess/huntgroups file. Here you can
  90   define different huntgroups. These can be used to:
  91
  92     - restrict access to certain huntgroups to certain users/groups of
  93       users (define this in the huntgroups file itself)
  94     - match a loginname with a huntgroup in /etc/raddb/users. One use
  95       for this is to give a user a static IP address based on the
  96       huntgroup / Point of Presence  (s)he dials in to.
  97
  98 3f. USERS
  99
 100   With the original RADIUS server, every user had to be defined in this
 101   file. There could be one default entry, where you could for example
 102   define that a user not in the radius file would be checked agains the
 103   UNIX password file and on successful login would get a PPP connection.
 104
 105   In the new style file, you can define multiple DEFAULT entries. All
 106   entries are processed in the order as they appear in the users file.
 107   If an entry matches the username, radiusd will stop scanning the users
 108   file unless the attribute "Fall-Through = Yes" is set.
 109
 110   You can uses spaces in usernames by escaping them with \ or by using
 111   quotes. For example, "joe user" or joe\ user.
 112
 113   The FreeRADIUS server does not trim any spaces from a username received
 114   from the portmaster (Livingston does, in perl notation, $user =~ s/\s+.*//;)
 115
 116 3g. NEW RADIUS ATTRIBUTES (to be used in the USERS file).
 117
 118   Name                  Type            Descr.
 119   ----                  ----            ------
 120   Simultaneous-Use      integer         Max. number of concurrent logins
 121   Fall-Through          integer         Yes/No
 122   Login-Time            string          Defines when user may login.
 123   Current-Time          string          Allows you to perform time-based
 124                                         checks when a request is received.
 125
 126   Login-Time defines the time span a user may login to the system. The
 127   format of a so-called time string is like the format used by UUCP.
 128   A time string may be a list of simple time strings separated by "|" or ",".
 129
 130   Each simple time string must begin with a day definition. That can be just
 131   one day, multiple days, or a range of days separated by a hyphen. A
 132   day is Mo, Tu, We, Th, Fr, Sa or Su, or Wk for Mo-Fr. "Any" or "Al"
 133   means all days.
 134
 135   After that a range of hours follows in hhmm-hhmm format.
 136
 137   For example, "Wk2305-0855,Sa,Su2305-1655".
 138
 139   radiusd calculates the number of seconds left in the time span, and
 140   sets the Session-Timeout to that number of seconds. So if someones
 141   Login-Time is "Al0800-1800" and she logs in at 17:30, Session-Timeout
 142   is set to 1800 seconds so that she is kicked off at 18:00.
 143
 144
 145 4. LOG FILES
 146
 147 4a. /var/log/radius/radutmp
 148
 149   In this file the currently logged in users are held. The program "radwho"
 150   reads this file and gives you a summary. Rogue sessions can be deleted
 151   from this file with the "radzap" program.
 152
 153 4b. /var/log/radius/radwtmp
 154
 155   This file is "wtmp" compatible and keeps a history of all radius logins/
 156   logouts. This file can be read with the "last" program, and other Unix
 157   accounting programs (such as "ac" and "sac") can be used to produce a
 158   summary.
 159
 160 4c. /var/log/radius/radius.log
 161
 162   All RADIUS informational, diagnostic and error messages are logged in
 163   this file, including all login attempts.
 164
 165 4d. /var/log/radius/radacct/<client_ip>/detail
 166
 167   This is the original radius logfile, as written by all the Livingston
 168   radius servers. It's only created if the directory
 169   /var/log/radius/radacct exists.
 170
 171   For more configuration options on the detail file please see
 172   raddb/mods-available/detail as it expands upon this greatly.
 173
 174
 175 5.  MORE INFO, SUPPORT
 176
 177   The latest version of FreeRADIUS is always available from
 178   the git repository hosted on GitHub at
 179
 180     https://github.com/FreeRADIUS/freeradius-server
 181
 182   or see
 183
 184     http://freeradius.org/git/
 185
 186   for more information.
 187
 188   There are two mailing lists for users and developers. General
 189   user, administrator and configuration issues should be discussed
 190   on the users list at:
 191
 192     http://lists.freeradius.org/mailman/listinfo/freeradius-users
 193
 194   When asking for help on the users list, be sure the include a
 195   detailed and clear description of the problem, together with
 196   full debug output from FreeRADIUS, obtained by running
 197
 198     radiusd -X
 199
 200   Developers only discussion is to be had on the devel list:
 201
 202     http://lists.freeradius.org/mailman/listinfo/freeradius-devel
 203
 204   Please do not raise general configuration issues here.
 205
 206
 207 6.  OTHER INFORMATION
 208
 209   The files in other directories are:
 210
 211   debian/       Files to build a "freeradius" Debian Linux package.
 212
 213   doc/          Various snippets of documentation
 214   doc/rfc/      Copies of the RFC's.  If you have Perl, do a 'make' in
 215                 that directory, and look at the HTML output.
 216
 217   libltdl/      Libtool platform independent library system.
 218
 219   man/          Unix Manual pages for the server, configuration files,
 220                 and associated utilities.
 221
 222   mibs/         SNMP Mibs for the server.
 223
 224   raddb/        Sample configuration files for the server.
 225
 226   redhat/       Additional files for a RedHat Linux system.
 227
 228   scripts/      Sample scripts for startup and maintenance.
 229
 230   src/          Source code
 231   src/main      source code for the daemon and associated utilities
 232   src/lib       source code for the RADIUS library
 233   src/include   header files
 234   src/modules   dynamic plug-in modules
 235
 236   suse/         Aditional files for a SuSE (UnitedLinux) system.
 237
 238   todo/         TODO list and assorted files.
 239
 240
 241   If you have ANY problems, concerns, or surprises when running
 242   the server, then run it in debugging mode, as root, from the
 243   command line:
 244
 245   $ radiusd -X
 246
 247   It will produce a large number of messages.  The answers to many
 248   questions, and the solution to many problems, can usually be found in
 249   these messages.
 250
 251   For further details, see:
 252
 253   http://www.freeradius.org/faq/
 254
 255   and the 'bugs' file, in this directory.
 256
 257 $Date$