hooks-lease-cmds.xml 32.7 KB
Newer Older
1
<!--
2
 - Copyright (C) 2018-2019 Internet Systems Consortium, Inc. ("ISC")
3 4 5
 -
 - 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
Suzanne Goldlust's avatar
Suzanne Goldlust committed
6
 - file, you can obtain one at http://mozilla.org/MPL/2.0/.
7 8 9 10 11
-->

      <section xml:id="lease-cmds">
        <title>lease_cmds: Lease Commands</title>
        <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
12
          This section describes the hook library with
13 14
          commands used to manage leases. Kea provides a way to store lease
          information in several backends (memfile, MySQL, PostgreSQL and
Suzanne Goldlust's avatar
Suzanne Goldlust committed
15 16 17 18 19 20 21
          Cassandra), and this library provides a interface that can
          manipulate leases in a unified, safe way. In particular, it allows
          things previously impossible: lease manipulation in memfile while Kea
          is running, sanity check changes, lease existence checks, and removal of all
          leases belonging to a specific subnet. It can also catch more obscure
          errors, like an attempt to add a lease with a subnet-id that does not exist in the
          configuration, or configuring a lease to use an address that is outside
22
          of the subnet to which it is supposed to belong.
Suzanne Goldlust's avatar
Suzanne Goldlust committed
23
          The library also provides a non-programmatic way to manage user contexts
Suzanne Goldlust's avatar
Suzanne Goldlust committed
24
          associated with leases.
25 26

          <note>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
27 28
            <para>This library may only be loaded by the <command>kea-dhcp4</command>
            or the <command>kea-dhcp6</command> process.
29 30 31 32
            </para>
          </note>
        </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
33 34
        <para>There are many use cases where an administrative command may be
        useful; for example, during migration between servers or
Suzanne Goldlust's avatar
Suzanne Goldlust committed
35
        different vendors, when a certain network is being retired, or when a
36 37 38 39 40 41 42 43 44
        device has been disconnected and the sysadmin knows for sure that it
        will not be coming back. The "get" queries may be useful for automating
        certain management and monitoring tasks. They can also act as
        preparatory steps for lease updates and removals.</para>

        <para>
          This library provides the following commands:
          <itemizedlist>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
45
              <para><command>lease4-add</command> - adds a new IPv4 lease;</para>
46 47
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
48
              <para><command>lease6-add</command> - adds a new IPv6 lease;</para>
49
            </listitem>
50 51 52 53
            <listitem>
              <para><command>lease6-bulk-apply</command> - creates, updates and/or
              deletes multiple IPv6 leases in a single transaction;</para>
            </listitem>
54
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
55
              <para><command>lease4-get</command> - checks whether an IPv4 lease with
56 57 58
              the specified parameters exists and returns it if it does;</para>
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
59
              <para><command>lease6-get</command> - checks whether an IPv6 lease with
60 61 62 63
              the specified parameters exists and returns it if it does;</para>
            </listitem>
            <listitem>
              <para><command>lease4-get-all</command> - returns all IPv4 leases
Suzanne Goldlust's avatar
Suzanne Goldlust committed
64
              or all IPv4 leases for the specified subnets;</para>
65 66 67
            </listitem>
            <listitem>
              <para><command>lease6-get-all</command> - returns all IPv6 leases
Suzanne Goldlust's avatar
Suzanne Goldlust committed
68
              or all IPv6 leases for the specified subnets;</para>
69 70
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
71 72 73
              <para><command>lease4-get-page</command> - returns a set ("page")
              of leases from the list of all IPv4 leases in the database. 
              By iterating through the pages it is possible to retrieve all the leases;</para>
74 75
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
76 77 78
              <para><command>lease6-get-page</command> - returns a set ("page")
              of leases from the list of all IPv6 leases in the database. 
              By iterating through the pages it is possible to retrieve all the leases;</para>
79 80
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
81
              <para><command>lease4-del</command> - deletes an IPv4
82 83 84
              lease with the specified parameters;</para>
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
85
              <para><command>lease6-del</command> - deletes an IPv6
86 87 88 89 90 91 92 93 94 95
              lease with the specified parameters;</para>
            </listitem>
            <listitem>
              <para><command>lease4-update</command> - updates an IPv4 lease;</para>
            </listitem>
            <listitem>
              <para><command>lease6-update</command> - updates an IPv6 lease;</para>
            </listitem>
            <listitem>
              <para><command>lease4-wipe</command> - removes all leases from a
