/[radius]/radius/doc/texinfo/extensions.texi
ViewVC logotype

Diff of /radius/doc/texinfo/extensions.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.13 by gray, Sat May 17 21:28:48 2003 UTC revision 1.14 by gray, Wed May 21 09:29:10 2003 UTC
# Line 6  Line 6 
6  @chapter Extensions  @chapter Extensions
7  @cindex Extensions  @cindex Extensions
8    
9  The use of extension language allows to extend the functionality of  The use of extension language allows extending the functionality of
10  GNU Radius without having to modify its source code. The two extension  GNU Radius without having to modify its source code. The two extension
11  languages supported are Rewrite and Scheme. Use of Rewrite is always  languages supported are Rewrite and Scheme. Use of Rewrite is always
12  enabled. Use of Scheme requires Guile version 1.4 or higher.  enabled. Use of Scheme requires Guile version 1.4 or higher.
# Line 22  enabled. Use of Scheme requires Guile ve Line 22  enabled. Use of Scheme requires Guile ve
22  @section Filters  @section Filters
23  @cindex Filters  @cindex Filters
24    
25  The simplest way to extend radius functionality is to use filters.  The simplest way to extend the functionality of Radius is to use filters.
26  A filter is an external program that communicates with radius via  A filter is an external program that communicates with Radius via
27  its standard input and output channels.  its standard input and output channels.
28    
29  @menu  @menu
# Line 38  its standard input and output channels. Line 38  its standard input and output channels.
38  @node Getting Acquainted with Filters  @node Getting Acquainted with Filters
39  @subsection Getting Acquainted with Filters  @subsection Getting Acquainted with Filters
40    
41  Suppose we wish to implement an authentication method based on  Suppose we wish to implement an authentication method based on the
42  user name and user's calling station @acronym{ID}. We have a  user name and the user's calling station @acronym{ID}. We have a
43  database of usernames with valid @acronym{ID}s and the new  database of user names with valid @acronym{ID}s, and the new
44  method should authenticate a user only if the combination  method should authenticate a user only if the combination
45  @code{user_name,id} is found in this database.  @{@var{user_name}, @var{id}@} is found in this database.
46    
47  We write a filter program that reads its standard input line by line.  We write a filter program that reads its standard input line by line.
48  Each input line must consist of exactly two words: the user name  Each input line must consist of exactly two words: the user name
49  and the calling station @acronym{ID}. For each input line, the  and the calling station @acronym{ID}. For each input line, the
50  program prints @code{0} if the @code{user_name,id} is found in the  program prints @code{0} if the @{@var{user_name}, @var{id}@} is found in the
51  database and @code{1} otherwise. Let's suppose for the example purposes  database and @code{1} otherwise. Let's suppose for the sake of example
52  that the database is a plaintext file and the filter is written in  that the database is a plaintext file and the filter is written in
53  Shell program language. Then, it will look like:  a shell programming language. Then it will look like
54    
55  @example  @example
56  #! /bin/sh  #! /bin/sh
# Line 70  done Line 70  done
70  @node Declaring the Filter  @node Declaring the Filter
71  @subsection Declaring the Filter  @subsection Declaring the Filter
72    
73  Here is how this filter is declared in @file{raddb/config} file:  Here is how this filter is declared in the @file{raddb/config} file:
74    
75  @example  @example
76  filters @{  filters @{
# Line 78  filters @{ Line 78  filters @{
78          exec-path "/usr/libexec/myfilter";          exec-path "/usr/libexec/myfilter";
79          error-log "myfilter.log";          error-log "myfilter.log";
80          auth @{          auth @{
81              input-format "%C@{User-Name@} %C@{Calling-Station-Id@}";              input-format "%C@{User-Name@}
82                %C@{Calling-Station-Id@}";
83              wait-reply yes;              wait-reply yes;
84          @};          @};
85      @};              @};        
86  @};                          @};                        
87  @end example      @end example    
88    
89  Let's analyze this declaration line by line.  Let's analyze this declaration line by line:
90    
91  @enumerate  @enumerate
92  @item filters @{  @item @code{filters @{}
93    
94  This keyword opens the filters declaration block. The block may  This keyword opens the filters declaration block. The block may
95  contain several declarations.  contain several declarations.
96    
97  @item filter check_clid @{  @item @code{filter check_clid @{}
98    
99  This line starts the declaration of this particular filter and names it  This line starts the declaration of this particular filter and names it
100  @samp{check_clid}.  @samp{check_clid}.
101    
102  @item exec-path "/usr/libexec/myfilter";  @item @code{exec-path "/usr/libexec/myfilter";}
103    
104  This line tells @command{radiusd} where to find the executable image of  This line tells @command{radiusd} where to find the executable image of
105  this filter.  this filter.
106    
107  @item error-log "myfilter.log";  @item @code{error-log "myfilter.log";}
108    
109  The diagnostic output from this filter must be redirected to the file  The diagnostic output from this filter must be redirected to the file
110  @file{myfilter.log} in the current logging directory  @file{myfilter.log} in the current logging directory
111    
112  @item auth @{  @item @code{auth @{}
113    
114  This filter will process authentication requests  This filter will process authentication requests.
115    
116  @item input-format "%C@{User-Name@} %C@{Calling-Station-Id@}";  @item @code{input-format "%C@{User-Name@} %C@{Calling-Station-Id@}";}
117    
118  Define the input line format for this filter. The %C@{@} notations  Define the input line format for this filter. The %C@{@} expressions
119  will be substituted by the values of corresponding attributes from  will be replaced by the values of the corresponding attributes from
120  the incoming request (@pxref{Macro Substitution}).  the incoming request (@pxref{Macro Substitution}).
121    
122  @item wait-reply yes;  @item @code{wait-reply yes;}
123    
124  Radiusd shall wait for the reply from this filter to decide whether to  @code{radiusd} will wait for the reply from this filter to decide whether to
125  authenticate the user.  authenticate the user.
126  @end enumerate  @end enumerate
127                                    
# Line 153  do Line 154  do
154      if grep "$1:$2" $DB; then      if grep "$1:$2" $DB; then
155          echo "0 Service-Type = Login, Session-Timeout = 1200"          echo "0 Service-Type = Login, Session-Timeout = 1200"
156      else      else
157          echo "1 Reply-Message = \"You are not authorized to log in\""          echo "1 Reply-Message =
158                  \"You are not authorized to log in\""
159      fi      fi
160  done  done
161  @end example  @end example
# Line 163  done Line 165  done
165    
166  Let's suppose we further modify our filter to also handle  Let's suppose we further modify our filter to also handle
167  accounting requests. To discern between the authentication and  accounting requests. To discern between the authentication and
168  accounting request we'll prefix each authentication request  accounting requests we'll prefix each authentication request
169  with the word @samp{auth} and each accounting request with  with the word @samp{auth} and each accounting request with
170  the word @samp{acct}. Furthermore, the input line for accounting  the word @samp{acct}. Furthermore, the input line for accounting
171  requests will also contain timestamp.  requests will contain a timestamp.
172    
173  Now, our filter program will look as follows:  Now, our filter program will look as follows:
174    
# Line 181  do Line 183  do
183      case CODE      case CODE
184      auth)      auth)
185          if grep "$1:$2" $DB; then          if grep "$1:$2" $DB; then
186              echo "0 Service-Type = Login, Session-Timeout = 1200"              echo "0 Service-Type = Login, \
187                      Session-Timeout = 1200"
188          else          else
189              echo "1 Reply-Message = \"You are not authorized to log in\""              echo "1 Reply-Message = \
190                      \"You are not authorized to log in\""
191          fi          fi
192      acct)      acct)
193          echo "$CODE $NAME $CLID $DATE" >> $ACCT_DB          echo "$CODE $NAME $CLID $DATE" >> $ACCT_DB
# Line 197  filter check_clid @{ Line 201  filter check_clid @{
201      exec-path "/usr/libexec/myfilter";      exec-path "/usr/libexec/myfilter";
202      error-log "myfilter.log";      error-log "myfilter.log";
203      auth @{      auth @{
204          input-format "auth %C@{User-Name@} %C@{Calling-Station-Id@}";          input-format "auth %C@{User-Name@}
205                          %C@{Calling-Station-Id@}";
206          wait-reply yes;          wait-reply yes;
207      @};      @};
208      acct @{      acct @{
209          input-format "acct %C@{User-Name@} %C@{Calling-Station-Id@} %D";          input-format "acct %C@{User-Name@}
210                          %C@{Calling-Station-Id@} %D";
211          wait-reply no;          wait-reply no;
212      @};      @};
213  @};          @};        
214  @end example  @end example
215    
216  @noindent  @noindent
217    (The @code{input-format} lines are split for readability. Each of them
218    is actually one line).
219    
220  @emph{Notice} @code{wait-reply no} in the @code{acct} statement. It  @emph{Notice} @code{wait-reply no} in the @code{acct} statement. It
221  tells @command{radiusd} that it shouldn't wait for the response on  tells @command{radiusd} that it shouldn't wait for the response on
222  accounting requests from the filter.  accounting requests from the filter.
223    
224  @node Invoking Accounting Filter  @node Invoking Accounting Filter
225  @subsection Invoking Accounting Filter  @subsection Invoking the Accounting Filter
226    
227  To invoke the accounting filter, specify its name prefixed with a  To invoke the accounting filter, specify its name prefixed with a
228  vertical bar character as a value of @attr{Acct-Ext-Program} in our  vertical bar character as a value of @attr{Acct-Ext-Program} in our
# Line 230  DEFAULT NULL Line 239  DEFAULT NULL
239  @cindex Rewrite  @cindex Rewrite
240    
241  Rewrite is the GNU Radius extension language. Its name reflects the  Rewrite is the GNU Radius extension language. Its name reflects the
242  fact that it was originally designed to rewrite the broken request packets,  fact that it was originally designed to rewrite the broken request packets
243  so they could be processed as usual (@pxref{Rewriting Incoming  so they could be processed as usual (@pxref{Rewriting Incoming
244  Requests}). Beside this basic use, however, Rewrite functions are used  Requests}). Beside this basic use, however, Rewrite functions are used
245  in verifying the activity of user sessions  in verifying the activity of user sessions
# Line 252  in verifying the activity of user sessio Line 261  in verifying the activity of user sessio
261  @subsection Syntax Overview  @subsection Syntax Overview
262  @cindex Rewrite, syntax overview  @cindex Rewrite, syntax overview
263    
264  Rewrite syntax resembles that of C. Rewrite has two basic data types:  The syntax of Rewrite resembles that of C. Rewrite has two basic data types:
265  integer and string. It does not have global variables, all variables are  integer and string. It does not have global variables; all variables are
266  automatic. The only exception are the @AVP{}s from the incoming request,  automatic. The only exceptions are the @AVP{}s from the incoming request,
267  which are accessible to Rewrite functions via special notation  which are accessible to Rewrite functions via the special notation
268  @code{%[@var{attr}]}.  @code{%[@var{attr}]}.
269    
270  @comment *L2****************************************************************  @comment *L2****************************************************************
# Line 280  foo(integer i) Line 289  foo(integer i)
289  @end group  @end group
290  @end example  @end example
291    
292  The function takes an integer argument and returns string  @noindent
293  ``the number is odd'' or ``the number is even'', depending on the  The function takes an integer argument and returns the string
294  value of @var{i}. This illustrates the fact that in Rewrite the  @samp{the number is odd} or @samp{the number is even}, depending on the
295    value of @code{i}. This illustrates the fact that in Rewrite the
296  addition operator is defined on the string type. The result of  addition operator is defined on the string type. The result of
297  such operation is the concatenation of operands.  such operation is the concatenation of operands.
298    
# Line 300  px_add() Line 310  px_add()
310  @end group  @end group
311  @end example  @end example
312    
313  The function manipulates the contents of the incoming request, its  @noindent
314    This function manipulates the contents of the incoming request; its
315  return value has no special meaning.  return value has no special meaning.
316    
317    
# Line 316  purpose. There are three major kinds of Line 327  purpose. There are three major kinds of
327  @itemize @bullet  @itemize @bullet
328  @item Functions used to rewrite the incoming requests.  @item Functions used to rewrite the incoming requests.
329  @item Functions designed for simultaneous login verification.  @item Functions designed for simultaneous login verification.
330  @item Functions used to generate @sc{radius} attribute values.  @item Functions used to generate Radius attribute values.
331  @end itemize  @end itemize
332    
333  @comment *L3****************************************************************  @comment *L3****************************************************************
# Line 324  purpose. There are three major kinds of Line 335  purpose. There are three major kinds of
335  @subsection Rewriting Incoming Requests  @subsection Rewriting Incoming Requests
336  @cindex Rewriting incoming requests  @cindex Rewriting incoming requests
337    
338  The need of rewriting the incoming requests arises from the fact that  The need for rewriting the incoming requests arises from the fact that
339  some @NAS{}es are very particular about the information they send with  some @NAS{}es are very particular about the information they send with
340  the requests. There are cases when the information they send  the requests. There are cases when the information they send
341  is hardly usable or even just unusable. For example, a  is hardly usable or even completely unusable. For example, a
342  Cisco @sc{as5300} terminal server used as a voice over @sc{ip} router packs  Cisco @sc{as5300} terminal server used as a voice-over IP router packs
343  a lot of information into its @attr{Acct-Session-Id} attribute. Though  a lot of information into its @attr{Acct-Session-Id} attribute. Though
344  the information stored there is otherwise relevant, it makes proper  the information stored there is otherwise relevant, it makes proper
345  accounting impossible since the @attr{Acct-Session-Id} attributes  accounting impossible, since the @attr{Acct-Session-Id} attributes
346  in the start and stop packets of the same session become different, and  in the start and stop packets of the same session become different, and
347  thus Radius cannot determine the @dfn{Session Start} to which the given  thus Radius cannot determine the session start to which the given
348  @dfn{Session Stop} request corresponds (@pxref{Acct-Session-Id}).  session stop request corresponds (@pxref{Acct-Session-Id}).
349    
350  In order to cope with such @NAS{}es, GNU Radius is able to invoke  In order to cope with such @NAS{}es, GNU Radius is able to invoke
351  a Rewrite function upon arrival of the packet and before further  a Rewrite function upon arrival of the packet and before
352  processing it. This function can transform the packet so, that  processing it further. This function can transform the packet so that
353  it obtains the form prescribed by @sc{rfc}s and its further processing  it obtains the form prescribed by @sc{rfc}s and its further processing
354  becomes possible.  becomes possible.
355    
356  For example, in the case of @sc{as5300} router, a corresponding rewrite  For example, in the case of the @sc{as5300} router, a corresponding Rewrite
357  function parses the @attr{Acct-Session-Id} attribute, breaks it  function parses the @attr{Acct-Session-Id} attribute; breaks it
358  down into fields, stores them into proper attributes, creating  down into fields; stores them into proper attributes, creating
359  them if necessary, and, finally replaces @attr{Acct-Session-Id} with  them if necessary; and finally replaces @attr{Acct-Session-Id} with
360  its real value, which is the same for start and stop records  its real value, which is the same for the start and stop records
361  corresponding to a single session. Thus all the information that  corresponding to a single session. Thus all the information that
362  came with the packet is preserved, but the packet itself is made  came with the packet is preserved, but the packet itself is made
363  usable for proper accounting.  usable for proper accounting.
# Line 371  DEFAULT  NAS-IP-Address = 11.10.10.11 Line 382  DEFAULT  NAS-IP-Address = 11.10.10.11
382  The @attr{Rewrite-Function} attribute may also be used in a @file{hints}  The @attr{Rewrite-Function} attribute may also be used in a @file{hints}
383  rule. In this case, it will invoke the function if the request matches  rule. In this case, it will invoke the function if the request matches
384  the rule (@pxref{Hints}). For example, this @file{hints} rule will  the rule (@pxref{Hints}). For example, this @file{hints} rule will
385  cause the function to be invoked for each request containing the username  cause the function to be invoked for each request containing the user name
386  starting with @samp{P}:  starting with @samp{P}:
387    
388  @example  @example
# Line 381  DEFAULT  Prefix = "P" Line 392  DEFAULT  Prefix = "P"
392  @end group  @end group
393  @end example  @end example
394    
395  @emph{Note}, that in both cases the attribute can be used  @noindent
396    Note that in both cases the attribute can be used
397  either in @LHS{} or in @RHS{} pairs of a rule.  either in @LHS{} or in @RHS{} pairs of a rule.
398    
399  The packet rewrite function must be declared as having no arguments,  The packet rewrite function must be declared as having no arguments
400  and returning integer value:  and returning an integer value:
401    
402  @example  @example
403  @group  @group
# Line 395  integer fixup() Line 407  integer fixup()
407  @end group  @end group
408  @end example  @end example
409    
410    @noindent
411  The actual return value from such a function is ignored, the integer  The actual return value from such a function is ignored, the integer
412  return type is just a matter of convention.  return type is just a matter of convention.
413    
414  The following subsection present some examples of packet rewriting  The following subsection present some examples of packet rewrite
415  functions.  functions.
416    
417  @menu  @menu
# Line 407  functions. Line 420  functions.
420    
421  @comment **L3***************************************************************  @comment **L3***************************************************************
422  @node Rewrite Examples  @node Rewrite Examples
423  @subsubsection Examples of Various Rewrite Functions.  @subsubsection Examples of Various Rewrite Functions
424  @exindex Rewrite functions  @exindex Rewrite functions
425    
426  The examples found in this chapter are working functions that can be  The examples found in this chapter are working functions that can be
427  used with various existing @NAS{} types. They are taken from the  used with various existing @NAS{} types. They are taken from the
428  @file{rewrite} file contained in distribution of GNU Radius.  @file{rewrite} file contained in distribution of GNU Radius.
429    
430  @subheading 1. Port rewriting for MAX Ascend terminal servers  @subheading 1. Port rewriting for @sc{max a}scend terminal servers
431    
432  Some @sc{max a}scend terminal servers pack additional information  Some @sc{max a}scend terminal servers pack additional information
433  into @attr{NAS-Port-Id} attribute. The port number is constructed as  into the @attr{NAS-Port-Id} attribute. The port number is constructed as
434  XYYZZ, where X = 1 for digital, X = 2 for analog, YY is line number  @var{XYYZZ}, where @var{X} = 1 for digital, @var{X} = 2 for analog,
435  (1 for first PRI/T1/E1, 2 for second, so on), and ZZ = channel number  @var{YY} is the line number
436  (on the PRI or Channelized T1/E1).  (1 for first PRI/T1/E1, 2 for second, and so on), and @var{ZZ} is the
437    channel number
438    (on the PRI or channelized T1/E1).
439    
440  The following rewrite functions are intended to compute the integer  The following rewrite functions are intended to compute the integer
441  port number in the range (1 .. @var{portcnt}), where @var{portcnt}  port number in the range (1 .. @var{portcnt}), where @var{portcnt}
442  represents the real number of physical ports available on the @NAS{}.  represents the real number of physical ports available on the @NAS{}.
443  Such port number can be used, for example, with  Such a port number can be used, for example, with the
444  @attr{Add-Port-To-IP-Address} attribute (@pxref{Add-Port-To-IP-Address}).  @attr{Add-Port-To-IP-Address} attribute (@pxref{Add-Port-To-IP-Address}):
445    
446  @example  @example
447  @group  @group
# Line 453  max_decode_port(integer P, integer portc Line 468  max_decode_port(integer P, integer portc
468  @group  @group
469  /*  /*
470   * Interface function for MAX terminal server with 23 ports.   * Interface function for MAX terminal server with 23 ports.
471   * Note that it saves the received NAS-Port-Id attribute in the   * Note that it saves the received NAS-Port-Id attribute in
472   * Orig-NAS-Port-Id attribute. The latter must be defined somewhere   * the Orig-NAS-Port-Id attribute. The latter must be
473   * in the dictionary   * defined somewhere in the dictionary
474   */   */
475  integer  integer
476  max_fixup()  max_fixup()
477  @{  @{
478      %[Orig-NAS-Port-Id] = %[NAS-Port-Id]; # Preserve original data      %[Orig-NAS-Port-Id] = %[NAS-Port-Id];
479                                      # Preserve original data
480      %[NAS-Port-Id] = max_decode_port(%[NAS-Port-Id], 23);      %[NAS-Port-Id] = max_decode_port(%[NAS-Port-Id], 23);
481      return 0;      return 0;
482  @}  @}
483  @end group  @end group
484  @end example  @end example
485    
486  @subheading 2. Session ID parsing for Cisco AS 5300 series  @subheading 2. Session @sc{id} parsing for Cisco AS 5300 series
487    
488  Cisco @sc{voip ios} encodes a lot of other information into its  Cisco @sc{voip ios} encodes a lot of other information into its
489  @attr{Acct-Session-Id}. The pieces of information are separated by  @attr{Acct-Session-Id}. The pieces of information are separated by
490  @samp{/} character. The part of @attr{Acct-Session-Id} up to first  @samp{/} characters. The part of @attr{Acct-Session-Id} up to the first
491  @samp{/} character is the actual session @sc{id}.  @samp{/} character is the actual session @sc{id}.
492    
493  On the other hand, its accounting packets lack @attr{NAS-Port-Id},  On the other hand, its accounting packets lack @attr{NAS-Port-Id},
494  though they may contain the vendor-specific pair with code 2  though they may contain the vendor-specific pair with code 2
495  (vendor @sc{pec} 9), which is the string in the form @samp{ISDN 9:D:999}  (vendor @sc{pec} 9), which is a string in the form @samp{ISDN 9:D:999}
496  (@samp{9} represents a decimal digit). The number after the last  (@samp{9} represents any decimal digit). The number after the last
497  @samp{:} character can be used as a port number.  @samp{:} character can be used as a port number.
498    
499  The following code parses @attr{Acct-Session-Id} attribute and stores  The following code parses @attr{Acct-Session-Id} attribute and stores
500  the information it contains in various other attributes, generates  the information it contains in various other attributes, generates a
501  normal @attr{Acct-Session-Id} and attempts to generate  normal @attr{Acct-Session-Id}, and attempts to generate a
502  @attr{NAS-Port-Id} attribute.  @attr{NAS-Port-Id} attribute.
503    
504  @example  @example
505  @group  @group
506  /*  /*
507   * The port rewriting function for Cisco AS5300 used for VoIP.   * The port rewriting function for Cisco AS5300 used for
508   * This function is used to generate NAS-Port-Id pair on the basis   * VoIP. This function is used to generate NAS-Port-Id pair
509   * of vendor-specific pair 2. If the latter is in the form   * on the basis of vendor-specific pair 2. If the latter is
510   * "ISDN 9:D:999" (where each 9 represents a decimal digit), then   * in the form "ISDN 9:D:999" (where each 9 represents a
511   * the function returns the number after the last colon. This is   * decimal digit), then the function returns the number
512   * used as a port number.   * after the last colon. This is used as a port number.
513   */   */
514  integer  integer
515  cisco_pid(string A)  cisco_pid(string A)
516  @{  @{
517      if (A =~      if (A =~
518          ".*\([0-9][0-9]*\):[A-Z0-9][A-Z0-9]*:\([0-9][0-9]*\)") @{          ".*\([0-9][0-9]*\):
519             [A-Z0-9][A-Z0-9]*:\([0-9][0-9]*\)") @{
520          return (integer)\2;          return (integer)\2;
521      @}      @}
522      return -1;      return -1;
# Line 509  cisco_pid(string A) Line 526  cisco_pid(string A)
526  @group  @group
527  /*  /*
528   * This function parses the packed session id.   * This function parses the packed session id.
529   * The actual sid is the number before the first slash character.   * The actual sid is the number before the first slash
530   * Other possibly relevant fields are also parsed out and saved   * character.  Other possibly relevant fields are also
531   * in the Voip-* A/V pairs. The latter should be defined somewhere   * parsed out and saved in the Voip-* A/V pairs. The latter
532   * in the dictionary.   * should be defined somewhere in the dictionary.
533   * Note, that the regular expression in this example   * Note that the regular expression in this example
534   * spans several lines for readability. It should be on one   * spans several lines for readability. It should be on one
535   * line in real file.   * line in real file.
536   */   */
# Line 559  cisco_fixup() Line 576  cisco_fixup()
576  @end group  @end group
577  @end example  @end example
578    
579  @subheading 3. Username rewriting for NT machines.  @subheading 3. User-name rewriting for @sc{nt} machines
580    
581  Users coming from Windows @sc{nt} machines often authenticate themselves as  Users coming from Windows @sc{nt} machines often authenticate themselves as
582  @samp{NT_DOMAIN\username}. The following function selects the username part  @samp{NT_DOMAIN\@var{username}}. The following function selects the
583  and stores it in the @attr{User-Name} attribute:  user-name part and stores it in the @attr{User-Name} attribute:
584    
585  @example  @example
586  @group  @group
# Line 595  nt_rewrite() Line 612  nt_rewrite()
612  A login verification function is invoked to process the output from the  A login verification function is invoked to process the output from the
613  @NAS{}. This process is described in @ref{Checking Simultaneous Logins}.  @NAS{}. This process is described in @ref{Checking Simultaneous Logins}.
614  The function to be invoked for given @NAS{} is defined by  The function to be invoked for given @NAS{} is defined by
615  @code{function} flag in @file{raddb/nastypes} or @file{raddb/naslist}  a @code{function} flag in the @file{raddb/nastypes} or @file{raddb/naslist}
616  files (@pxref{nastypes file}). It must be defined as follows:  file (@pxref{nastypes file}). It must be defined as follows:
617    
618  @example  @example
619  @group  @group
620  integer check(string str, string name, integer pid, string sid)  integer check(string @var{str}, string @var{name}, integer @var{pid},
621                  string @var{sid})
622  @{  @{
623  @}  @}
624  @end group  @end group
# Line 613  Its arguments are: Line 631  Its arguments are:
631  @item str  @item str
632  Input string. If the query method is @code{finger}, this is the string  Input string. If the query method is @code{finger}, this is the string
633  of output received from the @NAS{} with trailing newline stripped off. If  of output received from the @NAS{} with trailing newline stripped off. If
634  the query method is @code{snmp}, this is the received variable value  the query method is @code{snmp}, it is the received variable value
635  converted to its string representation.  converted to its string representation.
636  @item name  @item name
637  User name.  User name.
638  @item pid  @item pid
639  Port Id of the session.  Port @sc{id} of the session.
640  @item sid  @item sid
641  Session @sc{id}.  Session @sc{id}.
642  @end table  @end table
643    
644  The function should return non-0 if its arguments match user's  The function should return non-0 if its arguments match the user's
645  session and 0 otherwise.  session, and 0 otherwise.
646    
647  @menu  @menu
648  * Example: Examples of login verification functions.  * Example: Examples of Login Verification Functions
649  @end menu  @end menu
650    
651  @comment **L4*************************************************************  @comment **L4*************************************************************
652  @node Examples of login verification functions  @node Examples of Login Verification Functions
653  @subsubsection Examples of login verification functions  @subsubsection Examples of Login Verification Functions
654  @exindex Login verification functions  @exindex Login verification functions
655    
656  @exindex Checking UNIX finger output  @exindex Checking UNIX @code{finger} output
657  As an example, let's consider the function for analyzing a line  As an example, let's consider the function for analyzing a
658  line of output from a standard @acronym{UNIX} finger service. In each line  line of output from a standard @acronym{UNIX} @code{finger}
659  of finger output the first field contains username, the third field ---  service. In each line
660  tty number (Port @sc{id}), and the seventh field contains session @sc{id}.  of @code{finger} output the first field contains the user name; the
661    third field, the
662    @c{tty} number (port @sc{id}); and the seventh field, the session @sc{id}.
663  The function must return 1 if the three fields match the input  The function must return 1 if the three fields match the input
664  user name, port and session @sc{id}s.  user name and port and session @sc{id}s:
665    
666  @example  @example
667  integer  integer
# Line 656  check_unix(string str, string name, inte Line 676  check_unix(string str, string name, inte
676  @c @xref{UNIX Finger}.  @c @xref{UNIX Finger}.
677    
678  @exindex Analyzing SNMP output  @exindex Analyzing SNMP output
679  Next example is a function to analyze a line of output from an @acronym{SNMP}  The next example is a function to analyze a line of output from an SNMP
680  query returning a user name. This function must return 1 if entire input  query returning a user name. This function must return 1 if the entire input
681  line matches the user name.  line matches the user name:
682    
683  @example  @example
684  integer  integer
# Line 673  check_username(string str, string name, Line 693  check_username(string str, string name,
693  @subsection Attribute Creation Functions  @subsection Attribute Creation Functions
694  @cindex Rewrite, attribute creation functions  @cindex Rewrite, attribute creation functions
695    
696  These are the functions, used to create @RADIUS{} reply attributes. An  These are the functions used to create Radius reply attributes. An
697  attribute creation function can take any number of arguments. The type  attribute creation function can take any number of arguments. The type
698  of its return is determined by the type of @RADIUS{} attribute the  of its return is determined by the type of Radius attribute the
699  value will be assigned to. To invoke the function, write its name  value will be assigned to. To invoke the function, write its name
700  in the @AVP{} of @RHS{} in @file{raddb/users} file, e.g.:  in the @AVP{} of the @RHS{} in the @file{raddb/users} file, e.g.:
701    
702  @example  @example
703  @group  @group
704  DEFAULT Auth-Type = SQL  DEFAULT Auth-Type = SQL
705          Service-Type = Framed-User,          Service-Type = Framed-User,
706                  Framed-IP-Address = "=get_ip_addr(10.10.10.1)"              Framed-IP-Address = "=get_ip_addr(10.10.10.1)"
707  @end group  @end group
708  @end example  @end example
709    
710  @noindent  @noindent
711  The function @code{get_ip_addr} will be invoked after successful  The function @code{get_ip_addr} will be invoked after successful
712  authentication and it will be passed @IP{} @code{10.10.10.1} as its  authentication and it will be passed the IP @code{10.10.10.1} as its
713  argument. An example of a useful function, that can be invoked this  argument. An example of a useful function that can be invoked this
714  way:  way is
715    
716  @example  @example
717  @group  @group
# Line 727  get_ip_address(integer base) Line 747  get_ip_address(integer base)
747  There are only two data types: @code{integer} and @code{string},  There are only two data types: @code{integer} and @code{string},
748  the two being coercible to each other in the sense that a string  the two being coercible to each other in the sense that a string
749  can be coerced to an integer if it contains a valid @sc{ascii} representation  can be coerced to an integer if it contains a valid @sc{ascii} representation
750  of a decimal, octal or hex number, and the integer can always be coerced  of a decimal, octal, or hex number, and an integer can always be coerced
751  to a string, the result of such coercion being the @sc{ascii} string with  to a string, the result of such coercion being the @sc{ascii} string
752    that is the
753  decimal representation of the number.  decimal representation of the number.
754    
755  @comment **L4***************************************************************  @comment **L4***************************************************************
# Line 737  decimal representation of the number. Line 758  decimal representation of the number.
758  @cindex Symbols, Rewrite  @cindex Symbols, Rewrite
759  @cindex Rewrite, symbols  @cindex Rewrite, symbols
760    
761  A symbol is a lexical token. The following symbols are recognized:  A @dfn{symbol} is a lexical token. The following symbols are recognized:
762    
763  @table @asis  @table @asis
764  @item Arithmetical operators  @item Arithmetical operators
765  These are @samp{+}, @samp{-}, @samp{*}, @samp{/} representing the basic  These are @samp{+}, @samp{-}, @samp{*}, @samp{/} representing the basic
766  arithmetical operations and @samp{%} meaning remainder.  arithmetical operations, and @samp{%} meaning remainder.
767  @item Comparison operators  @item Comparison operators
768  These are: @samp{==}, @samp{!=}, @samp{<}, @samp{<=}, @samp{>},  These are: @samp{==}, @samp{!=}, @samp{<}, @samp{<=}, @samp{>},
769  @samp{>=} with the same meaning they have in C. Special operators  @samp{>=} with the same meaning they have in C. Special operators
770  are provided for regular expression matching. Binary  are provided for regular-expression matching. The binary
771  operator @samp{=~} returns true, if its left-hand-side operand  operator @samp{=~} returns true if its left-hand-side operand
772  matches the regular expression on its right-hand side. @samp{!~}  matches the regular expression on its right-hand side. @samp{!~}
773  returns true if the left-hand side operand @emph{does not match}  returns true if its left-hand-side operand does @emph{not} match
774  the regexp on right-hand side. The right-hand side operand of  the regexp on its right-hand side. The right-hand-side operand of
775  @samp{!~} or @samp{=~} must be a literal string, i.e. the regular  @samp{!~} or @samp{=~} must be a literal string, i.e., the regular
776  expression must be known at compile time.  expression must be known at compile time.
777  @item Unary operators.  @item Unary operators
778  Unary operators are @samp{-} and @samp{+} for unary plus and minus,  The unary operators are @samp{-} and @samp{+} for unary plus and minus,
779  @samp{!} for boolean negation and @samp{*} for testing for the  @samp{!} for boolean negation, and @samp{*} for testing for the
780  existence of an attribute.  existence of an attribute.
781  @item Boolean operators.  @item Boolean operators
782  These are: @samp{&&} and @samp{||}.  These are @samp{&&} and @samp{||}.
783  @item Parentheses @samp{(} and @samp{)}  @item Parentheses @samp{(} and @samp{)}
784  These are used to change the precedence of operators, to introduce  These are used to change the precedence of operators, to introduce
785  type casts (type coercions), to declare functions and to pass actual  type casts (type coercions), to declare functions, and to pass actual
786  arguments to functions.  arguments to functions.
787  @item Curly braces (@samp{@{} and @samp{@}})  @item Curly braces (@samp{@{} and @samp{@}})
788  These are used to delimit blocks of code.  These are used to delimit blocks of code.
789  @item Numbers  @item Numbers
790  Numbers follow usual C convention for integers. A number consisting of  Numbers follow the usual C convention for integers. A number consisting of
791  a sequence of digits, is taken to be octal if it begins with @samp{0}  a sequence of digits is taken to be octal if it begins with @samp{0}
792  (digit zero) and decimal otherwise. If the sequence of digits is  (digit zero), and decimal otherwise. If the sequence of digits is
793  preceded by @samp{0x} or @samp{0X}, it is taken to be a hexadecimal  preceded by @samp{0x} or @samp{0X}, it is taken to be a hexadecimal
794  integer.  integer.
795  @item Characters  @item Characters
796  These follow usual C convention for characters, i.e. either  These follow the usual C convention for characters, i.e., they consist
797  an @sc{ascii} character or its value enclosed in a pair of single  either of
798  quotes. The character value begins with @samp{\} (backslash) and  an @sc{ascii} character itself or of its value, enclosed in a pair of
799    singlequotes.
800    The character value begins with @samp{\} (backslash) and
801  consists either of three octal or of two hexadecimal digits.  consists either of three octal or of two hexadecimal digits.
802  A character does not form a special data type, it is represented  A character does not form a special data type; it is represented
803  internally by an integer.  internally by an integer.
804  @item Quoted strings  @item Quoted strings
805  These follow usual C conventions for strings.  These follow usual C conventions for strings.
806  @item Attribute values  @item Attribute values
807  The incoming request is passed implicitly to functions, invoked via  The incoming request is passed implicitly to functions invoked via the
808  @attr{Rewrite-Function} attribute. It is kept as an associative array,  @attr{Rewrite-Function} attribute. It is kept as an associative array,
809  whose entries can be accessed using the following syntax:  whose entries can be accessed using the following syntax:
810    
# Line 791  whose entries can be accessed using the Line 814  whose entries can be accessed using the
814  @end example  @end example
815    
816  @noindent  @noindent
817  The first notation returns the value of the attribute @var{attribute-name}.  The first form returns the value of the attribute @var{attribute-name}.
818  @var{attribute-name} should be a valid Radius dictionary name  Here @var{attribute-name} should be a valid Radius dictionary name
819  (@pxref{dictionary file}).  (@pxref{dictionary file}).
820    
821  The second notation returns the value of the @var{n}th attribute of type  The second form returns the value of the @var{n}th attribute of type
822  @var{attribute-name} . Index @var{n} is counted from zero, so  @var{attribute-name}. The index @var{n} is counted from zero, so
823    
824  @example  @example
825          %[@var{attribute-name}](0)          %[@var{attribute-name}](0)
# Line 811  is equivalent to Line 834  is equivalent to
834    
835  @item Identifiers  @item Identifiers
836  Identifiers represent functions and variables. These are described in  Identifiers represent functions and variables. These are described in
837  the next section.  the next sub-subsection.
838  @item Regexp group references  @item Regexp group references
839  A sequence of characters in the form:  A sequence of characters in the form
840    
841  @example  @example
842  @samp{\@var{number}}  @samp{\@var{number}}
# Line 823  A sequence of characters in the form: Line 846  A sequence of characters in the form:
846    
847  refers to the contents of parenthesized group number @var{number}  refers to the contents of parenthesized group number @var{number}
848  obtained as a result of the last executed @samp{=~} command.  obtained as a result of the last executed @samp{=~} command.
849  The regexp group reference has always string data type. E.g.  The regexp group reference has always string data type. For example:
850    
851  @example  @example
852  @group  @group
853  string  string
854  basename(string arg)  basename(string @var{arg})
855  @{  @{
856      if (arg =~ ".*/\(.*\)\..*")      if (arg =~ ".*/\(.*\)\..*")
857          return \1;          return \1;
# Line 840  basename(string arg) Line 863  basename(string arg)
863    
864  This function strips from @var{arg} all leading components up to the  This function strips from @var{arg} all leading components up to the
865  last slash character, and all trailing components after the last dot  last slash character, and all trailing components after the last dot
866  character. It returns @var{arg} unaltered, if it does not contain  character. It returns @var{arg} unaltered if it does not contain
867  slashes and dots. Roughly, it is analogous to the system @code{basename}  slashes and dots. It is roughly analogous to the system @code{basename}
868  utility.  utility.
869  @end table  @end table
870    
# Line 855  A valid identifier is a string of charac Line 878  A valid identifier is a string of charac
878  requirements:  requirements:
879    
880  @enumerate 1  @enumerate 1
881  @item It starts with either a lower- or uppercase letter of the Latin  @item It starts with either a lower- or an uppercase letter of the Latin
882  alphabet or any of the following symbols: @samp{_}, @samp{$}.  alphabet or either of the following symbols: @samp{_}, @samp{$}.
883  @item It consists of alphanumeric characters, underscores(@samp{_}) and  @item It consists of alphanumeric characters, underscores(@samp{_}), and
884  dollar signs (@samp{$}).  dollar signs (@samp{$}).
885  @end enumerate  @end enumerate
886    
# Line 869  dollar signs (@samp{$}). Line 892  dollar signs (@samp{$}).
892    
893  @subheading Function declarations  @subheading Function declarations
894    
895  The Rewrite function is declared as follows:  A Rewrite function is declared as follows:
896    
897  @example  @example
898  @var{type} @var{function-name} (@var{parameter-list})  @var{type} @var{function-name} (@var{parameter-list})
# Line 877  The Rewrite function is declared as foll Line 900  The Rewrite function is declared as foll
900    
901  @noindent  @noindent
902  where @var{type} specifies the return type of the function,  where @var{type} specifies the return type of the function,
903  @var{function-name} declares the symbolic name of the function and  @var{function-name} declares the symbolic name of the function, and
904  @var{parameter-list} declares the formal parameters to the function.  @var{parameter-list} declares the formal parameters to the function.
905  It is a comma-separated list of declarations in the form:  It is a comma-separated list of declarations in the form
906    
907  @example  @example
908  @var{type} @var{parm-name}  @var{type} @var{parm-name}
# Line 895  be valid identifiers. Line 918  be valid identifiers.
918  There are no global variables in Rewrite. All variables are local.  There are no global variables in Rewrite. All variables are local.
919  The local variables are declared right after the opening curly brace  The local variables are declared right after the opening curly brace
920  (@samp{@{}) and before any executable statements. The declaration  (@samp{@{}) and before any executable statements. The declaration
921  syntax is:  syntax is
922    
923  @example  @example
924  @var{type} @var{ident_list} ;  @var{type} @var{ident_list} ;
925  @end example  @end example
926    
927  @noindent  @noindent
928  Here @var{ident_list} is either a valid Rewrite identifier, or a comma-  Here @var{ident_list} is either a valid Rewrite identifier or a
929  separated list of such identifiers. @emph{Note} that, unlike in  comma-separated list of such identifiers.
930    
931    Note that, unlike in
932  C, no assignments are allowed in variable declarations.  C, no assignments are allowed in variable declarations.
933    
934  @comment **L4***************************************************************  @comment **L4***************************************************************
# Line 912  C, no assignments are allowed in variabl Line 937  C, no assignments are allowed in variabl
937  @cindex Statements, Rewrite  @cindex Statements, Rewrite
938    
939  The Rewrite statements are: expressions, assignments, conditional  The Rewrite statements are: expressions, assignments, conditional
940  statements and return statements. A statement is terminated by semicolon.  statements, and return statements. A statement is terminated by a semicolon.
941    
942  @subheading Expressions  @subheading Expressions
943    
944  An @dfn{expression} is:  An @dfn{expression} is one of the following:
945    
946  @itemize @bullet  @itemize @bullet
947  @item A variable identifier  @item A variable identifier
# Line 936  The type coercion is like a type cast in Line 961  The type coercion is like a type cast in
961  @end example  @end example
962    
963  @noindent  @noindent
964  the result of type coercion is as follows:  The result of type coercion is as follows:
965    
966  @multitable @columnfractions .20 .20 .60  @multitable @columnfractions .20 .20 .60
967  @item @var{type} @tab Variable type @tab Resulting conversion  @item @var{type} @tab Variable type @tab Resulting conversion
# Line 948  the result of type coercion is as follow Line 973  the result of type coercion is as follow
973  @item integer  @item integer
974  @tab string  @tab string
975  @tab If the string value of the variable is a valid @sc{ascii} representation  @tab If the string value of the variable is a valid @sc{ascii} representation
976  of the integer number (either decimal, octal or hex) it is converted to  of the integer number (either decimal, octal, or hex), it is converted to
977  the integer, otherwise the result of the conversion is undefined.  the integer; otherwise the result of the conversion is undefined.
978    
979  @item string  @item string
980  @tab integer  @tab integer
# Line 962  the integer, otherwise the result of the Line 987  the integer, otherwise the result of the
987  @end multitable  @end multitable
988    
989  @subheading Assignment  @subheading Assignment
990  An assignment is:  An assignment is
991    
992  @example  @example
993  @var{ident} = @var{expression} ;  @var{ident} = @var{expression} ;
# Line 972  An assignment is: Line 997  An assignment is:
997  The variable @var{ident} is assigned the value of @var{expression}.  The variable @var{ident} is assigned the value of @var{expression}.
998    
999  @subheading Function calls  @subheading Function calls
1000  These take the form:  These take the form
1001    
1002  @example  @example
1003  @var{ident} ( @var{arg-list} )  @var{ident} ( @var{arg-list} )
1004  @end example  @end example
1005    
1006  @noindent  @noindent
1007  where @var{ident} is the identifier representing the function,  where @var{ident} is the identifier representing the function, and
1008  @var{arg-list} is a comma-separated list of expressions supplying  @var{arg-list} is a comma-separated list of expressions supplying
1009  actual arguments to the function. The function @var{ident}  actual arguments to the function. The function that @var{ident}
1010  references can be either a compiled function or a built-in  references can be either a compiled function or a built-in
1011  function.  function.
1012    
1013  @emph{Note} that, unlike in C, the mismatch between the  Note that, unlike in C, a mismatch between the
1014  number of actual arguments and number of formal parameters in the  number of actual arguments and number of formal parameters in the
1015  compiled function declaration is not an error but rather a warning.  compiled function declaration is not an error but rather a warning.
1016    
1017  @subheading Delete statement  @subheading @samp{delete} statement
1018    
1019  The @samp{delete} statement is used to delete an attribute or attributes  The @samp{delete} statement is used to delete an attribute or attributes
1020  from the incoming request. Its syntax is:  from the incoming request. Its syntax is:
# Line 1000  delete @var{attribute-name}(@var{n}); Line 1025  delete @var{attribute-name}(@var{n});
1025  @end example  @end example
1026    
1027  The first variant deletes @emph{all} the attributes of the given type.  The first variant deletes @emph{all} the attributes of the given type.
1028  The second variant deletes only @var{n}th occurrence of the matching  The second variant deletes only the @var{n}th occurrence of the matching
1029  attribute.  attribute.
1030    
1031  @comment **L4***************************************************************  @comment **L4***************************************************************
# Line 1011  attribute. Line 1036  attribute.
1036  The following built-in functions are provided:  The following built-in functions are provided:
1037    
1038  @deftypefn Function integer length (string @var{s})  @deftypefn Function integer length (string @var{s})
1039  Returns the length of string @var{s}.  Returns the length of the string @var{s}.
1040  @end deftypefn  @end deftypefn
1041    
1042  @deftypefn Function integer index (string @var{s}, integer @var{c})  @deftypefn Function integer index (string @var{s}, integer @var{c})
1043  Returns the index of the first occurrence of the character @var{c} in  Returns the index of the first occurrence of the character @var{c} in
1044  the string @var{s}. Returns -1 if no such occurrence is found.  the string @var{s}. Returns @minus{}1 if no such occurrence is found.
1045  @end deftypefn  @end deftypefn
1046    
1047  @deftypefn Function integer rindex (string @var{s}, integer @var{i})  @deftypefn Function integer rindex (string @var{s}, integer @var{i})
1048  Returns the index of the last occurrence of the character @var{c} in  Returns the index of the last occurrence of the character @var{c} in
1049  the string @var{s}. Returns -1 if no such occurrence is found.  the string @var{s}. Returns @minus{}1 if no such occurrence is found.
1050  @end deftypefn  @end deftypefn
1051    
1052  @deftypefn Function string substr (string @var{s}, integer @var{start}, integer @var{length})  @deftypefn Function string substr (string @var{s}, integer @var{start}, integer @var{length})
1053  Returns the at most @var{length} substring of @var{s} starting at  Returns the substring of @var{s} of length at most @var{length} starting at
1054  position @var{start}.  position @var{start}.
1055  @end deftypefn  @end deftypefn
1056    
# Line 1034  All character positions in strings are c Line 1059  All character positions in strings are c
1059  @deftypefn Function string field (string @var{buffer}, integer @var{n})  @deftypefn Function string field (string @var{buffer}, integer @var{n})
1060  This function regards the @var{buffer} argument as consisting of  This function regards the @var{buffer} argument as consisting of
1061  fields separated with any amount of whitespace. It extracts and  fields separated with any amount of whitespace. It extracts and
1062  returns the @var{n}th field. The @var{n} is counted from 1.  returns the @var{n}th field. @var{n} is counted from 1.
1063  @end deftypefn  @end deftypefn
1064    
1065  @deftypefn Function integer logit (string @var{msg})  @deftypefn Function integer logit (string @var{msg})
1066  Outputs its argument to the radius log channel @code{info}. Returns 0.  Outputs its argument to the Radius log channel @code{info}. Returns 0.
1067  The function is intended for debugging purposes.  For debugging purposes.
1068  @end deftypefn  @end deftypefn
1069    
1070  @deftypefn Function integer inet_aton (string @var{str})  @deftypefn Function integer inet_aton (string @var{str})
1071  @command{inet_aton()} converts the Internet host address @var{str} from the  Converts the Internet host address @var{str} from the
1072  standard numbers-and-dots notation into equivalent integer in  standard numbers-and-dots notation into the equivalent integer in
1073  host byte order.  host byte order.
1074  @end deftypefn  @end deftypefn
1075    
1076  @deftypefn Function string inet_ntoa (integer @var{ip})  @deftypefn Function string inet_ntoa (integer @var{ip})
1077  This function converts the Internet host address @var{ip} given  Converts the Internet host address @var{ip} given
1078  in host byte order to a string in standard numbers-and-dots notation.  in host byte order to a string in standard numbers-and-dots notation.
1079  @end deftypefn  @end deftypefn
1080    
1081  @deftypefn Function integer htonl (integer @var{n})  @deftypefn Function integer htonl (integer @var{n})
1082  Converts the integer @var{n} regarded as long from host to network byte  Converts the integer @var{n}, regarded as long, from host to network byte
1083  order.  order.
1084  @end deftypefn  @end deftypefn
1085    
1086  @deftypefn Function integer ntohl (integer @var{n})  @deftypefn Function integer ntohl (integer @var{n})
1087  Converts the integer @var{n} regarded as long from network to host byte  Converts the integer @var{n}, regarded as long, from network to host byte
1088  order.  order.
1089  @end deftypefn  @end deftypefn
1090    
1091  @deftypefn Function integer htons (integer @var{n})  @deftypefn Function integer htons (integer @var{n})
1092  Converts the integer @var{n} regarded as short from host to network byte  Converts the integer @var{n}, regarded as short, from host to network byte
1093  order.  order.
1094  @end deftypefn  @end deftypefn
1095    
1096  @deftypefn Function integer ntohs (integer @var{n})  @deftypefn Function integer ntohs (integer @var{n})
1097  Converts the integer @var{n} regarded as short from network to host byte  Converts the integer @var{n}, regarded as short, from network to host byte
1098  order.  order.
1099  @end deftypefn  @end deftypefn
1100    
# Line 1079  order. Line 1104  order.
1104  @cindex Guile  @cindex Guile
1105    
1106  The name Guile stands for @dfn{GNU's Ubiquitous Intelligent Language for  The name Guile stands for @dfn{GNU's Ubiquitous Intelligent Language for
1107  Extensions}. It provides the Scheme interpreter conforming to R4RS  Extensions}. It provides a Scheme interpreter conforming to the R4RS
1108  language specification. This section describes use of Guile as an  language specification. This section describes use of Guile as an
1109  extension language for GNU Radius. It assumes that the reader is  extension language for GNU Radius. It assumes that the reader is
1110  sufficiently familiar with the Scheme language. Please, refer to  sufficiently familiar with the Scheme language. For information about
1111  @ref{Top,,,r4rs,Revised(4) Report on the Algorithmic Language Scheme},  the language, refer to
1112  for the information about the language. If you wish to know more  @ref{Top,,,r4rs,Revised(4) Report on the Algorithmic Language Scheme}.
1113  about the Guile, @xref{Top,,Overview,guile,The Guile Reference Manual}.  For more
1114    about Guile, @xref{Top,,Overview,guile,The Guile Reference Manual}.
1115    
1116  Scheme procedures can be called for processing both authentication  Scheme procedures can be called for processing both authentication
1117  and accounting requests. The invocation of a scheme procedure for an  and accounting requests. The invocation of a Scheme procedure for an
1118  authentication request is triggered by @attr{Scheme-Procedure}  authentication request is triggered by the @attr{Scheme-Procedure}
1119  attribute, the invocation for an accounting request is triggered  attribute; the invocation for an accounting request is triggered
1120  by @attr{Scheme-Acct-Procedure} attribute. The following sections  by the @attr{Scheme-Acct-Procedure} attribute. The following sections
1121  address these issues in more detail.  address these issues in more detail.
1122    
1123  @menu  @menu
# Line 1106  address these issues in more detail. Line 1132  address these issues in more detail.
1132  @subsection Data Representation  @subsection Data Representation
1133  @cindex Guile, representation of Radius data  @cindex Guile, representation of Radius data
1134    
1135  @AVP{} lists are the main object scheme functions operate upon. Scheme  @AVP{} lists are the main object Scheme functions operate upon. Scheme
1136  is extremely convenient for representation of such objects. A Radius @AVP{}  is extremely convenient for representation of such objects. A Radius @AVP{}
1137  is represented by a Scheme pair, e.g.  is represented by a Scheme pair; e.g.,
1138    
1139  @example  @example
1140          Session-Timeout = 10          Session-Timeout = 10
# Line 1121  is represented in Guile as Line 1147  is represented in Guile as
1147          (cons "Session-Timeout" 10)          (cons "Session-Timeout" 10)
1148  @end lisp  @end lisp
1149    
1150  The @sc{car} of the pair can contain either the attribute dictionary  The @code{car} of the pair can contain either the attribute dictionary
1151  name, or the attribute number. Thus, the above pair may also be  name or the attribute number. Thus, the above pair may also be
1152  written in Scheme as  written in Scheme as
1153    
1154  @lisp  @lisp
# Line 1130  written in Scheme as Line 1156  written in Scheme as
1156  @end lisp  @end lisp
1157    
1158  @noindent  @noindent
1159  (@attr{Session-Timeout} corresponds to attribute number 27).  (because @attr{Session-Timeout} corresponds to attribute number 27).
1160    
1161  Lists of @AVP{}s are represented by Scheme lists. For example,  Lists of @AVP{}s are represented by Scheme lists. For example,
1162  the following Radius pair list  the Radius pair list
1163    
1164  @example  @example
1165  @group  @group
# Line 1145  the following Radius pair list Line 1171  the following Radius pair list
1171  @end example  @end example
1172    
1173  @noindent  @noindent
1174  is written in Scheme as:  is written in Scheme as
1175    
1176  @lisp  @lisp
1177  @group  @group
# Line 1172  Its arguments are: Line 1198  Its arguments are:
1198  The list of @AVP{}s from the incoming request  The list of @AVP{}s from the incoming request
1199  @item check-list  @item check-list
1200  The list of @AVP{}s from the @LHS{} of the profile entry that matched  The list of @AVP{}s from the @LHS{} of the profile entry that matched
1201  the request.  the request
1202  @item reply-list  @item reply-list
1203  The list of @AVP{}s from the @RHS{} of the profile entry that matched  The list of @AVP{}s from the @RHS{} of the profile entry that matched
1204  the request.  the request
1205  @end table  @end table
1206  @end deffn  @end deffn
1207    
# Line 1184  succeed. The function must return either Line 1210  succeed. The function must return either
1210  The return of @code{#t} causes authentication to succeed. The return  The return of @code{#t} causes authentication to succeed. The return
1211  of @code{#f} causes it to fail.  of @code{#f} causes it to fail.
1212    
1213  If the function wishes to add something to the reply @AVP{}s, it  For a function to add something to the reply @AVP{}s, it
1214  should return a pair in the form:  should return a pair in the form
1215    
1216  @lisp  @lisp
1217      (cons @var{return-code} @var{list})      (cons @var{return-code} @var{list})
1218  @end lisp  @end lisp
1219    
1220  Where @var{return-code} is a boolean value of the same meaning as  @noindent
1221  described above. The @var{list} is a list of @AVP{}s to be added  where @var{return-code} is a boolean value of the same meaning as
1222    described above. @var{list} is a list of @AVP{}s to be added
1223  to the reply list. For example, the following function will always  to the reply list. For example, the following function will always
1224  deny the authentication, returning appropriate message to the user:  deny the authentication, returning an appropriate message to the user:
1225    
1226  @exindex Scheme authentication function  @exindex Scheme authentication function
1227  @lisp  @lisp
# Line 1203  deny the authentication, returning appro Line 1230  deny the authentication, returning appro
1230    (cons #f    (cons #f
1231          (list          (list
1232           (cons "Reply-Message"           (cons "Reply-Message"
1233                 "\r\nSorry, you are not allowed to log in\r\n"))))                 "\r\nSorry, you are not
1234                    allowed to log in\r\n"))))
1235  @end group  @end group
1236  @end lisp  @end lisp
1237    
1238  As a more constructive example, let's consider a function that  As a more constructive example, let's consider a function that
1239  allows the authentication only if a user name is found in its  allows the authentication only if a user name is found in its
1240  internal database.  internal database:
1241    
1242  @lisp  @lisp
1243  @group  @group
# Line 1250  internal database. Line 1278  internal database.
1278  @end lisp  @end lisp
1279    
1280  To trigger the invocation of the Scheme authentication function, assign  To trigger the invocation of the Scheme authentication function, assign
1281  its name to @attr{Scheme-Procedure} attribute in @RHS{} of a  its name to the @attr{Scheme-Procedure} attribute in the @RHS{} of a
1282  corresponding @file{raddb/users} profile. E.g.:  corresponding @file{raddb/users} profile. For example:
1283    
1284  @exindex Invoking Scheme authentication function  @exindex Invoking Scheme authentication function
1285  @exindex Scheme authentication function, invocation  @exindex Scheme authentication function, invocation
# Line 1270  DEFAULT Auth-Type = SQL Line 1298  DEFAULT Auth-Type = SQL
1298  The Scheme accounting procedure must be declared as follows:  The Scheme accounting procedure must be declared as follows:
1299    
1300  @deffn {Function Template} acct-function-name request-list  @deffn {Function Template} acct-function-name request-list
1301  Its arguments are:  Its argument is:
1302  @table @var  @table @var
1303  @item request-list  @item request-list
1304  The list of @AVP{}s from the incoming request  The list of @AVP{}s from the incoming request
# Line 1278  The list of @AVP{}s from the incoming re Line 1306  The list of @AVP{}s from the incoming re
1306  @end deffn  @end deffn
1307    
1308  The function must return a boolean value. The accounting succeeds only  The function must return a boolean value. The accounting succeeds only
1309  if it returned @code{#t}.  if it has returned @code{#t}.
1310    
1311  Here is an example of Scheme accounting function. The function dumps  Here is an example of a Scheme accounting function. The function dumps
1312  the contents of the incoming request to a file:  the contents of the incoming request to a file:
1313    
1314  @exindex Scheme accounting function  @exindex Scheme accounting function
# Line 1323  Return @code{#t} if all pairs from @var{ Line 1351  Return @code{#t} if all pairs from @var{
1351  Return a dictionary entry for the given attribute @var{name} or @code{#f} if  Return a dictionary entry for the given attribute @var{name} or @code{#f} if
1352  no such name was found in the dictionary.  no such name was found in the dictionary.
1353    
1354  A dictionary entry is a list in the form:  A dictionary entry is a list in the form
1355    
1356  @deffn {Scheme List} dict-entry name-string attr-number type-number vendor  @deffn {Scheme List} dict-entry name-string attr-number type-number vendor
1357  Where  
1358    @noindent
1359    where the arguments are as follows:
1360    
1361  @table @var  @table @var
1362  @item name-string  @item name-string
1363  The attribute name  The attribute name
# Line 1335  The attribute number Line 1366  The attribute number
1366  @item type-number  @item type-number
1367  The attribute type  The attribute type
1368  @item vendor  @item vendor
1369  is the vendor @acronym{PEC}, if the attribute is a Vendor-Specific one,  The vendor @acronym{PEC}, if the attribute is a vendor-specific one,
1370  or #f otherwise.  or @code{#f} otherwise.
1371  @end table  @end table
1372  @end deffn  @end deffn
1373  @end deffn  @end deffn
1374    
1375  @deffn {Scheme Function} rad-dict-value->name attr value  @deffn {Scheme Function} rad-dict-value->name attr value
1376  Returns a dictionary name of the given @var{value} for an integer-type  Returns the dictionary name of the given @var{value} for an integer-type
1377  attribute @var{attr}. @var{attr} can be either an attribute number  attribute @var{attr}, which can be either an attribute number
1378  or its dictionary name.  or its dictionary name.
1379  @end deffn  @end deffn
1380    
1381  @deffn {Scheme Function} rad-dict-name->value attr value  @deffn {Scheme Function} rad-dict-name->value attr value
1382  Convert a symbolic attribute value name into its integer representation  Convert a symbolic attribute value name into its integer representation.
1383  @end deffn  @end deffn
1384    
1385  @deffn {Scheme Function} rad-dict-pec->vendor pec  @deffn {Scheme Function} rad-dict-pec->vendor pec
1386  Convert @acronym{PEC} to the vendor name  Convert a @acronym{PEC} to the vendor name.
1387  @end deffn  @end deffn
1388    
1389  @deffn {Scheme Function} rad-log-open prio  @deffn {Scheme Function} rad-log-open prio
1390  Open radius logging to the severity level @var{prio}.  Open Radius logging to the severity level @var{prio}.
1391  @end deffn  @end deffn
1392    
1393  @deffn {Scheme Function} rad-log-close  @deffn {Scheme Function} rad-log-close
1394  Close radius logging channel open by a previous call to @code{rad-log-open}.  Close a Radius logging channel opened by a previous call to @code{rad-log-open}.
1395  @end deffn  @end deffn
1396    
1397  @deffn {Scheme Function} rad-rewrite-execute-string string  @deffn {Scheme Function} rad-rewrite-execute-string string
# Line 1394  Scheme interface to the system @code{clo Line 1425  Scheme interface to the system @code{clo
1425  @end deffn  @end deffn
1426    
1427  @deffn {Scheme Function} rad-utmp-putent status delay list radutmp_file radwtmp_file  @deffn {Scheme Function} rad-utmp-putent status delay list radutmp_file radwtmp_file
1428  Write the supplied data into the radutmp file. If RADWTMP_FILE is not nil  Write the supplied data into the radutmp file. If @var{radwtmp_file} is not nil,
1429  the constructed entry is also appended to WTMP_FILE.  the constructed entry is also appended to @var{wtmp_file}.
1430    
1431  @var{list} is:  @var{list} is:
1432    
1433  @deffn {Scheme List} utmp-entry user-name orig-name port-id port-type session-id caller-id framed-ip nas-ip proto  @deffn {Scheme List} utmp-entry user-name orig-name port-id port-type session-id caller-id framed-ip nas-ip proto
# Line 1404  the constructed entry is also appended t Line 1436  the constructed entry is also appended t
1436  @item user-name  @item user-name
1437  The user name  The user name
1438  @item orig-name  @item orig-name
1439  Original user name from the request  The original user name from the request
1440  @item port-id  @item port-id
1441  The value of @attr{NAS-Port-Id} attribute.  The value of the @attr{NAS-Port-Id} attribute
1442  @item port-type  @item port-type
1443  A number or character indicating the port type.  A number or character indicating the port type
1444  @item session-id  @item session-id
1445  Session @sc{id}.  The session @sc{id}
1446  @item caller-id  @item caller-id
1447  The value of @attr{Calling-Station-Id} attribute from the request.  The value of the @attr{Calling-Station-Id} attribute from the request
1448  @item framed-ip  @item framed-ip
1449  The framed @IP{} assigned to the user.  The framed IP assigned to the user
1450  @item nas-ip  @item nas-ip
1451  The @NAS{} @IP{}.  The @NAS{} IP
1452  @item proto  @item proto
1453  Number or character indicating type of the connection.  A number or character indicating the type of the connection
1454  @end table  @end table
1455  @end deffn  @end deffn
1456  @end deffn  @end deffn

Legend:
Removed from v.1.13  
changed lines
  Added in v.1.14

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26