dhcp6-srv.rst 260 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
.. _dhcp6:

*****************
The DHCPv6 Server
*****************

.. _dhcp6-start-stop:

Starting and Stopping the DHCPv6 Server
=======================================

It is recommended that the Kea DHCPv6 server be started and stopped
13
using ``keactrl`` (described in :ref:`keactrl`); however, it is also
14 15 16 17 18 19 20
possible to run the server directly. It accepts the following
command-line switches:

-  ``-c file`` - specifies the configuration file. This is the only
   mandatory switch.

-  ``-d`` - specifies whether the server logging should be switched to
21 22
   debug/verbose mode. In verbose mode, the logging severity and debuglevel
   specified in the configuration file are ignored; "debug" severity
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
   and the maximum debuglevel (99) are assumed. The flag is convenient
   for temporarily switching the server into maximum verbosity, e.g.
   when debugging.

-  ``-p server-port`` - specifies the local UDP port on which the server
   will listen. This is only useful during testing, as a DHCPv6 server
   listening on ports other than the standard ones will not be able to
   handle regular DHCPv6 queries.

-  ``-P client-port`` - specifies the remote UDP port to which the
   server will send all responses. This is only useful during testing,
   as a DHCPv6 server sending responses to ports other than the standard
   ones will not be able to handle regular DHCPv6 queries.

-  ``-t file`` - specifies a configuration file to be tested. Kea-dhcp6
   will load it, check it, and exit. During the test, log messages are
   printed to standard output and error messages to standard error. The
   result of the test is reported through the exit code (0 =
   configuration looks ok, 1 = error encountered). The check is not
   comprehensive; certain checks are possible only when running the
   server.

-  ``-v`` - displays the Kea version and exits.

-  ``-V`` - displays the Kea extended version with additional parameters
   and exits. The listing includes the versions of the libraries
   dynamically linked to Kea.

-  ``-W`` - displays the Kea configuration report and exits. The report
   is a copy of the ``config.report`` file produced by ``./configure``;
   it is embedded in the executable binary.

On startup, the server will detect available network interfaces and will
attempt to open UDP sockets on all interfaces mentioned in the
configuration file. Since the DHCPv6 server opens privileged ports, it
58
requires root access. This daemon must be run as root.
59 60

During startup, the server will attempt to create a PID file of the
61
form: [**runstatedir**]/kea/[**conf name**].kea-dhcp6.pid where:
62

63 64
-  ``runstatedir``: The value as passed into the build configure
   script; it defaults to "/usr/local/var/run". Note that this value may be
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
   overridden at runtime by setting the environment variable
   KEA_PIDFILE_DIR, although this is intended primarily for testing
   purposes.

-  ``conf name``: The configuration file name used to start the server,
   minus all preceding paths and the file extension. For example, given
   a pathname of "/usr/local/etc/kea/myconf.txt", the portion used would
   be "myconf".

If the file already exists and contains the PID of a live process, the
server will issue a DHCP6_ALREADY_RUNNING log message and exit. It is
possible, though unlikely, that the file is a remnant of a system crash
and the process to which the PID belongs is unrelated to Kea. In such a
case it would be necessary to manually delete the PID file.

The server can be stopped using the ``kill`` command. When running in a
console, the server can also be shut down by pressing ctrl-c. It detects
the key combination and shuts down gracefully.

.. _dhcp6-configuration:

DHCPv6 Server Configuration
===========================

Introduction
------------

This section explains how to configure the DHCPv6 server using a
93 94
configuration file. Before DHCPv6 is started, its configuration file must
be created. The basic configuration is as follows:
95 96 97 98 99 100 101 102 103 104 105 106 107

::

   {
   # DHCPv6 configuration starts on the next line
   "Dhcp6": {

   # First we set up global values
       "valid-lifetime": 4000,
       "renew-timer": 1000,
       "rebind-timer": 2000,
       "preferred-lifetime": 3000,

108
   # Next we set up the interfaces to be used by the server.
109 110 111 112 113 114 115 116
       "interfaces-config": {
           "interfaces": [ "eth0" ]
       },

   # And we specify the type of lease database
       "lease-database": {
           "type": "memfile",
           "persist": true,
117
           "name": "/var/lib/kea/dhcp6.leases"
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
       },

   # Finally, we list the subnets from which we will be leasing addresses.
       "subnet6": [
           {
               "subnet": "2001:db8:1::/64",
               "pools": [
                    {
                        "pool": "2001:db8:1::1-2001:db8:1::ffff"
                    }
                ]
           }
       ]
   # DHCPv6 configuration ends with the next line
   }

   }

The following paragraphs provide a brief overview of the parameters in
the above example, along with their format. Subsequent sections of this
chapter go into much greater detail for these and other parameters.