Suzanne Goldlust's avatar
Suzanne Goldlust committed
96
              specific IPv4 subnet or from all subnets;</para>
97 98 99
            </listitem>
            <listitem>
              <para><command>lease6-wipe</command> - removes all leases from a
Suzanne Goldlust's avatar
Suzanne Goldlust committed
100
              specific IPv6 subnet or from all subnets;</para>
101 102 103 104 105
            </listitem>
          </itemizedlist>

        </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
106
        <para>The lease commands library is part of the open source code and is
107 108 109
        available to every Kea user.</para>

        <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
110 111
          All commands use JSON syntax and can be issued either using
          control channel (see <xref linkend="ctrl-channel"/>) or Control
112 113 114 115
          Agent (see <xref linkend="kea-ctrl-agent"/>).
        </para>

        <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
116
          The library can be loaded in the same way as other hook libraries, and it
117 118 119 120 121 122 123 124 125 126 127 128 129 130
          does not take any parameters. It supports both DHCPv4 and DHCPv6
          servers.
<screen>
"Dhcp6": { <userinput>
    "hooks-libraries": [
        {
            "library": "/path/libdhcp_lease_cmds.so"
        }
        ...
    ] </userinput>
}
</screen>
        </para>

131
        <section id="command-lease4-add">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
132
          <title>lease4-add, lease6-add Commands</title>
133
        <para id="command-lease6-add">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
134
          The <command>lease4-add</command> and <command>lease6-add</command>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
135
          commands allow for the creation of a new lease. Typically Kea creates
Suzanne Goldlust's avatar
Suzanne Goldlust committed
136
          a lease when it first sees a new device; however,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
137
          sometimes it may be convenient to create the lease
Suzanne Goldlust's avatar
Suzanne Goldlust committed
138
          manually. The <command>lease4-add</command> command requires
Suzanne Goldlust's avatar
Suzanne Goldlust committed
139 140 141 142
          at least two parameters: an IPv4 address and an identifier, i.e. hardware
          (MAC) address. A third parameter, subnet-id, is optional. If the subnet-id is not
          specified or the specified value is 0, Kea will try to determine the
          value by running a subnet-selection procedure. If specified, however,
Thomas Markwalder's avatar
Thomas Markwalder committed
143 144
          its value must match the existing subnet. The simplest successful
          call might look as follows:
145 146 147 148 149 150 151 152 153 154 155
<screen>
{
    "command": "lease4-add",
    "arguments": {
        "ip-address": "192.0.2.202",
        "hw-address": "1a:1b:1c:1d:1e:1f"
    }
}
</screen>
        </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
156
        <para>The <command>lease6-add</command> command requires three parameters: an
Suzanne Goldlust's avatar
Suzanne Goldlust committed
157 158
        IPv6 address, an IAID value (identity association identifier, a value
        sent by clients), and a DUID. As with lease4-add, the subnet-id parameter is optional. If the subnet-id is not
Suzanne Goldlust's avatar
Suzanne Goldlust committed
159
        specified or the provided value is 0, Kea will try to determine the
Suzanne Goldlust's avatar
Suzanne Goldlust committed
160 161
        value by running a subnet-selection procedure. If specified, however,
        its value must match the existing subnet. For
Thomas Markwalder's avatar
Thomas Markwalder committed
162
        example:
163 164 165 166 167 168 169 170 171 172 173
<screen>
{
    "command": "lease6-add",
    "arguments": {
        "subnet-id": 66,
        "ip-address": "2001:db8::3",
        "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
        "iaid": 1234
    }
}</screen>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
174
<command>lease6-add</command> can also be used to add leases for IPv6
Tomek Mrugalski's avatar
Tomek Mrugalski committed
175
prefixes. In this case there are three additional parameters that must be
Suzanne Goldlust's avatar
Suzanne Goldlust committed
176
specified: subnet-id, type (set to value of "IA_PD"), and prefix
Suzanne Goldlust's avatar
Suzanne Goldlust committed
177
length. The actual prefix is set using ip-address field. Note that Kea cannot
Suzanne Goldlust's avatar
Suzanne Goldlust committed
178
guess subnet-id values for prefixes; they must be specified explicitly.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
179
For example, to configure a lease for prefix 2001:db8:abcd::/48, the following
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
command can be used:

<screen>
{
    "command": "lease6-add",
    "arguments": {
        "subnet-id": 66,
        "type": "IA_PD",
        "ip-address": "2001:db8:abcd::",
        "prefix-len": 48,
        "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
        "iaid": 1234
    }
}</screen>

The commands can take a number of additional optional parameters:
          <itemizedlist>
            <listitem>
              <para><command>valid-lft</command> - specifies the lifetime of the
              lease, expressed in seconds. If not specified, the value
Suzanne Goldlust's avatar
Suzanne Goldlust committed
200
              configured in the subnet related to the specified subnet-id is
201 202 203
              used.</para>
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
204
              <para><command>expire</command> - creates a timestamp of the lease
205
              expiration time, expressed in unix format (seconds since 1 Jan
Suzanne Goldlust's avatar
Suzanne Goldlust committed
206
              1970). If not specified, the default value is now + the lease lifetime (the value of valid-lft).</para>
207 208 209
            </listitem>
            <listitem>
              <para><command>fqdn-fwd</command> - specifies whether the lease
Suzanne Goldlust's avatar
Suzanne Goldlust committed
210 211 212
              should be marked as if a forward DNS update were conducted. Note this
              only affects the the data stored in the lease database, and no DNS update
              will be performed. If configured, a DNS
213 214
              update to remove the A or AAAA records will be conducted when the
              lease is removed due to expiration or being released by a
Suzanne Goldlust's avatar
Suzanne Goldlust committed
215 216
              client. If not specified, the default value is false. The hostname
              parameter must be specified if fqdn-fwd is set to true.</para>
217 218 219
            </listitem>
            <listitem>
              <para><command>fqdn-rev</command> - specifies whether the lease
Suzanne Goldlust's avatar
Suzanne Goldlust committed
220
              should be marked as if reverse DNS update were conducted. Note this
Suzanne Goldlust's avatar
Suzanne Goldlust committed
221 222
              only affects the the data stored in the lease database, and no DNS update
              will be performed.. If configured, a DNS
223 224
              update to remove the PTR record will be conducted when the lease
              is removed due to expiration or being released by a client. If not
Suzanne Goldlust's avatar
Suzanne Goldlust committed
225 226
              specified, the default value is false. The hostname parameter must be
              specified if fqdn-fwd is set to true.</para>
227 228 229 230 231 232 233 234
            </listitem>
            <listitem>
              <para><command>hostname</command> - specifies the hostname to be
              associated with this lease. Its value must be non-empty if either
              fqdn-fwd or fwdn-rev are set to true. If not specified, the
              default value is an empty string.</para>
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
235 236 237
              <para><command>hw-address</command> - optionally specifies a hardware (MAC) address
              for an IPv6 lease. It is a mandatory parameter
              for an IPv4 lease.</para>
238 239
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
240 241
              <para><command>client-id</command> - optionally specifies a client identifier
              for an IPv4 lease.</para>
242 243
            </listitem>
            <listitem>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
244 245
              <para><command>preferred-lft</command> - optionally specifies a preferred lifetime
              for IPv6 leases. If not specified, the value
246
              configured for the subnet corresponding to the specified subnet-id
Suzanne Goldlust's avatar
Suzanne Goldlust committed
247
              is used. This parameter is not used when adding an IPv4 lease.</para>
248
            </listitem>
249 250 251 252 253
            <listitem>
              <para><command>user-context</command> - specifies the user
              context to be associated with this lease. It must be a
              JSON map.</para>
              </listitem>
254 255 256
          </itemizedlist>
        </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
257
        <para>Here is an example of a more complex lease addition:
258 259 260 261 262 263 264 265 266 267 268 269 270 271 272

<screen>
{
    "command": "lease6-add",
    "arguments": {
        "subnet-id": 66,
        "ip-address": "2001:db8::3",
        "duid": "01:02:03:04:05:06:07:08",
        "iaid": 1234,
        "hw-address": "1a:1b:1c:1d:1e:1f",
        "preferred-lft": 500,
        "valid-lft": 1000,
        "expire": 12345678,
        "fqdn-fwd": true,
        "fqdn-rev": true,
273 274
        "hostname": "urania.example.org",
        "user-context": { "version": 1 }
275 276 277 278 279 280 281
    }
}
</screen>
        </para>

        <para>
          The command returns a status that indicates either a success (result
Suzanne Goldlust's avatar
Suzanne Goldlust committed
282
          0) or a failure (result 1). A failed command always includes a text
Suzanne Goldlust's avatar
Suzanne Goldlust committed
283
          parameter that explains the cause of failure. For example:
284 285 286 287
          <screen>{ "result": 0, "text": "Lease added." }</screen> Example failure:
          <screen>{ "result": 1, "text": "missing parameter 'ip-address' (&lt;string&gt;:3:19)" }</screen>
        </para>

288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367
        <section id="command-lease6-bulk-apply">
          <title>lease6-bulk-apply</title>
          <para>The <command>lease6-bulk-apply</command> was implemented to address
          the performance penalty in the High Availability when a single DHCPv6
          transaction resulted in multiple lease updates sent to the partner if
          multiple address and/or prefix leases were allocated. Consider the case
          when a DHCPv6 client requests the assignment of two IPv6 addresses and two IPv6
          prefixes. That may result in allocation of 4 leases. In addition, the
          DHCPv6 may assign different address than requested by the client during
          the renew or rebind and delete the leases previously used by this client.
          The are 6 of lease changes sent between the HA partners is in this case.
          Sending these updates in individual commands, e.g. <command>lease6-update</command>
          is highly inefficient and produces unnecessary delays in communication
          between the HA partners and in sending the response to the DHCPv6 client.
          </para>

          <para>The <command>lease6-bulk-apply</command> command deals with this
          problem by aggregating all lease changes in a single command. Both
          deleted leases and new/updated leases are conveyed in a single command.
          The receiving server iterates over the deleted leases and deletes them
          from its lease database. Next, it iterates over the new/updated leases
          and adds them to the database or updates them if they already exist.
          </para>

          <para>Even though the High Avialability is the major application for
          this command, it can be freely used in all cases when it is desired to
          send multiple lease changes in a single command.</para>

          <para>In the following example, we ask to delete two leases and to add
          or update two other leases in the database:
<screen>
{
    "command": "lease6-bulk-apply",
    "arguments": {
        "deleted-leases": [
            {
                "ip-address": "2001:db8:abcd::",
                "type": "IA_PD",
            },
            {
                "ip-address": "2001:db8:abcd::234",
                "type": "IA_NA",
            }
        ],
        "leases": [
           {
                "subnet-id": 66,
                "ip-address": "2001:db8:cafe::",
                "type": "IA_PD",
                 ...
           },
           {
                "subnet-id": 66,
                "ip-address": "2001:db8:abcd::333",
                "type": "IA_NA",
                ...
            }
        ]
    }
}
</screen>
          </para>

          <para>If any of the leases is malformed, no leases changes are applied
          to the lease database. If the leases are well formed but there is a
          failure to apply any of the lease changes to the database, the command
          will continue to be processed for other leases. All the leases for which
          the command was unable to apply the changes in the database will be
          listed in the response.
          </para>

          <para>For example:
<screen>
{
    "result": 0,
    "text": "Bulk apply of 2 IPv6 leases completed".
    "arguments": {
        "failed-deleted-leases": [
            {
                "ip-address": "2001:db8:abcd::",
368 369 370
                "type": "IA_PD",
                "result": 3,
                "error-message": "no lease found"
371 372 373 374 375 376
            }
        ],
        "failed-leases": [
            {
                "ip-address": "2001:db8:cafe::",
                "type": "IA_PD",
377 378
                "result": 1,
                "error-message": "unable to communicate with the lease database"
379 380 381 382 383 384 385 386 387
            }
        ]
    }
}
</screen>
          </para>
          <para>The response above indicates that the hooks library was unable to
          delete the lease for prefix "2001:db8:abcd::" and add or update the lease
          for prefix "2001:db8:cafe::". However, there are two other lease changes
388 389 390 391 392 393 394 395
          which have been applied as indicated by the text message. The
          <command>result</command> is the status constant that indicates the type
          of the error experienced for the particular lease. The meaning of the
          returned codes are the same as the results returned for the commands.
          In particular, the result of 1 indicates an error while processing the
          lease, e.g. a communication error with the database. The result of 3
          indicates that an attempt to delete the lease was unsuccessful because
          such lease doesn't exist (empty result).
396 397
          </para>
        </section>
398

399
        <section id="command-lease4-get">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
400
          <title>lease4-get, lease6-get Commands</title>
401 402
          <para  id="command-lease6-get">
            <command>lease4-get</command> or <command>lease6-get</command>
403 404
          can be used to query the lease database and retrieve existing
          leases. There are two types of parameters the
Suzanne Goldlust's avatar
Suzanne Goldlust committed
405 406
          <command>lease4-get</command> command supports: (address) or (subnet-id,
          identifier-type, identifier). There are also two types for
407 408 409
          <command>lease6-get</command>: (address,type) or (subnet-id,
          identifier-type, identifier, IAID, type). The first type of query is
          used when the address (either IPv4 or IPv6) is known, but the details
Suzanne Goldlust's avatar
Suzanne Goldlust committed
410 411 412 413
          of the lease are not; one common use case of this type of query is to
          find out whether a given address is being used. The second
          query uses identifiers; currently supported identifiers for leases are:
          "hw-address" (IPv4 only), "client-id" (IPv4 only), and "duid" (IPv6 only).
414 415 416 417
          </para>

          <para>
            An example <command>lease4-get</command> command for getting a lease
Suzanne Goldlust's avatar
Suzanne Goldlust committed
418
            using an IPv4 address is:
419 420 421 422 423 424 425 426 427 428 429
<screen>
{
    "command": "lease4-get",
    "arguments": {
        "ip-address": "192.0.2.1"
    }
}
</screen>
          </para>

          <para>An example of the <command>lease6-get</command> query
Suzanne Goldlust's avatar
Suzanne Goldlust committed
430
          is:
431 432 433 434 435 436 437 438 439 440
<screen>
{
  "command": "lease6-get",
  "arguments": {
    "ip-address": "2001:db8:1234:ab::",
    "type": "IA_PD"
  }
}</screen>
          </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
441
          <para>An example query by "hw-address" for an IPv4 lease looks
442 443 444 445 446 447 448 449 450 451 452 453 454
          as follows:
<screen>
{
    "command": "lease4-get",
    "arguments": {
        "identifier-type": "hw-address",
        "identifier": "08:08:08:08:08:08",
        "subnet-id": 44
    }
}</screen>

          </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
455
          <para>An example query by "client-id" for an IPv4 lease looks
456 457 458 459 460 461 462 463 464 465 466 467 468 469
          as follows:
<screen>
{
    "command": "lease4-get",
    "arguments": {
        "identifier-type": "client-id",
        "identifier": "01:01:02:03:04:05:06",
        "subnet-id": 44
    }
}</screen>

          </para>

          <para>An example query by (subnet-id, identifier-type,
Suzanne Goldlust's avatar
Suzanne Goldlust committed
470
          identifier, iaid, type) for an IPv6 lease is:
471 472 473 474 475 476 477 478 479 480 481 482
<screen>
{
    "command": "lease4-get",
    "arguments": {
        "identifier-type": "duid",
        "identifier": "08:08:08:08:08:08",
        "iaid": 1234567,
        "type": "IA_NA",
        "subnet-id": 44
    }
}</screen>
The type is an optional parameter. Supported values are: IA_NA
Suzanne Goldlust's avatar
Suzanne Goldlust committed
483
(non-temporary address) and IA_PD (IPv6 prefix).
484 485 486 487 488
If not specified, IA_NA is assumed.
          </para>

          <para><command>leaseX-get</command> returns a result that indicates a
          result of the operation and lease details, if found. It has one of the
Suzanne Goldlust's avatar
Suzanne Goldlust committed
489
          following values: 0 (success), 1 (error), or 2 (empty). An empty
490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516
          result means that a query has been completed properly, but the object
          (a lease in this case) has not been found. The lease parameters, if
          found, are returned as arguments.
          </para>

          <para>
An example result returned when the host was found:
<screen>{
  "arguments": {
    "client-id": "42:42:42:42:42:42:42:42",
    "cltt": 12345678,
    "fqdn-fwd": false,
    "fqdn-rev": true,
    "hostname": "myhost.example.com.",
    "hw-address": "08:08:08:08:08:08",
    "ip-address": "192.0.2.1",
    "state": 0,
    "subnet-id": 44,
    "valid-lft": 3600
  },
  "result": 0,
  "text": "IPv4 lease found."
}</screen>
</para>

        </section>

517
        <section id="command-lease4-get-all">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
518
          <title>lease4-get-all, lease6-get-all Commands</title>
519
          <para id="command-lease6-get-all"><command>lease4-get-all</command> and
520
          <command>lease6-get-all</command> are used to retrieve all
Suzanne Goldlust's avatar
Suzanne Goldlust committed
521
          IPv4 or IPv6 leases, or all leases for the specified set of
522
          subnets. All leases are returned when there are no arguments
Suzanne Goldlust's avatar
Suzanne Goldlust committed
523
          specified with the command, as in the following example:
524 525 526 527 528 529 530
<screen>
{
    "command": "lease4-get-all"
}
</screen>
          </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
531 532
          <para>If the arguments are provided, it is expected that they contain the
          "subnets" parameter, which is a list of subnet identifiers for which the
533
          leases should be returned. For example, in order to retrieve all IPv6
Suzanne Goldlust's avatar
Suzanne Goldlust committed
534
          leases belonging to the subnets with identifiers 1, 2, 3, and 4:
535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590
<screen>
{
    "command": "lease6-get-all",
    "arguments": {
        "subnets": [ 1, 2, 3, 4 ]
    }
}
</screen>
          </para>

          <para>
            The returned response contains a detailed list of leases in the
            following format:
<screen>{
    "arguments": {
        "leases": [
            {
                "cltt": 12345678,
                "duid": "42:42:42:42:42:42:42:42",
                "fqdn-fwd": false,
                "fqdn-rev": true,
                "hostname": "myhost.example.com.",
                "hw-address": "08:08:08:08:08:08",
                "iaid": 1,
                "ip-address": "2001:db8:2::1",
                "preferred-lft": 500,
                "state": 0,
                "subnet-id": 44,
                "type": "IA_NA",
                "valid-lft": 3600
            },
            {
                "cltt": 12345678,
                "duid": "21:21:21:21:21:21:21:21",
                "fqdn-fwd": false,
                "fqdn-rev": true,
                "hostname": "",
                "iaid": 1,
                "ip-address": "2001:db8:0:0:2::",
                "preferred-lft": 500,
                "prefix-len": 80,
                "state": 0,
                "subnet-id": 44,
                "type": "IA_PD",
                "valid-lft": 3600
            }
        ]
    },
    "result": 0,
    "text": "2 IPv6 lease(s) found."
}</screen>
          </para>

          <warning>
            <para>The <command>lease4-get-all</command> and
            <command>lease6-get-all</command> commands may result in very
Suzanne Goldlust's avatar
Suzanne Goldlust committed
591
            large responses. This may have a negative impact on the DHCP server's
592 593 594 595 596 597 598 599
            responsiveness while the response is generated and transmitted
            over the control channel, as the server imposes no restriction
            on the number of leases returned as a result of this command.
            </para>
          </warning>

        </section>

600
        <section xml:id="lease-get-page-cmds">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
601
          <title>lease4-get-page, lease6-get-page Commands</title>
602 603
          <para>The <command>lease4-get-all</command> and
          <command>lease6-get-all</command> commands may result in very
Suzanne Goldlust's avatar
Suzanne Goldlust committed
604
          large responses; generating such a response may consume CPU bandwidth
605 606
          as well as memory. It may even cause the server to become
          unresponsive. In case of large lease databases it is usually better
Suzanne Goldlust's avatar
Suzanne Goldlust committed
607
          to retrieve leases in chunks, using the paging mechanism.
608
          <command>lease4-get-page</command> and <command>lease6-get-page</command>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
609 610
          implement a paging mechanism for DHCPv4 and DHCPv6 servers respectively.
          The following command retrieves the first 1024 IPv4 leases:
611 612 613 614 615
<screen>
{
    "command": "lease4-get-page",
    "arguments": {
        "from": "start",
616
        "limit": 1024
617 618 619 620 621 622 623 624 625 626 627 628 629
    }
}
</screen>
          </para>

          <para>The keyword <command>start</command> denotes that the first page
          of leases should be retrieved. Alternatively, an IPv4 zero address
          can be specified to retrieve the first page:
<screen>
{
    "command": "lease4-get-page",
    "arguments": {
        "from": "0.0.0.0",
630
        "limit": 1024
631 632 633 634 635
    }
}
</screen>
          </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
636
          <para>Similarly, the IPv6 zero address can be specified in the
637 638 639 640 641 642
          <command>lease6-get-page</command> command:
<screen>
{
    "command": "lease6-get-page",
    "arguments": {
        "from": "::",
643
        "limit": 6
644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679
    }
}
</screen>
          </para>

          <para>The response has the following structure:
<screen>
{
    "arguments": {
        "leases": [
            {
                "ip-address": "2001:db8:2::1",
                ...
            },
            {
                "ip-address": "2001:db8:2::9",
                ...
            },
            {
                "ip-address": "2001:db8:3::1",
                ...
            },
            {
                "ip-address": "2001:db8:5::3",
                ...
            }
            {
                "ip-address": "2001:db8:4::1",
                ...
            },
            {
                "ip-address": "2001:db8:2::7",
                ...
            }

        ],
680
        "count": 6
681 682 683 684 685 686 687 688 689 690 691
    },
    "result": 0,
    "text": "6 IPv6 lease(s) found."
}
</screen>

          </para>

          <para>Note that the leases' details were excluded from the response above
          for brevity.</para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
692
          <para>Generally, the returned list is not sorted in any particular order.
693
          Some lease database backends may sort leases in ascending order of addresses,
Suzanne Goldlust's avatar
Suzanne Goldlust committed
694
          but the controlling client must not rely on this behavior. In cases of
695 696 697
          highly distributed databases, such as Cassandra, ordering may be inefficient
          or even impossible.</para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
698
          <para>The <command>count</command> parameter contains the number of returned
699
          leases on the page.
700 701
          </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
702
          <para>To fetch the next page, the client must use the last address
703 704
          of the current page as an input to the next
          <command>lease4-get-page</command> or <command>lease6-get-page</command>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
705
          command call. In this example it is:
706 707 708 709 710 711 712 713 714
<screen>
{
    "command": "lease6-get-page",
    "arguments": {
        "from": "2001:db8:2::7",
        "count": 6
    }
}
</screen>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
715
            because 2001:db8:2::7 is the last address on the current page.
716 717 718
          </para>

          <para>The client may assume that it has reached the last page when the
Suzanne Goldlust's avatar
Suzanne Goldlust committed
719 720 721
          <command>count</command> value is lower than that specified in the command;
          this includes the case when the <command>count</command> is equal to 0,
          meaning that no leases were found.
722 723 724 725
          </para>

        </section>

726
        <section id="command-lease4-del">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
727
          <title>lease4-del, lease6-del Commands</title>
728 729
          <para id="command-lease6-del">
            <command>leaseX-del</command> can be used to delete a lease from
730 731
          the lease database. There are two types of parameters this command
          supports, similar to leaseX-get commands: (address) for both v4 and
Suzanne Goldlust's avatar
Suzanne Goldlust committed
732
          v6, (subnet-id, identifier-type, identifier) for v4, and (subnet-id,
733 734
          identifier-type, identifier, type, IAID) for v6. The first type of
          query is used when the address (either IPv4 or IPv6) is known, but the
Suzanne Goldlust's avatar
Suzanne Goldlust committed
735 736
          details of the lease are not. One common use case is where an administrator
          wants a specified address to no longer be used. The second form of the command uses
737
          identifiers. For maximum flexibility, this interface uses identifiers
Suzanne Goldlust's avatar
Suzanne Goldlust committed
738
          as a pair of values: type and the actual identifier. The currently
739
          supported identifiers are "hw-address" (IPv4 only), "client-id"
Suzanne Goldlust's avatar
Suzanne Goldlust committed
740
          (IPv4 only), and "duid" (IPv6 only). </para>
741 742

          <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
743
            An example command for deleting a lease by address is:
744 745 746 747 748 749 750 751
<screen>
{
    "command": "lease4-del",
    "arguments": {
        "ip-address": "192.0.2.202"
    }
}</screen>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
752
An example IPv4 lease deletion by "hw-address" is:
753 754 755 756 757 758 759 760 761 762 763 764

<screen>{
  "command": "lease4-del",
  "arguments": {
    "identifier": "08:08:08:08:08:08",
    "identifier-type": "hw-address",
    "subnet-id": 44
  }
}</screen>
          </para>

          <para><command>leaseX-del</command> returns a result that
Suzanne Goldlust's avatar
Suzanne Goldlust committed
765 766
          indicates the outcome of the operation. It has one of the
          following values: 0 (success), 1 (error), or 3 (empty). The
767 768 769 770 771
          empty result means that a query has been completed properly,
          but the object (a lease in this case) has not been found.
          </para>
        </section>

772
        <section id="command-lease4-update">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
773 774
          <title>lease4-update, lease6-update Commands</title>
          <para id="command-lease6-update">The <command>lease4-update</command> and
775 776
          <command>lease6-update</command> commands can be used to update
          existing leases. Since all lease database backends are indexed by IP
Suzanne Goldlust's avatar
Suzanne Goldlust committed
777
          addresses, it is not possible to update an address, but all other fields
Suzanne Goldlust's avatar
Suzanne Goldlust committed
778
          may be altered. If an address needs to be changed, please use
