hooks.xml 104 KB
Newer Older
1 2 3 4 5 6 7
<!--
 - Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
 -
 - This Source Code Form is subject to the terms of the Mozilla Public
 - License, v. 2.0. If a copy of the MPL was not distributed with this
 - file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->
Tomek Mrugalski's avatar
Tomek Mrugalski committed
8

9 10
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hooks-libraries">
11 12

    <title>Hooks Libraries</title>
13
    <section xml:id="hooks-libraries-introduction">
14 15 16
      <title>Introduction</title>
      <para>
      Although Kea offers a lot of flexibility, there may be cases where
Josh Soref's avatar
Josh Soref committed
17
      its behavior needs customization.  To accommodate this possibility,
18 19 20 21 22 23
      Kea includes the idea of "Hooks".  This feature lets Kea load one
      or more dynamically-linked libraries (known as "hooks libraries")
      and, at various points in its processing ("hook points"), call
      functions in them.  Those functions perform whatever custom
      processing is required.
      </para>
24 25 26 27 28 29
      <para>
        The hooks concept also allows keeping the core Kea code reasonably small
        by moving features that some, but not all users find useful to external
        libraries. People who don't need specific functionality simply don't
        load the libraries.
      </para>
30
      <para>
31
      Hooks libraries are loaded by individual Kea processes, not to
32 33 34 35 36 37
      Kea as a whole.  This means (for example) that it is possible
      to associate one set of libraries with the DHCP4 server and a
      different set to the DHCP6 server.
      </para>
      <para>
      Another point to note is that it is possible for a process to
38 39 40 41 42 43
      load multiple libraries.  When processing reaches a hook point,
      Kea calls the hooks library functions attached to it.  If multiple
      libraries have attached a function to a given hook point, Kea calls
      all of them, in the order in which the libraries are specified in
      the configuration file. The order may be important: consult the
      documentation of the libraries to see if this is the case.
44 45 46 47
      </para>
      <para>
      The next section describes how to configure hooks libraries. If you
      are interested in writing your own hooks library, information can be
48
      found in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen">Kea
49
      Developer's Guide</link>.
50
      </para>
51 52 53 54 55 56 57 58 59 60 61

      <para>
        Note that some libraries are available under different licenses.
      </para>
      <para>
        Note that some libraries may require additional dependencies and/or
        compilation switches to be enabled, e.g. Radius library introduced in
        Kea 1.4 requires FreeRadius-client library to be present. If
        --with-free-radius option is not specified, the Radius library will not
        be built.
      </para>
62
    </section> <!-- end Introduction -->
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114

    <section>
      <title>Installing Hook packages</title>

      <note>
        <simpara>The installation procedure has changed in 1.4.0. Kea 1.3.0 and
        earlier needed special switches passed to configure script to detect the
        hook libraries. Please see this KB article: <uri
        xmlns:xlink="http://www.w3.org/1999/xlink"
        xlink:href="https://kb.isc.org/article/AA-01587">https://kb.isc.org/article/AA-01587</uri>
        .</simpara>
      </note>

      <para>Some hook packages are included in the base Kea sources. There is no
      need to do anything special to compile or install them, they are covered
      by the usual building and installation procedure. ISC also provides several
      additional hooks in form of various packages. All of those packages follow
      the same installation procedure that is similar to base Kea, but has
      several additional steps. For your convenience, the whole procedure is
      described here. Please refer to <xref linkend="installation"/> for general
      overview.</para>

      <para>
        1. Download the package. You will receive detailed instructions how to
        get it separately. This will be a file with a name similar to
        kea-premium-1.4.0.tar.gz. Your name may differ depending on which
        package you got.
      </para>

      <para>
        2. If you have the sources for the corresponding version of the
        open-source Kea package still on your system (from when you installed
        Kea), skip this step.  Otherwise extract the Kea source from the
        original tarball you downloaded.  For example, if you downloaded Kea
        1.4.0., you should have a tarball called kea-1.4.0.tar.gz on your
        system. Unpack this tarball:

<screen>
$ <userinput>tar zxvf kea-1.4.0.tar.gz</userinput>
</screen>

        This will unpack the tarball into the kea-1.4.0 subdirectory of your
        current working directory.
      </para>

      <para>
        3. Unpack the Kea premium tarball into the directory into which Kea was
        unpacked. For example, assuming that you followed step 2 and that Kea
        1.4.0 has been unpacked into a kea-1.4.0 subdirectory and that the Kea
        premium tarball is in your current directory, the following steps will
        unpack the premium tarball into the correct location:
<screen>
115
  $ <userinput>cd kea-1.4.0</userinput>
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
  $ <userinput>tar xvf ../kea-premium-1.4.0.tar.gz</userinput>
</screen>
        Note that unpacking the Kea premium package will put the files into a
        directory named premium. Regardless of the name of your package, the
        directory will always be called premium, just its content may vary.
      </para>

      <para>
        4. Run autoreconf tools. This step is necessary to update Kea's build
        script to include additional directory. If this tool is not already
        available on your system, you need to install automake and autoconf
        tools. To generate configure script, please use:
<screen>
  $ <userinput>autoreconf -i</userinput>
</screen>
      </para>
      <para>
        5. Rerun configure, using the same configure options as you used when
        originally building Kea. You can check if configure has detected the
        premium package by inspecting the summary printed when it exits.  The
        first section of the output should look something like:
<screen>
Package:
  Name:            kea
  Version:         1.4.0
  Extended version:1.4.0 (tarball)
  OS Family:       Linux
  Using GNU sed:   yes
  Premium package: yes
  Included Hooks:  forensic_log flex_id host_cmds
</screen>

The last line indicates which specific hooks were detected. Note that some
hooks may require its own dedicated switches, e.g. radius hook requires
extra switches for FreeRADIUS. Please consult later sections of this
chapter for details.
      </para>

      <para>
        6. Rebuild Kea
<screen>
  $ <userinput>make</userinput>
</screen>
If your machine has multiple CPU cores, interesting option to consider here
is -j X, where X is the number of available cores.
      </para>

      <para>
        7. Install Kea sources together with hooks:
<screen>
$ <userinput>sudo make install</userinput>
</screen>
      Note that as part of the installation procedure, the install script will
      eventually venture into premium/ directory and will install additional
      hook libraries and associated files.
      </para>
