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