radtest.texi

gnu 的radius服务器很好用的

@item keepauth=1
Do not alter request authenticator when resending the request.
@end table

@table @var
@item port-type
Specifies which port to use when sending the request. Use @samp{auth}
to send the request to the authentication port
(@pxref{client.conf,auth-port}), and @samp{acct} to send it to the
accounting port (@pxref{client.conf,acct-port}).

@item code
@RADIUS{} request code. Either numeric or symbolic (@pxref{Numeric
Values}).

@item expr-or-pair-list
Specifies the @AVP{}s to include in the request. This argument is
either an expression evaluating to @code{avlist}, or an immediate
@code{avlist} (@pxref{Avlists}). In the latter case, the parentheses
around the list are optional.
@end table

@end deffn

@deffn {Radtest statement} expect @var{code} [@var{expr-or-pair-list}]
Test if @code{REPLY_CODE} matches @var{code} and, optionally, if
@code{REPLY} matches @var{expr-or-pair-list}. If so, print the
string @samp{PASS}, otherwise print @samp{FAIL}.

@xref{Interacting with Radius Servers}, for the detailed discussion of
this statement.
@end deffn

@node Sample Radtest Program
@subsection Sample Radtest Program

As an example, let's consider @command{radauth} program
(@pxref{Radauth}). Its main purpose is to send authentication
request to the remote server, analyze its reply and if it is
positive, send an appropriate accounting record, thereby initiating
user's session. Optionally, the script should also be able to
send a lone accounting record.

In the discussion below, we will show and explain subsequent
parts of the script text. For the ease of explanation, each line
of program text will be prepended by its ordinal line number.

@subheading Parsing command line options

The script begins as follows:

@smallexample
@group
  1 #! /usr/bin/radtest -f
  2 
  3 while getopt "n:s:P:hv"
  4 begin
  5   case $OPTVAR in
  6   "-n") NASIP = $OPTARG 
  7   "-s") SID = $OPTARG 
  8   "-P") PID = $OPTARG 
  9   "-v") set -v
@end group
@end smallexample

@table @asis
@item 1
It is a @dfn{pragmatic comment} informing shell that it
should run @command{radtest} in order to interpret the program.

@item 3
This line starts option processing loop. @code{Getopt}
(@pxref{Built-in Primitives,getopt}) in line 3 analyzes each
subsequent command line argument and if it is an option checks
whether it matches one of the option letters defined in its
first argument. The option letter will be returned in @code{OPTVAR}
variable, its argument (if any) -- in @code{OPTARG} variable.

@item 4 -- 8
@code{OPTARG} value is analyzed using @code{case} statement. Lines
6 -- 8 preserve @code{OPTARG} values in appropriate variables for
later use. @code{NASIP} will be used as the value of
@attr{NAS-IP-Address} attribute, @attr{SID} is the session id
(@attr{Acct-Session-Id} attribute), and @attr{PID} is the port
number (for @attr{NAS-Port-Id} attribute.

@item 9
This line sets @option{-v} option to the @command{radtest}
interpreter (@pxref{Invoking radtest}). 
@end table

@noindent
The next piece of code handles @option{-h} and erroneous options:

@smallexample
@group  
 10   "-h") begin
 11           print <<-EOT
 12            usage: radauth [OPTIONS] [COMMAND] login [password]
 13            Options are:
 14            -v         Print verbose descriptions of what is being done
 15            -n IP      Set NAS IP address
 16            -s SID     Set session ID
 17            -P PORT    Set NAS port number
 18            COMMAND is one of:
 19            auth       Send only Access-Request (default)
 20            acct       Send Access-Request. If successfull, send
 21                       accounting start request
 22            start      Send accounting start request
 23            stop       Send accounting stop request
 24            EOT
 25           exit 0
 26         end
 27   ".*") begin
 28           print "Unknown option: " $OPTVAR "\n"
 29           exit 1
 30         end
 31   end
 32 end
@end group
@end smallexample

@table @asis 
@item 10 -- 26
Print short description and exit, if the program is given @option{-h}.
Notice that @samp{here document} syntax is used to print the text
(@xref{Strings}, for its description). The leading whitespace in
lines 12 to 24 is composed of tabulation characters (ASCII 9), not
usual space characters (ASCII 32), as required by @samp{<<-}
construct.

@item 27 -- 30
These lines handle unrecognized options.

@item 31
Closes case statement started on line 5
 
@item 32
Closes compound statement started on line 4
@end table

@subheading Checking Command Line Consistency

@smallexample
@group
 33 
 34 shift $@{OPTIND@}-1
 35 
 36 if $# > 3
 37 begin
 38         print "Wrong number of arguments."
 39         print "Try radauth -h for more info"
 40         exit 1
 41 end