172 173 174 175 176 177 178
      <para>
      The installation location of the hooks libraries depends whether you
      specified --prefix parameter to the configure script. If you did not,
      the default location will be /usr/local/lib/hooks. You can verify the
      libraries are installed properly with this command:
<screen>
$ <userinput>ls -l /usr/local/lib/hooks/*.so</userinput>
179
/usr/local/lib/hooks/libdhcp_class_cmds.so
180 181 182 183 184 185 186 187 188 189
/usr/local/lib/hooks/libdhcp_flex_id.so
/usr/local/lib/hooks/libdhcp_host_cmds.so
/usr/local/lib/hooks/libdhcp_lease_cmds.so
/usr/local/lib/hooks/libdhcp_legal_log.so
/usr/local/lib/hooks/libdhcp_subnet_cmds.so
</screen>
      The exact list you see will depend on the packages you have.
      If you specified directory via --prefix, the hooks libraries
      will be located in {prefix directory}/lib/hooks.
      </para>
190 191
    </section>

192 193 194 195 196 197 198
    <section>
      <title>Configuring Hooks Libraries</title>
      <para>
      The hooks libraries for a given process are configured using the
      <command>hooks-libraries</command> keyword in the
      configuration for that process. (Note that
      the word "hooks" is plural).  The value of the keyword
199 200 201
      is an array of map structures, each structure corresponding to a hooks
      library.  For example, to set up two hooks libraries for the DHCPv4
      server, the configuration would be:
202 203 204 205
<screen>
<userinput>"Dhcp4": {
    :
    "hooks-libraries": [
206 207 208 209
        {
            "library": "/opt/charging.so"
        },
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
210 211 212 213 214 215 216 217 218 219 220
            "library": "/opt/local/notification.so",
            "parameters": {
                "mail": "spam@example.com",
                "floor": 13,
                "debug": false,
                "users": [ "alice", "bob", "charlie" ],
                "languages": {
                    "french": "bonjour",
                    "klingon": "yl'el"
                }
            }
221
        }
222 223 224 225 226
    ]
    :
}</userinput>
</screen>
      </para>
227

228
      <note><para>
229 230
        This is a change to the syntax used in Kea 0.9.2 and earlier, where
        hooks-libraries was a list of strings, each string being the name of
231
        a library.  The change was made in Kea 1.0 to facilitate the
232
        specification of library-specific parameters, a capability
233
        available in Kea 1.1.0 onwards. Libraries should allow a parameter
234
        entry where to put comments as it is done for many configuration
235
        scopes with comment and user context.
236
      </para></note>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
237

238 239
        <note>
          <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
240 241 242 243
          The library reloading behavior has changed in Kea 1.1. Libraries are
          reloaded, even if their list hasn't changed. Kea does that, because
          the parameters specified for the library (or the files those
          parameters point to) may have changed.
244 245
          </para>
        </note>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
246 247 248 249 250 251 252 253 254 255 256

      <para>
        Libraries may have additional parameters. Those are not mandatory in the
        sense that there may be libraries that don't require them. However, for
        specific library there is often specific requirement for specify certain
        set of parameters. Please consult the documentation for your library
        for details. In the example above, the first library has no parameters.
        The second library has five parameters, specifying mail (string
        parameter), floor (integer parameter), debug (boolean parameter) and
        even lists (list of strings) and maps (containing strings). Nested
        parameters could be used if the library supports it. This topic is
257 258
        explained in detail in the Hooks Developer's Guide in the "Configuring
        Hooks Libraries" section.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
259 260
      </para>

261 262
      <para>
      Notes:
263
        <itemizedlist mark="bullet">
264 265 266 267 268 269 270 271 272 273
          <listitem><para>
          The full path to each library should be given.
          </para></listitem>
          <listitem><para>
          As noted above, order may be important - consult the documentation for
          each library.
          </para></listitem>
          <listitem><para>
          An empty list has the same effect as omitting the
          <command>hooks-libraries</command> configuration element all together.
Stephen Morris's avatar
Stephen Morris committed
274 275 276 277 278 279 280 281 282 283 284 285
          </para>
          <note><para>
          There is one case where this is not true: if Kea
          is running with a configuration that contains a
          <command>hooks-libraries</command> item, and that item is
          removed and the configuration reloaded, the removal will be
          ignored and the libraries remain loaded.  As a workaround,
          instead of removing the <command>hooks-libraries</command>
          item, change it to an empty list.  This will be fixed in a
          future version of Kea.
          </para></note>
          </listitem>
286 287 288 289 290 291 292
        </itemizedlist>
      </para>
      <para>
      At the present time, only the kea-dhcp4 and kea-dhcp6 processes support
      hooks libraries.
      </para>
    </section>
293 294 295 296

    <section>
      <title>Available Hooks Libraries</title>
      <para>
297
      As described above, the hooks functionality provides a way to customize
298
      a Kea server without modifying the core code.  ISC has chosen to take
299 300 301
      advantage of this feature to provide functions that may only be useful
      to a subset of Kea users.  To this end ISC has created some hooks
      libraries; these discussed in the following sections.
302 303
      </para>

304 305
      <note><para>
      Some of these libraries will be available with the base code while others
306 307
      will be shared with organizations supporting development of Kea
      , possibly as a 'benefit' or 'thank you' for helping to sustain
308
      the larger Kea project. If you would like to get access to those
309
      libraries, please consider taking out a support contract: this includes
310
      professional support, advance security notifications, input into our
311
      roadmap planning, and many other benefits, while helping
312 313 314
      making Kea sustainable in the long term.
      </para></note>

315
      <para>The following table provides a list of libraries currently available
Thomas Markwalder's avatar
Thomas Markwalder committed
316 317 318 319 320 321
      from ISC. It is important to pay attention to which libraries may be loaded
      by which Kea processes. It is a common mistake to configure the <command>
      kea-ctrl-agent</command> process to load libraries that should, in fact,
      be loaded by the <command>kea-dhcp4 </command> or <command>kea-dhcp6</command>
      processes.  If a library from ISC doesn't work as expected, please make sure
      that it has been loaded by the correct process per the table below.
322 323 324

      <warning>
        <para>
Thomas Markwalder's avatar
Thomas Markwalder committed
325 326 327
          While the Kea Control Agent includes the "hooks" functionality,
          (i.e. hooks libraries can be loaded by this process), none of ISC's
          current hooks libraries should be loaded by the Control Agent.
328 329
        </para>
      </warning>
330

331
        <table frame="all" xml:id="hook-libs">
332
          <title>List of available hooks libraries</title>
333 334 335
          <tgroup cols="3">
          <colspec colname="name"/>
          <colspec colname="avail"/>
336
          <colspec colname="module"/>
337
          <colspec colname="description"/>
338 339 340 341 342
          <thead>
            <row>
              <entry>Name</entry>
              <entry>Availability</entry>
              <entry>Since</entry>
Thomas Markwalder's avatar
Thomas Markwalder committed
343
              <entry>Load by process</entry>
344 345 346 347 348 349 350 351 352
              <entry>Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>user_chk</entry>
              <entry>Kea sources</entry>
              <entry>Kea 0.8</entry>
353 354
              <entry>
                <simplelist>
355 356
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
357 358
                </simplelist>
              </entry>
359 360
              <entry>Reads known users list from a file. Unknown users
              will be assigned a
361
              lease from the last subnet defined in the configuration file,
362 363 364 365
              e.g. to redirect them a captive portal. This demonstrates how an
              external source of information can be used to influence the Kea
              allocation engine. This hook is part of the Kea source code and is
              available in the src/hooks/dhcp/user_chk directory.</entry>
366 367 368 369 370
            </row>
            <row>
              <entry>Forensic Logging</entry>
              <entry>Support customers</entry>
              <entry>Kea 1.1.0</entry>
371 372
              <entry>
                <simplelist>
373 374
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
375 376
                </simplelist>
              </entry>
377
              <entry>This library provides hooks that record a detailed log of
378 379 380 381 382 383
              lease assignments and renewals into a set of log files. In many
              legal jurisdictions companies, especially ISPs, must record
              information about the addresses they have leased to DHCP
              clients. This library is designed to help with that
              requirement. If the information that it records is sufficient it
              may be used directly. If your jurisdiction requires that you save
384
              a different set of information, you may use it as a template or
385 386 387
              example and create your own custom logging hooks.</entry>
            </row>
            <row>
Francis Dupont's avatar
Francis Dupont committed
388
              <entry>Flexible Identifier</entry>
389
              <entry>Support customers</entry>
390
              <entry>Kea 1.2.0</entry>
391 392
              <entry>
                <simplelist>
393 394
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
395 396
                </simplelist>
              </entry>
397 398 399 400
              <entry>Kea software provides a way to handle host reservations
              that include addresses, prefixes, options, client classes and
              other features. The reservation can be based on hardware address,
              DUID, circuit-id or client-id in DHCPv4 and using hardware address
401
              or DUID in DHCPv6. However, there are sometimes scenarios where the
402 403 404
              reservation is more complex, e.g. uses other options that
              mentioned above, uses part of specific options or perhaps even a
              combination of several options and fields to uniquely identify a
Tomek Mrugalski's avatar
Tomek Mrugalski committed
405
              client. Those scenarios are addressed by the Flexible Identifiers
406
              hook application. It allows defining an expression, similar to
Francis Dupont's avatar
Francis Dupont committed
407
              the one used in client classification,
408 409 410
              e.g. substring(relay6[0].option[37],0,6). Each incoming packet is
              evaluated against that expression and its value is then searched
              in the reservations database.
411 412
              </entry>
            </row>
413 414 415 416
            <row>
              <entry>Host Commands</entry>
              <entry>Support customers</entry>
              <entry>Kea 1.2.0</entry>
417 418
              <entry>
                <simplelist>
419 420
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
421 422
                </simplelist>
              </entry>
423 424 425 426 427 428 429 430 431 432 433 434 435
              <entry>Kea provides a way to store host reservations in a
              database. In many larger deployments it is useful to be able to
              manage that information while the server is running. This library
              provides management commands for adding, querying and deleting
              host reservations in a safe way without restarting the server.
              In particular, it validates the parameters, so an attempt to
              insert incorrect data, e.g. add a host with conflicting identifier
              in the same subnet will be rejected. Those commands are
              exposed via command channel (JSON over unix sockets) and Control
              Agent (JSON over RESTful interface). Additional commands and
              capabilities related to host reservations will be added in the
              future.</entry>
            </row>
436 437 438 439
            <row>
              <entry>Subnet Commands</entry>
              <entry>Support customers</entry>
              <entry>Kea 1.3.0</entry>
440 441
              <entry>
                <simplelist>
442 443
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
444 445
                </simplelist>
              </entry>
446 447 448
              <entry>In deployments in which subnet configuration needs to
              be frequently updated, it is a hard requirement that such updates be
              performed without the need for a full DHCP server reconfiguration
449
              or restart. This hooks library allows for incremental changes
450
              to the subnet configuration such as: adding a subnet, removing
451 452 453 454 455 456
              a subnet. It also allows for listing all available subnets and
              fetching detailed information about a selected subnet. The
              commands exposed by this library do not affect other subnets
              or configuration parameters currently used by the server.
              </entry>
            </row>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
457 458 459 460 461

            <row>
              <entry>Lease Commands</entry>
              <entry>Kea sources</entry>
              <entry>Kea 1.3.0</entry>
462 463
              <entry>
                <simplelist>
464 465
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
466 467
                </simplelist>
              </entry>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
468 469 470 471 472 473 474 475 476 477 478
              <entry>The lease commands hook library offers a number of new
              commands used to manage leases. Kea provides a way to store lease
              information in various backends: memfile, MySQL, PostgreSQL and
              Cassandra. This library provides a unified interface that can
              manipulate leases in an unified, safe way. In particular, it
              allows: manipulate leases in memfile while Kea is running, sanity
              check changes, check lease existence and remove all leases
              belonging to specific subnet. It can also catch more obscure
              errors, like adding a lease with subnet-id that does not exist in
              the configuration or configuring a lease to use an address that is
              outside of the subnet to which it is supposed to belong.
479
              It provides a way to manage user contexts associated with leases.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
480 481 482
              </entry>
            </row>

483 484
            <row>
              <entry>High Availability</entry>
485
              <entry>Kea sources</entry>
486
              <entry>Kea 1.4.0</entry>
487 488
              <entry>
                <simplelist>
489 490
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
491 492
                </simplelist>
              </entry>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
493 494 495 496 497 498 499 500 501 502 503 504 505 506 507
              <entry>Minimizing a risk of DHCP service unavailability is
              achieved by setting up a pair of the DHCP servers in a network.
              Two modes of operation are supported. The first one is called load
              balancing and is sometimes referred to as active-active. Each
              server can handle selected group of clients in this network or all
              clients, if it detects that its partner has became unavailable.
              It is also possible
              to designate one server to serve all DHCP clients, and leave
              another server as "standby". This mode is called hot standby and
              is sometimes referenced to as active-passive. This server will
              activate its DHCP function when it detects that its partner is not
              available.  Such cooperation between the DHCP servers requires
              that these servers constantly communicate with each other to send
              updates about allocated leases and to periodically test whether
              their partners are still operational. The hook library also
508
              provides an ability to send lease updates to external backup
Tomek Mrugalski's avatar
Tomek Mrugalski committed
509 510
              server, making it much easier to have a replacement that is almost
              up to date. The "libdhcp_ha" library provides such functionality
511
              for Kea DHCP servers.
512 513
              </entry>
            </row>
514 515 516 517
            <row>
              <entry>Radius</entry>
              <entry>Support customers</entry>
              <entry>Kea 1.4.0</entry>
518 519
              <entry>
                <simplelist>
520 521
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
522 523
                </simplelist>
              </entry>
524 525 526 527 528 529 530 531 532 533 534 535 536
              <entry>The RADIUS Hook library allows Kea to interact with the
              RADIUS servers using access and accounting mechanisms. The access
              mechanism may be used for access control, assigning specific IPv4
              or IPv6 addresses reserved by RADIUS, dynamically assigning
              addresses from designated pools chosen by RADIUS or rejecting
              the client's messages altogether. The accounting mechanism allows
              RADIUS server to keep track of device activity over time.
              </entry>
            </row>
            <row>
              <entry>Host Cache</entry>
              <entry>Support customers</entry>
              <entry>Kea 1.4.0</entry>
537 538
              <entry>
                <simplelist>
539 540
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
541 542
                </simplelist>
              </entry>
543 544 545 546 547 548 549 550 551 552
              <entry>Some of the database backends, such as RADIUS, are
              considered slow and may take a long time to respond. Since Kea in
              general is synchronous, the backend performance directly affects
              the DHCP performance. To minimize the impact and improve
              performance, the Host Cache library provides a way to cache
              responses from other hosts. This includes negative caching,
              i.e. the ability to remember that there is no client information
              in the database.
              </entry>
            </row>
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567
            <row>
              <entry>Class Commands</entry>
              <entry>Support customers</entry>
              <entry>Kea 1.5.0</entry>
              <entry>
                <simplelist>
                  <member>kea-dhcp4</member>
                  <member>kea-dhcp6</member>
                </simplelist>
              </entry>
              <entry>This Class Cmds hooks library allows for adding, updating
              deleting and fetching configured DHCP client classes without the
              need to restart the DHCP server.
              </entry>
            </row>
568 569 570 571 572
          </tbody>
          </tgroup>
          </table>

      </para>
573
      <para>
574
        ISC hopes to see more hooks libraries become available as time
575
        progresses, both developed internally and externally. Since
576
        this list may evolve dynamically, we decided to keep it on a
577
        wiki page, available at this link: <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://oldkea.isc.org/wiki/Hooks">http://oldkea.isc.org/wiki/Hooks</link>.
578 579
        If you are a developer or are aware of any hooks libraries not
        listed there, please send a note to the kea-users or kea-dev
580
        mailing lists and someone will update it.
581
      </para>
582 583 584
      <para>
        The libraries developed by ISC are described in detail in the following sections.
      </para>
585
      <section>
586
        <title>user_chk: Checking User Access</title>
587
        <para>
588
          The user_chk library is the first hooks library published by ISC. It
589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606
          attempts to serve several purposes:

          <itemizedlist>
            <listitem>
              <para>To assign "new" or "unregistered" users to a
              restricted subnet, while "known" or "registered" users are assigned
              to unrestricted subnets.</para>
            </listitem>
            <listitem>
              <para>To allow DHCP response options or vendor option
              values to be customized based upon user identity. </para>
            </listitem>
            <listitem>
              <para>To provide a real time record of the user registration
              activity which can be sampled by an external consumer.</para>
            </listitem>
            <listitem>
              <para> To serve as a demonstration of various capabilities
607
              possible using the hooks interface.</para>
608 609 610 611
            </listitem>
          </itemizedlist>
        </para>
        <para>
Francis Dupont's avatar
Francis Dupont committed
612
          Once loaded, the library allows segregating incoming requests into
613 614 615 616 617 618 619 620
          known and unknown clients. For known clients, the packets are
          processed mostly as usual, except it is possible to override certain
          options being sent. That can be done on a per host basis. Clients
          that are not on the known hosts list will be treated as unknown and
          will be assigned to the last subnet defined in the configuration file.
        </para>

        <para>
621
          As an example of use, this behavior may be used to put unknown users into a
622 623
          separate subnet that leads to a walled garden, where they can only
          access a registration portal. Once they fill in necessary data, their
624
          details are added to the known clients file and they get a proper
625 626 627
          address after their device is restarted.
        </para>

628 629 630 631
        <note><para>This library was developed several years before the host
        reservation mechanism has become available. Currently host reservation is
        much more
        powerful and flexible, but nevertheless the user_chk capability to consult
632
        and external source of information about clients and alter Kea's
633
        behavior is useful and remains of educational value.
634 635 636 637
        </para></note>

        <para>
          The library reads the /tmp/user_chk_registry.txt file while being
638
          loaded and each time an incoming packet is processed. The file is expected
639 640 641 642
          to have each line contain a self-contained JSON snippet which must
          have the following two entries:

          <itemizedlist>
643 644 645 646
            <listitem><para><command>type</command>, whose value
            is "HW_ADDR" for IPv4 users or "DUID" for IPv6
            users</para></listitem>
            <listitem><para><command>id</command>, whose value is
Francis Dupont's avatar
Francis Dupont committed
647
            either the hardware address or the DUID from the request
648 649
            formatted as a string of hex digits, with or without
            ":" delimiters.</para></listitem>
650 651 652 653 654
          </itemizedlist>

and may have the zero or more of the following entries:

          <itemizedlist>
655 656 657 658 659
            <listitem><para><command>bootfile</command> whose value
            is the pathname of the desired file</para></listitem>
            <listitem><para><command>tftp_server</command> whose
            value is the hostname or IP address of the desired
            server</para></listitem>
660 661
          </itemizedlist>

662
          A sample user registry file is shown below:
663 664 665 666 667 668 669 670

<screen>{ "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:04", "bootfile" : "/tmp/v4bootfile" }
{ "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:06", "tftp_server" : "tftp.v4.example.com" }
{ "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:04", "bootfile" : "/tmp/v6bootfile" }
{ "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:06", "tftp_server" : "tftp.v6.example.com" }</screen>

        </para>

671
        <para>As with any other hooks libraries provided by ISC, internals of the
672
        user_chk code are well documented. You can take a look at the  <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/d8/db2/libdhcp_user_chk.html">Kea Developer's Guide section dedicated to the user_chk library</link>
673
        that discusses how the code works internally. That, together with
674
        our general entries in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen">Hooks
675
        Framework section</link> should give you some pointers how to extend
676 677
        this library and perhaps even write your own from scratch.</para>

678
      </section>
679
      <section>
680
        <title>legal_log: Forensic Logging Hooks</title>
681
        <para>
682
        This section describes the forensic log hooks library. This library
Francis Dupont's avatar
Francis Dupont committed
683
        provides hooks that record a detailed log of lease assignments
684
        and renewals into a set of log files.  Currently this library
685
        is only available to ISC customers with a support contract.
686 687

        <note>
688
          <para>This library may only be loaded by <command>kea-dhcp4</command>
689 690 691
          or <command>kea-dhcp6</command> process.
          </para>
        </note>
692 693 694 695 696 697 698 699 700 701
        </para>
        <para>
        In many legal jurisdictions companies, especially ISPs, must record
        information about the addresses they have leased to DHCP clients.
        This library is designed to help with that requirement.  If the
        information that it records is sufficient it may be used directly.
        If your jurisdiction requires that you save a different set of
        information you may use it as a template or example and create your
        own custom logging hooks.
        </para>
702 703 704 705 706 707 708
        <para>
        This logging is done as a set of hooks to allow it to be customized
        to any particular need.  Modifying a hooks library is easier and
        safer than updating the core code.  In addition by using the hooks
        features those users who don't need to log this information can
        leave it out and avoid any performance penalties.
        </para>
709 710 711 712 713 714 715 716 717
        <section>
        <title>Log File Naming</title>
          <para>
          The names for the log files have the following form:
          </para>
<screen>
path/base-name.CCYYMMDD.txt
</screen>
          <para>
718
          The "path" and "base-name" are supplied in the
719
          configuration as described below see
720
          <xref linkend="forensic-log-configuration"/>.  The next part of the name is
721 722 723 724 725
          the date the log file was started, with four digits for year, two digits
          for month and two digits for day.  The file is rotated on a daily basis.
          </para>
          <note><para>
          When running Kea servers for both DHCPv4 and DHCPv6 the log names must
726
          be distinct.  See the examples in <xref linkend="forensic-log-configuration"/>.
727 728 729 730 731 732 733 734 735 736
          </para></note>
        </section>
        <section>
        <title>DHCPv4 Log Entries</title>
          <para>
          For DHCPv4 the library creates entries based on DHCPREQUEST messages
          and corresponding DHCPv4 leases intercepted by lease4_select
          (for new leases) and lease4_renew (for renewed leases) hooks.
          </para>
          <para>
Francis Dupont's avatar
Francis Dupont committed
737 738
          An entry is a single string with no embedded end-of-line markers,
          a prepended timestamp and has the following sections:
739
<screen>
740
timestamp address duration device-id {client-info} {relay-info} {user-context}
741 742 743 744 745
</screen>
          </para>
          <para>
          Where:
          <itemizedlist>
Francis Dupont's avatar
Francis Dupont committed
746 747 748 749 750
            <listitem><para>
            timestamp - the current date and time the log entry was written
            in "%Y-%m-%d %H:%M:%S %Z" strftime format ("%Z" is the time zone
            name).
            </para></listitem>
751 752 753 754 755 756 757
            <listitem><para>
            address - the leased IPv4 address given out and whether it was
            assigned or renewed.
            </para></listitem>
            <listitem><para>
            duration - the lease lifetime expressed in days (if present),
            hours, minutes and seconds.  A lease lifetime of 0xFFFFFFFF will be
758
            denoted with the text "infinite duration".
759 760 761 762 763 764 765 766 767 768
            </para></listitem>
            <listitem><para>
            device-id - the client's hardware address shown as numerical type
            and hex digit string.
            </para></listitem>
            <listitem><para>
            client-info - the DHCP client id option (61) if present, shown as
            a hex string.
            </para></listitem>
            <listitem><para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
769 770 771
            relay-info - for relayed packets the giaddr and the RAI circuit-id,
            remote-id and subscriber-id options (option 82 sub
            options: 1, 2 and 6) if present.
772 773
            The circuit id and remote id are presented as hex strings
            </para></listitem>
774 775 776
            <listitem><para>
            user-context - the optional user context associated to the lease.
            </para></listitem>
777 778 779 780 781 782
          </itemizedlist>
          </para>
          <para>
          For instance (line breaks added for readability, they would not
          be present in the log file).
<screen>
783 784 785
2018-01-06 01:02:03 CET Address: 192.2.1.100 has been renewed for 1 hrs 52 min 15 secs to a device with hardware address:
hwtype=1 08:00:2b:02:3f:4e, client-id: 17:34:e2:ff:09:92:54 connected via relay at address: 192.2.16.33,
identified by circuit-id: 68:6f:77:64:79 and remote-id: 87:f6:79:77:ef
786
</screen>
787 788 789 790 791 792 793 794 795 796 797
        </para>
        <para>
        In addition to logging lease activity driven by DHCPv4 client traffic, it also
        logs entries for the following lease management control channel commands:
        lease4-add, lease4-update, and lease4-del.  Each entry is a single string
        with no embedded end-of-line markers and they will typically have the following
        forms:
        </para>
        <para>
        <command>lease4-add:</command>
<screen>
Francis Dupont's avatar
Francis Dupont committed
798
*timestamp* Administrator added a lease of address: *address* to a device with hardware address: *device-id*
799 800 801 802 803 804 805
</screen>
        Dependent on the arguments of the add command, it may also include the
        client-id and duration.
        </para>
        <para>
        Example:
<screen>
806
2018-01-06 01:02:03 CET Administrator added a lease of address: 192.0.2.202 to a device with hardware address:
807
1a:1b:1c:1d:1e:1f for 1 days 0 hrs 0 mins 0 secs
808 809 810 811 812
</screen>
        </para>
        <para>
        <command>lease4-update:</command>
<screen>
Francis Dupont's avatar
Francis Dupont committed
813
*timestamp* Administrator updated information on the lease of address: *address* to a device with hardware address: *device-id*
814 815 816 817 818 819 820
</screen>
        Dependent on the arguments of the update command, it may also include the
        client-id and lease duration.
        </para>
        <para>
        Example:
<screen>
821
2018-01-06 01:02:03 CET Administrator updated information on the lease of address: 192.0.2.202 to a device
822
with hardware address: 1a:1b:1c:1d:1e:1f, client-id: 1234567890
823 824 825 826 827 828
</screen>
        </para>
        <para>
        <command>lease4-del:</command>
        Deletes have two forms, one by address and one by identifier and identifier type:
<screen>
Francis Dupont's avatar
Francis Dupont committed
829
*timestamp* Administrator deleted the lease for address: *address*
830 831 832
</screen>
        or
<screen>
Francis Dupont's avatar
Francis Dupont committed
833
*timestamp* Administrator deleted a lease for a device identified by: *identifier-type* of *identifier*
834 835 836 837 838 839
</screen>
        Currently only a type of @b hw-address (hardware address) is supported.
        </para>
        <para>
        Examples:
<screen>
Francis Dupont's avatar
Francis Dupont committed
840
2018-01-06 01:02:03 CET Administrator deleted the lease for address: 192.0.2.202
841

Francis Dupont's avatar
Francis Dupont committed
842
2018-01-06 01:02:12 CET Administrator deleted a lease for a device identified by: hw-address of 1a:1b:1c:1d:1e:1f
843 844
</screen>
        </para>
845
        </section>
846

847 848 849 850 851 852 853 854
        <section>
        <title>DHCPv6 Log Entries</title>
          <para>
          For DHCPv6 the library creates entries based on lease management
          actions intercepted by the lease6_select (for new leases), lease6_renew
          (for renewed leases) and lease6_rebind (for rebound leases).
          </para>
          <para>
Francis Dupont's avatar
Francis Dupont committed
855 856
          An entry is a single string with no embedded end-of-line markers,
          a prepended timestamp and has the following sections:
857
<screen>
858
timestamp address duration device-id {relay-info}* {user-context}
859 860 861 862 863
</screen>
          </para>
          <para>
          Where:
          <itemizedlist>
Francis Dupont's avatar
Francis Dupont committed
864 865 866 867 868
            <listitem><para>
            timestamp - the current date and time the log entry was written
            in "%Y-%m-%d %H:%M:%S %Z" strftime format ("%Z" is the time zone
            name).
            </para></listitem>
869 870 871 872 873 874 875 876 877 878 879 880 881 882
            <listitem><para>
            address - the leased IPv6 address or prefix given out and whether
            it was assigned or renewed.
            </para></listitem>
            <listitem><para>
            duration - the lease lifetime expressed in days (if present),
            hours, minutes and seconds.  A lease lifetime of 0xFFFFFFFF will be
            denoted with the text "infinite duration".
            </para></listitem>
            <listitem><para>
            device-id - the client's DUID and hardware address (if present).
            </para></listitem>
            <listitem><para>
            relay-info - for relayed packets the content of relay agent
Tomek Mrugalski's avatar
Tomek Mrugalski committed
883 884 885 886 887 888 889
            messages, remote-id (code 37), subscriber-id (code 38) and
            interface-id (code 18) options if present. Note that
            interface-id option, if present, identifies the whole interface the
            relay agent received the message on. This typically translates to a
            single link in your network, but it depends on your specific network
            topology. Nevertheless, this is useful information to better scope
            down the location of the device, so it is being recorded, if present.
890
            </para></listitem>
891 892 893
            <listitem><para>
            user-context - the optional user context associated to the lease.
            </para></listitem>
894 895 896 897 898 899
          </itemizedlist>
          </para>
          <para>
          For instance (line breaks added for readability, they would not
          be present in the log file).
<screen>
900 901 902 903
2018-01-06 01:02:03 PST Address:2001:db8:1:: has been assigned for 0 hrs 11 mins 53 secs
to a device with DUID: 17:34:e2:ff:09:92:54 and hardware address: hwtype=1 08:00:2b:02:3f:4e
(from Raw Socket) connected via relay at address: fe80::abcd for client on link address: 3001::1,
hop count: 1, identified by remote-id: 01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f
904
</screen>
905 906 907 908 909 910 911 912 913 914 915
        </para>
        <para>
        In addition to logging lease activity driven by DHCPv6 client traffic, it also
        logs entries for the following lease management control channel commands:
        lease6-add, lease6-update, and lease6-del.  Each entry is a single string
        with no embedded end-of-line markers and they will typically have the following
        forms:
        </para>
        <para>
        <command>lease6-add:</command>
<screen>
Francis Dupont's avatar
Francis Dupont committed
916
*timestamp* Administrator added a lease of address: *address* to a device with DUID: *DUID*
917 918 919 920 921 922
</screen>
        Dependent on the arguments of the add command, it may also include the hardware address and duration.
        </para>
        <para>
        Example:
<screen>
923 924
2018-01-06 01:02:03 PST Administrator added a lease of address: 2001:db8::3 to a device with DUID:
1a:1b:1c:1d:1e:1f:20:21:22:23:24 for 1 days 0 hrs 0 mins 0 secs
925 926 927 928 929
</screen>
        </para>
        <para>
        <command>lease6-update:</command>
<screen>
Francis Dupont's avatar
Francis Dupont committed
930
*timestamp* Administrator updated information on the lease of address: *address* to a device with DUID: *DUID*
931 932 933 934 935 936
</screen>
        Dependent on the arguments of the update command, it may also include the hardware address and lease duration.
        </para>
        <para>
        Example:
<screen>
937 938
2018-01-06 01:02:03 PST Administrator updated information on the lease of address: 2001:db8::3 to a device with
DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24, hardware address: 1a:1b:1c:1d:1e:1f
939 940 941 942 943 944
</screen>
        </para>
        <para>
        <command>lease6-del:</command>
        Deletes have two forms, one by address and one by identifier and identifier type:
<screen>
Francis Dupont's avatar
Francis Dupont committed
945
*timestamp* Administrator deleted the lease for address: *address*
946 947 948
</screen>
        or
<screen>
Francis Dupont's avatar
Francis Dupont committed
949
*timestamp* Administrator deleted a lease for a device identified by: *identifier-type* of *identifier*
950 951 952 953 954 955
</screen>
        Currently only a type of DUID is supported.
        </para>
        <para>
Examples:
<screen>
Francis Dupont's avatar
Francis Dupont committed
956
2018-01-06 01:02:03 PST Administrator deleted the lease for address: 2001:db8::3
957

Francis Dupont's avatar
Francis Dupont committed
958
2018-01-06 01:02:11 PST Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e:1f:20:21:22:23:24
959 960
</screen>
        </para>
961
        </section>
962
        <section xml:id="forensic-log-configuration">
963
        <title>Configuring the Forensic Log Hooks</title>
964 965 966 967 968 969
          <para>
          To use this functionality the hook library must be included in the
          configuration of the desired DHCP server modules. The legal_log
          library is installed alongside the Kea libraries in
          <filename>[kea-install-dir]/lib</filename> where
          <filename>kea-install-dir</filename> is determined by the
970
          "--prefix" option of the configure script.  It defaults to
971 972 973 974 975
          <filename>/usr/local</filename>.  Assuming the
          default value then, configuring kea-dhcp4 to load the legal_log
          library could be done with the following Kea4 configuration:
<screen>
"Dhcp4": { <userinput>
976 977 978 979 980 981 982 983
    "hooks-libraries": [
        {
            "library": "/usr/local/lib/libdhcp_legal_log.so",
            "parameters": {
                "path": "/var/kea/var",
                "base-name": "kea-forensic4"
            }
        },
984 985 986 987 988 989 990 991 992
        ...
    ] </userinput>
}
</screen>
          </para>
          <para>
          To configure it for kea-dhcp6, the commands are simply as shown below:
<screen>
"Dhcp6": { <userinput>
993 994 995 996 997 998 999 1000
    "hooks-libraries": [
        {
            "library": "/usr/local/lib/libdhcp_legal_log.so",
            "parameters": {
                "path": "/var/kea/var",
                "base-name": "kea-forensic6"
            }
        },
1001 1002 1003 1004 1005 1006 1007 1008 1009
        ...
    ] </userinput>
}
</screen>
          </para>
          <para>
          Two Hook Library parameters are supported:
          <itemizedlist>
            <listitem><para>
1010
            path - the directory in which the forensic file(s) will be written.  The
1011 1012 1013 1014 1015
            default value is
            <filename>[prefix]/kea/var</filename>.  The directory must exist.
            </para></listitem>
            <listitem><para>
            base-name - an arbitrary value which is used in conjunction with
Francis Dupont's avatar
Francis Dupont committed
1016
            the current system date to form the current forensic file name.  It defaults
1017 1018 1019 1020
            to <filename>kea-legal</filename>.
            </para></listitem>
          </itemizedlist>
          </para>
1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073

          <para>
            If it is desired to restrict forensic logging to certain subnets, the
            "legal-logging" boolean parameter can be specified within a user context of
            these subnets. For example:
<screen>
"Dhcpv4" {
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "pools": [
                {
                     "pool": "192.0.2.1 - 192.0.2.200"
                }
            ],
            <userinput>"user-context": {
                "legal-logging": false
            }</userinput>
        }
    ]
}
</screen>
              disables legal logging for the subnet "192.0.2.0/24". If this parameter
              is not specified, it defaults to 'true', which enables legal logging for
              the subnet.
          </para>

          <para>
            The following example demonstrates how to selectively disable legal logging
            for an IPv6 subnet.
<screen>
"Dhcpv6": {
    "subnet6": [
        {
            "subnet": "2001:db8:1::/64",
            "pools": [
                 {
                     "pool": "2001:db8:1::1-2001:db8:1::ffff"
                 }
            ],
            <userinput>"user-context": {
                "legal-logging": false
            }</userinput>
        }
    ]
}
</screen>
          </para>

          <para>
            See <xref linkend="dhcp4-user-contexts"/> and <xref linkend="dhcp6-user-contexts"/>
            to learn more about user contexts in Kea configuration.
          </para>
1074
        </section>
Francis Dupont's avatar
Francis Dupont committed
1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088

        <section id="forensic-log-database">
        <title>Database backend</title>
          <para>
          Log entries can be inserted into a database when Kea is configured
          with database backend support: a table named 'logs' is used with a
          timestamp (timeuuid for Cassandra CQL) generated by the database
          software and a text log with the same format than for files
          without the timestamp.
          </para>
          <para>
          Please refer to <xref linkend="mysql-database"/> for MySQL,
          to <xref linkend="pgsql-database"/> for PostgreSQL or
          to <xref linkend="cql-database"/> for Cassandra CQL.
1089
          The logs table is part of the Kea database schemas.
Francis Dupont's avatar
Francis Dupont committed
1090 1091 1092 1093 1094
          </para>
          <para>
          Configuration parameters are extended by standard lease database
          parameters as defined in <xref linkend="database-configuration4"/>.
          The "type" parameter should be "mysql", "postgresql",  "cql" or
1095
          be "logfile". When it is absent or set to "logfile" files are
Francis Dupont's avatar
Francis Dupont committed
1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115
          used.
          </para>
          <para>
          This database feature is experimental and will be likely
          improved, for instance to add an address / prefix index (currently
          the only index is the timestamp). No specific tools is provided
          to operate the database but standard tools are applicable,
          for instance to dump the logs table from a CQL database:
<screen>
$ <userinput>echo 'SELECT dateOf(timeuuid), log FROM logs;' | cqlsh -k <replaceable>database-name</replaceable></userinput>

 system.dateof(timeuuid)         | log
---------------------------------+---------------------------------------
 2018-01-06 01:02:03.227000+0000 | Address: 192.2.1.100 has been renewed ...
 ...
(12 rows)
$
</screen>
          </para>
        </section>
1116
      </section>
1117

1118
      <section xml:id="flex-id">
1119 1120
        <title>flex_id: Flexible Identifiers for Host Reservations</title>
        <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
1121 1122 1123 1124 1125 1126
          This section describes a hook application dedicated to generate
          flexible identifiers for host reservation. Kea software provides a way
          to handle host reservations that include addresses, prefixes, options,
          client classes and other features. The reservation can be based on
          hardware address, DUID, circuit-id or client-id in DHCPv4 and using
          hardware address or DUID in DHCPv6. However, there are sometimes
1127
          scenarios where the reservation is more complex, e.g. uses other
Tomek Mrugalski's avatar
Tomek Mrugalski committed
1128 1129 1130
          options that mentioned above, uses part of specific options or perhaps
          even a combination of several options and fields to uniquely identify
          a client. Those scenarios are addressed by the Flexible Identifiers
1131 1132 1133
        hook application.</para>

        <para>Currently this library is only available to ISC customers with a
1134 1135 1136
        support contract.

        <note>
1137
          <para>This library may only be loaded by <command>kea-dhcp4</command>
1138 1139 1140 1141
          or <command>kea-dhcp6</command> process.
          </para>
        </note>
      </para>
1142

1143
        <para>The library allows for defining an expression, using notation
1144
        initially used for client classification only. See <xref linkend="classification-using-expressions"/> for detailed description
1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157
        of the syntax available. One notable difference is that for client
        classification the expression currently has to evaluate to either true
        or false, while the flexible identifier expression is expected to
        evaluate to a string that will be used as identifier. It is a valid case
        for the expression to evaluate to empty string (e.g. in cases where a
        client does not sent specific options). This expression is then
        evaluated for each incoming packet. This evaluation generates an
        identifier that is used to identify the client. In particular, there may
        be host reservations that are tied to specific values of the flexible
        identifier.</para>

        <para>
          The library can be loaded in similar way as other hook libraries. It
1158 1159
          takes a mandatory parameter identifier-expression and optional
          boolean parameter replace-client-id:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
1160 1161 1162 1163 1164 1165
<screen>
"Dhcp6": { <userinput>
    "hooks-libraries": [
        {
            "library": "/path/libdhcp_flex_id.so",
            "parameters": {
1166 1167
                "identifier-expression": "<userinput>expression</userinput>",
                "replace-client-id": "<userinput>false</userinput>"
Tomek Mrugalski's avatar
Tomek Mrugalski committed
1168 1169 1170 1171 1172 1173
            }
        },
        ...
    ] </userinput>
}
</screen>
1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191
        </para>

        <para>
          The flexible identifier library supports both DHCPv4 and DHCPv6.
        </para>

        <para>
          EXAMPLE: Let's consider a case of an IPv6 network that has an
          independent interface for each of the connected customers. Customers
          are able to plug in whatever device they want, so any type of
          identifier (e.g. a client-id) is unreliable. Therefore the operator
          may decide to use an option inserted by a relay agent to differentiate
          between clients. In this particular deployment, the operator verified
          that the interface-id is unique for each customer facing
          interface. Therefore it is suitable for usage as reservation. However,
          only the first 6 bytes of the interface-id are interesting, because
          remaining bytes are either randomly changed or not unique between
          devices. Therefore the customer decided to use first 6 bytes of the
1192 1193 1194
          interface-id option inserted by the relay agent. After adding "flex-id"
          host-reservation-identifiers goal can be achieved by using the
          following configuration:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
1195 1196 1197 1198 1199 1200 1201 1202
<screen>
"Dhcp6": {
    "subnet6": [{ ..., // subnet definition starts here
    "reservations": [
        <userinput>"flex-id": "'port1234'"</userinput>, // value of the first 8 bytes of the interface-id
        "ip-addresses": [ "2001:db8::1" ]
    ],
    }], // end of subnet definitions
1203
    "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
Tomek Mrugalski's avatar
Tomek Mrugalski committed
1204 1205 1206 1207
    "hooks-libraries": [
        {
            "library": "/path/libdhcp_flex_id.so",
            "parameters": {
1208
                "identifier-expression": "<userinput>substring(relay6[0].option[18].hex,0,8)</userinput>"
Tomek Mrugalski's avatar
Tomek Mrugalski committed
1209 1210 1211 1212 1213 1214
            }
        },
        ...
    ]
}
</screen>
1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233
        </para>

        <para>
          NOTE: Care should be taken when adjusting the expression. If the
          expression changes, then all the flex-id values may change, possibly
          rendering all reservations based on flex-id unusable until they're
          manually updated. Therefore it is strongly recommended to start with
          the expression and a handful reservations, adjust the expression as
          needed and only after it was confirmed the expression does exactly
          what is expected out of it go forward with host reservations on any
          broader scale.
        </para>

        <para>
          flex-id values in host reservations can be specified in two
          ways. First, they can be expressed as hex string, e.g. bar string
          can be represented as 626174. Alternatively, it can be expressed
          as quoted value (using double and single quotes), e.g. "'bar'".
          The former is more convenient for printable characters, while hex
1234 1235 1236
          string values are more convenient for non-printable characters
          and does not require the use of the <command>hexstring</command>
          operator.
1237
        </para>
1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257
<screen>
"Dhcp6": {
    "subnet6": [{ ..., // subnet definition starts here
    "reservations": [
        <userinput>"flex-id": "01:02:03:04:05:06"</userinput>, // value of the first 8 bytes of the interface-id
        "ip-addresses": [ "2001:db8::1" ]
    ],
    }], // end of subnet definitions
    "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers</