radtest.texi

gnu 的radius服务器很好用的

@c This is part of the Radius manual.
@c Copyright (C) 2004 Free Software Foundation, Inc.
@c Written by Sergey Poznyakoff
@c See file radius.texi for copying conditions.
@comment *******************************************************************
@node radtest
@section radtest
@pindex radtest

@command{Radtest} is a radius client shell, providing a simple and
convenient language for sending requests to @RADIUS{} servers and
analyzing their reply packets.

@menu
* Invoking radtest::
* Literal Values::
* Reserved Keywords::
* Variables in radtest::
* Positional Parameters::
* Expressions in radtest::
* Function Definitions::
* Interacting with Radius Servers::
* Conditional Statements::
* Loops::
* Built-in Primitives::
* Sample Radtest Program::
@end menu

@node Invoking radtest
@subsection Invoking radtest
@UNREVISED{}

@table @option
@item -a @var{variable}=@var{value}
@itemx --assign=@var{variable}=@var{value}
Assign a @var{value} to @var{variable}. @xref{Assignment Options}, for
a detailed discussion.

@item -f @var{file}
@itemx --file=@var{file}
Read input from @var{file}. Stops further processing of the command line.

@item -i
@itemx --no-interactive
Disable interactive mode.

@item -n
@itemx --dry-run
Check the input file syntax and exit.

@item -q
@itemx --quick
Do not read the configuration file.
@FIXME{}

@item -r @var{number}
@itemx --retry=@var{number}
Set number of retries.

@item -s @var{server}
@itemx --server=@var{server}
Set radius server parameters.

@item -t @var{number}
@itemx --timeout=@var{number}
Set timeout

@item -v
@itemx --verbose
Verbose mode

@item -x @var{debugspec}
@item --debug=@var{debugspec}
Set debugging level

@item -d @var{dir}
@itemx --directory @var{dir}
Specify alternate configuration directory. Default is @file{@value{RADDB}}.

@item -L
@itemx --license
Print license and exit.

@item -?
@itemx --help
Print short usage summary

@item --usage
Print even shorter usage summary.

@item -V
@itemx --version
Print program version.
@end table

@node Literal Values
@subsection Literal Values

There are four basic data types in @command{radtest} language: @code{integer},
@code{ipaddr}, @code{string} and @code{avlist}.

@menu
* Numeric Values::      Integers and IP addresses.
* Strings::             Character Strings.
* Avlists::             Lists of A/V pairs.
@end menu

@node Numeric Values
@subsubsection Numeric Values

@dfn{Integer} means a signed integer value in the range
-2147483648..2147483647.

@dfn{Ipaddr} is an unsigned integer value suitable for representing
@sc{ip}v4 addresses. These can be input either as decimal numbers or
as @IP{}s in usual ``dotted-quad'' notation.

As a convenience measure, @RADIUS{} request code names can be used
in integer context. The following table lists currently defined
request names with their integer codes:

@multitable @columnfractions .40 .20
@item Access-Request @tab 1
@item Access-Accept  @tab 2 
@item Access-Reject  @tab 3
@item Accounting-Request  @tab 4
@item Accounting-Response @tab 5
@item Accounting-Status   @tab 6
@item Password-Request    @tab 7
@item Password-Ack        @tab 8
@item Password-Reject     @tab 9
@item Accounting-Message  @tab 10
@item Access-Challenge    @tab 11
@item Status-Server       @tab 12
@item Status-Client       @tab 13  
@item Ascend-Terminate-Session @tab 31
@item Ascend-Event-Request     @tab 33
@item Ascend-Event-Response    @tab 34
@item Ascend-Allocate-IP       @tab 51
@item Ascend-Release-IP        @tab 52
@end multitable 

@node Strings
@subsubsection Character Strings

@dfn{String} is an arbitrary string of characters. Any input token
consisting of letters of Latin alphabet, decimal digits, underscores
dashes and dots and starting with a Latin alphabet letter or
underscores is considered a string. To input strings containing other
letters, surround them by double quotes. The following are valid strings:

@smallexample
@group
A-string
"String, containing white space"
@end group
@end smallexample

The double quote character @samp{"} must be preceeded by a backslash
@samp{\} if it is part of a string:

@smallexample
"Always quote \" character"
@end smallexample

Generally speaking, @samp{\} is an @dfn{escape character}, that
alters the meaning of the immediately following character. If it is
located at the end of the line, it allows to input newline
character to strings:

@smallexample
@group
"This string contains a \
newline character."
@end group
@end smallexample

Other special escape sequences are:

@table @asis
@item \a
Audible bell character (ASCII 7)
@item \b
Backspace (ASCII 8)
@item \e
Escape character (ASCII 27)
@item \f
Form feed (ASCII 12)
@item \n
Newline (ASCII 10)
@item \r
Carriage return (ASCII 13)
@item \t
Horizontal tab (ASCII 9)
@item \\
Backslash
@item \ooo
(@samp{o} represents an octal digit)
A character whose ASCII value is represented by the octal number @samp{ooo}.
@item \xHH
@itemx \XHH
(@samp{H} represents a hex digit)
A character whose ASCII value is represented by the hex number @samp{HH}.
@end table

If the character following the backslash is not one of those
specified, the backslash is ignored.

@anchor{STRNUM}An important variant of @code{string} is a @dfn{numeric string},
or @dfn{STRNUM} for short. A numeric string is a string that
can be converted to a number, for example @code{"+2"}. This concept
is used for type conversion between @code{integer} and @code{string}
values.

Another way to represent strings is using @dfn{here document} syntax.
Its format is as follows:

@smallexample
@group
<<[-]@var{delimiter}
  @var{text}
@var{delimiter}
@end group
@end smallexample

@noindent
@var{Delimiter} is any word you choose to delimit the text, @var{text}
represent the text of the string. If @var{delimiter} is prepended by a
dash, any leading tabulation characters will be removed from @var{text}. This
allows for natural indentation of @samp{here document} constructs.

The @samp{here document} construct is especially useful to represent strings
containing embedded newlines, as shown in the example below:

@smallexample
@group
print <<EOT
usage: foo [OPTIONS] [NAME...]
OPTIONS are:
  -h            Print this help list.
EOT
@end group
@end smallexample                                        

@node Avlists
@subsubsection Lists of A/V pairs

@dfn{Avlist} are whitespace or comma-separated lists of
@RADIUS{} attribute-value pairs. A syntax for @AVP{} is

@example
@var{name} @var{op} @var{value}
@end example

@noindent
where @var{name} is attribute name, @var{op} is a comparison
operator (@samp{=}, @samp{!=}, @samp{<}, @samp{<=}, @samp{>},
@samp{>=}), and @var{value} is any valid @command{radtest} data
or expression.
An @AVP{} list must be enclosed in parentheses. This is an
example of an @AVP{} list consisting of two pairs:

@smallexample
@group
( User-Name = "test" NAS-IP-Address = 10.10.10.1 )
@end group
@end smallexample

@noindent
An empty pair list is represented by a pair of parentheses: @code{()}.

@node Reserved Keywords
@subsection Reserved Keywords

The following keywords are reserved in @command{radtest}:

@smallexample
@group
acct, and, auth, begin, break, case, continue, 
do, else, end, exit, expect, getopt, if,       
in, input, not, or, print, return, send,     
set, shift, while    
@end group
@end smallexample

The reserved keywords may be used as variable names, provided that
the following requrements are met:

@itemize @bullet
@item In assignment, these names are quoted using single quotes.

@smallexample
'case' = 1
@end smallexample

@item When dereferencing, the use of curly braces is obligatory:

@smallexample
$@{case@} + 2
@end smallexample
@end itemize

@node Variables in radtest
@subsection Variables

Variables are means of storing data values at one point of your
program for using them in another parts of it. Variables can be
assigned either in the program itself, or from the @command{radtest}
command line.

@menu
* Using Variables::
* Variable Assignments::
* Dereferencing Variables::
* Accessing Elements of A/V Pair Lists::
* Assignment Options::
* Built-in Variables::
@end menu

@node Using Variables
@subsubsection Using Variables

The name of a variable must be a sequence of letters, digits,
underscores and dashes, but it may not begin with a digit or dash. Notice,
that in contrast to the majority of programming languages, use of
dashes (minus signs) is allowed in user names. This is because
traditionally @RADIUS{} attribute names contain dashes, so
extending this practice to variable names makes @code{radtest}
programs more consistent. On the other hand, this means that you
should be careful when using minus sign as a subtraction
operator (@pxref{minus-ambiguity}). Case is significant in variable names:
@code{a} and @code{A} are different variables. 

A name of a variable may coincide with one of @code{radtest} reserved
keywords. @xref{Reserved Keywords}, for description on how to use such
variables.

A few variables have special built-in meanings (@pxref{Built-in Variables}). Such
variables can be assigned and accessed just as any other ones. All
built-in variables names are entirely upper-case.

Variables are never declared, they spring into existence when
an assignment is made to them. The type of a variable is determined
by the type of the value assigned to it. 

@node Variable Assignments
@subsubsection Variable Assignments

An @dfn{assignment} stores a new value into a variable. It's syntax
is quite straightforward:

@smallexample
@var{variable} = @var{expression}
@end smallexample

@noindent
As a result of the assignment, the @var{expression} is evaluated and
its value is assigned to @var{variable}. If @var{variable} did not
exist before the assignment, it is created. Otherwise, whatever old
value it had before the assignment is forgotten.

It is important to notice that variables do @emph{not} have
permanent types. The type of a variable is the type of whatever
value it currently holds. For example:

@smallexample
@group
foo = 1
print $foo @result{} 1
foo = "bar"
print $foo @result{} bar
foo = ( User-Name = "antonius" NAS-IP-Address = 127.0.0.1 )
print $foo @result{} ( User-Name = "antonius" NAS-IP-Address = 127.0.0.1 )
@end group
@end smallexample

Another important point is that in @command{radtest}, assignment is
not an expression, as it is in many other programming languages. So
@code{C} programmers should resist temptation to use assignments in
expressions. The following is @emph{not} correct:

@smallexample
x = y = 1
@end smallexample

Finally, if the variable name coincides with one of @command{radtest}
keywords, it must be enclosed in single quotes:

@smallexample
'case' = 1
@end smallexample

@node Dereferencing Variables
@subsubsection Dereferencing Variables

@dfn{Dereferencing} a variable means accessing its value. The
simplest form of dereferencing is by prepending a dollar sign
to the variable name:

@smallexample
@group
foo = 1
print foo @result{} foo
print $foo @result{} 1
@end group
@end smallexample

@noindent
Notice, that in the example above, the first @code{print} statement
understands @code{foo} as a literal string, whereas the second one
prints the value of the variable.

Dereferencing an undefined variable produces error message:

@smallexample
print $x @error{} variable `x' used before definition
@end smallexample

Optionally, the variable name may be surrounded by curly braces.
Both @code{$foo} and @code{$@{foo@}} are equivalent. The use of
the latter form is obligatory only when the variable name coincides
with one of the reserved keywords (@pxref{Reserved Keywords}).
@anchor{minus-ambiguity}It also can be used to resolve ambiguity between using dash as
a part of user name and as a subtraction operator:

@smallexample
@group
long-name = 2
$long-name @result{} 2
$long-name-1 @error{} variable `long-name-1' used before definition
$@{long-name@}-1 @result{} 1
$long-name - 1 @result{} 1
@end group
@end smallexample

We recommend to always surround @samp{-} with whitespace when it is
used as arithmetic operator.

The @code{$@{@}} notation also permits some operations similar to
shell variable substitution.

@table @asis
@item $@{variable:-text@}
Use default values. If @var{variable} is unset, return @var{text},
otherwise return the value of the @var{variable}.

@smallexample
@group
$x @error{} variable `x' used before definition
$@{x:-1@} @result{} 1
x = 2
$@{x:-1@} @result{} 2
@end group
@end smallexample

@item $@{variable:=text@}
Assign default values. If @var{variable} is unset, @var{text} is
assigned to it. The expression always returns the value of the
variable.

@smallexample
@group
$x @error{} variable `x' used before definition
$@{x:=1@} @result{} 1
$x @result{} 1
@end group
@end smallexample

@item $@{variable:?text@}
Display error if unset. If @var{variable} is unset, @var{text} is
written to the standard error (if @var{text} is empty, the default
diagnostic message is used) and further execution of the program is
aborted. Otherwise, the value of @var{variable}
is returned. 

@smallexample
@group
$x @error{} variable `x' used before definition
$@{x:?@} @error{} x: variable unset
$@{x:?foobar@} @error{} foobar
@end group
@end smallexample

@item $@{variable::text@}
Prompt for the value if unset. If @var{variable} is unset,
@command{radtest} prints @var{text} (or a default message, if it
is empty), reads the standard input up to the newline character
and returns the value read. Otherwise, the value of the variable
is returned. This notation provides a convenient way for asking
user to supply default values.

@smallexample
@group