1.. _cb-cmds-library: 2 3cb_cmds: Configuration Backend Commands 4======================================= 5 6This section describes the ``cb_cmds`` hooks library, used to manage Kea 7servers' configurations in the Configuration Backends. This library must 8be used in conjunction with the available CB hooks libraries implementing 9the common APIs to create, read, update, and delete (CRUD) the 10configuration information in the respective databases. For example: 11the ``mysql_cb`` hooks library implements this API for MySQL. In order to 12manage the configuration information in the MySQL database, both the 13``mysql_cb`` and ``cb_cmds`` libraries must be loaded by the server 14used for the configuration management. 15 16The ``cb_cmds`` library is only available to ISC customers with a paid 17support contract. 18 19.. note:: 20 21 This library may only be loaded by the ``kea-dhcp4`` or 22 ``kea-dhcp6`` process. 23 24.. note:: 25 26 Please read about :ref:`cb-limitations` before using the commands 27 described in this section. 28 29Commands Structure 30~~~~~~~~~~~~~~~~~~ 31 32There are 5 types of commands supported by this library: 33 34- ``del`` - delete the selected object from the database, e.g. 35 ``remote-global-parameter4-del``. 36 37- ``get`` - fetch the selected object from the database, e.g. 38 ``remote-subnet4-get``. 39 40- ``get-all`` - fetch all objects of the particular type from the 41 database, e.g. ``remote-option-def4-get-all``. 42 43- ``list`` - list all objects of the particular type in the database, 44 e.g. ``remote-network4-list``; this class of commands returns brief 45 information about each object compared to the output of ``get-all``. 46 47- ``set`` - creates or replaces an object of the given type in the 48 database, e.g. ``remote-option4-global-set``. 49 50All types of commands accept an optional ``remote`` map which selects the 51database instance to which the command refers. For example: 52 53.. code-block:: json 54 55 { 56 "command": "remote-subnet4-list", 57 "arguments": { 58 "remote": { 59 "type": "mysql", 60 "host": "192.0.2.33", 61 "port": 3302 62 } 63 } 64 } 65 66selects the MySQL database, running on host 192.0.2.33 and port 3302, to 67fetch the list of subnets from. All parameters in the ``remote`` argument are 68optional. The ``port`` parameter can be only specified in conjunction 69with the ``host``. If no options in the ``remote`` parameter are to 70be specified, the parameter should be omitted. In this case, the server 71will use the first backend listed in the ``config-control`` map within 72the configuration of the server receiving the command. 73 74.. note:: 75 76 In the present Kea release, it is possible to configure the Kea server 77 to use only one configuration backend. Strictly speaking, it is 78 possible to point the Kea server to at most one MySQL database using the 79 ``config-control`` parameter. That's why the ``remote`` parameter may 80 be omitted in the commands and the cb_cmds hooks library will use the 81 sole backend by default. 82 83.. _cb-cmds-dhcp: 84 85Control Commands for DHCP Servers 86~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 87 88This section describes and gives some examples of the control commands 89implemented by the ``cb_cmds`` hooks library, to manage the 90configuration information of the DHCPv4 and DHCPv6 servers. Many of the 91commands are almost identical between DHCPv4 and DHCPv6; they only 92differ by the command name. Other commands differ slightly by the 93structure of the inserted data; for example, the structure of the IPv4 subnet 94information is different than that of the IPv6 subnet. 95Nevertheless, they still share the structure of their command arguments 96and thus it makes sense to describe them together. 97 98In the following sections, various commands are described and some usage 99examples are provided. In the sections jointly describing the DHCPv4 and 100DHCPv6 variants of the particular command, we sometimes use the following 101notation: the ``remote-subnet[46]-set`` is the wildcard name for the 102two commands: ``remote-subnet4-set`` and ``remote-subnet6-set``. 103 104In addition, whenever the text in the subsequent sections refers to a 105DHCP command or DHCP parameter, it refers to both DHCPv4 and DHCPv6 106variants. The text specific to the particular server type refers to them 107as: DHCPv4 command, DHCPv4 parameter, DHCPv6 command, DHCPv6 parameter, 108etc. 109 110.. _cb-cmds-metadata: 111 112Metadata 113~~~~~~~~ 114 115The typical response to the ``get`` or ``list`` command includes a list 116of returned objects (e.g. subnets), and each such object contains the 117``metadata`` map with some database-specific information describing this 118object. In other words, the metadata contains any information about the 119fetched object which may be useful for an administrator but which is not 120part of the object specification from the DHCP server standpoint. In the 121present Kea release, the metadata is limited to the ``server-tag``. It 122describes the association of the object with a particular server or 123all servers. 124 125The following is the example response to the ``remote-network4-list`` 126command, which includes the metadata: 127 128.. code-block:: json 129 130 { 131 "result": 0, 132 "text": "1 IPv4 shared network(s) found.", 133 "arguments": { 134 "shared-networks": [ 135 { 136 "name": "level3", 137 "metadata": { 138 "server-tags": [ "all" ] 139 } 140 } 141 ], 142 "count": 1 143 } 144 } 145 146 147Client implementations must not assume that the metadata contains only 148the ``server-tags`` parameter. In future releases, this map will be 149extended with additional information, e.g. object modification time, log 150message created during the last modification, etc. 151 152.. _command-remote-server4-del: 153.. _command-remote-server6-del: 154 155remote-server4-del, remote-server6-del commands 156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 157 158This command is used to delete the information about a selected DHCP server from 159the configuration database. The server is identified by a unique case 160insensitive server tag. For example: 161 162.. code-block:: json 163 164 { 165 "command": "remote-server4-del", 166 "arguments": { 167 "servers": [ 168 { 169 "server-tag": "server1" 170 } 171 ], 172 "remote": { 173 "type": "mysql" 174 } 175 } 176 } 177 178As a result of this command, the user defined server called `server1` is removed 179from the database. All associations of the configuration information with this 180server are automatically removed from the database. The non-shareable 181configuration information, such as: global parameters, option definitions and 182global options associated with the server are removed from the database. The 183shareable configuration information, i.e. the configuration elements which may 184be associated with more than one server, is preserved. In particular, the 185subnets and shared networks associated with the deleted servers are 186preserved. If any of the shareable configuration elements was associated only 187with the deleted server, this object becomes unassigned (orphaned). For 188example: if a subnet has been created and associated with the `server1` using 189the `remote-subnet4-set` command and the server1 is subsequently deleted, the 190subnet remains in the database but none of the servers can use this subnet. The 191subnet can be updated using the `remote-subnet4-set` and associated with some 192other server or with all servers using the special server tag "all". Such subnet 193can be also deleted from the database using the `remote-subnet4-del-by-id` or 194`remote-subnet4-del-by-prefix`, if it is no longer needed. 195 196The following is the successful response to the `remote-server4-del` command: 197 198.. code-block:: json 199 200 { 201 "result": 0, 202 "text": "1 DHCPv4 server(s) deleted." 203 "arguments": { 204 "count": 1 205 } 206 } 207 208 209.. note:: 210 211 The `remote-server4-del` and `remote-server6-del` commands must be used with 212 care, because an accidental deletion of the server causes some parts of the 213 existing configurations to be lost permanently from the database. This 214 operation is not reversible. Re-creation of the accidentally deleted server 215 does not revert the lost configuration for that server and such configuration 216 must be re-created manually by the user. 217 218.. _command-remote-server4-get: 219.. _command-remote-server6-get: 220 221remote-server4-get, remote-server6-get commands 222~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 223 224This command is used to fetch the information about the selected DHCP server 225from the configuration database. For example: 226 227.. code-block:: json 228 229 { 230 "command": "remote-server6-get" 231 "arguments": { 232 "servers": [ 233 { 234 "server-tag": "server1" 235 } 236 ], 237 "remote": { 238 "type": "mysql" 239 } 240 } 241 } 242 243 244This command fetches the information about the DHCPv6 server identified by the 245server tag `server1`. The server tag is case insensitive. A successful response 246returns basic information about the server, such as server tag and the user's 247description of the server: 248 249.. code-block:: json 250 251 { 252 "result": 0, 253 "text": "DHCP server server1 found.", 254 "arguments": { 255 "servers": [ 256 { 257 "server-tag": "server1", 258 "description": "A DHCPv6 server located on the first floor." 259 } 260 ], 261 "count": 1 262 } 263 } 264 265.. _command-remote-server4-get-all: 266.. _command-remote-server6-get-all: 267 268remote-server4-get-all, remote-server6-get-all commands 269~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 270 271This command is used to fetch all user defined DHCPv4 or DHCPv6 servers from the 272database. The command structure is very simple: 273 274.. code-block:: json 275 276 { 277 "command": "remote-server4-get-all" 278 "arguments": { 279 "remote": { 280 "type": "mysql" 281 } 282 } 283 } 284 285The response includes basic information about each server, such as its server 286tag and description: 287 288.. code-block:: json 289 290 { 291 "result": 0, 292 "text": "DHCPv4 servers found.", 293 "arguments": { 294 "servers": [ 295 { 296 "server-tag": "server1", 297 "description": "A DHCP server located on the first floor." 298 }, 299 { 300 "server-tag": "server2", 301 "description": "An old DHCP server to be soon replaced." 302 } 303 ], 304 "count": 2 305 } 306 } 307 308.. _command-remote-server4-set: 309.. _command-remote-server6-set: 310 311remote-server4-set, remote-server6-set commands 312~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 313 314This command is used to create or replace an information about a DHCP server in 315the database. The information about the server must be created when there is a 316need to differentiate the configurations used by various Kea instances 317connecting to the same database. Various configuration elements, e.g. global 318parameters, subnets etc. may be explicitly associated with the selected servers 319(using server tags as identifiers), allowing only these servers to use the 320respective configuration elements. Using the particular server tag to make such 321associations is only possible when the server information has been stored in the 322database via the `remote-server4-set` or `remote-server6-set` commands. The 323following command creates a new (or updates an existing) DHCPv6 server in the 324database: 325 326.. code-block:: json 327 328 { 329 "command": "remote-server6-set" 330 "arguments": { 331 "servers": [ 332 { 333 "server-tag": "server1", 334 "description": "A DHCP server on the ground floor." 335 } 336 ], 337 "remote": { 338 "type": "mysql" 339 } 340 } 341 } 342 343The server tag must be unique across all servers in the database. When the 344server information under the given server tag already exists, it is replaced 345with the new information. The specified server tag is case-insensitive, and the 346maximum length of the server tag is 256 characters. The following keywords are 347reserved and must not be used as server tags: "all" and "any". 348 349The following is the example response to the above command: 350 351.. code-block:: json 352 353 { 354 "result": 0, 355 "text": "DHCPv6 server successfully set.", 356 "arguments": { 357 "servers": [ 358 { 359 "server-tag": "server1", 360 "description": "A DHCP server on the ground floor." 361 } 362 ] 363 } 364 } 365 366 367.. _command-remote-global-parameter4-del: 368 369.. _command-remote-global-parameter6-del: 370 371The remote-global-parameter4-del, remote-global-parameter6-del Commands 372~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 373 374These commands are used to delete a global DHCP parameter from the 375configuration database. When the parameter is deleted from the database, 376the server will use the value specified in the configuration file for 377this parameter, or a default value if the parameter is not specified in 378the configuration file. 379 380The following command attempts to delete the DHCPv4 ``renew-timer`` 381parameter common for all servers from the database: 382 383.. code-block:: json 384 385 { 386 "command": "remote-global-parameter4-del", 387 "arguments": { 388 "parameters": [ "renew-timer" ], 389 "remote": { 390 "type": "mysql" 391 }, 392 "server-tags": [ "all" ] 393 } 394 } 395 396If the server specific parameter is to be deleted, the 397`server-tags` list must contain the tag of the appropriate 398server. There must be exactly one server tag specified in this list. 399 400 401.. _command-remote-global-parameter4-get: 402 403.. _command-remote-global-parameter6-get: 404 405The remote-global-parameter4-get, remote-global-parameter6-get Commands 406~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 407 408These commands are used to fetch a scalar global DHCP parameter from the 409configuration database. 410 411The following command attempts to fetch the ``boot-file-name`` 412parameter for the "server1": 413 414.. code-block:: json 415 416 { 417 "command": "remote-global-parameter4-get", 418 "arguments": { 419 "parameters": [ "boot-file-name" ], 420 "remote": { 421 "type": "mysql" 422 }, 423 "server-tags": [ "server1" ] 424 } 425 } 426 427 428The returned value has one of the four scalar types: string, integer, 429real, or boolean. Non-scalar global configuration parameters, such as map 430or list, are not returned by this command. 431 432In the case of the example above, the string value is returned, e.g.: 433 434.. code-block:: json 435 436 { 437 "result": 0, 438 "text": "1 DHCPv4 global parameter found.", 439 "arguments": { 440 "parameters": { 441 "boot-file-name": "/dev/null", 442 "metadata": { 443 "server-tags": [ "all" ] 444 } 445 }, 446 "count": 1 447 } 448 } 449 450 451Note that the response above indicates that the returned parameter is associated 452with "all" servers rather than "server1" used in the command. This indicates 453that there is no server1 specific value in the database. Therefore, the value 454shared by all servers is returned. If there was the server1 specific value 455in the database this value would be returned instead. 456 457The example response for the integer value is: 458 459.. code-block:: json 460 461 { 462 "result": 0, 463 "text": "1 DHCPv4 global parameter found.", 464 "arguments": { 465 "parameters": { 466 "renew-timer": 2000, 467 "metadata": { 468 "server-tags": [ "server1" ] 469 } 470 }, 471 "count": 1 472 } 473 } 474 475 476The real value: 477 478.. code-block:: json 479 480 { 481 "result": 0, 482 "text": "1 DHCPv4 global parameter found.", 483 "arguments": { 484 "parameters": { 485 "t1-percent": 0.85, 486 "metadata": { 487 "server-tags": [ "all" ] 488 } 489 }, 490 "count": 1 491 } 492 } 493 494 495Finally, the boolean value: 496 497.. code-block:: json 498 499 { 500 "result": 0, 501 "text": "1 DHCPv4 global parameter found.", 502 "arguments": { 503 "parameters": { 504 "match-client-id": true, 505 "metadata": { 506 "server-tags": [ "server2" ] 507 } 508 }, 509 "count": 1 510 } 511 } 512 513 514.. _command-remote-global-parameter4-get-all: 515 516.. _command-remote-global-parameter6-get-all: 517 518The remote-global-parameter4-get-all, remote-global-parameter6-get-all Commands 519~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 520 521These commands are used to fetch all global DHCP parameters from the database 522for the specified server. The following example demonstrates how to fetch all 523global parameters to be used by the server "server1": 524 525.. code-block:: json 526 527 { 528 "command": "remote-global-parameter4-get-all", 529 "arguments": { 530 "remote": { 531 "type": "mysql" 532 }, 533 "server-tags": [ "server1" ] 534 } 535 } 536 537The example response may look as follows: 538 539.. code-block:: json 540 541 { 542 "result": 0, 543 "text": "DHCPv4 global parameters found.", 544 "arguments": { 545 "parameters": [ 546 { 547 "boot-file-name": "/dev/null", 548 "metadata": { 549 "server-tags": [ "server1" ] 550 } 551 }, 552 { 553 "match-client-id": true, 554 "metadata": { 555 "server-tags": [ "all" ] 556 } 557 } 558 ], 559 "count": 2 560 } 561 } 562 563 564The example response contains two parameters, one string parameter and one 565boolean parameter. The metadata returned for each parameter indicates 566if this parameter is specific to the "server1" or all servers. Since the 567`match-client-id` value is associated with "all" servers 568it indicates that there is no server1 specific setting for this parameter. 569Each parameter always has exactly one server tag associated with it, because 570the global parameters are non-shareable configuration elements. 571 572.. note:: 573 574 If the server tag is set to "all" in the command, the response will 575 contain only the global parameters associated with the logical server 576 "all". When the server tag points to the specific server (as in the 577 example above), the returned list combines parameters associated with 578 this server and all servers, but the former take precedence. 579 580.. _command-remote-global-parameter4-set: 581 582.. _command-remote-global-parameter6-set: 583 584The remote-global-parameter4-set, remote-global-parameter6-set Commands 585~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 586 587This command is used to create scalar global DHCP parameters in the 588database. If any of the parameters already exists, its value is replaced 589as a result of this command. It is possible to set multiple parameters 590within a single command, each having one of the four types: string, 591integer, real, or boolean. For example: 592 593.. code-block:: json 594 595 { 596 "command": "remote-global-parameter4-set" 597 "arguments": { 598 "parameters": { 599 "boot-file-name": "/dev/null", 600 "renew-timer": 2000, 601 "t1-percent": 0.85, 602 "match-client-id": true 603 }, 604 "remote": { 605 "type": "mysql" 606 }, 607 "server-tags": [ "server1" ] 608 } 609 } 610 611 612An error is returned if any of the parameters is not supported by the DHCP 613server or its type does not match. Care should be taken when multiple parameters 614are specified in a single command, because it is possible that only some of the 615parameters are stored successfully and some fail. If an error occurs when 616processing this command, it is recommended to use 617``remote-global-parameter[46]-get-all`` to check which of the parameters have 618been stored/updated successfully and which have failed. 619 620The `server-tags` list is mandatory and it must contain a single server tag or 621the keyword "all". In the example above, all specified parameters are associated 622with the "server1" server. 623 624.. _command-remote-network4-del: 625 626.. _command-remote-network6-del: 627 628The remote-network4-del, remote-network6-del Commands 629~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 630 631These commands are used to delete an IPv4 or IPv6 shared network from 632the database. The optional parameter ``subnets-action`` determines 633whether the subnets belonging to the deleted shared network should also 634be deleted or preserved. The ``subnets-action`` parameter defaults to ``keep``, 635which preserves the subnets. If it is set to ``delete``, the subnets are 636deleted along with the shared network. 637 638The following command: 639 640.. code-block:: json 641 642 { 643 "command": "remote-network6-del", 644 "arguments": { 645 "shared-networks": [ 646 { 647 "name": "level3" 648 } 649 ], 650 "subnets-action": "keep", 651 "remote": { 652 "type": "mysql" 653 } 654 } 655 } 656 657 658deletes the "level3" IPv6 shared network. The subnets are preserved, but 659they are disassociated from the deleted shared network and become 660global. This behavior corresponds to the behavior of the 661``network[46]-del`` commands with respect to the ``subnets-action`` parameter. 662 663Note that the `server-tags` parameter must not be used for this command. 664 665.. _command-remote-network4-get: 666 667.. _command-remote-network6-get: 668 669The remote-network4-get, remote-network6-get Commands 670~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 671 672These commands are used to retrieve information about an IPv4 or 673IPv6 shared network. The optional parameter ``subnets-include`` denotes 674whether the subnets belonging to the shared network should also be 675returned. This parameter defaults to ``no``, in which case the subnets 676are not returned. If this parameter is set to ``full``, the subnets are 677returned together with the shared network. 678 679The following command fetches the "level3" IPv6 shared network along 680with the full information about the subnets belonging to it: 681 682.. code-block:: json 683 684 { 685 "command": "remote-network6-get", 686 "arguments": { 687 "shared-networks": [ 688 { 689 "name": "level3" 690 } 691 ], 692 "subnets-include": "full", 693 "remote": { 694 "type": "mysql" 695 } 696 } 697 } 698 699Note that the `server-tags` parameter must not be used for this command. 700 701.. _command-remote-network4-list: 702 703.. _command-remote-network6-list: 704 705The remote-network4-list, remote-network6-list Commands 706~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 707 708These commands are used to list all IPv4 or IPv6 shared networks for a server. 709 710The following command retrieves all shared networks to be used by the 711"server1" and "server2": 712 713.. code-block:: json 714 715 { 716 "command": "remote-network4-list" 717 "arguments": { 718 "remote": { 719 "type": "mysql" 720 }, 721 "server-tags": [ "server1", "server2" ] 722 } 723 } 724 725The `server-tags` parameter is mandatory and it contains one or more server 726tags. It may contain the keyword "all" to fetch the shared networks associated 727with all servers. When the `server-tags` list contains the 728`null` value the returned response contains a list of unassigned shared 729networks, i.e. the networks which are associated with no servers. For example: 730 731.. code-block:: json 732 733 { 734 "command": "remote-network4-list" 735 "arguments": { 736 "remote": { 737 "type": "mysql" 738 }, 739 "server-tags": [ null ] 740 } 741 } 742 743The example response to this command when non-null server tags are specified 744looks similar to this: 745 746.. code-block:: json 747 748 { 749 "result": 0, 750 "text": "3 IPv4 shared network(s) found.", 751 "arguments": { 752 "shared-networks": [ 753 { 754 "name": "ground floor", 755 "metadata": { 756 "server-tags": [ "all" ] 757 } 758 }, 759 { 760 "name": "floor2", 761 "metadata": { 762 "server-tags": [ "server1" ] 763 } 764 }, 765 { 766 "name": "floor3", 767 "metadata": { 768 "server-tags": [ "server2" ] 769 } 770 } 771 ], 772 "count": 3 773 } 774 } 775 776The returned information about each shared network merely contains the shared 777network name and the metadata. In order to fetch the detailed information about 778the selected shared network, use the `remote-network[46]-get` command. 779 780The example response above contains three shared networks. One of the 781shared networks is associated with all servers, so it is included in 782the list of shared networks to be used by "server1" and "server2". 783The remaining two shared networks are returned because one of them 784is associated with the "server1" and another one is associated with 785the "server2". 786 787 788When listing unassigned shared networks, the response will look similar 789to this: 790 791.. code-block:: json 792 793 { 794 "result": 0, 795 "text": "1 IPv4 shared network(s) found.", 796 "arguments": { 797 "shared-networks": [ 798 { 799 "name": "fancy", 800 "metadata": { 801 "server-tags": [ null ] 802 } 803 } 804 ], 805 "count": 1 806 } 807 } 808 809The `null` value in the metadata indicates that the 810returned shared network is unassigned. 811 812.. _command-remote-network4-set: 813 814.. _command-remote-network6-set: 815 816The remote-network4-set, remote-network6-set Commands 817~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 818 819These commands create a new or replace an existing IPv4 or IPv6 shared 820network in the database. The structure of the shared network information 821is the same as in the Kea configuration file (see 822:ref:`shared-network4` and :ref:`shared-network6` for details), 823except that specifying subnets along with the shared 824network information is not allowed. Including the ``subnet4`` or ``subnet6`` parameter 825within the shared network information will result in an error. 826 827These commands are intended to be used for managing the shared 828network-specific information and DHCP options. In order to associate and 829disassociate the subnets with the shared networks, the 830``remote-subnet[46]-set`` commands should be used. 831 832The following command adds the IPv6 shared network "level3" to the 833database: 834 835.. code-block:: json 836 837 { 838 "command": "remote-network6-set", 839 "arguments": { 840 "shared-networks": [ 841 { 842 "name": "level3", 843 "interface": "eth0", 844 "option-data": [ { 845 "name": "sntp-servers", 846 "data": "2001:db8:1::1" 847 } ], 848 } 849 ], 850 "remote": { 851 "type": "mysql" 852 }, 853 "server-tags": [ "all" ] 854 } 855 } 856 857 858This command includes the ``interface`` parameter, which sets the shared 859network-level interface name. Any remaining shared network-level parameters, 860which are not specified with the command, will be marked as 861"unspecified" in the database. The DHCP server will use the global 862values for unspecified parameters or, if the global values are not 863specified, the default values will be used. 864 865The `server-tags` list is mandatory for this command and it must include one or 866more server tags. As a result the shared network is associated with all listed 867servers. The shared network may be associated with all servers connecting to the 868database when the keyword "all" is included. 869 870.. note:: 871 872 As with other "set" commands, this command replaces all the 873 information about the given shared network in the database, if the 874 shared network already exists. Therefore, when sending this command, 875 make sure to always include all parameters that must be specified for 876 the updated shared-network instance. Any unspecified parameter will 877 be marked unspecified in the database, even if its value was present 878 prior to sending the command. 879 880.. _command-remote-option-def4-del: 881 882.. _command-remote-option-def6-del: 883 884The remote-option-def4-del, remote-option-def6-del Commands 885~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 886 887These commands are used to delete a DHCP option definition from the 888database. The option definition is identified by an option code and 889option space. For example: 890 891.. code-block:: json 892 893 { 894 "command": "remote-option-def6-del", 895 "arguments": { 896 "option-defs": [ 897 { 898 "code": 1, 899 "space": "isc" 900 } 901 ], 902 "remote": { 903 "type": "mysql" 904 }, 905 "server-tags": [ "server1" ] 906 } 907 } 908 909 910deletes the definition of the option associated with the "server1", having the 911code of 1 and belonging to the option space "isc". The default option spaces are 912"dhcp4" and "dhcp6" for the DHCPv4 and DHCPv6 top level options respectively. If 913there is no such option explicitly associated with the server1, no option is 914deleted. In order to delete an option belonging to "all" servers, the keyword 915"all" must be used as the server tag. The `server-tags` list must contain exactly 916one tag. It must not include the `null` value. 917 918.. _command-remote-option-def4-get: 919 920.. _command-remote-option-def6-get: 921 922The remote-option-def4-get, remote-option-def6-get Commands 923~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 924 925These commands are used to fetch a specified DHCP option definition from 926the database. The option definition is identified by the option code and 927option space. The default option spaces are "dhcp4" and "dhcp6" for the 928DHCPv4 and DHCPv6 top-level options, respectively. 929 930The following command retrieves a DHCPv4 option definition associated with all 931servers, having the code of 1 and belonging to the option space "isc": 932 933.. code-block:: json 934 935 { 936 "command": "remote-option-def4-get" 937 "arguments": { 938 "option-defs": [ 939 { 940 "code": 1, 941 "space": "isc" 942 } 943 ], 944 "remote": { 945 "type": "mysql" 946 }, 947 "server-tags": [ "all" ] 948 } 949 } 950 951The `server-tags` list must include exactly one server tag or the keyword 952"all". It must not contain the `null` value. 953 954.. _command-remote-option-def4-get-all: 955 956.. _command-remote-option-def6-get-all: 957 958The remote-option-def4-get-all, remote-option-def6-get-all Commands 959~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 960 961These commands are used to fetch all DHCP option definitions from the database 962for the particular server or all servers. For example: 963 964.. code-block:: json 965 966 { 967 "command": "remote-option-def6-get-all" 968 "arguments": { 969 "remote": { 970 "type": "mysql" 971 }, 972 "server-tags": [ "all" ] 973 } 974 } 975 976 977This command attempts to fetch all DHCPv6 option definitions associated 978with "all" servers. The `server-tags` list is mandatory for 979this command and it must include exactly one server tag or the keyword "all". 980It must not include the `null` value.</para> 981 982The following is the example response to this command: 983 984.. code-block:: json 985 986 { 987 "result": 0, 988 "text": "1 DHCPv6 option definition(s) found.", 989 "arguments": { 990 "option-defs": [ 991 { 992 "name": "bar", 993 "code": 1012, 994 "space": "dhcp6", 995 "type": "record", 996 "array": true, 997 "record-types": "ipv6-address, uint16", 998 "encapsulate": "", 999 "metadata": { 1000 "server-tags": [ "all" ] 1001 } 1002 } 1003 ], 1004 "count": 1 1005 } 1006 } 1007 1008The response contains an option definition associated with all servers as 1009indicated by the metadata. 1010 1011.. _command-remote-option-def4-set: 1012 1013.. _command-remote-option-def6-set: 1014 1015The remote-option-def4-set, remote-option-def6-set Commands 1016~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1017 1018These commands create a new DHCP option definition or replace an 1019existing option definition in the database. The structure of the option 1020definition information is the same as in the Kea configuration file (see 1021:ref:`dhcp4-custom-options` and :ref:`dhcp6-custom-options`). 1022The following command creates the DHCPv4 option definition at the 1023top-level "dhcp4" option space and associates it with the "server1": 1024 1025.. code-block:: json 1026 1027 { 1028 "command": "remote-option-def4-set", 1029 "arguments": { 1030 "option-defs": [ 1031 { 1032 "name": "foo", 1033 "code": 222, 1034 "type": "uint32", 1035 "array": false, 1036 "record-types": "", 1037 "space": "dhcp4", 1038 "encapsulate": "" 1039 } 1040 ], 1041 "remote": { 1042 "type": "mysql" 1043 }, 1044 "server-tags": [ "server1" ] 1045 } 1046 } 1047 1048The `server-tags` list must include exactly one 1049server tag or the keyword "all". It must not contain the 1050`null` value. 1051 1052 1053.. _command-remote-option4-global-del: 1054 1055.. _command-remote-option6-global-del: 1056 1057The remote-option4-global-del, remote-option6-global-del Commands 1058~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1059 1060These commands are used to delete a global DHCP option from the 1061database. The option is identified by an option code and option space. 1062For example: 1063 1064.. code-block:: json 1065 1066 { 1067 "command": "remote-option4-global-del", 1068 "arguments": { 1069 "options": [ 1070 { 1071 "code": 5 1072 "space": "dhcp4" 1073 } 1074 ], 1075 "remote": { 1076 "type": "mysql" 1077 }, 1078 "server-tags": [ "server1" ] 1079 } 1080 } 1081 1082The "dhcp4" is the top-level option space where the standard DHCPv4 options 1083belong. The `server-tags` is mandatory and it must include a 1084single option tag or the keyword "all". If the explicit server tag is specified 1085then this command attempts to delete a global option associated with this 1086server. If there is no such option associated with the given server, no option 1087is deleted. In order to delete the option associated with all servers, the 1088keyword "all" must be specified. 1089 1090.. _command-remote-option4-global-get: 1091 1092.. _command-remote-option6-global-get: 1093 1094The remote-option4-global-get, remote-option6-global-get Commands 1095~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1096 1097These commands are used to fetch a global DHCP option from the database. 1098The option is identified by the code and option space. The top-level 1099option spaces where DHCP standard options belong are called "dhcp4" and 1100"dhcp6" for the DHCPv4 and DHCPv6 servers, respectively. 1101 1102The following command retrieves the IPv6 "DNS Servers" (code 23) option 1103associated with all servers: 1104 1105.. code-block:: json 1106 1107 { 1108 "command": "remote-option6-global-get", 1109 "arguments": { 1110 "options": [ 1111 { 1112 "code": 23, 1113 "space": "dhcp6" 1114 } 1115 ], 1116 "remote": { 1117 "type": "mysql" 1118 }, 1119 "server-tags": [ "all" ] 1120 } 1121 } 1122 1123The `server-tags` is mandatory and it must include exactly one 1124server tag or the keyword "all". It must not contain the `null` 1125value. 1126 1127.. _command-remote-option4-global-get-all: 1128 1129.. _command-remote-option6-global-get-all: 1130 1131The remote-option4-global-get-all, remote-option6-global-get-all Commands 1132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1133 1134These commands are used to fetch all global DHCP options from the configuration 1135database for the particular server or for all servers. The following command 1136fetches all global DHCPv4 options for the "server1": 1137 1138.. code-block:: json 1139 1140 { 1141 "command": "remote-option6-global-get-all", 1142 "arguments": { 1143 "remote": { 1144 "type": "mysql" 1145 }, 1146 "server-tags": [ "server1" ] 1147 } 1148 } 1149 1150The `server-tags` list is mandatory for this command and 1151it must contain exactly one server tag or a keyword "all". It must not contain 1152the `null` value. The following is the example response to this 1153command with a single option being associated with the "server1" returned: 1154 1155.. code-block:: json 1156 1157 { 1158 "result": 0, 1159 "text": "DHCPv4 options found.", 1160 "arguments": { 1161 "options": [ 1162 { 1163 "name": "domain-name-servers", 1164 "code": 6, 1165 "space": "dhcp4", 1166 "csv-format": false, 1167 "data": "192.0.2.3", 1168 "metadata": { 1169 "server-tags": [ "server1" ] 1170 } 1171 } 1172 ], 1173 "count": 1 1174 } 1175 } 1176 1177 1178.. _command-remote-option4-global-set: 1179 1180.. _command-remote-option6-global-set: 1181 1182The remote-option4-global-set, remote-option6-global-set Commands 1183~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1184 1185These commands create a new global DHCP option or replace an existing 1186option in the database. The structure of the option information is the 1187same as in the Kea configuration file (see :ref:`dhcp4-std-options` 1188and :ref:`dhcp6-std-options`). For example: 1189 1190.. code-block:: json 1191 1192 { 1193 "command": "remote-option6-global-set", 1194 "arguments": { 1195 "options": [ 1196 { 1197 "name": "dns-servers", 1198 "data": "2001:db8:1::1" 1199 } 1200 ], 1201 "remote": { 1202 "type": "mysql" 1203 }, 1204 "server-tags": [ "server1" ] 1205 } 1206 } 1207 1208The `server-tags` list is mandatory for this command 1209and it must include exactly one server tag or the keyword "all". It must 1210not include the `null` value. The command above associates 1211the option with the "server1" server. 1212 1213Note that specifying an option name instead of the option code only 1214works reliably for the standard DHCP options. When specifying a value 1215for the user-defined DHCP option, the option code should be specified 1216instead of the name. For example: 1217 1218.. code-block:: json 1219 1220 { 1221 "command": "remote-option6-global-set", 1222 "arguments": { 1223 "options": [ 1224 { 1225 "code": 1, 1226 "space": "isc", 1227 "data": "2001:db8:1::1" 1228 } 1229 ], 1230 "server-tags": [ "server1" ] 1231 } 1232 } 1233 1234.. _command-remote-option4-network-del: 1235 1236.. _command-remote-option6-network-del: 1237 1238The remote-option4-network-del, remote-option6-network-del Commands 1239~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1240 1241These commands are used to delete a shared network specific DHCP 1242option from the database. The option is identified by an option code 1243and option space and these two parameters are passed within the 1244`options` list. Another list, `shared-networks`, contains a map 1245with the name of the shared network from which the option is to 1246be deleted. If the option is not explicitly specified for this 1247shared network, no option is deleted. In particular, the given 1248option may be present for a subnet belonging to the shared network. 1249Such an option instance is not affected by this command as this 1250command merely deletes the shared network level option. In order to 1251delete a subnet level option the `remote-option[46]-subnet-del` 1252command must be used instead. 1253 1254The following command attempts to delete an option having the 1255option code 5 in the top-level option space from the shared 1256network "fancy". 1257 1258.. code-block:: json 1259 1260 { 1261 "command": "remote-option4-network-del", 1262 "arguments": { 1263 "shared-networks": [ 1264 { 1265 "name": "fancy" 1266 } 1267 ], 1268 "options": [ 1269 { 1270 "code": 5, 1271 "space": "dhcp4" 1272 } 1273 ], 1274 "remote": { 1275 "type": "mysql" 1276 } 1277 } 1278 } 1279 1280The "dhcp4" is the top-level option space where the standard DHCPv4 options 1281belong. The `server-tags` parameter must not be specified for this command. 1282 1283.. _command-remote-option4-network-set: 1284 1285.. _command-remote-option6-network-set: 1286 1287The remote-option4-network-set, remote-option6-network-set Commands 1288~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1289 1290These commands create a new shared network specific DHCP option or replace 1291an existing option in the database. The structure of the option information 1292is the same as in the Kea configuration file (see :ref:`dhcp4-std-options` 1293and :ref:`dhcp6-std-options`). The option information is carried in the 1294`options` list. Another list, `shared-networks`, contains a map with the 1295name of the shared network for which the option is to be set. If such an option 1296already exists for the shared network, it is replaced with the new instance. 1297 1298.. code-block:: json 1299 1300 { 1301 "command": "remote-option6-network-set", 1302 "arguments": { 1303 "shared-networks": [ 1304 { 1305 "name": "fancy" 1306 } 1307 ], 1308 "options": [ 1309 { 1310 "name": "dns-servers", 1311 "data": "2001:db8:1::1" 1312 } 1313 ], 1314 "remote": { 1315 "type": "mysql" 1316 } 1317 } 1318 } 1319 1320The `sever-tags` parameter must not be specified for this command. 1321 1322Specifying an option name instead of the option code only works reliably 1323for the standard DHCP options. When specifying a value for the user-defined 1324DHCP option, the option code should be specified instead of the name. 1325 1326.. _command-remote-option6-pd-pool-del: 1327 1328The remote-option6-pd-pool-del Command 1329~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1330 1331This command is used to delete a prefix delegation pool specific DHCPv6 1332option from the database. The option is identified by an option code 1333and option space and these two parameters are passed within the 1334`options` list. Another list, `pd-pools`, contains a map with the 1335prefix delegation pool prefix and length identifying the pool. If the 1336option is not explicitly specified for this pool, no option is deleted. 1337In particular, the given option may exist for a subnet containing 1338the specified pool. Such an option instance is not affected by this 1339command as this command merely deletes a prefix delegation pool level 1340option. In order to delete a subnet level option the 1341`remote-option6-subnet-del` command must be used instead. 1342 1343.. code-block:: json 1344 1345 { 1346 "command": "remote-option6-pd-pool-del", 1347 "arguments": { 1348 "pd-pools": [ 1349 { 1350 "prefix": "3000::", 1351 "prefix-len": 64 1352 } 1353 ], 1354 "options": [ 1355 { 1356 "code": 23, 1357 "space": "dhcp6" 1358 } 1359 ], 1360 "remote": { 1361 "type": "mysql" 1362 } 1363 } 1364 } 1365 1366The "dhcp6" is the top-level option space where the standard DHCPv6 options 1367belong. The `server-tags` parameter must not be specified for this command. 1368 1369 1370.. _command-remote-option6-pd-pool-set: 1371 1372The remote-option6-pd-pool-set Command 1373~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1374 1375This command creates a new prefix delegation pool-specific DHCPv6 option or 1376replaces an existing option in the database. The structure of the option 1377information is the same as in the Kea configuration file (see :ref:`dhcp4-std-options` 1378and :ref:`dhcp6-std-options`). The option information is carried in the 1379`options` list. Another list, `pd-pools`, contains a map with the prefix 1380delegation pool prefix and the prefix length identifying the pool. If such an 1381option already exists for the prefix delegation pool, it is replaced with 1382the new instance. 1383 1384For example: 1385 1386.. code-block:: json 1387 1388 { 1389 "command": "remote-option6-pd-pool-set", 1390 "arguments": { 1391 "pd-pools": [ 1392 { 1393 "prefix": "3001:1::", 1394 "length": 64 1395 } 1396 ], 1397 "options": [ 1398 { 1399 "name": "dns-servers", 1400 "data": "2001:db8:1::1" 1401 } 1402 ], 1403 "remote": { 1404 "type": "mysql" 1405 } 1406 } 1407 } 1408 1409The `sever-tags` parameter must not be specified for this command. 1410 1411Specifying an option name instead of the option code only works reliably 1412for the standard DHCP options. When specifying a value for the user-defined 1413DHCP option, the option code should be specified instead of the name. 1414 1415 1416.. _command-remote-option4-pool-del: 1417 1418.. _command-remote-option6-pool-del: 1419 1420The remote-option4-pool-del, remote-option6-pool-del Commands 1421~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1422 1423These commands are used to delete an address pool specific DHCP 1424option from the database. The option is identified by an option code 1425and option space and these two parameters are passed within the 1426`options` list. Another list, `pools`, contains a map with the 1427IP address range or prefix identifying the pool. If the option 1428is not explicitly specified for this pool, no option is deleted. 1429In particular, the given option may exist for a subnet containing 1430the specified pool. Such option instance is not affected by this 1431command as this command merely deletes a pool level option. In 1432order to delete subnet level option the `remote-option[46]-subnet-del` 1433command must be used instead. 1434 1435The following command attempts to delete an option having the 1436option code 5 in the top-level option space from an IPv4 address 1437pool: 1438 1439.. code-block:: json 1440 1441 { 1442 "command": "remote-option4-pool-del", 1443 "arguments": { 1444 "pools": [ 1445 { 1446 "pool": "192.0.2.10 - 192.0.2.100" 1447 } 1448 ], 1449 "options": [ 1450 { 1451 "code": 5, 1452 "space": "dhcp4" 1453 } 1454 ], 1455 "remote": { 1456 "type": "mysql" 1457 } 1458 } 1459 } 1460 1461The "dhcp4" is the top-level option space where the standard DHCPv4 options 1462belong. The `server-tags` parameter must not be specified for this command. 1463 1464 1465.. _command-remote-option4-pool-set: 1466 1467.. _command-remote-option6-pool-set: 1468 1469The remote-option4-pool-set, remote-option6-pool-set Commands 1470~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1471 1472These commands create a new address pool specific DHCP option or replace 1473an existing option in the database. The structure of the option information 1474is the same as in the Kea configuration file (see :ref:`dhcp4-std-options` 1475and :ref:`dhcp6-std-options`). The option information is carried in the 1476`options` list. Another list, `pools`, contains a map with the IP address 1477range or prefix identifying the pool. If such an option already exists for 1478the pool, it is replaced with the new instance. 1479 1480For example: 1481 1482.. code-block:: json 1483 1484 { 1485 "command": "remote-option4-pool-set", 1486 "arguments": { 1487 "pools": [ 1488 { 1489 "pool": "192.0.2.10 - 192.0.2.100" 1490 } 1491 ], 1492 "options": [ 1493 { 1494 "name": "domain-name-servers", 1495 "data": "10.0.0.1" 1496 } 1497 ], 1498 "remote": { 1499 "type": "mysql" 1500 } 1501 } 1502 } 1503 1504The `sever-tags` parameter must not be specified for this command. 1505 1506Specifying an option name instead of the option code only works reliably 1507for the standard DHCP options. When specifying a value for the user-defined 1508DHCP option, the option code should be specified instead of the name. 1509 1510.. _command-remote-option4-subnet-del: 1511 1512.. _command-remote-option6-subnet-del: 1513 1514The remote-option4-subnet-del, remote-option6-subnet-del Commands 1515~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1516 1517These commands are used to delete a subnet specific DHCP option 1518from the database. The option is identified by an option code 1519and option space and these two parameters are passed within the 1520`options` list. Another list, `subnets`, contains a map with the 1521identifier of the subnet from which the option is to be deleted. 1522If the option is not explicitly specified for this subnet, no 1523option is deleted. 1524 1525The following command attempts to delete an option having the 1526option code 5 in the top-level option space from the subnet 1527having an identifier of 123. 1528 1529.. code-block:: json 1530 1531 { 1532 "command": "remote-option4-subnet-del", 1533 "arguments": { 1534 "subnets": [ 1535 { 1536 "id": 123 1537 } 1538 ], 1539 "options": [ 1540 { 1541 "code": 5, 1542 "space": "dhcp4" 1543 } 1544 ], 1545 "remote": { 1546 "type": "mysql" 1547 } 1548 } 1549 } 1550 1551The "dhcp4" is the top-level option space where the standard DHCPv4 options 1552belong. The `server-tags` parameter must not be specified for this command. 1553 1554.. _command-remote-option4-subnet-set: 1555 1556.. _command-remote-option6-subnet-set: 1557 1558The remote-option4-subnet-set, remote-option6-subnet-set Commands 1559~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1560 1561These commands create a new subnet specific DHCP option or replace an existing 1562option in the database. The structure of the option information is the same as 1563in the Kea configuration file (see :ref:`dhcp4-std-options` 1564and :ref:`dhcp6-std-options`). The option information is carried in the 1565`options` list. Another list, `subnets`, contains a map with the identifier of 1566the subnet for which the option is to be set. If such an option already exists 1567for the subnet, it is replaced with the new instance. 1568 1569.. code-block:: json 1570 1571 { 1572 "command": "remote-option6-subnet-set", 1573 "arguments": { 1574 "subnets": [ 1575 { 1576 "id": 123 1577 } 1578 ], 1579 "options": [ 1580 { 1581 "name": "dns-servers", 1582 "data": "2001:db8:1::1" 1583 } 1584 ], 1585 "remote": { 1586 "type": "mysql" 1587 } 1588 } 1589 } 1590 1591The `sever-tags` parameter must not be specified for this command. 1592 1593Specifying an option name instead of the option code only works reliably 1594for the standard DHCP options. When specifying a value for the user-defined 1595DHCP option, the option code should be specified instead of the name. 1596 1597.. _command-remote-subnet4-del-by-id: 1598 1599.. _command-remote-subnet6-del-by-id: 1600 1601The remote-subnet4-del-by-id, remote-subnet6-del-by-id Commands 1602~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1603 1604This is the first variant of the commands used to delete an IPv4 or IPv6 1605subnet from the database. It uses the subnet ID to identify the subnet. For 1606example, to delete the IPv4 subnet with an ID of 5: 1607 1608.. code-block:: json 1609 1610 { 1611 "command": "remote-subnet4-del-by-id", 1612 "arguments": { 1613 "subnets": [ 1614 { 1615 "id": 5 1616 } 1617 ], 1618 "remote": { 1619 "type": "mysql" 1620 } 1621 } 1622 } 1623 1624The `server-tags` parameter must not be used with this command. 1625 1626.. _command-remote-subnet4-del-by-prefix: 1627 1628.. _command-remote-subnet6-del-by-prefix: 1629 1630The remote-subnet4-del-by-prefix, remote-subnet6-del-by-prefix Commands 1631~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1632 1633This is the second variant of the commands used to delete an IPv4 or 1634IPv6 subnet from the database. It uses the subnet prefix to identify the 1635subnet. For example: 1636 1637.. code-block:: json 1638 1639 { 1640 "command": "remote-subnet6-del-by-prefix", 1641 "arguments": { 1642 "subnets": [ 1643 { 1644 "subnet": "2001:db8:1::/64" 1645 } 1646 ], 1647 "remote": { 1648 "type": "mysql" 1649 } 1650 } 1651 } 1652 1653The `server-tags` parameter must not be used with this command. 1654 1655.. _command-remote-subnet4-get-by-id: 1656 1657.. _command-remote-subnet6-get-by-id: 1658 1659The remote-subnet4-get-by-id, remote-subnet6-get-by-id Commands 1660~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1661 1662This is the first variant of the commands used to fetch an IPv4 or IPv6 1663subnet from the database. It uses a subnet ID to identify the subnet. 1664For example: 1665 1666.. code-block:: json 1667 1668 { 1669 "command": "remote-subnet4-get-by-id", 1670 "arguments": { 1671 "subnets": [ 1672 { 1673 "id": 5 1674 } 1675 ], 1676 "remote": { 1677 "type": "mysql" 1678 } 1679 } 1680 } 1681 1682The `server-tags` parameter must not be used with this command. 1683 1684.. _command-remote-subnet4-get-by-prefix: 1685 1686.. _command-remote-subnet6-get-by-prefix: 1687 1688The remote-subnet4-get-by-prefix, remote-subnet6-get-by-prefix Commands 1689~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1690 1691This is the second variant of the commands used to fetch an IPv4 or IPv6 1692subnet from the database. It uses a subnet prefix to identify the 1693subnet. For example: 1694 1695.. code-block:: json 1696 1697 { 1698 "command": "remote-subnet6-get-by-prefix", 1699 "arguments": { 1700 "subnets": [ 1701 { 1702 "subnet": "2001:db8:1::/64" 1703 } 1704 ], 1705 "remote": { 1706 "type": "mysql" 1707 } 1708 } 1709 } 1710 1711The `server-tags` parameter must not be used with this command. 1712 1713.. _command-remote-subnet4-list: 1714 1715.. _command-remote-subnet6-list: 1716 1717The remote-subnet4-list, remote-subnet6-list Commands 1718~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1719 1720These commands are used to list all IPv4 or IPv6 subnets from the database for 1721selected servers or all servers. The following command retrieves all servers to 1722be used by the "server1" and "server2": 1723 1724.. code-block:: json 1725 1726 { 1727 "command": "remote-subnet4-list" 1728 "arguments": { 1729 "remote": { 1730 "type": "mysql" 1731 }, 1732 "server-tags": [ "server1", "server2" ] 1733 } 1734 } 1735 1736The `server-tags` parameter is mandatory and contains one or 1737more server tags. It may contain the keyword "all", to fetch the subnets 1738associated with all servers. When the `server-tags` list 1739contains the `null` value, the returned response contains a list 1740of unassigned subnets, i.e. the subnets which are associated with no servers. 1741For example: 1742 1743.. code-block:: json 1744 1745 { 1746 "command": "remote-subnet4-list" 1747 "arguments": { 1748 "remote": { 1749 "type": "mysql" 1750 }, 1751 "server-tags": [ null ] 1752 } 1753 } 1754 1755The example response to this command when non-null server tags are specified 1756looks similar to this: 1757 1758.. code-block:: json 1759 1760 { 1761 "result": 0, 1762 "text": "2 IPv4 subnet(s) found.", 1763 "arguments": { 1764 "subnets": [ 1765 { 1766 "id": 1, 1767 "subnet": "192.0.2.0/24", 1768 "shared-network-name": null, 1769 "metadata": { 1770 "server-tags": [ "server1", "server2" ] 1771 } 1772 }, 1773 { 1774 "id": 2, 1775 "subnet": "192.0.3.0/24", 1776 "shared-network-name": null, 1777 "metadata": { 1778 "server-tags": [ "all" ] 1779 } 1780 } 1781 ], 1782 "count": 2 1783 } 1784 } 1785 1786The returned information about each subnet is limited to subnet identifier, 1787prefix and associated shared network name. In order to retrieve full 1788information about the selected subnet use the 1789`remote-subnet[46]-get-by-id` or 1790`remote-subnet[46]-get-by-prefix`. 1791 1792The example response above contains two subnets. One of the subnets is 1793associated with both servers: "server1" and "server2". The second subnet is 1794associated with all servers, thus it is also present in the configuration for 1795the "server1" and "server2". 1796 1797When listing unassigned subnets, the response will look similar to this: 1798 1799.. code-block:: json 1800 1801 { 1802 "result": 0, 1803 "text": "1 IPv4 subnet(s) found.", 1804 "arguments": { 1805 "subnets": [ 1806 { 1807 "id": 3, 1808 "subnet": "192.0.4.0/24", 1809 "shared-network-name": null, 1810 "metadata": { 1811 "server-tags": [ null ] 1812 } 1813 } 1814 ], 1815 "count": 1 1816 } 1817 } 1818 1819The `null` value in the metadata indicates that the 1820returned subnet is unassigned. 1821 1822.. _command-remote-subnet4-set: 1823 1824.. _command-remote-subnet6-set: 1825 1826The remote-subnet4-set, remote-subnet6-set Commands 1827~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1828 1829These commands are used to create a new IPv4 or IPv6 subnet or replace 1830an existing subnet in the database. Setting the subnet also associates 1831or disassociates the subnet with a shared network. 1832 1833The structure of the subnet information is similar to the structure used 1834in the configuration file (see :ref:`dhcp4-configuration` and 1835:ref:`dhcp6-configuration`). The subnet information conveyed in the 1836``remote-subnet[46]-set`` command must include the additional parameter 1837``shared-network-name``, which denotes whether the subnet belongs to a 1838shared network. 1839 1840Consider the following example: 1841 1842.. code-block:: json 1843 1844 { 1845 "command": "remote-subnet4-set", 1846 "arguments": { 1847 "subnets": [ 1848 { 1849 "id": 5, 1850 "subnet": "192.0.2.0/24", 1851 "shared-network-name": "level3", 1852 "pools": [ { "pool": "192.0.2.100-192.0.2.200" } ], 1853 "option-data": [ { 1854 "name": "routers", 1855 "data": "192.0.2.1" 1856 } ] 1857 } 1858 ], 1859 "remote": { 1860 "type": "mysql" 1861 }, 1862 "server-tags": [ "all" ] 1863 } 1864 } 1865 1866 1867It creates the subnet and associates it with the "level3" shared 1868network. The "level3" shared network must be created with the ``remote-network4-set`` 1869command prior to creating the subnet. 1870 1871If the created subnet must be global - that is, not associated with any shared 1872network - the ``shared-network-name`` must be explicitly set to 1873``null``: 1874 1875.. code-block:: json 1876 1877 { 1878 "command": "remote-subnet4-set", 1879 "arguments": { 1880 "subnets": [ 1881 { 1882 "id": 5, 1883 "subnet": "192.0.2.0/24", 1884 "shared-network-name": null, 1885 "pools": [ { "pool": "192.0.2.100-192.0.2.200" } ], 1886 "option-data": [ { 1887 "name": "routers", 1888 "data": "192.0.2.1" 1889 } ] 1890 } 1891 ], 1892 "server-tags": [ "all" ] 1893 } 1894 } 1895 1896 1897The subnet created in the previous example is replaced with the new 1898subnet having the same parameters, but it becomes global. 1899 1900The ``shared-network-name`` parameter is mandatory for the 1901``remote-subnet4-set`` command. The `server-tags` list is mandatory and it must 1902include one or more server tags. As a result, the subnet is associated with all 1903of the listed servers. It may also be associated with "all" servers connecting 1904to the database when the keyword "all" is used as the server tag.</para> 1905 1906.. note:: 1907 1908 As with other "set" commands, this command replaces all the 1909 information about the particular subnet in the database, if the 1910 subnet information is already present. Therefore, when sending this 1911 command, make sure to always include all parameters that must be 1912 specified for the updated subnet instance. Any unspecified parameter 1913 will be marked as unspecified in the database, even if its value was 1914 present prior to sending the command. 1915 1916.. _command-remote-class4-del: 1917 1918.. _command-remote-class6-del: 1919 1920The remote-class4-del, remote-class6-del Commands 1921~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1922 1923These commands delete a DHCPv4 or DHCPv6 client class by name. If any client 1924classes in the database depend on the deleted class, an error is returned in 1925response to this command. In this case, to successfully delete the class, 1926the dependent client classes must be deleted first. Use the 1927``remote-class4-get-all`` command to fetch all client classes and find 1928the dependent ones. 1929 1930.. code-block:: json 1931 1932 { 1933 "command": "remote-class4-del", 1934 "arguments": { 1935 "client-classes": [ 1936 { 1937 "name": "foo" 1938 } 1939 ], 1940 "remote": { 1941 "type": "mysql" 1942 } 1943 } 1944 } 1945 1946The `server-tags` parameter must not be used for this command because client 1947classes are uniquely identified by name. 1948 1949.. _command-remote-class4-get: 1950 1951.. _command-remote-class6-get: 1952 1953The remote-class4-get, remote-class6-get Commands 1954~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1955 1956These commands retrieve DHCPv4 or DHCPv6 client class information by a client 1957class name. 1958 1959.. code-block:: json 1960 1961 { 1962 "command": "remote-class4-get", 1963 "arguments": { 1964 "client-classes": [ 1965 { 1966 "name": "foo" 1967 } 1968 ], 1969 "remote": { 1970 "type": "mysql" 1971 } 1972 } 1973 } 1974 1975The `server-tags` parameter must not be used for this command because client 1976classes are uniquely identified by name. 1977 1978A response to the command looks similar to this: 1979 1980.. code-block:: json 1981 1982 { 1983 "result": 0, 1984 "text": "DHCPv4 client class 'foo' found.", 1985 "arguments": { 1986 "client-classes": [ 1987 { 1988 "name": "foo", 1989 "metadata": { 1990 "server-tags": [ "all" ] 1991 } 1992 } 1993 ], 1994 "count": 1 1995 } 1996 } 1997 1998.. _command-remote-class4-get-all: 1999 2000.. _command-remote-class6-get-all: 2001 2002The remote-class4-get-all, remote-class6-get-all Commands 2003~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2004 2005These commands retrieve all DHCPv4 or DHCPv6 client classes for a particular server, 2006multiple explicitly listed servers, or all servers. For example, the following 2007command retrieves all client classes defined for a server having the server tag 2008of `server1` and all servers. In other words, it returns all client classes 2009used by that server. 2010 2011.. code-block:: json 2012 2013 { 2014 "command": "remote-class4-get-all", 2015 "arguments": { 2016 "remote": { 2017 "type": "mysql" 2018 }, 2019 "server-tags": [ "server1" ] 2020 } 2021 } 2022 2023The `server-tags` parameter is mandatory and it contains one or more server 2024tags. It may contain the keyword "all" to fetch the client classes associated 2025with all servers. When the `server-tags` list contains the 2026`null` value the returned response contains a list of unassigned client 2027classes, i.e. the networks which are associated with no servers. 2028 2029A response to the command looks similar to this: 2030 2031.. code-block:: json 2032 2033 { 2034 "result": 0, 2035 "text": "2 DHCPv4 client class(es) found.", 2036 "arguments": { 2037 "client-classes": [ 2038 { 2039 "name": "foo", 2040 "metadata": { 2041 "server-tags": [ "all" ] 2042 } 2043 }, 2044 { 2045 "name": "bar", 2046 "test": "member('foo')", 2047 "metadata": { 2048 "server-tags": [ "all" ] 2049 } 2050 } 2051 ], 2052 "count": 2 2053 } 2054 } 2055 2056 2057.. _command-remote-class4-set: 2058 2059.. _command-remote-class6-set: 2060 2061The remote-class4-set, remote-class6-set Commands 2062~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2063 2064These commands insert a new or replace an existing DHCPv4 or DHCPv6 client class in 2065the database. The client class information structure is the same as in the Kea 2066configuration file (see :ref:`dhcp4-client-classifier` and 2067:ref:`dhcp6-client-classifier` for details). 2068 2069.. code-block:: json 2070 2071 { 2072 "command": "remote-class4-set", 2073 "arguments": { 2074 "client-classes": [ 2075 { 2076 "name": "foo", 2077 "test": "member('KNOWN') or member('bar')", 2078 "option-def": [ 2079 { 2080 "name": "configfile", 2081 "code": 224, 2082 "type": "string" 2083 } 2084 ], 2085 "option-data": [ 2086 { 2087 "name": "configfile", 2088 "data": "1APC" 2089 } 2090 ] 2091 } 2092 ], 2093 "remote": { 2094 "type": "mysql" 2095 }, 2096 "server-tags": [ "all" ] 2097 } 2098 } 2099 2100 2101Client class ordering rules described in :ref:`classification-using-expressions` 2102apply to the classes inserted into the database. It implies that the class `bar` 2103referenced in the test expression must exist in the database when issuing the 2104above command. 2105 2106By default, a new client class is inserted at the end of the class hierarchy in 2107the database and can reference any class associated with the same server tag or 2108with the special server tag `all`. If an existing class is updated, it remains 2109at its current position within the class hierarchy. 2110 2111However, the class commands allow for specifying a position of the inserted 2112or updated client class. The optional `follow-class-name` parameter can be 2113included in the command to specify the name of the existing class after which 2114the managed class should be placed. Suppose there are two DHCPv6 classes in the 2115database: `first-class` and `second-class`. To add a new class, `third-class`, 2116between these two, use the command similar to the following: 2117 2118.. code-block:: json 2119 2120 { 2121 "command": "remote-class6-set", 2122 "arguments": { 2123 "client-classes": [ 2124 { 2125 "name": "third-class", 2126 "test": "member('first-class')" 2127 } 2128 ], 2129 "follow-class-name": "first-class", 2130 "remote": { 2131 "type": "mysql" 2132 }, 2133 "server-tags": [ "all" ] 2134 } 2135 } 2136 2137Note that the `third-class` can depend on the `first-class` because it is placed 2138after the `first-class`. The `third-class` must not depend on the `second-class` 2139because it is placed before it. However, the `second-class` could now be updated to 2140depend on the `third-class`. 2141 2142The `follow-class-name` parameter can be explicitly set to `null`, e.g.: 2143 2144.. code-block:: json 2145 2146 { 2147 "command": "remote-class6-set", 2148 "arguments": { 2149 "client-classes": [ 2150 { 2151 "name": "third-class", 2152 "test": "member('first-class')" 2153 } 2154 ], 2155 "follow-class-name": null, 2156 "remote": { 2157 "type": "mysql" 2158 }, 2159 "server-tags": [ "all" ] 2160 } 2161 } 2162 2163It yields the same behavior as if the `follow-class-name` parameter is not included, 2164i.e. the new class is appended at the end of the class hierarchy, and the updated 2165class remains at the current position. 2166