hooks.xml 24.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
]>

  <chapter id="hooks-libraries">
    <title>Hooks Libraries</title>
    <section id="hooks-libraries-introduction">
      <title>Introduction</title>
      <para>
      Although Kea offers a lot of flexibility, there may be cases where
      its behavior needs customisation.  To accommodate this possibility,
      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>
      <para>
      Hooks libraries are attached to individual Kea processes, not to
      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
28 29 30 31 32 33
      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.
34 35 36 37
      </para>
      <para>
      The next section describes how to configure hooks libraries. If you
      are interested in writing your own hooks library, information can be
38
      found in the <ulink url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Kea
39 40 41 42 43 44 45 46 47 48
      Developer's Guide</ulink>.
      </para>
    </section> <!-- end Introduction -->
    <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
49 50 51
      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:
52 53 54 55
<screen>
<userinput>"Dhcp4": {
    :
    "hooks-libraries": [
56 57 58 59
        {
            "library": "/opt/charging.so"
        },
        {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
60 61 62 63 64 65 66 67 68 69 70
            "library": "/opt/local/notification.so",
            "parameters": {
                "mail": "spam@example.com",
                "floor": 13,
                "debug": false,
                "users": [ "alice", "bob", "charlie" ],
                "languages": {
                    "french": "bonjour",
                    "klingon": "yl'el"
                }
            }
71
        }
72 73 74 75 76
    ]
    :
}</userinput>
</screen>
      </para>
77

78
      <note><para>
79 80
        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
81
        a library.  The change was made in Kea 1.0 to facilitate the
82
        specification of library-specific parameters, a capability
83
        available in Kea 1.1.0 onwards.
84
      </para></note>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
85

86 87
        <note>
          <para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
88 89 90 91
          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.
92 93
          </para>
        </note>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
94 95 96 97 98 99 100 101 102 103 104

      <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
105 106
        explained in detail in the Hooks Developer's Guide in the "Configuring
        Hooks Libraries" section.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
107 108
      </para>

109 110 111 112 113 114 115 116 117 118 119 120 121
      <para>
      Notes:
        <itemizedlist mark='bullet'>
          <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
122 123 124 125 126 127 128 129 130 131 132 133
          </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>
134 135 136 137 138 139 140
        </itemizedlist>
      </para>
      <para>
      At the present time, only the kea-dhcp4 and kea-dhcp6 processes support
      hooks libraries.
      </para>
    </section>
141 142 143 144

    <section>
      <title>Available Hooks Libraries</title>
      <para>
145
      As described above, the hooks functionality provides a way to customize
146
      a Kea server without modifying the core code.  ISC has chosen to take
147 148 149
      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.
150 151
      </para>

152 153
      <note><para>
      Some of these libraries will be available with the base code while others
154 155
      will be shared with organizations supporting development of Kea
      , possibly as a 'benefit' or 'thank you' for helping to sustain
156
      the larger Kea project. If you would like to get access to those
157
      libraries, please consider taking out a support contract: this includes
158
      professional support, advance security notifications, input into our
159
      roadmap planning, and many other benefits, while helping
160 161 162 163 164 165
      making Kea sustainable in the long term.
      </para></note>

      <para>Currently the following libraries are available or planned from ISC:

        <table frame="all" id="hook-libs">
166
          <title>List of available hooks libraries</title>
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
          <tgroup cols='3'>
          <colspec colname='name' />
          <colspec colname='avail' />
          <colspec colname='description' />
          <thead>
            <row>
              <entry>Name</entry>
              <entry>Availability</entry>
              <entry>Since</entry>
              <entry>Description</entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>user_chk</entry>
              <entry>Kea sources</entry>
              <entry>Kea 0.8</entry>
185 186
              <entry>Reads known users list from a file. Unknown users
              will be assigned a
187
              lease from the last subnet defined in the configuration file,
188 189 190 191
              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>
192 193 194 195 196
            </row>
            <row>
              <entry>Forensic Logging</entry>
              <entry>Support customers</entry>
              <entry>Kea 1.1.0</entry>
197
              <entry>This library provides hooks that record a detailed log of
198 199 200 201 202 203
              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
204
              a different set of information, you may use it as a template or
205 206 207 208 209 210
              example and create your own custom logging hooks.</entry>
            </row>
            <row>
              <entry>Lightweight 4over6</entry>
              <entry>Support customers</entry>
              <entry>Autumn 2016</entry>
211 212 213
              <entry>Lightweight 4over6
              (<ulink url="http://tools.ietf.org/html/rfc7596">RFC 7596</ulink>)
              is a new IPv6 transition
214
              technology that provides IPv4 as a service in IPv6-only
215 216
              network. It assumes that dual-stack clients will get a regular IPv6
              address and IPv6 prefix, but only a fraction of an IPv4 address. The
217 218 219
              fraction is specified as port-set, which is essentially a range of
              TCP and UDP ports a client can use. By doing the transition on the
              client side, this technology eliminates the need to deploy
220
              expensive Carrier Grade NATs within the operator's network. The
221
              problem on the DHCP side is the non-trivial logic behind it: each
222 223 224
              client needs to receive an unique set of lightweight 4over6 options
              (<ulink url="http://tools.ietf.org/html/rfc7598">RFC 7598</ulink>),
              that include the IPv4 address (shared among several
225
              clients), port-set (which is unique among clients sharing the same
226
              IPv4 address) and a number of additional parameters. This hooks
227 228 229 230 231 232 233 234 235 236
              library will generate values of those options dynamically, thus
              eliminating the need to manually configure values for each client
              separately.
              </entry>
            </row>
          </tbody>
          </tgroup>
          </table>

      </para>
237
      <para>
238
        ISC hopes to see more hooks libraries become available as time
239
        progresses, both developed internally and externally. Since
240
        this list may evolve dynamically, we decided to keep it on a
241 242
        wiki page, available at this link: <ulink
        url="http://kea.isc.org/wiki/Hooks">http://kea.isc.org/wiki/Hooks</ulink>.
243 244
        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
245
        mailing lists and someone will update it.
246
      </para>
247
      <section>
248
        <title>user_chk: Checking User Access</title>
249
        <para>
250
          The user_chk library is the first hooks library published by ISC. It
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
          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
269
              possible using the hooks interface.</para>
270 271 272 273
            </listitem>
          </itemizedlist>
        </para>
        <para>
Andrei Pavel's avatar
Andrei Pavel committed
274
          Once loaded, the library allows segregating incoming requests into
275 276 277 278 279 280 281 282
          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>
283
          As an example of use, this behavior may be used to put unknown users into a
284 285
          separate subnet that leads to a walled garden, where they can only
          access a registration portal. Once they fill in necessary data, their
286
          details are added to the known clients file and they get a proper
287 288 289
          address after their device is restarted.
        </para>

290 291 292 293
        <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
294
        and external source of information about clients and alter Kea's
295
        behavior is useful and remains of educational value.
296 297 298 299
        </para></note>

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

          <itemizedlist>
305 306 307 308
            <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
Andrei Pavel's avatar
Andrei Pavel committed
309
            either the hardware address or the DUID from the request
310 311
            formatted as a string of hex digits, with or without
            ":" delimiters.</para></listitem>
312 313 314 315 316
          </itemizedlist>

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

          <itemizedlist>
317 318 319 320 321
            <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>
322 323
          </itemizedlist>

324
          A sample user registry file is shown below:
325 326 327 328 329 330 331 332

<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>

333
        <para>As with any other hooks libraries provided by ISC, internals of the
334 335 336 337 338 339 340 341
        user_chk code are well documented. You can take a look at the  <ulink
        url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/d8/db2/libdhcp_user_chk.html">Kea Developer's Guide section dedicated to the user_chk library</ulink>
        that discusses how the code works internally. That, together with
        our general entries in <ulink
        url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Hooks
        Framework section</ulink> should give you some pointers how to extend
        this library and perhaps even write your own from scratch.</para>

342
      </section>
343
      <section>
344
        <title>Forensic Logging Hooks</title>
345
        <para>
346
        This section describes the forensic log hooks library. This library
Andrei Pavel's avatar
Andrei Pavel committed
347
        provides hooks that record a detailed log of lease assignments
348
        and renewals into a set of log files.  Currently this library
349
        is only available to ISC customers with a support contract.
350 351 352 353 354 355 356 357 358 359
        </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>
360 361 362 363 364 365 366
        <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>
367 368 369 370 371 372 373 374 375 376 377
        <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>
          The &quot;path&quot; and &quot;base-name&quot; are supplied in the
          configuration as described below see
378
          <xref linkend="forensic-log-configuration"/>.  The next part of the name is
379 380 381 382 383
          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
384
          be distinct.  See the examples in <xref linkend="forensic-log-configuration"/>.
385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485
          </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>
          An entry is a single string with no embedded end-of-line markers
          and has the following sections:
<screen>
address duration device-id {client-info} {relay-info}
</screen>
          </para>
          <para>
          Where:
          <itemizedlist>
            <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
            denoted with the text &quot;infinite duration&quot;.
            </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>
            relay-info - for relayed packets the giaddr and the RAI circuit id
            and remote id options (option 82 sub options 1 and 2) if present.
            The circuit id and remote id are presented as hex strings
            </para></listitem>
          </itemizedlist>
          </para>
          <para>
          For instance (line breaks added for readability, they would not
          be present in the log file).
<screen>
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
</screen>
          </para>
        </section>
        <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>
          An entry is a single string with no embedded end-of-line markers
          and has the following sections:
<screen>
address duration device-id {relay-info}*
</screen>
          </para>
          <para>
          Where:
          <itemizedlist>
            <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
            messages, remote id and subscriber id options (x and xx) if present.
            </para></listitem>
          </itemizedlist>
          </para>
          <para>
          For instance (line breaks added for readability, they would not
          be present in the log file).
<screen>
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
</screen>
          </para>
        </section>
486 487
        <section id="forensic-log-configuration">
        <title>Configuring the Forensic Log Hooks</title>
488 489 490 491 492 493 494 495 496 497 498 499
          <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
          &quot;--prefix&quot; option of the configure script.  It defaults to
          <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>
500 501 502 503 504 505 506 507
    "hooks-libraries": [
        {
            "library": "/usr/local/lib/libdhcp_legal_log.so",
            "parameters": {
                "path": "/var/kea/var",
                "base-name": "kea-forensic4"
            }
        },
508 509 510 511 512 513 514 515 516
        ...
    ] </userinput>
}
</screen>
          </para>
          <para>
          To configure it for kea-dhcp6, the commands are simply as shown below:
<screen>
"Dhcp6": { <userinput>
517 518 519 520 521 522 523 524
    "hooks-libraries": [
        {
            "library": "/usr/local/lib/libdhcp_legal_log.so",
            "parameters": {
                "path": "/var/kea/var",
                "base-name": "kea-forensic6"
            }
        },
525 526 527 528 529 530 531 532 533
        ...
    ] </userinput>
}
</screen>
          </para>
          <para>
          Two Hook Library parameters are supported:
          <itemizedlist>
            <listitem><para>
534
            path - the directory in which the forensic file(s) will be written.  The
535 536 537 538 539
            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
540
            the current system date to form the current foresnic file name.  It defaults
541 542 543 544 545 546 547
            to <filename>kea-legal</filename>.
            </para></listitem>
          </itemizedlist>
          </para>
        </section>
      </section>
    </section>
548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566
    <section id="user-context">
      <title>User contexts</title>
      <para>Hook libraries can have their own configuration parameters. That is
      convenient if the parameter applies to the whole library. However,
      sometimes it is very useful if certain configuration entities are extended
      with additional configuration data. This is where the concept of user
      contexts comes in. A sysadmin can define an arbitrary set of data and
      attach it to Kea structures, as long as the data is specified as JSON map.
      In particular, it is possible to define fields that are integers, strings,
      boolean, lists and maps. It is possible to define nested structures of
      arbitrary complexity. Kea does not use that data on its own, simply stores
      and makes it available for the hook libraries.
      </para>
      <para>
        As of Kea 1.2, the only structures that allow user contexts are address
        and prefix pools, but it is expected to extend other structures with the
        user context capability.
      </para>
    </section>
567
   </chapter> <!-- hooks-libraries -->