The lines starting with a hash (#) are comments and are ignored by the
server; they do not impact its operation in any way.

The configuration starts in the first line with the initial opening
curly bracket (or brace). Each configuration must contain an object
specifying the configuration of the Kea module using it. In the example
above this object is called ``Dhcp6``.

148
.. note::
149 150 151

   In the current Kea release it is possible to specify configurations
   of multiple modules within a single configuration file, but this is
152 153 154
   not recommended and support for it will be removed in a future
   release. The only object, besides the one specifying module
   configuration, which can be (and usually was) included in the same file
155
   is ``Logging``. However, we don't include this object in the example
156 157
   above for clarity; its content, the list of loggers, should now be
   inside the ``Dhcp6`` object instead of this deprecated object.
158 159 160 161 162 163

The Dhcp6 configuration starts with the ``"Dhcp6": {`` line and ends
with the corresponding closing brace (in the above example, the brace
after the last comment). Everything defined between those lines is
considered to be the Dhcp6 configuration.

164
In general, the order in which those parameters appear does not
165 166
matter, but there are two caveats. The first one is to remember that the
configuration file must be well-formed JSON. That means that the
167
parameters for any given scope must be separated by a comma, and there
168 169 170 171 172 173 174 175
must not be a comma after the last parameter. When reordering a
configuration file, keep in mind that moving a parameter to or from the
last position in a given scope may also require moving the comma. The
second caveat is that it is uncommon — although legal JSON — to repeat
the same parameter multiple times. If that happens, the last occurrence
of a given parameter in a given scope is used, while all previous
instances are ignored. This is unlikely to cause any confusion as there
are no real-life reasons to keep multiple copies of the same parameter
176
in the configuration file.
177

178
The first few DHCPv6 configuration elements
179 180 181 182 183 184 185
define some global parameters. ``valid-lifetime`` defines how long the
addresses (leases) given out by the server are valid. If nothing
changes, a client that got an address is allowed to use it for 4000
seconds. (Note that integer numbers are specified as is, without any
quotes around them.) The address will become deprecated in 3000 seconds,
i.e. clients are allowed to keep old connections, but can't use this
address for creating new connections. ``renew-timer`` and
186
``rebind-timer`` are values (also in seconds) that define T1 and T2 timers that govern
187 188 189
when the client will begin the renewal and rebind procedures.

The ``interfaces-config`` map specifies the server configuration
190
concerning the network interfaces on which the server should listen to
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
the DHCP messages. The ``interfaces`` parameter specifies a list of
network interfaces on which the server should listen. Lists are opened
and closed with square brackets, with elements separated by commas. To
listen on two interfaces, the ``interfaces-config`` should look like
this:

::

   "interfaces-config": {
       "interfaces": [ "eth0", "eth1" ]
   },

The next couple of lines define the lease database, the place where the
server stores its lease information. This particular example tells the
server to use ``memfile``, which is the simplest (and fastest) database
backend. It uses an in-memory database and stores leases on disk in a
207
CSV (comma-separated values) file. This is a very simple configuration; usually the lease
208 209
database configuration is more extensive and contains additional
parameters. Note that ``lease-database`` is an object and opens up a new
210 211
scope, using an opening brace. Its parameters (just one in this example:
``type``) follow. If there were more than one, they would be separated
212 213 214 215
by commas. This scope is closed with a closing brace. As more parameters
for the Dhcp6 definition follow, a trailing comma is present.

Finally, we need to define a list of IPv6 subnets. This is the most
216
important DHCPv6 configuration structure, as the server uses that
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
information to process clients' requests. It defines all subnets from
which the server is expected to receive DHCP requests. The subnets are
specified with the ``subnet6`` parameter. It is a list, so it starts and
ends with square brackets. Each subnet definition in the list has
several attributes associated with it, so it is a structure and is
opened and closed with braces. At a minimum, a subnet definition has to
have at least two parameters: ``subnet`` (which defines the whole
subnet) and ``pools`` (which is a list of dynamically allocated pools
that are governed by the DHCP server).

The example contains a single subnet. If more than one were defined,
additional elements in the ``subnet6`` parameter would be specified and
separated by commas. For example, to define two subnets, the following
syntax would be used:

::

   "subnet6": [
       {
           "pools": [ { "pool": "2001:db8:1::/112" } ],
           "subnet": "2001:db8:1::/64"
       },
       {
           "pools": [ { "pool": "2001:db8:2::1-2001:db8:2::ffff" } ],
           "subnet": "2001:db8:2::/64"
       }
   ]

Note that indentation is optional and is used for aesthetic purposes
only. In some cases in may be preferable to use more compact notation.

248 249
After all the parameters are specified, we have two contexts open: global
and Dhcp6; thus, we need two closing curly brackets to close them.
250 251 252 253 254 255 256 257 258 259 260 261

Lease Storage
-------------

All leases issued by the server are stored in the lease database.
Currently there are four database backends available: memfile (which is
the default backend), MySQL, PostgreSQL, and Cassandra.

Memfile - Basic Storage for Leases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The server is able to store lease data in different repositories. Larger
262 263 264
deployments may elect to store leases in a database.
:ref:`database-configuration6` describes this option. In
typical smaller deployments, though, the server will store lease
265 266 267 268
information in a CSV file rather than a database. As well as requiring
less administration, an advantage of using a file for storage is that it
eliminates a dependency on third-party database software.

269
The configuration of the file backend (memfile) is controlled through
270 271 272 273
the Dhcp6/lease-database parameters. The ``type`` parameter is mandatory
and it specifies which storage for leases the server should use. The
value of ``"memfile"`` indicates that the file should be used as the
storage. The following list gives additional optional parameters that
274
can be used to configure the memfile backend.
275 276 277

-  ``persist``: controls whether the new leases and updates to existing
   leases are written to the file. It is strongly recommended that the
278
   value of this parameter be set to ``true`` at all times during the
279 280
   server's normal operation. Not writing leases to disk means that if a
   server is restarted (e.g. after a power failure), it will not know
281 282
   which addresses have been assigned. As a result, it may assign new clients
   addresses that are already in use. The value of
283 284 285 286 287 288
   ``false`` is mostly useful for performance-testing purposes. The
   default value of the ``persist`` parameter is ``true``, which enables
   writing lease updates to the lease file.

-  ``name``: specifies an absolute location of the lease file in which
   new leases and lease updates will be recorded. The default value for
289
   this parameter is ``"[kea-install-dir]/var/lib/kea/kea-leases6.csv"``.
290 291 292 293 294

-  ``lfc-interval``: specifies the interval, in seconds, at which the
   server will perform a lease file cleanup (LFC). This removes
   redundant (historical) information from the lease file and
   effectively reduces the lease file size. The cleanup process is
295
   described in more detail later in this section. The
296 297 298
   default value of the ``lfc-interval`` is ``3600``. A value of 0
   disables the LFC.

299 300 301 302 303 304 305 306 307
-  ``max-row-errors``: when the server loads a lease file, it is processed
   row by row, each row contaning a single lease. If a row is flawed and
   cannot be processed correctly the server will log it, discard the row,
   and go on to the next row. This parameter can be used to set a limit on
   the number of such discards that may occur after which the server will
   abandon the effort and exit.  The default value of 0 disables the limit
   and allows the server to process the entire file, regardless of how many
   rows are discarded.

308
An example configuration of the memfile backend is presented below:
309 310 311 312 313 314 315 316

::

   "Dhcp6": {
       "lease-database": {
           "type": "memfile",
           "persist": true,
           "name": "/tmp/kea-leases6.csv",
317 318
           "lfc-interval": 1800,
           "max-row-errors": 100
319 320 321 322 323 324
       }
   }

This configuration selects the ``/tmp/kea-leases6.csv`` as the storage
for lease information and enables persistence (writing lease updates to
this file). It also configures the backend to perform a periodic cleanup
325
of the lease file every 30 minutes and sets the maximum number of row
326 327
errors to 100.

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

It is important to know how the lease file contents are organized to
understand why the periodic lease file cleanup is needed. Every time the
server updates a lease or creates a new lease for the client, the new
lease information must be recorded in the lease file. For performance
reasons, the server does not update the existing client's lease in the
file, as this would potentially require rewriting the entire file.
Instead, it simply appends the new lease information to the end of the
file; the previous lease entries for the client are not removed. When
the server loads leases from the lease file, e.g. at the server startup,
it assumes that the latest lease entry for the client is the valid one.
The previous entries are discarded, meaning that the server can
re-construct the accurate information about the leases even though there
may be many lease entries for each client. However, storing many entries
for each client results in a bloated lease file and impairs the
performance of the server's startup and reconfiguration, as it needs to
process a larger number of lease entries.

Lease file cleanup (LFC) removes all previous entries for each client
and leaves only the latest ones. The interval at which the cleanup is
performed is configurable, and it should be selected according to the
frequency of lease renewals initiated by the clients. The more frequent
the renewals, the smaller the value of ``lfc-interval`` should be. Note,
however, that the LFC takes time and thus it is possible (although
unlikely) that, if the ``lfc-interval`` is too short, a new cleanup may
be started while the previous one is still running. The server would
354 355
recover from this by skipping the new cleanup when it detected that the
previous cleanup was still in progress. But it implies that the actual
356 357 358 359
cleanups will be triggered more rarely than configured. Moreover,
triggering a new cleanup adds overhead to the server, which will not be
able to respond to new requests for a short period of time when the new
cleanup process is spawned. Therefore, it is recommended that the
360
``lfc-interval`` value be selected in a way that allows the LFC
361 362 363 364
to complete the cleanup before a new cleanup is triggered.

Lease file cleanup is performed by a separate process (in the
background) to avoid a performance impact on the server process. To
365 366
avoid conflicts between two processes both using the same lease
files, the LFC process starts with Kea opening a new lease file; the
367 368
actual LFC process operates on the lease file that is no longer used by
the server. There are also other files created as a side effect of the
369 370
lease file cleanup. The detailed description of the LFC process is located later
in this Kea Administrator's Reference Manual: :ref:`kea-lfc`.
371 372 373 374 375 376

.. _database-configuration6:

Lease Database Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

377
.. note::
378 379 380 381 382 383 384

   Lease database access information must be configured for the DHCPv6
   server, even if it has already been configured for the DHCPv4 server.
   The servers store their information independently, so each server can
   use a separate database or both servers can use the same database.

Lease database configuration is controlled through the
385
Dhcp6/lease-database parameters. The database type must be set to
386 387 388 389 390 391 392 393
"memfile", "mysql", "postgresql", or "cql", e.g.:

::

   "Dhcp6": { "lease-database": { "type": "mysql", ... }, ... }

Next, the name of the database to hold the leases must be set; this is
the name used when the database was created (see
394 395
:ref:`mysql-database-create`, :ref:`pgsql-database-create`, or
:ref:`cql-database-create`).
396 397 398 399 400 401 402 403 404 405 406 407

::

   "Dhcp6": { "lease-database": { "name": "database-name" , ... }, ... }

For Cassandra:

::

   "Dhcp6": { "lease-database": { "keyspace": "database-name" , ... }, ... }

If the database is located on a different system from the DHCPv6 server,
408
the database host name must also be specified:
409 410 411 412 413

::

   "Dhcp6": { "lease-database": { "host": "remote-host-name", ... }, ... }

414 415
(It should be noted that this configuration may have a severe impact on server performance.)

416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
For Cassandra, multiple contact points can be provided:

::

   "Dhcp6": { "lease-database": { "contact-points": "remote-host-name[, ...]" , ... }, ... }

Normally, the database will be on the same machine as the DHCPv6 server.
In this case, set the value to the empty string:

::

   "Dhcp6": { "lease-database": { "host" : "", ... }, ... }

For Cassandra:

::

   "Dhcp6": { "lease-database": { "contact-points": "", ... }, ... }

435
Should the database use a port other than the default, it may be
436 437 438 439 440 441
specified as well:

::

   "Dhcp6": { "lease-database": { "port" : 12345, ... }, ... }

442
Should the database be located on a different system, the administrator may need to
443 444 445 446 447 448 449 450 451 452
specify a longer interval for the connection timeout:

::

   "Dhcp6": { "lease-database": { "connect-timeout" : timeout-in-seconds, ... }, ... }

The default value of five seconds should be more than adequate for local
connections. If a timeout is given, though, it should be an integer
greater than zero.

453
The maximum number of times the server will automatically attempt to
454 455 456 457 458 459 460 461
reconnect to the lease database after connectivity has been lost may be
specified:

::

   "Dhcp6": { "lease-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }

If the server is unable to reconnect to the database after making the
462
maximum number of attempts, the server will exit. A value of zero (the
463
default) disables automatic recovery and the server will exit
464
immediately upon detecting a loss of connectivity (MySQL and PostgreSQL
465 466
only).

467
The number of milliseconds the server will wait between attempts to
468 469 470 471 472 473 474
reconnect to the lease database after connectivity has been lost may
also be specified:

::

   "Dhcp6": { "lease-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... }

475
The default value for MySQL and PostgreSQL is 0, which disables automatic
476 477 478
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.

479
.. note::
480 481

   Automatic reconnection to database backends is configured
482 483 484 485
   individually per backend. This allows users to tailor the recovery
   parameters to each backend they use. We do suggest that users enable it
   either for all backends or none, so behavior is consistent.
   Losing connectivity to a backend for which reconnect is
486 487 488 489 490 491
   disabled will result in the server shutting itself down. This
   includes cases when the lease database backend and the hosts database
   backend are connected to the same database instance.

..

492
.. note::
493

494 495
   Note that the host parameter is used by the MySQL and PostgreSQL backends.
   Cassandra has a concept of contact points that can be used to
496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519
   contact the cluster, instead of a single IP or hostname. It takes a
   list of comma-separated IP addresses, which may be specified as:
   ::

      "Dhcp6": { "lease-database": { "contact-points" : "192.0.2.1,192.0.2.2", ... }, ... }

Finally, the credentials of the account under which the server will
access the database should be set:

::

   "Dhcp6": { "lease-database": { "user": "user-name",
                                  "password": "password",
                                 ... },
              ... }

If there is no password to the account, set the password to the empty
string "". (This is also the default.)

.. _cassandra-database-configuration6:

Cassandra-Specific Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

520 521
The parameters are the same for both DHCPv4 and DHCPv6. See
:ref:`cassandra-database-configuration4` for details.
522 523 524 525 526 527 528 529 530 531 532 533

.. _hosts6-storage:

Hosts Storage
-------------

Kea is also able to store information about host reservations in the
database. The hosts database configuration uses the same syntax as the
lease database. In fact, a Kea server opens independent connections for
each purpose, be it lease or hosts information. This arrangement gives
the most flexibility. Kea can keep leases and host reservations
separately, but can also point to the same database. Currently the
534
supported hosts database types are MySQL, PostgreSQL, and Cassandra.
535

536
For example, the following configuration can be used to configure a
537 538 539 540 541 542 543 544 545 546 547 548 549 550 551
connection to MySQL:

::

   "Dhcp6": {
       "hosts-database": {
           "type": "mysql",
           "name": "kea",
           "user": "kea",
           "password": "secret123",
           "host": "localhost",
           "port": 3306
       }
   }

552
Note that depending on the database configuration, many of the
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
parameters may be optional.

Please note that usage of hosts storage is optional. A user can define
all host reservations in the configuration file, and that is the
recommended way if the number of reservations is small. However, when
the number of reservations grows, it is more convenient to use host
storage. Please note that both storage methods (configuration file and
one of the supported databases) can be used together. If hosts are
defined in both places, the definitions from the configuration file are
checked first and external storage is checked later, if necessary.

In fact, host information can be placed in multiple stores. Operations
are performed on the stores in the order they are defined in the
configuration file, although this leads to a restriction in ordering in
the case of a host reservation addition; read-only stores must be
configured after a (required) read-write store, or the addition will
fail.

.. _hosts-databases-configuration6:

DHCPv6 Hosts Database Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Hosts database configuration is controlled through the
Dhcp6/hosts-database parameters. If enabled, the type of database must
be set to "mysql" or "postgresql".

::

   "Dhcp6": { "hosts-database": { "type": "mysql", ... }, ... }

Next, the name of the database to hold the reservations must be set;
585
this is the name used when the lease database was created (see
586
:ref:`supported-databases` for instructions on how to set up the
587
desired database type):
588 589 590 591 592 593

::

   "Dhcp6": { "hosts-database": { "name": "database-name" , ... }, ... }

If the database is located on a different system than the DHCPv6 server,
594
the database host name must also be specified:
595 596 597 598 599

::

   "Dhcp6": { "hosts-database": { "host": remote-host-name, ... }, ... }

600 601
(Again, it should be noted that this configuration may have a severe impact on server performance.)

602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621
Normally, the database will be on the same machine as the DHCPv6 server.
In this case, set the value to the empty string:

::

   "Dhcp6": { "hosts-database": { "host" : "", ... }, ... }

::

   "Dhcp6": { "hosts-database": { "port" : 12345, ... }, ... }

The maximum number of times the server will automatically attempt to
reconnect to the host database after connectivity has been lost may be
specified:

::

   "Dhcp6": { "host-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }

If the server is unable to reconnect to the database after making the
622
maximum number of attempts, the server will exit. A value of zero (the
623
default) disables automatic recovery and the server will exit
624
immediately upon detecting a loss of connectivity (MySQL and PostgreSQL
625 626 627 628 629 630 631 632 633 634 635 636
only). For Cassandra, Kea uses a Cassandra interface that connects to
all nodes in a cluster at the same time. Any connectivity issues should
be handled by internal Cassandra mechanisms.

The number of milliseconds the server will wait between attempts to
reconnect to the host database after connectivity has been lost may also
be specified:

::

   "Dhcp6": { "hosts-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... }

637
The default value for MySQL and PostgreSQL is 0, which disables automatic
638 639 640
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.

641
.. note::
642 643

   Automatic reconnection to database backends is configured
644 645 646 647
   individually per backend. This allows users to tailor the recovery
   parameters to each backend they use. We do suggest that users enable it
   either for all backends or none, so behavior is consistent.
   Losing connectivity to a backend for which reconnect is
648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664
   disabled will result in the server shutting itself down. This
   includes cases when the lease database backend and the hosts database
   backend are connected to the same database instance.

Finally, the credentials of the account under which the server will
access the database should be set:

::

   "Dhcp6": { "hosts-database": { "user": "user-name",
                                  "password": "password",
                                 ... },
              ... }

If there is no password to the account, set the password to the empty
string "". (This is also the default.)

665
The multiple storage extension uses a similar syntax; a configuration is
666
placed into a "hosts-databases" list instead of into a "hosts-database"
667
entry, as in:
668 669 670 671 672 673

::

   "Dhcp6": { "hosts-databases": [ { "type": "mysql", ... }, ... ], ... }

For additional Cassandra-specific parameters, see
674
:ref:`cassandra-database-configuration4`.
675 676 677

.. _read-only-database-configuration6:

678 679
Using Read-Only Databases for Host Reservations with DHCPv6
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
680 681 682 683 684 685 686 687 688 689 690 691 692 693 694

In some deployments the database user whose name is specified in the
database backend configuration may not have write privileges to the
database. This is often required by the policy within a given network to
secure the data from being unintentionally modified. In many cases
administrators have deployed inventory databases, which contain
substantially more information about the hosts than just the static
reservations assigned to them. The inventory database can be used to
create a view of a Kea hosts database and such a view is often
read-only.

Kea host database backends operate with an implicit configuration to
both read from and write to the database. If the database user does not
have write access to the host database, the backend will fail to start
and the server will refuse to start (or reconfigure). However, if access
695
to a read-only host database is required for retrieving reservations
696 697 698 699 700 701 702 703 704 705 706 707
for clients and/or assigning specific addresses and options, it is
possible to explicitly configure Kea to start in "read-only" mode. This
is controlled by the ``readonly`` boolean parameter as follows:

::

   "Dhcp6": { "hosts-database": { "readonly": true, ... }, ... }

Setting this parameter to ``false`` configures the database backend to
operate in "read-write" mode, which is also the default configuration if
the parameter is not specified.

708
.. note::
709 710 711 712 713 714 715 716 717

   The ``readonly`` parameter is currently only supported for MySQL and
   PostgreSQL databases.

.. _dhcp6-interface-configuration:

Interface Configuration
-----------------------

718 719
The DHCPv6 server must be configured to listen on specific network
interfaces. The simplest network interface configuration tells the
720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763
server to listen on all available interfaces:

::

   "Dhcp6": {
       "interfaces-config": {
           "interfaces": [ "*" ]
       }
       ...
   }

The asterisk plays the role of a wildcard and means "listen on all
interfaces." However, it is usually a good idea to explicitly specify
interface names:

::

   "Dhcp6": {
       "interfaces-config": {
           "interfaces": [ "eth1", "eth3" ]
       },
       ...
   }


It is possible to use a wildcard interface name (asterisk) concurrently
with explicit interface names:

::

   "Dhcp6": {
       "interfaces-config": {
           "interfaces": [ "eth1", "eth3", "*" ]
       },
       ...
   }


It is anticipated that this form of usage will only be used when it is
desired to temporarily override a list of interface names and listen on
all interfaces.

As with the DHCPv4 server, binding to specific addresses and disabling
re-detection of interfaces are supported. But ``dhcp-socket-type`` is
764
not supported, because DHCPv6 uses UDP/IPv6 sockets only. The following example
765 766 767 768 769 770 771 772 773 774 775 776 777 778
shows how to disable the interface detection:

::

   "Dhcp6": {
       "interfaces-config": {
           "interfaces": [ "eth1", "eth3" ],
           "re-detect": false
       },
       ...
   }


The loopback interfaces (i.e. the "lo" or "lo0" interface) are not
779
configured by default, unless explicitly mentioned in the
780
configuration. Note that Kea requires a link-local address (which does
781
not exist on all systems) or a specified unicast address, as in:
782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813

::

   "Dhcp6": {
       "interfaces-config": {
           "interfaces": [ "enp0s2/2001:db8::1234:abcd" ]
       },
       ...
   }


.. _ipv6-subnet-id:

IPv6 Subnet Identifier
----------------------

The subnet identifier is a unique number associated with a particular
subnet. In principle, it is used to associate clients' leases with their
respective subnets. When a subnet identifier is not specified for a
subnet being configured, it will be automatically assigned by the
configuration mechanism. The identifiers are assigned from 1 and are
monotonically increased for each subsequent subnet: 1, 2, 3 ....

If there are multiple subnets configured with auto-generated identifiers
and one of them is removed, the subnet identifiers may be renumbered.
For example: if there are four subnets and the third is removed, the
last subnet will be assigned the identifier that the third subnet had
before removal. As a result, the leases stored in the lease database for
subnet 3 are now associated with subnet 4, something that may have
unexpected consequences. The only remedy for this issue at present is to
manually specify a unique identifier for each subnet.

814
.. note::
815 816 817 818

   Subnet IDs must be greater than zero and less than 4294967295.

The following configuration will assign the specified subnet identifier
819
to a newly configured subnet:
820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836

::

   "Dhcp6": {
       "subnet6": [
           {
               "subnet": "2001:db8:1::/64",
               "id": 1024,
               ...
           }
       ]
   }

This identifier will not change for this subnet unless the "id"
parameter is removed or set to 0. The value of 0 forces auto-generation
of the subnet identifier.

837 838 839 840 841 842 843 844 845 846 847
.. _ipv6-subnet-prefix:

IPv6 Subnet Prefix
------------------

The subnet prefix is the second way to identify a subnet. It does not
need to have the address part to match the prefix length, for instance
this configuration is accepted:

::

Michal Nowikowski's avatar
Michal Nowikowski committed
848 849 850 851 852 853 854 855
   "Dhcp6": {
      "subnet6": [
          {
               "subnet": "2001:db8:1::1/64",
               ...
          }
       ]
   }
856 857 858 859 860 861

Even there is another subnet with the "2001:db8:1::/64" prefix:
only the textual form of subnets are compared to avoid duplicates.

.. note::

Michal Nowikowski's avatar
Michal Nowikowski committed
862 863
   Abuse of this feature can lead to incorrect subnet selection
   (see :ref:`dhcp6-config-subnets`).
864

865 866 867 868 869 870 871
.. _dhcp6-unicast:

Unicast Traffic Support
-----------------------

When the DHCPv6 server starts, by default it listens to the DHCP traffic
sent to multicast address ff02::1:2 on each interface that it is
872
configured to listen on (see :ref:`dhcp6-interface-configuration`). In some cases it is
873
useful to configure a server to handle incoming traffic sent to global
874
unicast addresses as well; the most common reason for this is to have
875
relays send their traffic to the server directly. To configure the
876 877 878
server to listen on a specific unicast address, add a slash after the interface name,
followed by the global unicast
address on which the server should listen. The server will listen to this
879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912
address in addition to normal link-local binding and listening on the
ff02::1:2 address. The sample configuration below shows how to listen on
2001:db8::1 (a global address) configured on the eth1 interface.

::

   "Dhcp6": {
       "interfaces-config": {
           "interfaces": [ "eth1/2001:db8::1" ]
       },
       ...
       "option-data": [
           {
               "name": "unicast",
               "data": "2001:db8::1"
           } ],
       ...
   }


This configuration will cause the server to listen on eth1 on the
link-local address, the multicast group (ff02::1:2), and 2001:db8::1.

Usually unicast support is associated with a server unicast option which
allows clients to send unicast messages to the server. The example above
includes a server unicast option specification which will cause the
client to send messages to the specified unicast address.

It is possible to mix interface names, wildcards, and interface
names/addresses in the list of interfaces. It is not possible, however,
to specify more than one unicast address on a given interface.

Care should be taken to specify proper unicast addresses. The server
will attempt to bind to the addresses specified without any additional
913
checks. This approach was selected on purpose, to allow the software to
914 915 916 917
communicate over uncommon addresses if so desired.

.. _dhcp6-address-config:

918 919
Configuration of IPv6 Address Pools
-----------------------------------
920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016

The main role of a DHCPv6 server is address assignment. For this, the
server must be configured with at least one subnet and one pool of
dynamic addresses to be managed. For example, assume that the server is
connected to a network segment that uses the 2001:db8:1::/64 prefix. The
administrator of that network decides that addresses from range
2001:db8:1::1 to 2001:db8:1::ffff are going to be managed by the Dhcp6
server. Such a configuration can be achieved in the following way:

::

   "Dhcp6": {
       "subnet6": [
          {
              "subnet": "2001:db8:1::/64",
              "pools": [
                  {
                      "pool": "2001:db8:1::1-2001:db8:1::ffff"
                  }
              ],
              ...
          }
       ]
   }

Note that ``subnet`` is defined as a simple string, but the ``pools``
parameter is actually a list of pools; for this reason, the pool
definition is enclosed in square brackets, even though only one range of
addresses is specified.

Each ``pool`` is a structure that contains the parameters that describe
a single pool. Currently there is only one parameter, ``pool``, which
gives the range of addresses in the pool.

It is possible to define more than one pool in a subnet; continuing the
previous example, further assume that 2001:db8:1:0:5::/80 should also be
managed by the server. It could be written as 2001:db8:1:0:5:: to
2001:db8:1::5:ffff:ffff:ffff, but typing so many 'f's is cumbersome. It
can be expressed more simply as 2001:db8:1:0:5::/80. Both formats are
supported by Dhcp6 and can be mixed in the pool list. For example, one
could define the following pools:

::

   "Dhcp6": {
       "subnet6": [
       {
           "subnet": "2001:db8:1::/64",
           "pools": [
               { "pool": "2001:db8:1::1-2001:db8:1::ffff" },
               { "pool": "2001:db8:1:05::/80" }
           ],
           ...
       }
       ]
   }

White space in pool definitions is ignored, so spaces before and after
the hyphen are optional. They can be used to improve readability.

The number of pools is not limited, but for performance reasons it is
recommended to use as few as possible.

The server may be configured to serve more than one subnet. To add a
second subnet, use a command similar to the following:

::

   "Dhcp6": {
       "subnet6": [
       {
           "subnet": "2001:db8:1::/64",
           "pools": [
               { "pool": "2001:db8:1::1-2001:db8:1::ffff" }
           ]
       },
       {
           "subnet": "2001:db8:2::/64",
           "pools": [
               { "pool": "2001:db8:2::/64" }
           ]
       },

           ...
       ]
   }

In this example, we allow the server to dynamically assign all addresses
available in the whole subnet. Although rather wasteful, it is certainly
a valid configuration to dedicate the whole /64 subnet for that purpose.
Note that the Kea server does not preallocate the leases, so there is no
danger in using gigantic address pools.

When configuring a DHCPv6 server using prefix/length notation, please
pay attention to the boundary values. When specifying that the server
can use a given pool, it will also be able to allocate the first
(typically a network address) address from that pool. For example, for
1017
pool 2001:db8:2::/64, the 2001:db8:2:: address may be assigned as well.
1018 1019 1020 1021 1022 1023
To avoid this, use the "min-max" notation.

Subnet and Prefix Delegation Pools
----------------------------------

Subnets may also be configured to delegate prefixes, as defined in `RFC
1024
8415 <https://tools.ietf.org/html/rfc8415>`__, section 6.3. A subnet may
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
have one or more prefix delegation pools. Each pool has a prefixed
address, which is specified as a prefix (``prefix``) and a prefix length
(``prefix-len``), as well as a delegated prefix length
(``delegated-len``). The delegated length must not be shorter than (that
is, it must be numerically greater than or equal to) the prefix length.
If both the delegated and prefix lengths are equal, the server will be
able to delegate only one prefix. The delegated prefix does not have to
match the subnet prefix.

Below is a sample subnet configuration which enables prefix delegation
for the subnet:

::

   "Dhcp6": {
       "subnet6": [
           {
               "subnet": "2001:d8b:1::/64",
               "pd-pools": [
                   {
                       "prefix": "3000:1::",
                       "prefix-len": 64,
                       "delegated-len": 96
                   }
               ]
           }
       ],
       ...
   }

.. _pd-exclude-option:

Prefix Exclude Option
---------------------

For each delegated prefix, the delegating router may choose to exclude a
single prefix out of the delegated prefix as specified in `RFC
1062
6603 <https://tools.ietf.org/html/rfc6603>`__. The requesting router must
1063 1064 1065 1066 1067
not assign the excluded prefix to any of its downstream interfaces, and
it is intended to be used on a link through which the delegating router
exchanges DHCPv6 messages with the requesting router. The configuration
example below demonstrates how to specify an excluded prefix within a
prefix pool definition. The excluded prefix
1068
"2001:db8:1:8000:cafe:80::/72" will be sent to a requesting router which
1069 1070
includes the Prefix Exclude option in the Option Request option (ORO),
and which is delegated a prefix from this pool.
1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082

::

   "Dhcp6": {
       "subnet6": [
           {
               "subnet": "2001:db8:1::/48",
               "pd-pools": [
                   {
                       "prefix": "2001:db8:1:8000::",
                       "prefix-len": 48,
                       "delegated-len": 64,
1083
                       "excluded-prefix": "2001:db8:1:8000:cafe:80::",
1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095
                       "excluded-prefix-len": 72
                   }
               ]
           }
       ]
   }

.. _dhcp6-std-options:

Standard DHCPv6 Options
-----------------------

1096
One of the major features of the DHCPv6 server is the ability to provide
1097 1098 1099
configuration options to clients. Although there are several options
that require special behavior, most options are sent by the server only
if the client explicitly requests them. The following example shows how
1100 1101
to configure the addresses of DNS servers, one of the most frequently used options.
Options specified in this way are considered global and apply to all configured subnets.
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121

::

   "Dhcp6": {
       "option-data": [
           {
              "name": "dns-servers",
              "code": 23,
              "space": "dhcp6",
              "csv-format": true,
              "data": "2001:db8::cafe, 2001:db8::babe"
           },
           ...
       ]
   }

The ``option-data`` line creates a new entry in the option-data table.
This table contains information on all global options that the server is
supposed to configure in all subnets. The ``name`` line specifies the
option name. (For a complete list of currently supported names, see
1122
:ref:`dhcp6-std-options-list`.) The next line specifies the
1123 1124 1125
option code, which must match one of the values from that list. The line
beginning with ``space`` specifies the option space, which must always
be set to "dhcp6" as these are standard DHCPv6 options. For other name
1126
spaces, including custom option spaces, see :ref:`dhcp6-option-spaces`. The following line
1127 1128
specifies the format in which the data will be entered; use of CSV
(comma-separated values) is recommended. Finally, the ``data`` line
1129
gives the actual value to be sent to clients. The data parameter is specified as
1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156
normal text, with values separated by commas if more than one value is
allowed.

Options can also be configured as hexadecimal values. If "csv-format" is
set to false, the option data must be specified as a hexadecimal string.
The following commands configure the DNS-SERVERS option for all subnets
with the following addresses: 2001:db8:1::cafe and 2001:db8:1::babe.

::

   "Dhcp6": {
       "option-data": [
           {
              "name": "dns-servers",
              "code": 23,
              "space": "dhcp6",
              "csv-format": false,
              "data": "20 01 0D B8 00 01 00 00 00 00 00 00 00 00 CA FE
                       20 01 0D B8 00 01 00 00 00 00 00 00 00 00 BA BE"
           },
           ...
       ]
   }


..

1157
.. note::
1158 1159 1160 1161 1162 1163 1164

   The value for the setting of the "data" element is split across two
   lines in this example for clarity; when entering the command, the
   whole string should be entered on the same line.

Kea supports the following formats when specifying hexadecimal data:

1165
-  ``Delimited octets`` - one or more octets separated by either colons or
1166 1167 1168 1169
   spaces (':' or ' '). While each octet may contain one or two digits,
   we strongly recommend always using two digits. Valid examples are
   "ab:cd:ef" and "ab cd ef".

1170
-  ``String of digits`` - a continuous string of hexadecimal digits with
1171 1172 1173
   or without a "0x" prefix. Valid examples are "0xabcdef" and "abcdef".

Care should be taken to use proper encoding when using hexadecimal
1174
format; Kea's ability to validate data correctness in hexadecimal is
1175 1176
limited.

1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196
As of Kea 1.6.0, it is also possible to specify data for binary options as
a single-quoted text string within double quotes as shown (note that
``csv-format`` must be set to false):

::

   "Dhcp6": {
       "option-data": [
           {
               "name": "subscriber-id",
               "code": 38,
               "space": "dhcp6",
               "csv-format": false,
               "data": "'convert this text to binary'"
           },
           ...
       ],
       ...
   }

1197
Most of the parameters in the "option-data" structure are optional and
1198 1199 1200
can be omitted in some circumstances, as discussed in :ref:`dhcp6-option-data-defaults`.
Only one of name or code
is required; it is not necessary to specify both. Space has a default value
1201 1202 1203
of "dhcp6", so this can be skipped as well if a regular (not
encapsulated) DHCPv6 option is defined. Finally, csv-format defaults to "true", so it
too can be skipped, unless the option value is specified as
1204
hexstring. Therefore, the above example can be simplified to:
1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239

::

   "Dhcp6": {
       "option-data": [
           {
              "name": "dns-servers",
              "data": "2001:db8::cafe, 2001:db8::babe"
           },
           ...
       ]
   }


Defined options are added to the response when the client requests them,
as well as any options required by a protocol. An administrator can also
specify that an option is always sent, even if a client did not
specifically request it. To enforce the addition of a particular option,
set the "always-send" flag to true as in:

::

   "Dhcp6": {
       "option-data": [
           {
              "name": "dns-servers",
              "data": "2001:db8::cafe, 2001:db8::babe",
              "always-send": true
           },
           ...
       ]
   }


The effect is the same as if the client added the option code in the
1240
Option Request option (or its equivalent for vendor options), as in:
1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271

::

   "Dhcp6": {
       "option-data": [
           {
              "name": "dns-servers",
              "data": "2001:db8::cafe, 2001:db8::babe",
              "always-send": true
           },
           ...
       ],
       "subnet6": [
           {
              "subnet": "2001:db8:1::/64",
              "option-data": [
                  {
                      "name": "dns-servers",
                      "data": "2001:db8:1::cafe, 2001:db8:1::babe"
                  },
                  ...
              ],
              ...
           },
           ...
       ],
       ...
   }


The DNS servers option is always added to responses (the always-send is
1272
"sticky"), but the value is the subnet one when the client is localized
1273 1274 1275
in the subnet.

It is possible to override options on a per-subnet basis. If clients
1276 1277 1278 1279 1280
connected to most subnets are expected to get the same values of
a given option, administrators should use global options; it is possible to override
specific values for a small number of subnets. On the other hand, if
different values are used in each subnet, it does not make sense to specify
global option values; rather, only subnet-specific ones should be set.
1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308

The following commands override the global DNS servers option for a
particular subnet, setting a single DNS server with address
2001:db8:1::3.

::

   "Dhcp6": {
       "subnet6": [
           {
               "option-data": [
                   {
                       "name": "dns-servers",
                       "code": 23,
                       "space": "dhcp6",
                       "csv-format": true,
                       "data": "2001:db8:1::3"
                   },
                   ...
               ],
               ...
           },
           ...
       ],
       ...
   }

In some cases it is useful to associate some options with an address or
1309
prefix pool from which a client is assigned a lease. Pool-specific
1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344
option values override subnet-specific and global option values. If the
client is assigned multiple leases from different pools, the server will
assign options from all pools from which the leases have been obtained.
However, if the particular option is specified in multiple pools from
which the client obtains the leases, only one instance of this option
will be handed out to the client. The server's administrator must not
try to prioritize assignment of pool-specific options by trying to order
pools declarations in the server configuration.

The following configuration snippet demonstrates how to specify the DNS
servers option, which will be assigned to a client only if the client
obtains an address from the given pool:

::

   "Dhcp6": {
       "subnet6": [
           {
               "pools": [
                   {
                       "pool": "2001:db8:1::100-2001:db8:1::300",
                       "option-data": [
                           {
                               "name": "dns-servers",
                               "data": "2001:db8:1::10"
                           }
                       ]
                   }
               ]
           },
           ...
       ],
       ...
   }

1345
Options can also be specified in class or host reservation scope. The
1346 1347 1348 1349
current Kea options precedence order is (from most important): host
reservation, pool, subnet, shared network, class, global.

The currently supported standard DHCPv6 options are listed in
1350
:ref:`dhcp6-std-options-list`. "Name" and "Code" are the
1351 1352
values that should be used as a name/code in the option-data structures.
"Type" designates the format of the data; the meanings of the various
1353
types are given in :ref:`dhcp-types`.
1354

1355 1356 1357
When a data field is a string and that string contains the comma (,;
U+002C) character, the comma must be escaped with two backslashes (\;
U+005C). This double escape is required because both the routine
1358 1359
splitting CSV data into fields and JSON use the same escape character; a
single escape (\,) would make the JSON invalid. For example, the string
1360
"EST5EDT4,M3.2.0/02:00,M11.1.0/02:00" must be represented as:
1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389

::

   "Dhcp6": {
       "subnet6": [
           {
               "pools": [
                   {
                       "option-data": [
                           {
                               "name": "new-posix-timezone",
                               "data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
                           }
                       ]
                   },
                   ...
               ],
               ...
           },
           ...
       ],
       ...
   }

Some options are designated as arrays, which means that more than one
value is allowed in such an option. For example, the option dns-servers
allows the specification of more than one IPv6 address, enabling clients
to obtain the addresses of multiple DNS servers.

1390
:ref:`dhcp6-custom-options` describes the
1391 1392 1393 1394 1395 1396
configuration syntax to create custom option definitions (formats).
Creation of custom definitions for standard options is generally not
permitted, even if the definition being created matches the actual
option format defined in the RFCs. There is an exception to this rule
for standard options for which Kea currently does not provide a
definition. In order to use such options, a server administrator must
1397
create a definition as described in :ref:`dhcp6-custom-options` in the 'dhcp6' option space. This
1398
definition should match the option format described in the relevant RFC,
1399
but the configuration mechanism will allow any option format as it
1400 1401
currently has no means to validate it.

1402 1403
.. _dhcp6-std-options-list:

1404 1405
.. table:: List of Standard DHCPv6 Options

1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537
   +--------------------------+-----------------+-----------------+-----------------+
   | Name                     | Code            | Type            | Array?          |
   +==========================+=================+=================+=================+
   | preference               | 7               | uint8           | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | unicast                  | 12              | ipv6-address    | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | vendor-opts              | 17              | uint32          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | sip-server-dns           | 21              | fqdn            | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | sip-server-addr          | 22              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | dns-servers              | 23              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | domain-search            | 24              | fqdn            | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | nis-servers              | 27              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | nisp-servers             | 28              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | nis-domain-name          | 29              | fqdn            | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | nisp-domain-name         | 30              | fqdn            | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | sntp-servers             | 31              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | information-refresh-time | 32              | uint32          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | bcmcs-server-dns         | 33              | fqdn            | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | bcmcs-server-addr        | 34              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | geoconf-civic            | 36              | record (uint8,  | false           |
   |                          |                 | uint16, binary) |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | remote-id                | 37              | record (uint32, | false           |
   |                          |                 | binary)         |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | subscriber-id            | 38              | binary          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | client-fqdn              | 39              | record (uint8,  | false           |
   |                          |                 | fqdn)           |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | pana-agent               | 40              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | new-posix-timezone       | 41              | string          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | new-tzdb-timezone        | 42              | string          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | ero                      | 43              | uint16          | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | lq-query (1)             | 44              | record (uint8,  | false           |
   |                          |                 | ipv6-address)   |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | client-data (1)          | 45              | empty           | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | clt-time (1)             | 46              | uint32          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | lq-relay-data (1)        | 47              | record          | false           |
   |                          |                 | (ipv6-address,  |                 |
   |                          |                 | binary)         |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | lq-client-link (1)       | 48              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | v6-lost                  | 51              | fqdn            | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | capwap-ac-v6             | 52              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | relay-id                 | 53              | binary          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | v6-access-domain         | 57              | fqdn            | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | sip-ua-cs-list           | 58              | fqdn            | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | bootfile-url             | 59              | string          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | bootfile-param           | 60              | tuple           | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | client-arch-type         | 61              | uint16          | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | nii                      | 62              | record (uint8,  | false           |
   |                          |                 | uint8, uint8)   |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | aftr-name                | 64              | fqdn            | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | erp-local-domain-name    | 65              | fqdn            | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | rsoo                     | 66              | empty           | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | pd-exclude               | 67              | binary          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | rdnss-selection          | 74              | record          | true            |
   |                          |                 | (ipv6-address,  |                 |
   |                          |                 | uint8, fqdn)    |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | client-linklayer-addr    | 79              | binary          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | link-address             | 80              | ipv6-address    | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | solmax-rt                | 82              | uint32          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | inf-max-rt               | 83              | uint32          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | dhcp4o6-server-addr      | 88              | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-rule                 | 89              | record (uint8,  | false           |
   |                          |                 | uint8, uint8,   |                 |
   |                          |                 | ipv4-address,   |                 |
   |                          |                 | ipv6-prefix)    |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-br                   | 90              | ipv6-address    | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-dmr                  | 91              | ipv6-prefix     | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-v4v6bind             | 92              | record          | false           |
   |                          |                 | (ipv4-address,  |                 |
   |                          |                 | ipv6-prefix)    |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-portparams           | 93              | record(uint8,   | false           |
   |                          |                 | psid)           |                 |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-cont-mape            | 94              | empty           | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-cont-mapt            | 95              | empty           | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | s46-cont-lw              | 96              | empty           | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | v6-captive-portal        | 103             | string          | false           |
   +--------------------------+-----------------+-----------------+-----------------+
   | ipv6-address-andsf       | 143             | ipv6-address    | true            |
   +--------------------------+-----------------+-----------------+-----------------+
1538 1539

Options marked with (1) have option definitions, but the logic behind
1540
them is not implemented. That means that, technically, Kea knows how to
1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553
parse them in incoming messages or how to send them if configured to do
so, but not what to do with them. Since the related RFCs require certain
processing, the support for those options is non-functional. However, it
may be useful in some limited lab testing; hence the definition formats
are listed here.

.. _s46-options:

Common Softwire46 Options
-------------------------

Softwire46 options are involved in IPv4 over IPv6 provisioning by means
of tunneling or translation as specified in `RFC
1554
7598 <https://tools.ietf.org/html/rfc7598>`__. The following sections
1555 1556 1557 1558 1559 1560 1561
provide configuration examples of these options.

.. _s46-containers:

Softwire46 Container Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1562
Softwire46 (S46) container options group rules and optional port parameters for a
1563 1564 1565
specified domain. There are three container options specified in the
"dhcp6" (top-level) option space: the MAP-E Container option, the MAP-T
Container option, and the S46 Lightweight 4over6 Container option. These
1566
options only contain the encapsulated options specified below; they do not
1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588
include any data fields.

To configure the server to send a specific container option along with
all encapsulated options, the container option must be included in the
server configuration as shown below:

::

   "Dhcp6": {
       ...
       "option-data": [
           {
               "name": "s46-cont-mape"
           } ],
       ...
   }

This configuration will cause the server to include the MAP-E Container
option to the client. Use "s46-cont-mapt" or "s46-cont-lw" for the MAP-T
Container and S46 Lightweight 4over6 Container options, respectively.

All remaining Softwire options described below are included in one of
1589
the container options. Thus, they must be included in appropriate
1590 1591 1592 1593 1594 1595