Using radclient
===============

Introduction
------------

The "radclient" program sends a RADIUS request as received on standard input as
ASCII A/V pairs to a set of target servers given on the command line, and 
outputs the response on standard output, again as a set of ASCII A/V pairs.
The A/V pair encoding follows the standard OpenRADIUS ASCII module interface.

The RADIUS client will add any required information that's missing from your
request to make it RFC-compliant. If anything is missing for which it cannot
provide a meaningful value itself, it will warn you.

A simple PAP request would therefore consist of just the following A/V pairs:

	User-Name = "someuser"
	User-Password = "herpasswordincleartext"

The NAS-IP-Address pair is added automatically and the User-Password is also
properly encoded. Similarly, a CHAP request would require only these pairs:

	User-Name = "someuser"
	CHAP-Password = "herpasswordincleartext"

A CHAP-Challenge pair is generated automatically and the CHAP-Password contains 
the result of hashing this with the given cleartext password. For accounting,
you either specify -a on the command line or include the following A/V pair in
your request:

	RAD-Code = Accounting-Request

(Note that if you don't specify -a, the default UDP port will remain 1812 and
not 1813 regardless of the value of RAD-Code; you may therefore want to specify
1813 explicitly as the target port in that case). A valid accounting request
would be

	RAD-Code = Accounting-Request
	User-Name = "someuser"
	Acct-Status-Type = Start

The RADIUS client prepares the request and sends it off, retrying a certain
number of times across the servers you specified, if it doesn't receive an
answer. You can specify up to 4 servers and secrets on the command line [1].
The number of retries and the timeout period can be specified using the -c 

After receiving a response, radclient will decode it, verify the response
authenticator, and output the A/V pairs in ASCII if it is valid. 

All input and output is done according to OpenRADIUS' standard module
interface; please see http://www.openradius.net/doc-module-interface.html,
section 3.2 for the syntax definition.

After EOF on standard input (Ctrl-D if you run it on a terminal), it will
wait till all its outstanding requests have been answered or timed out, and
exit with the RADIUS code of the last response, or another exit code as 
follows:

64	Wrong arguments on command line; usage message displayed
65	There was an error reading the dictionary
66	There was an error processing input from stdin
67 	There was an error processing input from the UDP socket
68	The request timed out

79	Internal error, eg. out of memory


[1] If you need more than 4 redundant target servers, all you have to do is
change MAX_SERVERS in radclient.c.


Using radclients from your own programs
---------------------------------------

If you want to use radclient to implement RADIUS support in your program, you
don't need to link your code to a C interface. Just open two pipes, one for
input and one for output, and pass these as file descriptors 0 and 1 to 
radclient.

Then, you send series of text lines containing A/V pairs, terminated by an
empty line to the pipe connected to radclient's file descriptor 0, and read
the response from the other pipe in the same format.

The correct format for A/V pairs is described in detail in
http://www.openradius.net/doc-module-interface.html

You can send as many requests as you want; the radclient program will stay
running until you close its input pipe and the last request has been answered
or has timed out. It even supports multiple requests in parallel; up to 256, as
that is the maximum for RADIUS if you use a single source UDP port. 

To allow your program to match a response received from radclient to the
requests you sent it, you can include a Radclient-Query-Id A/V pair in your
request. This pair will then be echoed in any subsequent communication from
radclient about that request, even if no answer was received from the servers.
That way, you know which outstanding request the answer or timeout indication
is for.


Command line options
--------------------

radclient supports the following command line options:

	-r dir	Allows you to specify a different configuration directory.
		Default: /usr/local/etc/openradius

	-i ip	Local IP address to send requests from; needed if you have
		multiple interfaces. Default: 0.0.0.0

	-t sec	Timeout period in seconds. Default: 5

	-c n	Number of times to retry if no valid answer was received
		within the timeout period. Default: 3

	-a	If no request type is given in a RAD-Code pair in the request,
		default to accounting. Also sets the default port to 1813
		instead of 1812.

	-n	Normally, radclient will include a dummy 'int' pair in its
		output containing the status code as defined above; this option
		suppresses that A/V pair.

	-l	Causes returned attribute names to be fully qualified with
		space and vendor prefixes.

	-p	Send User-Password and CHAP-Password attributes as-is
		instead of encoding them according to PAP/CHAP rules.

	-q	Suppresses all prompting or error messages on the standard
	        error output.

	-v      Outputs extra debugging information on standard error.


Wrapper scripts
---------------

Two convenient wrapper scripts are included that allow you to perform a simple
authentication or accounting test using information specified on the command
line.

The "radtest" script is for authentication testing and works similar to
FreeRADIUS' version. It should be invoked as "radtest [options] user password
server[:port] secret", where square brackets denote optional arguments. It
supports two command line options, -v and -chap.

The "radaccttest" script should be invoked as "radaccttest [options] user
server[:port] secret" and supports the command line options -v, -start and
-time, which allow verbose output, an accounting-start request instead of the
default -stop request, and the session time in seconds for stop requests to be
specified.

