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   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.
 134
 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.
 138
 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.
 141
 142   robert        Service-Type = Framed-User
 143                 Exec-Program = "/usr/local/sbin/brunq -h %f delta",
 144                 Fall-Through = 1
 145
 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.
 149
 150   If Exec-Program-Wait returns a non-zero exit status, access will be
 151   denied to the user. With a zero-exit status, access is granted.
 152
 153   Login-Time defines the time span a user may login to the system. The
 154   format of a so-called time string is like the format used by UUCP.
 155   A time string may be a list of simple time strings separated by "|" or ",".
 156
 157   Each simple time string must begin with a day definition. That can be just
 158   one day, multiple days, or a range of days separated by a hyphen. A
 159   day is Mo, Tu, We, Th, Fr, Sa or Su, or Wk for Mo-Fr. "Any" or "Al"
 160   means all days.
 161
 162   After that a range of hours follows in hhmm-hhmm format.
 163
 164   For example, "Wk2305-0855,Sa,Su2305-1655".
 165
 166   Radiusd calculates the number of seconds left in the time span, and
 167   sets the Session-Timeout to that number of seconds. So if someones
 168   Login-Time is "Al0800-1800" and she logs in at 17:30, Session-Timeout
 169   is set to 1800 seconds so that she is kicked off at 18:00.
 170
 171 4. LOG FILES
 172
 173 4a. /var/log/radutmp
 174
 175   In this file the currently logged in users are held. The program "radwho"
 176   reads this file and gives you a summary. Rogue sessions can be deleted
 177   from this file with the "radzap" program.
 178
 179 4b. /var/log/radwtmp
 180
 181   This file is "wtmp" compatible and keeps a history of all radius logins/
 182   logouts. This file can be read with the "last" program, and other Unix
 183   accounting programs (such as "ac" and "sac") can be used to produce a
 184   summary.
 185
 186 4c. /var/log/radius.log
 187
 188   All RADIUS informational. diagnostic and error messages are logged in
 189   this file.  If radiusd has been started with the "-y" flag, all logins
 190   attempts will be logged in this file. For failed logins, the wrong password
 191   will also be logged.  With the "-z" flag, the passwords for successful
 192   logins will be logged as well. That's pretty dangerous though in case
 193   anyone unpriviliged ever manages to get access to this file!
 194
 195 4d. /var/log/radacct/<terminal_server>/detail
 196
 197   This is the original radius logfile, as written by all the livingston
 198   radius servers. It's only created if the directory /var/log/radacct exists.
 199   The <terminal_server> name is the short name if one is defined in
 200   /etc/raddb/naslist.
 201
 202   For more configuration options on the detail file please see
 203   README.rlm_detail as it expands upon this greatly.
 204
 205 5.  MORE INFO, SUPPORT
 206
 207   We know that the documentation provided is sparse. However it is not in
 208   the scope of the radius server to provide a guide as to how terminal
 209   servers works and how the RADIUS protocol works and is used.
 210
 211   The latest version of FreeRadius is always available through
 212   anonymous CVS from cvs.freeradius.org - for more info, see
 213   <URL: http://www.freeradius.org/>
 214
 215   There are two GNU Mailman mailing lists hosted by Cistron Internet Services:
 216   a 'users' list, at:
 217
 218         http://lists.freeradius.org/pipermail/freeradius-users/
 219
 220   and a 'developers only' list, at
 221
 222         http://lists.freeradius.org/pipermail/freeradius-devel/
 223
 224 6.  OTHER INFORMATION
 225
 226   The files in other directories are:
 227
 228   debian/       Files to build a "freeradius" Debian Linux package.
 229
 230   dialup_admin/ A PHP web front-end to manage an SQL database associated
 231                 with the server.
 232
 233   doc/          Various snippets of documentation
 234   doc/rfc/      Copies of the RFC's.  If you have Perl, do a 'make' in
 235                 that directory, and look at the HTML output.
 236
 237   libltdl/      Libtool platform independent library system.
 238
 239   man/          Unix Manual pages for the server, configuration files,
 240                 and associated utilities.
 241
 242   mibs/         SNMP Mibs for the server.
 243
 244   raddb/        Sample configuration files for the server.
 245
 246   redhat/       Additional files for a RedHat Linux system.
 247
 248   scripts/      Sample scripts for startup and maintenance.
 249
 250   src/          Source code
 251   src/main      source code for the daemon and associated utilities
 252   src/lib       source code for the RADIUS library
 253   src/include   header files
 254   src/modules   dynamic plug-in modules
 255
 256   src/billing   Some scripts and configuration files to assist in billing,
 257                 Currently mostly VoIP related.
 258
 259   suse/         Aditional files for a SuSE (UnitedLinux) system.
 260
 261   todo/         TODO list and assorted files.
 262
 263
 264   If you have ANY problems, concerns, or surprises when running the
 265 server, then run it in debugging mode, as root, from the command line:
 266
 267 $ radiusd -X
 268
 269 It will produce a large number of messages.  The answers to many
 270 questions, and the solution to many problems, can usually be found in
 271 these messages.
 272
 273   For further details, see:
 274
 275   http://www.freeradius.org/faq/
 276
 277   and the 'bugs' file, in this directory.
 278
 279 $Date$