Initial revision

[freeradius.git] / doc / README

0. WARNING!

  Cistron Radius now uses autoconf - some of the default directories
  have changed! Configuration is now by default in /usr/local/etc/raddb,
  and logfiles are in /usr/local/var/log/ ....
  See 2. for more info.

1. INTRO

  This is version 1.6-alphaX of the Cistron Radius daemon.

        *** THIS IS AN ALPHA VERSION! IT MIGHT NOT WORK ***

  All code in this server was written from scratch.

  The server is mostly compatible with livingston radiusd-2.01
  (no menus or s/key support though) but with more feautures, 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
    o Deny/permit access based on huntgroup 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
    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 documentation of the Livingston server is available on the web at:
  http://www.livingston.com/Tech/Docs/RADIUS/guide/

  Extra command line flags:
  o -y: log all login attempts in /var/log/radius.log, include (wrong)
        password for failed logins.
  o -z: log the password of successful logins too (STRONLY discouraged).

2. COMPILE

  Ignore this section (2) if you have a pre-installed binary package.

  Radiusd now has autoconf support. This means you have to run
  ./configure --flags, then run make. You can set the following flags:

  --prefix=             Prefix to install (default: /usr/local)
  --localstatedir=      Base prefix for the logfiles. Defaults
                        to PREFIX/var
  --with-logdir=DIR     Directory for radutmp, radwtmp and radius.log.
                        Defaults to LOCALSTATEDIR/log
  --with-radacctdir=DIR Directory for the detail files. Defaults to
                        LOGDIR/radacct
  --sysconfdir          Base prefix for the raddb directory. Defaults to
                        PREFIX/etc
  --with-raddbdir=DIR   Configuration files. Defaults to SYSCONFDIR/raddb
  --with-dbm            Include DBM support (Old-style DBM)
  --with-ndbm           Include NDBM support
  --with-pam            Include PAM support
  --with-ascend-hack    Include Ascend hacks
  --with-ascend-cpl=N   Set Ascend Channels Per Line to N
  --with-ntdomain-hack  Include NT Domain hack (strip first part of
                        NT_DOMAIN\loginname if seen)
  --with-spcj-hack      Include Specialix Jetstream hacks
  --with-dict-nocase    Make dictionary case-independant
  --without-dynamic-modules
                        Turn off dynamic modules even if your
                        system supports them.

  To get the defaults that Cistron Radius used up to 1.5.4.3-beta18, use:

        ./configure --localstatedir=/var --sysconfdir=/etc

  That means binaries will get installed in /usr/local/{bin,sbin},
  manpages in /usr/local/man, configuration files in /etc/raddb,
  and logfiles in /var/log and /var/log/radacct.

  Now type "make". The binaries will be compiled.

  Then you do a "make install". That will install JUST the binaries
  for now. You need to install the rest by hand like this:

  o Copy the examples in raddb to /etc/raddb and edit+rename the sample files.
  o If you have a Debian system, you might want to install rc.radiusd
    as /etc/init.d/radiusd and install startup symlinks with
    "update-rc.d radiusd defaults".
  o If you use rc.radiusd, also install radwatch in /usr/local/sbin.
  o Start radiusd (using /etc/init.d/radiusd start if applicable).

3. USAGE

  You can use last -f /var/log/radwtmp to get last info on all users.
  You can use "radwho" at any time to find out who's logged in.
  If you want, you can install "radwho" as /usr/sbin/in.fingerd.
  Also, the "raduse" program can be very useful to monitor your modem pool.

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. Currently Cistron Radius supports the following NAS types:

  Terminal Server                       Type in naslist

  3Com/USR Hiper Arc Total Control      usrhiper
  3Com/USR NetServer                    netserver
  3Com/USR TotalControl                 tc
  Ascend Max 4000 family                max40xx
  Cisco Access Server family            cisco
  Cistron PortSlave                     portslave
  Computone PowerRack                   computone
  Cyclades PathRAS                      pathras
  Livingston PortMaster                 livingston
  Multitech CommPlete Server            multitech
  Patton 2800 family                    patton

  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).

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, NetServer and
  Cyclades PathRAS 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 = 1

  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.

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/<terminal_server>/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 <terminal_server> name is the short name if one is defined in
  /etc/raddb/naslist.

6.  MORE INFO, SUPPORT

  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 version of Cistron Radius is always available from
  http://www.www.cistron.nl/radius/

  There is a majordomo mailing list hosted by Cistron Internet Services. Send
  a message with "help" in the body to cistron-radius-request@info.cistron.nl.
  You can browse the archive of this mailing list at
  http://info.cistron.nl/archives/cistron-radius/

  There are a few other mailing lists that might offer some help:

  You can also try the the linux-isp mailing list, which on a lot of sites
  used to be accessible as the newsgroup linux.admin.isp (not anymore).
  For the mailing list, send a message with "help" in the body to
  linuxisp-request@friendly.jeffnet.org. Several people on that list are
  successfully using this software.

  There is a linux-radius list run by miguel a.l. paraz <map@iphil.net>.
  See http://www.iphil.net/~map/radius/ for details.

  Then ofcourse 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@livingston.com to find
  out how to subscribe.


   README 1.6-alpha2  Miquel van Smoorenburg <miquels@cistron.nl>  11-Aug-1999