From: Tomek Mrugalski <tomasz@isc.org>
Date: Tue, 1 May 2018 22:32:59 +0000 (+0100)
Subject: [5605a] [5608] Added example for sending extra Attributes.
X-Git-Tag: trac5536_base~4^2~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=37a3132d473d228a41f565bec95ca28cb9dc14e4;p=thirdparty%2Fkea.git

[5605a] [5608] Added example for sending extra Attributes.
---

diff --git a/doc/guide/hooks-radius.xml b/doc/guide/hooks-radius.xml
index e310243e30..ddfbf7bbf2 100644
--- a/doc/guide/hooks-radius.xml
+++ b/doc/guide/hooks-radius.xml
@@ -466,8 +466,15 @@ Please make sure that your compilation has the following:
         </listitem>
 
         <listitem>
-          <simpara>attributes which define attributes which are used by the
-          service with:</simpara>
+          <simpara>attributes which define additional attributes that
+          the Kea server will send to a RADIUS server. Currently this
+          feature is supported for access servers only. The parameter
+          must be identified either by a name or type. Its value can
+          be specified using one of three possible ways: data (which
+          defines a plain text value), raw (which defines the value in
+          hex) or expr (which defines an expression, which will be
+          evaluated for each incoming packet independently).
+          </simpara>
           <itemizedlist>
             <listitem><simpara><command>name</command> of the
             attribute. </simpara></listitem>
@@ -475,28 +482,84 @@ Please make sure that your compilation has the following:
             name is required, and the attribute must be defined in the
             dictionary.</simpara></listitem>
 
-            <listitem><simpara><command>data</command> is one of the three ways
-            to specify the attribute content.  The data entry is parsed by the
-            FreeRADIUS library so values defined in the dictionary of the
+            <listitem><simpara><command>data</command> is the first out of three
+            ways to specify the attribute content. The data entry is parsed by
+            the FreeRADIUS library so values defined in the dictionary of the
             attribute may be used.</simpara></listitem>
 
-            <listitem><simpara><command>raw</command> specifies the content in
+            <listitem><simpara><command>raw</command> is the second out of three
+            way to specify the attribute content. It specifies the content in
             hexadecimal. Note it does not work with integer content attributes
             (date, integer and IPv4 address), a string content attribute
             (string. IPv6 address and IPv6 prefix) is
             required.</simpara></listitem>
 
-            <listitem><simpara><command>expr</command> specifies an evaluation
-            expression which must return a not empty string when evaluated with
-            the DHCP query packet.  A priori this is restricted to the access
+            <listitem><simpara><command>expr</command> is the last way to
+            specify the attribute content. It specifies an evaluation expression
+            which must return a not empty string when evaluated with the DHCP
+            query packet.  A priori this is restricted to the access
             service. </simpara></listitem>
           </itemizedlist>
         </listitem>
       </itemizedlist>
-
     </para>
 <para>
-
+  For example, to specify a single access server available on localhost that
+  uses "secret" as a secret and tell Kea to send three additional attributes
+  (Password, Connect-Token and Configuration-Info), the following snipped could
+  be used:
+  <screen>
+"parameters": {
+
+    // Other RADIUS parameters here
+
+    "access": {
+
+        // This starts the list of access servers
+        "servers": [
+        {
+            // These are parameters for the first (and only) access server
+            "name": "127.0.0.1",
+            "server": "127.0.0.1",
+            "secret": "secret",
+            "port": 1812
+        }
+        // Additional access servers could be specified here
+        ],
+
+        // This define a list of additional attributes Kea will send to each
+        // access server in Access-Request.
+        "attributes": [
+        {
+            // This attribute is identified by name (must be present in the
+            // dictionary) and has static value (i.e. the same value will be
+            // sent to every server for every packet)
+            "name": "Password",
+            "data": "mysecretpassword"
+        },
+        {
+            // It's also possible to specify an attribute using its type,
+            // rather than a name. 77 is Connect-Token. The value is specified
+            // using hex. Again, this is a static value. It will be sent the
+            // same for every packet and to every server.
+            "type": 77,
+            "raw": "65666a6a71"
+        },
+        {
+            // This example shows how an expression can be used to send dynamic
+            // value. The expression (see Section 13) may take any value from
+            // the incoming packet or even its metadata (e.g. the interface
+            // it was received over from)
+            "name": "Configuration-Info",
+            "expr": "pkt.iface"
+        }
+        ] // End of attributes
+    } // End of access
+
+    // accounting could be specified here.
+
+    }
+</screen>
 </para>
 
 <para>For the RADIUS Hook library to operate properly in DHCPv4, it is necessary