779
          <command>leaseX-del</command> followed by
Suzanne Goldlust's avatar
Suzanne Goldlust committed
780
          <command>leaseX-add</command>.</para>
781

Suzanne Goldlust's avatar
Suzanne Goldlust committed
782
          <para>The subnet-id parameter
Suzanne Goldlust's avatar
Suzanne Goldlust committed
783
          is optional. If not specified, or if the specified value is 0, Kea
Suzanne Goldlust's avatar
Suzanne Goldlust committed
784
          will try to determine its value by running a subnet-selection
Thomas Markwalder's avatar
Thomas Markwalder committed
785 786
          procedure. If specified, however, its value must match the existing
          subnet.</para>
Tomek Mrugalski's avatar
Tomek Mrugalski committed
787

788
          <para>The optional boolean parameter "force-create" specifies
Suzanne Goldlust's avatar
Suzanne Goldlust committed
789
          whether the lease should be created if it doesn't exist in the database.
790
          It defaults to false, which indicates that the lease is not created
Suzanne Goldlust's avatar
Suzanne Goldlust committed
791
          if it doesn't exist. In such a case, an error is returned as a result
792
          of trying to update a non-existing lease. If the "force-create" parameter
Suzanne Goldlust's avatar
Suzanne Goldlust committed
793
          is set to true and the updated lease does not exist, the new lease is
794 795 796 797
          created as a result of receiving the <command>leaseX-update</command>.
          </para>

          <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
798
            An example of a command to update an IPv4 lease is:
799 800 801 802 803 804 805 806 807 808 809 810 811
<screen>{
  "command": "lease4-update",
  "arguments": {
    "ip-address": "192.0.2.1",
    "hostname": "newhostname.example.org",
    "hw-address": "1a:1b:1c:1d:1e:1f",
    "subnet-id": 44,
    "force-create": true
  }
}</screen>
          </para>

          <para>
Suzanne Goldlust's avatar
Suzanne Goldlust committed
812
            An example of a command to update an IPv6 lease is:
813 814 815 816 817 818 819 820 821 822 823 824 825 826
<screen>{
  "command": "lease6-update",
  "arguments": {
    "ip-address": "2001:db8::1",
    "duid": "88:88:88:88:88:88:88:88",
    "iaid": 7654321,
    "hostname": "newhostname.example.org",
    "subnet-id": 66,
    "force-create": false
  }
}</screen>
          </para>
        </section>

827
        <section id="command-lease4-wipe">
Suzanne Goldlust's avatar
Suzanne Goldlust committed
828
          <title>lease4-wipe, lease6-wipe Commands</title>
829
          <para id="command-lease6-wipe"><command>lease4-wipe</command> and
830 831
          <command>lease6-wipe</command> are designed to remove all
          leases associated with a given subnet. This administrative
Suzanne Goldlust's avatar
Suzanne Goldlust committed
832
          task is expected to be used when an existing subnet is being
Suzanne Goldlust's avatar
Suzanne Goldlust committed
833 834 835
          retired. Note that the leases are not properly expired:
          no DNS updates are carried out, no log messages are created, and
          hooks are not called for the leases being removed.</para>
836

Suzanne Goldlust's avatar
Suzanne Goldlust committed
837
          <para>An example of <command>lease4-wipe</command> is:
838 839 840 841 842 843 844 845
<screen>{
  "command": "lease4-wipe",
  "arguments": {
    "subnet-id": 44
  }
}</screen>
          </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
846
          <para>An example of <command>lease6-wipe</command> is:
847 848 849 850 851 852 853 854
<screen>{
  "command": "lease6-wipe",
  "arguments": {
    "subnet-id": 66
  }
}</screen>
          </para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
855 856 857 858
          <para>The commands return a text description of the
          number of leases removed, plus the status code 0 (success) if any
          leases were removed or 2 (empty) if there were no
          leases. Status code 1 (error) may be returned if the
859 860 861
          parameters are incorrect or some other exception is
          encountered.</para>

Suzanne Goldlust's avatar
Suzanne Goldlust committed
862
          <para>Subnet-id 0 has a special meaning; it tells Kea to
863 864 865 866 867 868 869 870
          delete leases from all configured subnets. Also, the
          subnet-id parameter may be omitted. If not specified, leases
          from all subnets are wiped.</para>

          <para>Note: not all backends support this command.</para>
        </section>
      </section>
    </section>