USAGE

BASIC USAGE
===========

1.) Create a server definition file. Refer to the `servers.example'
    file for more information. Note, that *all* servers in that file
    will be queried sequentially, until the first one answers.

2.) Be sure you have a RADIUS dictionary. It should at least include
    the attributes "User-Name", "User-Password", "CHAP-Password",
    "Nas-IP-Address", "NAS-Port", as they are mandatory for a RFC 2865
    compliant RADIUS packet. The default search path is defined by the
    FreeRADIUS installation (specifically in freeradius/radpaths.h).

3.) If your program is single-threaded, simply call

        rad_auth_simple(user, pw, config)

    or, alternatively,

        rad_auth(user, pw, tries, config, dict, vps)

    from your program, where `user', `pw' and `config' are char*
    strings. All servers in the config file will be tried until any of
    them answers. This will be tried three times in total.

    `tries' is an integer specifying how many times the
    authentication should be tried. The `dict' argument must point to
    a FreeRADIUS dictionary. If you specify NULL here, a temporary
    file containig an RFC 2865 compliant dictionary will be created.

    The `vps' argument is a simple char* string and may contain
    additional value pairs that will be added to the request. Multiple
    VPs can be separated by commas. Be aware that when an invalid
    attribute or syntax is discovered, parsing will be aborted and all
    further attributes will be silently discarded. A warning and the
    list of successfully added attributes is printed in debug mode.

    Refer to `radauth_test.c' for a complete example. Note that these
    functions are *NOT* thread-safe. See 4).

    return code | meaning
    ------------+----------------------------------------------
        0       | authentication: Accepted
        1       | authentication: Rejected
       -1       | an error happened; look at rad_auth_errstr()
       -2       | no servers could be reached

4.) If your program uses threads and different threads might call the
    rad_auth*() functions at the same time, you will have to use the
    re-entrant API. The dictionary initialization from `libfreeradius`
    is not re-entrant, so this has to be done in a separate
    initialization function at program start (or module load, etc).
    Subsequently, you should use the rad_auth*_r() functions. E.g.:

        /* Might be in main() or some initializer function */
        rad_auth_init("dictionary.rfc2865");

        /* Actual auth check */
        int rc = -1;
        char errmsg[1024];
        rc = rad_auth_r(username, password, 3, "servers", vp, errmsg);

        /* clean up */
        rad_auth_cleanup();

    See `radauth_test_threaded.c` for a complete example. (That
    program can be used for RADIUS load testing, too. Try increasing
    the number of threads to 128...)

5.) If things don't work, re-compile the library with -DDEBUG, or via
    `make clean && make DEBUG=1'. You should get tons of output, then.
    Alternatively, and this is recommended, you can set up the
    environment variable `LIBRADAUTH_DEBUG` to achieve this. If set to
    0, debugging is disabled. Setting it to 1 will send debugging info
    to standard error. If set to anything else, that string will be
    interpreted as a file name and the debug information will be
    appended to the file, creating it if necessary. For example:

    $ env LIBRADAUTH_DEBUG=/dev/shm/libradauth-debug.log ./my-application

ADVANCED USAGE
==============

The functions rad_auth_simple() and rad_auth() are actually wrapper
functions for the rad_auth_cb() function that takes the usual
parameters user, pw, tries, config, dict. But the two consecutive
arguments must be a callback function and a void * argument pointer.
The callback-function must match the signature

    int fn(rad_cb_action action, const void *arg, void *data)

where rad_cb_action is an enum specifying at which stage the function
is called, thus determining what type of data is supplied in `data'.
The `arg' argument is the user-supplied last argument to rad_auth_cb().

For an example, refer to the rad_cb_userparse() function libradauth.c
which implements the callback function used by rad_auth() to add
value-pairs from a string.

Note you'll probably have to include FreeRADIUS's header files if you
want to do anything meaningful, for example casting to VALUE_PAIR or
calling pairadd();

ACCOUNTING PACKETS
==================

There is also an rad_acct_*() interface similar to the auth interface.
You will need to set the "acctport" if you don't use the default port,
and include all attributes manually. In particular, you will probably
need a dictionary that has definitions suitable for accounting (see
e.g. "dictionary.rfc2866").

    char err[1024];
    rad_auth_init("dictionary.zedat");
    rad_acct_r(1, "servers.acct", "Acct-Status-Type = Start", (void *)&err);

This will try only once to send the accounting packet. If an
acknowledgement is received, this function returns 0; a negative code
has the same meaning as the auth case.