@end group
@end smallexample

@table @asis
@item 34
@code{OPTIND} keeps the ordinal number of the first non-optional
argument. This line shifts off all the options processed by
@code{getopt}, so that the first non-optional argument may be
addressed by @code{$1} notation. Notice use of curly braces to
solve @dfn{minus ambiguity} (@pxref{minus-ambiguity}).

@item 36 -- 41
At this point we may have at most three arguments:
command, user name, and password. If there are more, display
the diagnostic message and exit the program.
@end table 

@noindent
Next piece of code: 

@smallexample
@group
 42
 43 case $1 in
 44 "auth|acct|start|stop") begin
 45                           COMMAND=$1
 46                           shift 1
 47                         end
 48 ".*")   COMMAND="auth"
 49 end
 50 
 51 LOGIN=$@{1:?User name is not specified. Try radauth -h for more info.@}
 52 
 53 if $@{NASIP:-@} = ""
 54         NASIP=$SOURCEIP
 55 
 56 LIST = ( User-Name = $LOGIN NAS-IP-Address = $NASIP )
@end group
@end smallexample

@table @asis
@item 43 -- 48
Check if a command is given. If so, store command name in the variable
@code{COMMAND} and shift arguments by one, so login becomes argument
@code{$1}. Otherwise, assume @samp{auth} command.

@item 51
If the user login name is supplied, store it into @code{LOGIN}
variable. Otherwise, print diagnostic message and exit.

@item 53 -- 54
Provide a default value for @code{NASIP} variable from the built-in
variable @code{SOURCEIP} (@pxref{Built-in Variables})

@item 56
The variable @code{LIST} will hold the list of A/V pairs to be sent
to the server. This line initializes it with a list of two @AVP{}s:
@attr{User-Name} and @attr{NAS-IP-Address}.
@end table

@subheading Defining Accounting Function

Accounting function will be used to send accounting requests to
the server. It is supposed to take a single argument: an @code{avlist}
of @AVP{}s to be sent to the server.

@smallexample
@group 
 57 
 58 'acct'
 59 begin
 60   if $@{SID:-@} = ""
 61     input "Enter session ID: " SID
 62   if $@{PID:-@} = ""
 63     input "Enter NAS port ID: " PID
 64   send auth Accounting-Request $1 + \
            (Acct-Session-Id = $SID NAS-Port-Id = $PID)
@end group
@end smallexample

@table @asis
@item 58 -- 59
These lines start the function definition. Notice quoting of the
function name (@samp{acct}): it is necessary because it coincides
with a reserved keyword (@pxref{Reserved Keywords}).

@item 60 -- 61
If the value of @code{SID} (session ID) is not supplied, prompt the
user to input it.

@item 62 -- 63
If the value of @code{PID} (port ID) is not supplied, prompt the
user to input it.

@item 64
Send accounting request. The list of @AVP{}s to send is formed by
concatenating @attr{Acct-Session-Id} and @attr{NAS-Port-Id} attributes
to the function's first argument.
@end table

@noindent
The final part of @code{acct} function analyzes the reply from the
server:

@smallexample
@group            
 65   if $REPLY_CODE != Accounting-Response
 66   begin
 67     print "Accounting failed.\n"
 68     exit 1  
 69   end
 70   print "Accounting OK.\n"
 71   exit 0
 72 end
 73
@end group
@end smallexample

@noindent
Notice, that @code{acct} never returns. Instead it exits with an
error code indicating success or failure.

@subheading Defining Authentication Function

The purpose of the authentication function @code{auth} is
to send an @code{Access-Request} to the server and perform
some actions based on its reply. 

The function will take three arguments:

@table @code
@item $1
The list of @AVP{}s to include in the request.

@item $2
User password.

@item $3
This argument indicates whether accounting request must be sent
after successful authentication. String @samp{yes} means to send
the accounting request, @samp{no} means not to send it.
@end table

The function is not expected to return. Instead it should exit
to the shell with an appropriate error code.

@smallexample
@group 
 74 'auth'
 75 begin
 76   send auth Access-Request $1 + (User-Password = $2)
@end group
@end smallexample

@table @asis
@item 74 -- 75
Begin the function definition. Notice quoting of the
function name (@samp{auth}): it is necessary because it coincides
with a reserved keyword (@pxref{Reserved Keywords}).

@item 76
Send the initial authentication request. The list of @AVP{}s is
formed by appending @attr{User-Password} pair to the list given
by the first argument to the function.
@end table

@noindent
The rest of the function analyzes the reply from the server and takes
appropriate actions. Notice that if the server replies with an
@code{Access-Challenge} packet, we will have to send subsequent
authentication requests, so this piece of code is enclosed within
a @code{while} loop.

