See the TUTORIAL file for a brief overview/history of RADIUS.


The Files:
----------
INSTALL          -- This file.
*.tarlist        -- Relative pathnames of all the files in the tar file(s)
README           -- Release announcements, what's changed, etc.
README.TACACS    -- Compile and link instructions specific to TACACS version.
README.hostnames -- Reminders about DNS and how the Merit AAA Server uses it.
TUTORIAL         -- Overview of RADIUS.
Makefile         -- This file is used by make(1) to build things.
src/*            -- Contains all the Merit AAA source files and testing clients.
raddb/*          -- Contains the sample Merit AAA Server 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, FreeBSD 2.1.5 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 Merit AAA Server may be run by any non-privileged user account,
      some operating systems (notably Solaris, FreeBSD 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:

       % 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 lines which define DEFS, RADLIBS and INCS then
    uncomment your chosen "flavor".  Most installations should leave the
    MERIT_GRANDFATHER macro defined.  This enables two special features:
    backwards compatibility with older Merit RADIUS 1.17 style authentication
    and 2) backwards compatibility with RADIUS 1.17 style clients (radcheck
    and radpwtst).  

    Omit the -DNOSHADOW flag from the DEFS make(1) macro if your system has
    the shadow.h file in the /usr/include directory (normally found on some
    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 make(1) macros found between the line starting 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 logfile truncation occurs.  The default found in the
    source code is "/usr/ucb/compress".

    The default build options were chosen to build a working Merit AAA 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 Merit AAA Server and the various 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 thirteen
    (13), below, when you have finished testing your server.


Local configuration and testing:
--------------------------------

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 make(1) macro.

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

       % make man-install

    to have the man pages installed.  If you have retained the Makefile
    macros MAN and MAN_INSDIR in the Makefile as distributed, the man 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
    command (e.g., % man man).  Future releases may contain HTML manuals.


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

    Enhanced (LAS) Note: The same applies to the log.config file.  Edit any
    older versions and or local changes into the distribution copy of the
    log.config file.

    Each Merit AAA Server configuration file is distributed with read-only
    permission, so you may want to change that now.  Switch 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 *").


7.  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
    Merit AAA Server).  Additionally, you may need an entry for each RADIUS
    client or 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      <any-secret>    type=Merit:PROXY

    Replace 'my.radius.host.dns.name' with the full DNS name of the system
    running the Merit AAA Server.  Your secret may be any character string
    which does not contain blanks or control characters.


8.  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, then 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 Merit AAA Server).  Be sure to
    comment out all seven (7) sample entries in the distributed 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 or vendors files in the raddb directory.


9.  Note: This step only applies to the enhanced Merit AAA Server 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.

    The newer "las.conf" file (described in the las.conf(5) man page) does all
    that the realms.las file did and more.  In fact, you may rename an existing
    realms.las file to las.conf and the enhanced Merit AAA Server still works.


10. 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 pages for radiusd(8) (the
    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 Merit AAA Server
    and the test clients' executables.


11. 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 (these default to 1645 and 1646, respectively).


12. 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 server which may be listening on the 1645/6 ports.

    Problems here 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 Merit AAA Server or the user who is running it to
    access the password file (or possibly a shadow password file).

    If this step is successful, you need to properly terminate the test
    Merit AAA 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 read the tip in step thirteen (13).


Installation and production operation:
--------------------------------------

13. To install the Merit AAA Server "radiusd" just enter, "% make install",
    for the Merit AAA Server configuration files use, "% make config-install",
    for the Merit AAA Server test utility files enter, "% make util-install",
    for the Merit AAA Server man page files use, "% make man-install", if
    you haven't already installed the man pages in step five (5), above.

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

    TIP: If you are upgrading your existing production Merit AAA 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 version number of the Merit AAA Server 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.


14. 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
    in /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

    Should the Merit AAA Server terminate, 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 after you edit the file:

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

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


Accounting:
-----------

The Livingston style accounting call detail records are produced by default by
the basic server for compatibility with other systems.  However, the enhanced
Merit AAA Server produces session accounting log files by default.  For more
information see the Merit AAA Server FAQ located at:

   http://www.merit.edu/aaa/documentation.html

The FAQ has instructions on how to archive Livingston style accounting call
detail records when using the enhanced Merit AAA Server.


Session Accounting: (only available with the enhanced Merit AAA Server)
-------------------

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 Merit AAA Server may be used
to process the session logs to obtain user billing information.  See the
radbnr(8) man page for details.

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 Merit AAA Server Directory Structure:
---------------------------------------------

As supplied, the Merit AAA Server 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
   radbnr    -  Merit AAA accounting and reporting utility [requires Berkeley
                DB package] (only with the enhanced Merit AAA Server)
   radcheck  -  Merit AAA Server test utility [like the UNIX ping(8) command]
   radiusd   -  Merit AAA Server executable
   radpwtst  -  Merit AAA Server test client utility
   radrecord -  read and print Merit AAA Server session log files
                (only with the enhanced Merit AAA Server)
   rlmadmin  -  Merit AAA realm file administration utility
                (only with the enhanced Merit AAA Server)
   sesstab   -  print contents of the Merit AAA Server session table file

   radacct/  -  Livingston style RADIUS accounting call detail records are
                placed into directories under 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 RADIUS RFC2138
                                 as implemented in the Merit AAA Server
        dictionary             - definition file required by radiusd
        engine.config          - sample runtime configuration file
        las.conf               - new style enhanced Merit AAA Server config
                                 (only with the enhanced Merit AAA Server)
        log.config             - session logging configuration file
                                 (only with the enhanced Merit AAA Server)
        logfile                - the server log file
        logfile.yymmdd.Z       - compressed daily or weekly log files
        radius.fsm             - the finite state machine (FSM) definitions file
        radius.pid             - contains the process id for the server, etc.
        realms.las             - old style enhanced Merit AAA Server config
                                 (only with the enhanced Merit AAA Server)
        record.las.yymmdd      - old style session accounting logs
                                 (only with the enhanced Merit AAA Server)
        rlmadmin.help          - usage help messages for the rlmadmin(8) tool
                                 (only with the enhanced Merit AAA Server)
        session.las            - currently active sessions, use the sesstab(8)
                                 command to view these files
                                 (only with the enhanced Merit AAA Server)
        session.yyyy-dd-mm.log - session accounting logs
                                 (only with the enhanced Merit AAA Server)
        users                  - holds user security profiles and reply items
        vendors                - holds vendor specific details (IANA numbers)

The logfile, logfile.yymmdd.{gz,Z} files, (session.las and session log files)
are created by the enhanced Merit AAA Server during normal execution.


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

The man directory in the distribution hierarchy contains these man pages:

    man/

      authfile.5      - authfile description
      builddbm.8      - builddbm command description for dbm(3) user database,
                        important if the server was built with USE_DBM defined
      clients.5       - clients file description
      dictionary.5    - dictionary file description
      engine.config.5 - runtime configuration file description
      dnscheck.8      - dnscheck command description for checking DNS config
      las.conf.5      - las.conf file description
                        (only with enhanced Merit AAA Server)
      lasrecord.8     - description of the lasrecord accounting print utility
                        (only with enhanced Merit AAA Server)
      log.config.5    - description of the session logging configuration file
                        (only with enhanced Merit AAA Server)
      radbnr.8        - radbnr command description (billing and reporting from
                        session log files only in enhanced Merit AAA Server)
      radbnr.conf.5   - link to las.conf.5
                        (only with enhanced Merit AAA Server)
      radcheck.8      - radcheck command description for checking server status
      radius.fsm.5    - description of Merit AAA Server FSM table
      radiusd.8       - radiusd Merit AAA Server description
      radpwtst.8      - radpwtst command description (client simulation utility)
      radrecord.8     - radrecord command description for reading and printing
                        session log files (only with enhanced Merit AAA Server)
      realms.las.5    - realms.las file description
                        (only with enhanced Merit AAA Server)
      record.las.5    - description of the daily accounting log file
                        (only with enhanced Merit AAA Server)
      rlmadmin.8      - rlmadmin Merit AAA Server realm file administration tool
                        (only with enhanced Merit AAA Server)
      session.las.5   - description of logfile for currently active session
                        (only with enhanced Merit AAA Server)
      sesstab.8       - sesstab command description to print session.las files
                        (only with enhanced Merit AAA Server)
      users.5         - users file description
      vendors.5       - vendors 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

Please place one of the strings "[AAA]" or "[AAA support]" in front of
the "Subject:" lines of your email message.
