doc/variables.txt

   1   Run-time variables
   2   ------------------
   3
   4   The run-time variables defined by the server are:
   5
   6      %{Attribute-Name}               The value of the given Attribute-Name
   7                                      in the request packet
   8
   9      %{request:Attribute-Name}       The value of value the given
  10                                      Attribute-Name in the request packet
  11      %{reply:Attribute-Name}         The value of the given Attribute-Name
  12                                      in the reply packet
  13      %{proxy-request:Attribute-Name} The value of the given Attribute-Name
  14                                      in the proxy request packet (if it exists)
  15      %{proxy-reply:Attribute-Name}   The value of the given Attribute-Name
  16                                      in the proxy reply packet (if it exists)
  17
  18   The above variable expansions also support the meta-attribute
  19 Packet-Type as well. See the RADIUS dictionary for details on its
  20 values.
  21
  22      %{check:Attribute-Name}         Corresponding value for Attribute-Name
  23                                      in check items for request
  24
  25
  26      %{config:section.subsection.item} Corresponding value in 'radiusd.conf'
  27                                        for the string value of that item.
  28
  29   The %{config:...} variables should be used VERY carefully, as they
  30 may leak secret information from your RADIUS server, if you use them
  31 in reply attributes to the NAS!
  32
  33   If your system supports regular expressions, then regular expression
  34 matching defines other special variables, just like in Perl.
  35
  36      %{0}       What the regular expression matched
  37      %{1}       The first group which matched
  38      %{2}       The second group which matched
  39      ...
  40      %{8}       The eight group which matched.
  41
  42   These variables are defined during a regular expression match =~,
  43 and only when the expression matches.  They are NOT defined for the
  44 operator !~, or when =~ doesn't match.  Any use of =~ destroys all
  45 previous values of %{0}..%{8}, but the variables.
  46
  47   Some examples.
  48
  49   %{User-Name}                   The string value of the User-Name attribute.
  50   %{proxy-reply:Framed-Protocol} The string value of the Framed-Protocol
  51                                  attribute, from the proxy reply.
  52   %{config:modules.unix.passwd}  The string value of the 'passwd' configuration
  53                                  item in the 'unix' module, in the 'modules'
  54                                  section of radiusd.conf.
  55
  56 DEFAULT  User-Name =~ "^([^@]+)@(.*)"
  57          All-That-Matched = `%{0}`
  58          Just-The-User-Name = `%{1}`
  59          Just-The-Realm-Name = `%{2}`
  60
  61
  62   The variables are used in dynamically translated strings.  Most of
  63 the configuration entries in radiusd.conf (and related files) will do
  64 dynamic string translation.  To do the same dynamic translation in a
  65 RADIUS attribute (when pulling it from a database, or "users" file),
  66 you must put the string into an back-quoted string:
  67
  68        Session-Timeout = `%{expr: 2 + 3}`
  69
  70   To do the dynamic translation in the 'radiusd.conf' (or some other
  71 configuration files), just use the variable as-is.  See 'radiusd.conf'
  72 for examples.
  73
  74
  75   Conditional syntax
  76   --------------------
  77
  78   Additionally, you can use conditional syntax similar to ${foo:-bar} as
  79 defined in 'sh'.  For example:
  80
  81   1.  %{Foo:-bar}
  82     When attribute Foo is set:    returns value of Foo
  83     When attribute Foo is unset:  returns literal string 'bar'
  84
  85   2.  %{Foo:-%{Bar}}
  86     When attribute Foo is set:    returns value of attribute Foo
  87     When attribute Foo is unset:  returns value of attribute Bar (if any)
  88
  89   3.  %{Foo:-%{Bar:-baz}}
  90     When attribute Foo is set:    returns value of attribute Foo
  91     When attribute Foo is unset:  returns value of attribute Bar (if any)
  92     When attribute Bar is unset:  returns literal string 'baz'
  93
  94
  95   String Lengths
  96   --------------
  97
  98   The dynamic translations support a few additional operatons, too.
  99
 100      %{#string}
 101         The number of characters in %{string}.  If %{string} is not
 102         set, then the length is not set.  This will NOT work for the
 103         one-character variables defined below.
 104
 105         e.g. %{#Junk-junk:-foo} will yeild the string "foo".
 106
 107
 108      %{Attribute-Name[index]}
 109         Reference the N'th occurance of the given attribute.  The
 110         indexes start at zero.  This feature is NOT available for
 111         non-attribute dynamic translations, like %{sql:...}.
 112
 113         e.g. %{User-Name[0]} is the same as %{User-Name}
 114         e.g. %{Cisco-AVPair[2]} references the value of the *third*
 115              Cisco-AVPair attribute (if it exists) in the request
 116              packet,
 117
 118      %{Attribute-Name[#]}
 119         Returns the total number of attributes of that name in
 120         the relevant attribute list.  The number will usually
 121         be between 0 and 200.
 122
 123         e.g. For most requests, %{request:User-Name[#]} == 1
 124
 125      %{Attribute-Name[*]}
 126         Expands to a single string, with the value of each array
 127         member separated by a newline.
 128
 129      %{#Attribute-Name[index]}
 130         Expands to the length of the string %{Attribute-Name[index]}.
 131
 132
 133   Attributes as environment variables in executed programs
 134   --------------------------------------------------------
 135
 136   When calling an external program (e.g. from Exec-Program-Wait), these
 137 variables can be passed on the command line to the program.  In
 138 addition, the server places all of the attributes in the RADIUS
 139 request into environment variables for the external program.  The
 140 variables are renamed under the following rules:
 141
 142   1.  All letters are made upper-case.
 143
 144   2.  All hyphens '-' are turned into underscores '_'
 145
 146 so the attribute User-Name can be passed on the command line to the
 147 program as %{User-Name}, or used inside the program as the environment
 148 variable USER_NAME (or $USER_NAME for shell scripts).
 149
 150   If you want to see the list of all of the variables, try adding a
 151 line 'printenv > /tmp/exec-program-wait' to the script.  Then look in
 152 the file for a complete list of variables.
 153
 154
 155   One-character variables
 156   -----------------------
 157
 158   The following one-character variables are also defined.  However, they
 159 are duplicates of the previous general cases, and are only provided
 160 for backwards compatibility.  They WILL BE removed in a future
 161 release.  They also do NOT permit the use of conditional syntax
 162 (':-'), as described above.
 163
 164
 165     Variable  Description                 Proper Equivalent
 166     --------  -----------                 ----------------
 167      %a       Protocol (SLIP/PPP)         %{Framed-Protocol}
 168      %c       Callback-Number             %{Callback-Number}
 169      %d       request day (DD)
 170      %f       Framed IP address           %{Framed-IP-Address}
 171      %i       Calling Station ID          %{Calling-Station-Id}
 172      %l       request timestamp
 173      %m       request month (MM)
 174      %n       NAS IP address              %{NAS-IP-Address}
 175      %p       Port number                 %{NAS-Port}
 176      %s       Speed (PW_CONNECT_INFO)     %{Connect-Info}
 177      %t       request in ctime format
 178      %u       User name                   %{User-Name}
 179      %A       radacct_dir                 %{config:radacctdir}
 180      %C       clientname
 181      %D       request date (YYYYMMDD)
 182      %H       request hour
 183      %L       radlog_dir                  %{config:logdir}
 184      %M       MTU                         %{Framed-MTU}
 185      %R       radius_dir                  %{config:raddbdir}
 186      %S       request timestamp
 187                 in SQL format
 188      %T       request timestamp
 189                 in database format
 190      %U       Stripped User name          %{Stripped-User-Name}
 191      %V       Request-Authenticator
 192                 (Verified/None)
 193      %Y       request year (YYYY)
 194      %Z       All request attributes
 195                except password
 196                (must have a big buffer)
 197
 198  $Id$