First, the function handles @code{Access-Accept} and
@code{Access-Reject} replies:

@smallexample
@group 
 77   while 1
 78   begin
 79     if $REPLY_CODE = Access-Accept
 80     begin
 81       print "Authentication passed. " + $REPLY[Reply-Message*] + "\n"
 82       if $@{3:-no@} = no
 83         exit 0
 84       'acct'($1 + ( Acct-Status-Type = Start ))
 85     end else if $REPLY_CODE = Access-Reject
 86     begin
 87       print "Authentication failed. " + $REPLY[Reply-Message*] + "\n"
 88       break
@end group
@end smallexample

@table @asis
@item 77
Begin an ``endless'' @code{while} loop. It will eventually be exited
either using @code{break}, or using @code{exit} (see below).

@item 79 -- 84
Hanlde @code{Access-Accept} replies:

@item 81
Print the reply message. Notice the use of @samp{*} to print all
the instances of @attr{Reply-Message} attribute from the reply
packet (@pxref{Accessing Elements of A/V Pair Lists}).

@item 82 -- 83
If the third argument is missing or is a string @samp{no}, exit
indicating success (@pxref{Dereferencing Variables}). 

@item 84
Otherwise, call @code{acct} function to perform accounting. The
@AVP{}s included in the accounting request are formed by adding
@attr{Acct-Status-Type} attribute to the list given by the first
argument to the function.

@item 85 -- 88
Handle @code{Access-Reject} replies. Print the reply message and
break from the loop.
@end table

@noindent
Next piece of code deals with @code{Access-Challenge} replies. For
simplicity we assume that such replies always carry user menus
(@xref{menus directory}, for the description of these). So, upon
receiving an @code{Access-Challenge} we should print out the menu,
read the users selection and send back an @code{Access-Request}
to the server. This part is the only one that actually continues
the loop at line 77. 

@smallexample
@group 
 89     end else if $REPLY_CODE = Access-Challenge
 90     begin
 91       print $REPLY[Reply-Message*]
 92       input 
 93       send auth Access-Request \
 94         (User-Name = $LOGIN User-Password = $INPUT \
             State = $REPLY[State])
@end group
@end smallexample

@table @asis
@item 91
Print the menu contents carrieb by @attr{Reply-Message}
attributes. There may be several instances of the attribute, hence the
use of @samp{*} to concatenate their values together.

@item 92
Read the input from the user. The input will be stored in @code{INPUT}
variable. @xref{Built-in Primitives}, for the description of
@code{input} statement.

@item 93 -- 94
Send an @code{Access-Request} packet with three attributes.
@attr{User-Password} contains the user reply, @attr{State} contains
the menu state from the server reply packet.
@end table

@noindent
Final part of the function:
 
@smallexample
@group 
 95     end else begin
 96       print "Authentication failed. Reply code " + $REPLY_CODE + "\n"
 97       break
 98     end
 99   end
100   exit 1
101 end
102
@end group
@end smallexample

@table @asis
@item 95 -- 98
Handle unknown reply codes.

@item 99
Closes the while loop started on line 77.

@item 100
Exit to the shell indicating failure. This statement will be reached
only if a @code{break} is executed either on line 88 or on line 97.

@item 101
Closes function definition started on lines 74 -- 75 
@end table

@subheading Final Part of Radauth Program

The final part selects an action based on the user command and
executes it. It is equivalent to the @code{main} function in a
@code{C} program:

@smallexample
@group
103 case $@{COMMAND@} in
104 "auth")   'auth'($LIST, $@{2:&Password: @}, no)
105 "acct")   'auth'($LIST, $@{2:&Password: @}, yes)
106 "start")  'acct'($LIST+(Acct-Status-Type = Start))
107 "stop")   'acct'($LIST+(Acct-Status-Type = Stop))
108 ".*")       begin
109               print "Unknown command. Try radauth -h for more info"
110               exit 1
111             end
112 end
113 
114 # End of radauth
@end group
@end smallexample

@table @asis
@item 103
Select an action based on the value of @code{COMMAND} variable.

@item 104 -- 105
Call @code{auth} function. If the second argument is given in the
command line, its value is taken as user's password. Otherwise, the
user is prompted for the password with the string @samp{Password: }.
The input is read with echo turned off to prevent the password from
being compromised (the @samp{:&} construct, @pxref{Dereferencing
Variables}).

@item 106 -- 107
Call @code{acct} function for @samp{start} and @code{stop} commands.

@item 108 -- 111
Handle an unknown command verb.

@item 112
Closes @code{case} statement from line 103.
@end table

@c End of radtest.texi