See the TUTORIAL file for a brief overview of Radius.


The Files:
----------
INSTALL          -- This file.
las.tarlist      -- Relative pathnames of all the files in the tar file
README           -- Release announcements, what's changed, etc.
README.TACACS    -- Compile and link instructions specific to TACACS version.
README.hostnames -- Reminders about DNS and how RADIUS uses it.
TUTORIAL         -- Overview of RADIUS.
Makefile         -- This file is used by make(1) to build things.
src/*            -- Contains all the RADIUS source files and testing clients.
raddb/*          -- Contains sample RADIUS database files.
man/*            -- The man(1) pages for executable and configuration files.
doc/*            -- Contains descriptive documents about the RADIUS protocol.


How To Build:
-------------

The server builds and runs correctly on SunOS 4.1.3 and above, Solaris 2.3
and above, ULTRIX 4.2 and above, BSDi 1.0 and above, AIX 3.2 and above,
HP-UX 9.05 and above, UnixWare, Linux version 1.2.3 and DEC Alpha OSF/1.

Note: While the RADIUS server may be run by any non-privileged user account,
      some operating systems (notably Solaris and others where the shadow
      password file is readable only by the user "root") require the server
      process to be owned by the user "root".  In some of the testing steps
      below, the tests may need to be run as "root" if your situation calls
      for this.


1.  Uncompress the tar archive and run tar(1) on the resultant tar file.
    For example, depending on which files you downloaded via FTP:

       % gunzip radius.*.*.tar.gz
       % tar -xf radius.*.*.tar
    or
       % uncompress radius.*.*.tar.Z
       % tar -xf radius.*.*.tar


2.  Edit the Makefile to select the "flavor" of the server you wish to build.
    Some of the various flavors are:  UNIX password file (this is the default),
    MIT Kerberos, AFS Kerberos, KCHAP, DBM and TACACS.  Both versions of
    Kerberos use the MIT Kerberos include files which you should be able to
    get from MIT, if you do not already have them.  Add the comment ("#")
    character to the three default lines and uncomment your "flavor".  Most
    installations should leave the MERIT_GRANDFATHER macro defined.  This
    enables three features: 1) enhanced duplicate detection, 2) backwards
    compatibility with RADIUS 1.17 style authentication and 3) backwards
    compatibility with RADIUS 1.17 style clients (radcheck and radpwtst).  

    Omit out the -DNOSHADOW make(1) macro if your system has the shadow.h
    file in the /usr/include directory (normally found on Solaris systems).


3.  Any of the changes indicated in this step need to be undertaken with
    care and understanding by someone with knowledge of the local operating
    system and hardware.  This is probably the local system administrator.

    The Makefile is set up for native builds on the SunOS 4.1.3 operating
    system.  For non-SunOS 4.1.3 systems, you may need to edit the Makefile
    in the "operating system" section.  Add the comment character ("#") to
    the default (SunOS) section.  Then un-comment those lines which pertain
    to your operating system by removing the comment character ("#") from
    the start of the appropriate lines.  Exercise care if you apply any local
    changes to the definitions found between the line that starts with "SRC"
    and the line which starts with "SERVER".  For example, you may want to
    change the pathname for the "compress" program used to reduce the size
    of the logfile when nightly (or weekly) logfile truncation occurs.  The
    default in the source code is "/usr/ucb/compress".

    The default build options were chosen to build a working RADIUS server
    across a large number of systems.  If you need to change options for
    your installation for improved efficiency or different configurations,
    read the entire Makefile and proceed carefully.


4.  Type "make" to build the new RADIUS server and the utilities.

    Typical problems in this step are compiler errors and/or linker errors
    which may exist in the code as distributed.  Extensive testing on many
    different systems has reduced the known errors in this category to the
    absolute minimum.  Some may appear, however, if your system is not one
    of the ones which has been extensively tested.  If you are unable to
    resolve any problems which may appear, send email to the address at the
    end of this document requesting assistance.

    The warnings that appear on SunOS systems for redefinition of NULL (when
    compiling with USE_DBM configured) may be ignored.

    NOTE: Making the server and utilities by typing "make" does NOT install
    any programs or other files.  Installation is covered in step 12, below,
    when you have finished testing your server.


5.  Make sure your system has an /etc/shells file.  This file lists the full
    path names of the various shell programs on your system, one per line.
    This is needed to support the UNIX-PW type of user authentication.  Some
    examples are: /bin/sh, /bin/csh and /bin/ksh (but only one per line).
    These paths must be correct or your users will be unable to use the 
    chsh command.  It is possible to omit this feature by editing the 
    Makefile and commenting out the CHK_SHELLS definition line.

    For some of the steps below, you may want to install the man(1) pages.
    This is described in step 12 below, but it is advisable to install them
    now.  Just enter:

       % make man-install

    to have the man(1) pages installed.  If you have retained the Makefile
    macros MAN and MAN_INSDIR in the Makefile as distributed, the man(1)
    pages will be placed into the /usr/local/man/man5 and /usr/local/man/man8
    directories.  Feel free to change these definitions as explained in step
    three (3) above.  You may also want to check that /usr/local/man/man5
    (and /usr/local/man/man8) are part of your MANPATH environment variable
    (e.g., "% echo $MANPATH") or read your system's manual page on the man(1)
    command (e.g., % man man).


6.  Note:  Discard any authfile, users and dictionary files from all previous
    versions!  Edit any local entries and customization into the files which
    are provided with this release.

    All the RADIUS configuration files have read-only permission, so you may
    want to change that now.  Change to the ./raddb directory in the Merit
    distribution (e.g., "% cd raddb") and add write permission to all the
    configuration files (e.g., "% chmod u+w *").

    Configure the "clients" file for your site.  This file is used to define
    the secrets shared with other RADIUS machines communicating with your
    server.  Read the clients(5) man page and the comments inside the sample
    "clients" file for more information.  You will need, at the minimum, one
    entry for your site's host machine (the one on which you plan to run the
    RADIUS server).  Additionally, you may need an entry for each RADIUS
    client/server exchanging authentication requests or replies with the
    server you are building.

    For testing purposes, you should remove all the sample entries by placing
    the comment character ("#") in column one of those entries and by adding
    just the following line:

       my.radius.host.dns.name      <a-sixteen-or-fewer-character-secret>

    Replace 'my.radius.host.dns.name' with the full DNS name of the system
    running the RADIUS server.  Your secret may be any character string that
    does not contain blanks or control characters and is no longer than
    sixteen (16) characters.


7.  Configure the "authfile" for your site.  This file is used to define
    the realm to authentication-type mapping for your installation.  Read
    the authfile(5) man page and the comments inside the sample "authfile"
    for more information.  This file is needed if the Authentication-Type is
    set equal to "Realm" for _any_ entries in the "users" configuration file.
    If you use the default "users" file, which has the authentication-type
    set to "Realm" for the DEFAULT entry, so you will require an authfile. 
    You will need, at the minimum, one entry for your site's host machine
    (the one on which you plan to run the RADIUS server).  Be sure to comment
    out all seven example entries in the sample authfile.

    A typical example might resemble the following: (for using /etc/passwd)

       my_realm (my_realm_alias)   UNIX-PW

    Or if you wish to apply the same packet filter to each user in my_realm:

       my_realm (my_realm_alias)   UNIX-PW    my.host.dns.name   a_filter

    Normally, UNIX-PW authentication does not require the DNS name in the
    third field.  When specifying a filter, however, since the filter name
    is in the fourth field, the DNS name is required for parsing purposes.

    The users file may be used in some cases to specify user authentication
    information.  See the users(5) man page and the sample users file for
    more information.  In most cases, however, the authfile mechanism is
    preferable and the sample "users" file may be used without modification.
    Do not alter the entries in the "users" file following the DEFAULT entry.

    Do not alter the dictionary file in the raddb directory.


8.  Note: This step only applies to the enhanced AAA software available
    under license.

    Configure the "realms.las" file for your site.  The realms.las file is
    used to define which realms are being authorized by the Local Authorization
    Server (LAS) code.  It may also be used to define optional procedures to
    use for authorization and accounting.  Read the realms.las(5) man page and
    the comments inside the sample "realms.las" file for more information.
    You will need, at the minimum, one entry for your local realm (if any).
    If you are not using realms, just use the entry "NULL".  Be sure to comment
    out all other entries in the sample "realms.las" file.


9.  It is possible to test the server in the as-delivered distribution tree.
    After testing you should install the radiusd executable and configuration
    files into their final directories.  See the man(1) pages for radiusd(8)
    (server) and the configuration files authfile(5), clients(5), dictionary(5)
    and users(5), for more information.  The server, as built, expects the
    executables to be in the /usr/private/etc directory and the configuration
    files to be in the /usr/private/etc/raddb directory.

    However, for testing purposes, it is perfectly reasonable to test the
    server by leaving the files where they end up during the build process.
    To facilitate your testing efforts, you may wish to alter your shell
    "PATH" environment variable to include the path to the RADIUS server and
    the test clients' executables.


10. Using the example in the radiusd(8) man page, be sure your copy of the
    /etc/services file contains the two entries for RADIUS authentication and
    accounting services.  These entries tell the server which UDP ports to 
    use (defaults to 1645 and 1646, respectively).


11. Test your server by issuing the following commands.  If you use windows,
    try to run the server (radiusd) in one window and the client (radcheck)
    in another window.  This example assumes the server and the test clients
    are on your path (or you could enter ./src/radiusd -p 1647 ... etc.):

    % radiusd -p 1647 -q 1648 -d <raddb-dir> -x &
    % radcheck -p 1647 -r 1 <srv-DNS-name>

    (Note: add -n option to radcheck if you built without MERIT_GRANDFATHER)

    The choice of port 1647/8 is arbitrary, but meant to steer clear of an
    already running RADIUS server which may be listening on the 1645/6 ports.

    Problems at this point may stem from an incomplete "clients" file 
    configuration.

    If radcheck was successful, try to authenticate a test user as follows:

    % radpwtst -p 1647 -d <raddb-dir> -s <srv-DNS-name> -r 1 -u ppp xyz@realm
    Password:

    (Note: add -n option to radpwtst if you built without MERIT_GRANDFATHER)

    If you have defined the -DUSE_DBM option in the Makefile, you will need
    to run the builddbm(8) command to build the "users" file binary database
    before testing with radpwtst(8) and every time after you make any changes
    to the "users" file.  If you have not specifically defined the -DUSE_DBM
    option, which is the case in the Makefile as delivered, you should ignore
    this paragraph.  The Merit AAA server caches the "users" file in memory
    at start up time, so using USE_DBM and builddbm(8) may be unnecessary.

    The "realm" following "xyz@" must be a realm in your authfile (if you
    are using realms and have an authfile) and, if its authentication type
    is UNIX-PW, the "xyz" must be in your /etc/passwd file.  If you are
    not using realms, you do not need the authfile at all, and you may omit
    the "@realm" string from the end of the above radpwtst command.  Any
    problems here may stem from an incomplete "authfile" configuration or
    an inability of the RADIUS server or the user who is running it to read
    the password file (or possibly a shadow password file).

    If this step is successful, you need to properly terminate the test
    RADIUS server process (called radiusd) to avoid confusion later (e.g.,
    use "kill -TERM xxx" where xxx is the radiusd process number or PID).

    If you are going to re-install the server on a machine running an older
    version in production mode, be sure to see the tip in step 12 below.


12. To install the RADIUS server executable file just enter, "% make install".
    To install the RADIUS configuration files enter, "% make config-install".
    To install the RADIUS test utility files enter, "% make util-install".
    To install the RADIUS man(1) page files enter, "% make man-install", if
    you haven't already installed the man(1) pages in step 5 above.

    You may configure the Makefile to put the above files wherever you wish.

    TIP: If you are upgrading your existing production RADIUS server, you
    may want to alter the default path in the Makefile used for installing
    to avoid over-writing your existing configuration.  For example, you
    might want to change:

       RADDB_INSDIR    = /usr/private/etc/raddb

    to become:

       RADDB_INSDIR    = /usr/private/etc/raddb.x.y.z

    where "x.y.z" is the software version number of the RADIUS upgrade.
    Of course, after you install the server and the configuration files,
    you will need to "kill -TERM" your running server (if any) and then
    rename your old ./raddb directory to be, say, ./raddb.old, but then
    do not forget to rename the /usr/private/etc/raddb.x.y.z directory
    to become your new ./raddb directory.


13. To set up for production use, you should add an entry to your system's
    /etc/inetd.conf file which will start the server if it isn't already 
    running whenever a RADIUS request arrives at your machine.  The line
    for /etc/inetd.conf should look like (use <TAB> characters to keep the
    fields aligned with the other lines in the file):

      radius dgram   udp wait root /usr/private/etc/radiusd radiusd

    Also, should the RADIUS server crash, inetd(8) will restart the server 
    automatically at the next incoming RADIUS request.  Do not forget to 
    send the "HUP" signal to your inetd(8) process:

       % kill -HUP yyy         [where yyy is the inetd(8) PID]

    You need to do this each time after you change your /etc/inetd.conf file.


Accounting
----------

The Livingston style accounting detail record files are produced by default by
the basic server for compatibility with other systems.  However, the enhanced
software produces session accounting records by default.  See the on-line FAQ

   http://home.merit.edu/radius/faq.html#detail

for instructions on how to recover Livingston style accounting records when
using the enhanced server.


Session Accounting (only available in the enhanced version)
------------------

Session accounting is enabled by default.   Accounting records are produced in
files named session.yyyy-mm-dd.log in the /usr/private/etc/raddb directory.  

The radbnr(8) program supplied with the enhanced binary release may be used
to process the session logs to obtain user billing information.  See the
radbnr(8) man page for details.  NOTE: this program is not supplied with the
source release, you must obtain a version from the binary release at this time.

If you need to maintain pre-2.4.23 LAS logging behavior, see the comments
at the beginning of the log.config file installed in the .../raddb directory
as well as the log.config(5) man page.

The sesstab(8) command may be used to obtain details of current sessions.  See
the sesstab(8) man page.


Default RADIUS Directory Structure
----------------------------------

As supplied, RADIUS will be installed into the following directory hierarchy:

/usr/private/etc/

   dnscheck  -  utility to check DNS mapping
   lasrecord -  print a listing of LAS accounting records
   radcheck  -  RADIUS test utility (like the UNIX ping(8) command)
   radiusd   -  RADIUS server executable
   radpwtst  -  RADIUS test client utility
   sesstab   -  print contents of the current LAS session table file.

   radacct/  -  Livingston style RADIUS accounting detail records are placed
                in this directory.

   raddb/

        authfile               - realm to authentication-type mapping file
        clients                - client to shared secret mapping file
        conversion.pl          - Perl script to change Livingston style
                                 "users" files to match the Draft RADIUS RFC
                                 as implemented in Merit RADIUS
        dictionary             - definition file required by radiusd
        log.config             - session logging configuration file
                                 (only in enhanced version)
        logfile                - the server log file
        logfile.yymmdd.Z       - compressed daily or weekly log files
        radius.fsm             - the finite state machine definitions file
        radius.pid             - contains the process id for the server, etc.
        record.las.yymmdd      - old style session accounting logs
                                 (only in enhanced version)
        session.las            - current active sessions, use the sesstab(8)
                                 command to view these files
                                 (only in enhanced version)
        session.yyyy-dd-mm.log - session accounting logs
                                 (only in enhanced version)
        users                  - holds user security profiles and reply items

The logfile, logfile.yymmdd.Z files, session.las and session log files are
created by radiusd during normal execution.


Other files supplied with the distribution
------------------------------------------

The man directory in the distribution hierarchy contains these man(1) pages:

    man/

      authfile.5    - authfile description
      builddbm.8    - builddbm command description for dbm(3) user database.
                      Important if radiusd was built with USE_DBM defined.
      clients.5     - clients file description
      dictionary.5  - dictionary file description
      las.conf.5    - las.conf file description (only in enhanced version)
      lasrecord.8   - description of the lasrecord accounting print utility
                      (only in enhanced version)
      log.config.5  - description of the session logging configuration file
                      (only in enhanced version)
      radbnr.8      - radbnr command description for billing and reporting
                      from session log files (only in enhanced version)
      radbnr.conf.5 - link to las.conf.5 (only in enhanced version)
                      (only in enhanced version)
      radcheck.8    - radcheck command description for checking server status
      radius.fsm.5  - description of RADIUS finite state machine tables
      radiusd.8     - radiusd server description
      radpwtst.8    - radpwtst command description of client simulation utility
      realms.las.5  - realms.las description (only in enhanced version)
                      (only in enhanced version)
      record.las.5  - description of the daily accounting log file
                      (only in enhanced version)
      session.las.5 - description of logfile for currently active session
                      (only in enhanced version)
      sesstab.8     - sesstab command description to print session.las files
                      (only in enhanced version)
      users.5       - users file description

By default, these files will be installed into the /usr/local/man/man5 and 
/usr/local/man/man8 directories.


How To Get Help:
---------------- 

If you have any problems or fixes send them to:  aaa-support@merit.edu
