diff --git a/AUTHORS b/AUTHORS index ca397b588b37beb1cf7afc8c176eff4134dd6456..5a8a7ab3cb95d5f5f98141f5af02b4a5546d552d 100644 --- a/AUTHORS +++ b/AUTHORS @@ -180,10 +180,14 @@ We have received the following contributions: - Vicky Risk 2018-08: Documentation clean up + 2018-10: API documentation clean ups - Franciszek Gorski 2018-10: Makefile bug fixed + - Suzanne Goldlust + 2018-10: API documentation + Kea uses log4cplus (http://sourceforge.net/projects/log4cplus/) for logging, Boost (http://www.boost.org/) library for almost everything, and can use Botan (http://botan.randombit.net/) or OpenSSL (https://www.openssl.org/) for diff --git a/Makefile.am b/Makefile.am index 42bdfe0534fbe9e0027d7a655bc669093317668a..21f19fc4870fe6c4f19ff0949101a116898ceabd 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,7 +2,9 @@ ACLOCAL_AMFLAGS = -I m4macros ${ACLOCAL_FLAGS} # ^^^^^^^^ This has to be the first line and cannot come later in this # Makefile.am due to some bork in some versions of autotools. -SUBDIRS = compatcheck tools doc . ext src m4macros @PREMIUM_DIR@ @CONTRIB_DIR@ +# We now build doc after src/, because docgen, a tool to generate API +# documentation requires libkea-exceptions and libkea-cc. +SUBDIRS = compatcheck tools . ext src doc m4macros @PREMIUM_DIR@ @CONTRIB_DIR@ USE_LCOV=@USE_LCOV@ LCOV=@LCOV@ diff --git a/configure.ac b/configure.ac index ba86b3e0ade097c65c211a2976863eb6fbc6297d..9a6a1ec541e4127412fd89db1a11e13f7c150f1f 100644 --- a/configure.ac +++ b/configure.ac @@ -1468,6 +1468,7 @@ AC_CONFIG_FILES([Makefile doc/Makefile doc/guide/Makefile doc/version.ent + doc/docgen/Makefile ext/Makefile ext/gtest/Makefile kea_version.h diff --git a/doc/Makefile.am b/doc/Makefile.am index 1237c598ca71d80ccf96480021683f77138f177c..951c257a19ccb36fd376575625a4ab5a8713b268 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -7,6 +7,7 @@ EXTRA_DIST += devel/contribute.dox EXTRA_DIST += devel/mainpage.dox EXTRA_DIST += devel/terminology.dox EXTRA_DIST += devel/unit-tests.dox +EXTRA_DIST += devel/doc.dox nobase_dist_doc_DATA = examples/agent/comments.json nobase_dist_doc_DATA += examples/agent/simple.json @@ -63,6 +64,44 @@ nobase_dist_doc_DATA += examples/netconf/comments.json nobase_dist_doc_DATA += examples/netconf/simple.json nobase_dist_doc_DATA += examples/netconf/simple-dhcp4.json +# These are files that document our APIs. They're not really needed as the +# content is included in the api.xml, but may be useful for people who +# want to document the API. +EXTRA_DIST += api/build-report.json +EXTRA_DIST += api/cache-clear.json api/cache-get.json +EXTRA_DIST += api/cache-insert.json api/cache-load.json +EXTRA_DIST += api/cache-remove.json api/cache-write.json +EXTRA_DIST += api/config-get.json api/config-reload.json +EXTRA_DIST += api/config-set.json api/config-test.json +EXTRA_DIST += api/config-write.json api/dhcp-disable.json +EXTRA_DIST += api/dhcp-enable.json api/ha-continue.json +EXTRA_DIST += api/ha-heartbeat.json api/ha-scopes.json +EXTRA_DIST += api/ha-sync.json api/lease4-add.json +EXTRA_DIST += api/lease4-del.json api/lease4-get-all.json +EXTRA_DIST += api/lease4-get.json api/lease4-update.json +EXTRA_DIST += api/lease4-wipe.json api/lease6-add.json +EXTRA_DIST += api/lease6-del.json api/lease6-get-all.json +EXTRA_DIST += api/lease6-get.json api/lease6-update.json +EXTRA_DIST += api/lease6-wipe.json api/leases-reclaim.json +EXTRA_DIST += api/libreload.json api/list-commands.json +EXTRA_DIST += api/network4-add.json api/network4-del.json +EXTRA_DIST += api/network4-get.json api/network4-list.json +EXTRA_DIST += api/network4-subnet-add.json api/network4-subnet-del.json +EXTRA_DIST += api/network6-add.json api/network6-del.json +EXTRA_DIST += api/network6-get.json api/network6-list.json +EXTRA_DIST += api/network6-subnet-add.json api/network6-subnet-del.json +EXTRA_DIST += api/reservation-add.json api/reservation-del.json +EXTRA_DIST += api/reservation-get.json api/shutdown.json +EXTRA_DIST += api/statistic-get-all.json api/statistic-get.json +EXTRA_DIST += api/statistic-remove-all.json api/statistic-remove.json +EXTRA_DIST += api/statistic-reset-all.json api/statistic-reset.json +EXTRA_DIST += api/stat-lease4-get.json api/stat-lease6-get.json +EXTRA_DIST += api/subnet4-add.json api/subnet4-del.json +EXTRA_DIST += api/subnet4-get.json api/subnet4-list.json +EXTRA_DIST += api/subnet6-add.json api/subnet6-del.json +EXTRA_DIST += api/subnet6-get.json api/subnet6-list.json +EXTRA_DIST += api/_template.json api/version-get.json + devel: mkdir -p html (cat Doxyfile; echo PROJECT_NUMBER=$(PACKAGE_VERSION)) | doxygen - > html/doxygen.log 2> html/doxygen-error.log @@ -74,7 +113,45 @@ guide: clean: rm -rf html +# There are several steps needed to document new API command: +# +# 1. edit docgen/cmds-list and add the new command +# 2. ./configure --enable-generate-docs +# 3. make - you need to build the sources first, am afraid. The reason why you +# need to do this is that the tool kea-docgen depends on libkea-cc as it +# loads JSON files. This means that the libs need to be built first. +# 4. (optional) run: make templates +# This will go through the list of commands listed in cmds-list +# and will check if there are corresponding JSON files in api/name.json +# If the file is missing, a new JSON will be created using template. +# If you dislike this generator, you can always use api/_template.json +# and copy it over under the name of a new command. +# 5. Edit api/command-name.json. If the command is provided by the daemon +# out of its own (and not via hook), simply delete the hook entry. +# If you don't want to provide command syntax (cmd-syntax key), +# any comments about the syntax (cmd-comment key) or response syntax +# (resp-syntax) or any comment about response (resp-comment), simply +# remove those unused keys. The generator will attempt to generate +# boilerplates for it. +# 6. Generate api.xml: make api +# 7. Rebuild User's Guide as usual: make guide + +# This target will generate templates. There's no need to run it, unless +# new commands have been added or there are existing commands that are +# still not documented. +templates: docgen + docgen/generate-templates docgen/cmds-list + +# This will generate the api.xml file using docgen generator. It will +# read the JSON files from api/ directory. Make sure they're up to date. +api: docgen + docgen/kea-docgen api/*.json + +# This convenience target makes sure the docgen tool is built properly +docgen: + $(MAKE) -C docgen + # That's a bit of a hack, but we are making sure that devel target # is always valid. The alternative is to make devel depend on all # *.cc *.h files in the whole tree. -.PHONY: devel guide +.PHONY: devel guide docgen diff --git a/doc/api/_template.json b/doc/api/_template.json new file mode 100644 index 0000000000000000000000000000000000000000..c0cd378687454b23f95298af36de97eb3ab7eb6a --- /dev/null +++ b/doc/api/_template.json @@ -0,0 +1,40 @@ +{ + // This specifies the name of the command. Must be the same as the filename. + "name": "template-command", + + // This provides a short description. + "brief": "a sentence or two explaining what it is", + + // This provides a full description. Since we have most (all?) commands + // already documented, we don't want to copy over the text. Instead, + // we provide links to specific section. + "description": "See ", + + // This enumerates the daemons that are able to handle specific commands. + // Usually this will be a subset of those specified below as there are very + // few commands that are supported by every daemon. + "support": [ "kea-dhcp4", "kea-dhcp6", "dhcp-ddns", "ca", "netconf" ], + + // Historical information. May need a bit of digging, but this info can + // be extracted by looking at older Kea user guides. We have them published + // on FTP. + "avail": "first version the command appeared in", + + // Many commands are provided by a hook. Specify the name of the hook here. + // If this hook is provided by the daemons natively (without needing to load + // a hook), remove the whole "hook" entry. + "hook": "name of the hook that provides this command. remove if provided by + the core code", + + // This defines the syntax of the command. + "cmd-syntax": "Syntax of the command", + + // This defines a description printed immediately below the command syntax. + "cmd-comment": "Possibly some extra comments after the syntax.", + + // This defines the syntax of the response. + "resp-syntax": "Syntax of the response", + + // This defines a description printed immediately below the response syntax. + "resp-comment": "Optional extra comments after the response syntax." +} diff --git a/doc/api/build-report.json b/doc/api/build-report.json new file mode 100644 index 0000000000000000000000000000000000000000..14682c083b0e0b802611bfba6edc0609e5094bff --- /dev/null +++ b/doc/api/build-report.json @@ -0,0 +1,16 @@ +{ + "name": "build-report", + "brief": "Returns a list of compilation options that this particular binary was built with", + "support": [ "kea-dhcp4", "kea-dhcp6", "kea-ctrl-agent" ], + "avail": "1.2.0", + + "cmd-syntax": "{ + \"command\": \"build-report\" +}", + + "resp-syntax": "{ + \"result\": 0, + \"text\": +}", + "resp-comment": "" +} diff --git a/doc/api/cache-clear.json b/doc/api/cache-clear.json new file mode 100644 index 0000000000000000000000000000000000000000..d1096e3e5d8025c65383130217aba4652f9dbc1b --- /dev/null +++ b/doc/api/cache-clear.json @@ -0,0 +1,7 @@ +{ + "name": "cache-clear", + "brief": "This command removes all cached host reservations.", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "hook": "host_cache", + "avail": "1.4.0" +} diff --git a/doc/api/cache-get.json b/doc/api/cache-get.json new file mode 100644 index 0000000000000000000000000000000000000000..7c72ff1b7fcad88c4d5389986b1211ae3cdfa83b --- /dev/null +++ b/doc/api/cache-get.json @@ -0,0 +1,13 @@ +{ + "name": "cache-get", + "brief": "Returns full content of the host cache.", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "host_cache", + + "resp-syntax": "{ + \"result\": 0 + \"text\": \"123 entries returned.\" + \"arguments\": +}" +} diff --git a/doc/api/cache-insert.json b/doc/api/cache-insert.json new file mode 100644 index 0000000000000000000000000000000000000000..e872c9ae045c1df6121e415129585727edfcae96 --- /dev/null +++ b/doc/api/cache-insert.json @@ -0,0 +1,45 @@ +{ + "name": "cache-insert", + "brief": "This command may be used to manually insert a host into the cache.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "host_cache", + "cmd-syntax": "{ + \"command\": \"cache-insert\", + \"arguments\": { + \"hw-address\": \"01:02:03:04:05:06\", + \"subnet-id4\": 4, + \"subnet-id6\": 0, + \"ip-address\": \"192.0.2.100\", + \"hostname\": \"somehost.example.org\", + \"client-classes4\": [ ], + \"client-classes6\": [ ], + \"option-data4\": [ ], + \"option-data6\": [ ], + \"next-server\": \"192.0.0.2\", + \"server-hostname\": \"server-hostname.example.org\", + \"boot-file-name\": \"bootfile.efi\", + \"host-id\": 0 + } +}, +{ + \"command\": \"cache-insert\", + \"arguments\": { + \"hw-address\": \"01:02:03:04:05:06\", + \"subnet-id4\": 0, + \"subnet-id6\": 6, + \"ip-addresses\": [ \"2001:db8::cafe:babe\" ], + \"prefixes\": [ \"2001:db8:dead:beef::/64\" ], + \"hostname\": \"\", + \"client-classes4\": [ ], + \"client-classes6\": [ ], + \"option-data4\": [ ], + \"option-data6\": [ ], + \"next-server\": \"0.0.0.0\", + \"server-hostname\": \"\", + \"boot-file-name\": \"\", + \"host-id\": 0 + } +}" +} diff --git a/doc/api/cache-load.json b/doc/api/cache-load.json new file mode 100644 index 0000000000000000000000000000000000000000..582dc11b8682e67cdc579e4901197dfa7f29f533 --- /dev/null +++ b/doc/api/cache-load.json @@ -0,0 +1,12 @@ +{ + "name": "cache-load", + "brief": "This command allows load the contents of a file on disk into an in-memory cache.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "host_cache", + "cmd-syntax": "{ + \"command\": \"cache-load\", + \"arguments\": \"/tmp/kea-host-cache.json\" +}" +} diff --git a/doc/api/cache-remove.json b/doc/api/cache-remove.json new file mode 100644 index 0000000000000000000000000000000000000000..564a28ec566228d1a6f11c11550d5a03b277037b --- /dev/null +++ b/doc/api/cache-remove.json @@ -0,0 +1,24 @@ +{ + "name": "cache-remove", + "brief": "The cache-remove command works similarly to reservation-get command.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "host_cache", + "cmd-syntax": "{ + \"command\": \"cache-remove\", + \"arguments\": { + \"ip-address\": \"192.0.2.1\", + \"subnet-id\": 123 + } +} + +Another example that removes IPv6 host identifier by DUID and specific subnet-id is: +{ + \"command\": \"cache-remove\", + \"arguments\": { + \"duid\": \"00:01:ab:cd:f0:a1:c2:d3:e4\", + \"subnet-id\": 123 + } +}" +} diff --git a/doc/api/cache-write.json b/doc/api/cache-write.json new file mode 100644 index 0000000000000000000000000000000000000000..635fe666e7e89f1a5a34237d57dad689e1b448c7 --- /dev/null +++ b/doc/api/cache-write.json @@ -0,0 +1,13 @@ +{ + "name": "cache-write", + "brief": "Instructs Kea to write its host cache content to disk.", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "host_cache", + + "cmd-syntax": "{ + \"command\": \"cache-write\", + \"arguments\": \"/path/to/the/file.json\" +}", + "cmd-comment": "The command takes one mandatory argument that specifies a filename path of a file to be written." +} diff --git a/doc/api/config-get.json b/doc/api/config-get.json new file mode 100644 index 0000000000000000000000000000000000000000..7ed254a56a9237161f61d2d9e6eda938dae069b2 --- /dev/null +++ b/doc/api/config-get.json @@ -0,0 +1,20 @@ +{ + "name": "config-get", + "brief": "Retrieves the current configuration used by the server. The configuration + is roughtly equal to the configuration file, but includes additional + changes made by other commands and due to parameters inheritance.", + "support": [ "kea-dhcp4", "kea-dhcp6", "kea-ctrl-agent" ], + "avail": "1.2.0", + + "cmd-syntax": "{ + \"command\": \"config-get\" +}", + "cmd-comment": "This command takes no parameters.", + + "resp-syntax": "{ + \"result\": , + \"arguments\": { + + } +}" +} diff --git a/doc/api/config-reload.json b/doc/api/config-reload.json new file mode 100644 index 0000000000000000000000000000000000000000..8104db373e1b68147ef779e2a352bf9325232d5f --- /dev/null +++ b/doc/api/config-reload.json @@ -0,0 +1,10 @@ +{ + "name": "config-reload", + "brief": "The config-reload command instructs Kea to load again the configuration file that was used previously.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.2.0", + "cmd-syntax": "{ + \"command\": \"config-reload\" +}" +} diff --git a/doc/api/config-set.json b/doc/api/config-set.json new file mode 100644 index 0000000000000000000000000000000000000000..b8b7b009273cea664b08d3c3923038bb83fadf2f --- /dev/null +++ b/doc/api/config-set.json @@ -0,0 +1,22 @@ +{ + "name": "config-set", + "brief": "The config-set command instructs the server to replace its current configuration with the new configuration supplied in the command's arguments.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.2.0", + "cmd-syntax": "{ + \"command\": \"config-set\", + \"arguments\": { + \"\": { + }, + \"Logging\": { + } + } +}", + "cmd-comment": "where <server> is the configuration element name for a given server such as \"Dhcp4\" or \"Dhcp6\"", + "resp-syntax": " {\"result\": 0, \"text\": \"Configuration successful.\" } + + or + + {\"result\": 1, \"text\": \"unsupported parameter: BOGUS (:16:26)\" }" +} diff --git a/doc/api/config-test.json b/doc/api/config-test.json new file mode 100644 index 0000000000000000000000000000000000000000..aa6ef357db22f9cb0e869f22c2d91c25d31e9c7d --- /dev/null +++ b/doc/api/config-test.json @@ -0,0 +1,22 @@ +{ + "name": "config-test", + "brief": "The config-test command instructs the server to check whether the new configuration supplied in the command's arguments can be loaded.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6", "kea-ctrl-agent" ], + "avail": "1.2.0", + "cmd-syntax": "{ + \"command\": \"config-test\", + \"arguments\": { + \"\": { + }, + \"Logging\": { + } + } +}", + "cmd-comment": "where >server< is the configuration element name for a given server such as \"Dhcp4\" or \"Dhcp6\"", + "resp-syntax": "{\"result\": 0, \"text\": \"Configuration seems sane...\" } + + or + + {\"result\": 1, \"text\": \"unsupported parameter: BOGUS (:16:26)\" }" +} diff --git a/doc/api/config-write.json b/doc/api/config-write.json new file mode 100644 index 0000000000000000000000000000000000000000..bce80a9007a69bf08e30e38c38e2b60f905faeda --- /dev/null +++ b/doc/api/config-write.json @@ -0,0 +1,14 @@ +{ + "name": "config-write", + "brief": "The config-write command instructs the Kea server to write its + current configuration to a file on disk.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6", "kea-ctrl-agent" ], + "avail": "1.2.0", + "cmd-syntax": "{ + \"command\": \"config-write\", + \"arguments\": { + \"filename\": \"config-modified-2017-03-15.json\" + } +}" +} diff --git a/doc/api/dhcp-disable.json b/doc/api/dhcp-disable.json new file mode 100644 index 0000000000000000000000000000000000000000..80baa6b2b97722a0cde9a93980e253c14eb0d3b8 --- /dev/null +++ b/doc/api/dhcp-disable.json @@ -0,0 +1,13 @@ +{ + "name": "dhcp-disable", + "brief": "The dhcp-disable command globally disables the DHCP service.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "cmd-syntax": "{ + \"command\": \"dhcp-disable\", + \"arguments\": { + \"max-period\": 20 + } +}" +} diff --git a/doc/api/dhcp-enable.json b/doc/api/dhcp-enable.json new file mode 100644 index 0000000000000000000000000000000000000000..a945b931f4523639ec4ca800ec7504807df24b0f --- /dev/null +++ b/doc/api/dhcp-enable.json @@ -0,0 +1,10 @@ +{ + "name": "dhcp-enable", + "brief": "The dhcp-enable command globally enables the DHCP service.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "cmd-syntax": "{ + \"command\": \"dhcp-enable\" +}" +} diff --git a/doc/api/ha-continue.json b/doc/api/ha-continue.json new file mode 100644 index 0000000000000000000000000000000000000000..c61b3f43cf297ad2ac06d846d0a6fe50e95a377b --- /dev/null +++ b/doc/api/ha-continue.json @@ -0,0 +1,8 @@ +{ + "name": "ha-continue", + "brief": "This command is used to resume the operation of the paused HA state machine.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "high_availability" +} diff --git a/doc/api/ha-heartbeat.json b/doc/api/ha-heartbeat.json new file mode 100644 index 0000000000000000000000000000000000000000..0ed6464e19c61b8502ea0ee69907e4a4847125e8 --- /dev/null +++ b/doc/api/ha-heartbeat.json @@ -0,0 +1,13 @@ +{ + "name": "ha-heartbeat", + "brief": "This command is sent internally by Kea partner when operating + in High Availability (HA) mode. It will retrieve the server HA state and clock value.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "high_availability", + "cmd-syntax": "{ + \"command\": \"ha-heartbeat\", + }", + "resp-comment": "The response to this command is different from the typical command response. The response will include server state (see plus the current clock value." +} diff --git a/doc/api/ha-scopes.json b/doc/api/ha-scopes.json new file mode 100644 index 0000000000000000000000000000000000000000..28b48eeb92d70717cf72e85d1a1c81fd3e5b037c --- /dev/null +++ b/doc/api/ha-scopes.json @@ -0,0 +1,15 @@ +{ + "name": "ha-scopes", + "brief": "This command modifies the scope that the server is responsible for serving when operating in High Availability (HA) mode.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "high_availability", + "cmd-syntax": "{ + \"command\": \"ha-scopes\", + \"service\": [ ], + \"arguments\": { + \"scopes\": [ \"HA_server1\", \"HA_server2\" ] + }", + "cmd-comment": "In the example given, the arguments configure the server to handle traffic from both HA_server1 and HA_server2 scopes." +} diff --git a/doc/api/ha-sync.json b/doc/api/ha-sync.json new file mode 100644 index 0000000000000000000000000000000000000000..282ca606d837ecc3ee831499d0cdd879a62eaeb7 --- /dev/null +++ b/doc/api/ha-sync.json @@ -0,0 +1,17 @@ +{ + "name": "ha-sync", + "brief": "The command is issued to instruct the server running in HA mode to + synchronize its local lease database with the selected peer.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "high_availability", + "cmd-syntax": "{ + \"command\": \"ha-sync\", + \"service\": [ , + \"max-period\": + } +}" +} diff --git a/doc/api/lease4-add.json b/doc/api/lease4-add.json new file mode 100644 index 0000000000000000000000000000000000000000..7e95990ce1fc6e48f2a1b6714168b47cd22f4cf4 --- /dev/null +++ b/doc/api/lease4-add.json @@ -0,0 +1,16 @@ +{ + "name": "lease4-add", + "brief": "The lease4-add command adds a new IPv4 lease administratively.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease4-add\", + \"arguments\": { + \"ip-address\": \"192.0.2.202\", + \"hw-address\": \"1a:1b:1c:1d:1e:1f\" + } +}", + "cmd-comment": "Note that Kea 1.4 requires an additional argument, subnet-ID, which is optional as of Kea 1.5. A number of other more detailed optional arguments are also supported." +} diff --git a/doc/api/lease4-del.json b/doc/api/lease4-del.json new file mode 100644 index 0000000000000000000000000000000000000000..37ccc6bb9afdd62bfd501e8325e16b59f457fc13 --- /dev/null +++ b/doc/api/lease4-del.json @@ -0,0 +1,15 @@ +{ + "name": "lease4-del", + "brief": "lease4-del can be used to delete a lease from the lease database.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease4-del\", + \"arguments\": { + \"ip-address\": \"192.0.2.202\" + } +}", + "cmd-comment": "Specify the lease to be deleted either by IP address, or by identifier-type and identifier value. Currently supported identifiers are \"hw-address\" and \"client-id\"." +} \ No newline at end of file diff --git a/doc/api/lease4-get-all.json b/doc/api/lease4-get-all.json new file mode 100644 index 0000000000000000000000000000000000000000..1b03e3abfe7f0f8ba9a654605ae6dfee829f2dc0 --- /dev/null +++ b/doc/api/lease4-get-all.json @@ -0,0 +1,13 @@ +{ + "name": "lease4-get-all", + "brief": "lease4-get-all is used to retrieve all IPv4 leases or all leases for the specified set of subnets.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.4.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease4-get-all\" + \"arguments\": \"subnets\" +}", + "cmd-comment": "The lease4-get-all command may result in very large responses." +} diff --git a/doc/api/lease4-get.json b/doc/api/lease4-get.json new file mode 100644 index 0000000000000000000000000000000000000000..2fea7c8b4967bebce76618d1edbd9a790175280a --- /dev/null +++ b/doc/api/lease4-get.json @@ -0,0 +1,31 @@ +{ + "name": "lease4-get", + "brief": "lease4-get can be used to query the lease database and retrieve existing leases.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease4-get\", + \"arguments\": { + \"ip-address\": \"192.0.2.1\" + } +}", + "resp-syntax": "{ + \"arguments\": { + \"client-id\": \"42:42:42:42:42:42:42:42\", + \"cltt\": 12345678, + \"fqdn-fwd\": false, + \"fqdn-rev\": true, + \"hostname\": \"myhost.example.com.\", + \"hw-address\": \"08:08:08:08:08:08\", + \"ip-address\": \"192.0.2.1\", + \"state\": 0, + \"subnet-id\": 44, + \"valid-lft\": 3600 + }, + \"result\": 0, + \"text\": \"IPv4 lease found.\" +}", + "resp-comment": "lease4-get returns a result that indicates a result of the operation and lease details, if found. It has one of the following values: 0 (success), 1 (error) or 2 (empty)." +} diff --git a/doc/api/lease4-update.json b/doc/api/lease4-update.json new file mode 100644 index 0000000000000000000000000000000000000000..8ae92c23867aae4f9d1451a97a1e156ed4928e76 --- /dev/null +++ b/doc/api/lease4-update.json @@ -0,0 +1,18 @@ +{ + "name": "lease4-update", + "brief": "The lease4-update command can be used to update existing leases.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease4-update\", + \"arguments\": { + \"ip-address\": \"192.0.2.1\", + \"hostname\": \"newhostname.example.org\", + \"hw-address\": \"1a:1b:1c:1d:1e:1f\", + \"subnet-id\": 44, + \"force-create\": true + } +}" +} diff --git a/doc/api/lease4-wipe.json b/doc/api/lease4-wipe.json new file mode 100644 index 0000000000000000000000000000000000000000..1b6d745dcbb3b807cc8e6fc4377684aa044f6710 --- /dev/null +++ b/doc/api/lease4-wipe.json @@ -0,0 +1,14 @@ +{ + "name": "lease4-wipe", + "brief": "lease4-wipe is designed to remove all leases associated with a given subnet.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease4-wipe\", + \"arguments\": { + \"subnet-id\": 44 + } +}" +} diff --git a/doc/api/lease6-add.json b/doc/api/lease6-add.json new file mode 100644 index 0000000000000000000000000000000000000000..039b11203ad7ad26b5dfa6ef1e8cbdb5f6b9abd2 --- /dev/null +++ b/doc/api/lease6-add.json @@ -0,0 +1,20 @@ +{ + "name": "lease6-add", + "brief": "The lease6-add command creates a new lease administratively.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease6-add\", + \"arguments\": { + \"subnet-id\": 66, + \"ip-address\": \"2001:db8::3\", + \"duid\": \"1a:1b:1c:1d:1e:1f:20:21:22:23:24\", + \"iaid\": 1234 + } +}", + "cmd-comment": "lease6-add can be also used to add leases for IPv6 prefixes..", + "resp-syntax": "{ \"result\": 0, \"text\": \"Lease added.\" } + { \"result\": 1, \"text\": \"missing parameter 'ip-address' (:3:19)\" }" +} diff --git a/doc/api/lease6-del.json b/doc/api/lease6-del.json new file mode 100644 index 0000000000000000000000000000000000000000..c81bb27b83fd34949201b4f1e05d54d2f69aac9b --- /dev/null +++ b/doc/api/lease6-del.json @@ -0,0 +1,15 @@ +{ + "name": "lease6-del", + "brief": "lease6-del can be used to delete a lease from the lease database.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease6-del\", + \"arguments\": { + \"ip-address\": \"192.0.2.202\" + } +}", + "cmd-comment": "lease6-del returns a result that indicates a outcome of the operation. It has one of the following values: 0 (success), 1 (error) or 3 (empty)." +} diff --git a/doc/api/lease6-get-all.json b/doc/api/lease6-get-all.json new file mode 100644 index 0000000000000000000000000000000000000000..e60bc812b9b6b837bc9cd792c159278fd714f459 --- /dev/null +++ b/doc/api/lease6-get-all.json @@ -0,0 +1,53 @@ +{ + "name": "lease6-get-all", + "brief": "lease6-get-all is used to retrieve all IPv6 leases or all leases for the specified set of subnets.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease6-get-all\", + \"arguments\": { + \"subnets\": [ 1, 2, 3, 4 ] + } +}", + "resp-syntax": "{ + \"arguments\": { + \"leases\": [ + { + \"cltt\": 12345678, + \"duid\": \"42:42:42:42:42:42:42:42\", + \"fqdn-fwd\": false, + \"fqdn-rev\": true, + \"hostname\": \"myhost.example.com.\", + \"hw-address\": \"08:08:08:08:08:08\", + \"iaid\": 1, + \"ip-address\": \"2001:db8:2::1\", + \"preferred-lft\": 500, + \"state\": 0, + \"subnet-id\": 44, + \"type\": \"IA_NA\", + \"valid-lft\": 3600 + }, + { + \"cltt\": 12345678, + \"duid\": \"21:21:21:21:21:21:21:21\", + \"fqdn-fwd\": false, + \"fqdn-rev\": true, + \"hostname\": \"\", + \"iaid\": 1, + \"ip-address\": \"2001:db8:0:0:2::\", + \"preferred-lft\": 500, + \"prefix-len\": 80, + \"state\": 0, + \"subnet-id\": 44, + \"type\": \"IA_PD\", + \"valid-lft\": 3600 + } + ] + }, + \"result\": 0, + \"text\": \"2 IPv6 lease(s) found.\" +}", + "resp-comment": "The lease6-get-all command may result in very large responses." +} \ No newline at end of file diff --git a/doc/api/lease6-get.json b/doc/api/lease6-get.json new file mode 100644 index 0000000000000000000000000000000000000000..646c7eafbc5be8ba238c62816e0b26d9279d865f --- /dev/null +++ b/doc/api/lease6-get.json @@ -0,0 +1,16 @@ +{ + "name": "lease6-get", + "brief": "lease6-get can be used to query the lease database and retrieve existing leases.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease6-get\", + \"arguments\": { + \"ip-address\": \"2001:db8:1234:ab::\", + \"type\": \"IA_PD\" + } +}", + "cmd-comment": "lease6-get returns a result that indicates a result of the operation and lease details, if found. It has one of the following values: 0 (success), 1 (error) or 2 (empty)." +} \ No newline at end of file diff --git a/doc/api/lease6-update.json b/doc/api/lease6-update.json new file mode 100644 index 0000000000000000000000000000000000000000..26a7bb694d7a7c16ab01b6e7a749867cc0a1c330 --- /dev/null +++ b/doc/api/lease6-update.json @@ -0,0 +1,20 @@ +{ + "name": "lease6-update", + "brief": "The lease6-update command can be used to update existing leases.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease6-update\", + \"arguments\": { + \"ip-address\": \"2001:db8::1\", + \"duid\": \"88:88:88:88:88:88:88:88\", + \"iaid\": 7654321, + \"hostname\": \"newhostname.example.org\", + \"subnet-id\": 66, + \"force-create\": false + } +} +" +} diff --git a/doc/api/lease6-wipe.json b/doc/api/lease6-wipe.json new file mode 100644 index 0000000000000000000000000000000000000000..ace82847b791b95d2a03437ee30060a304e8297d --- /dev/null +++ b/doc/api/lease6-wipe.json @@ -0,0 +1,15 @@ +{ + "name": "lease6-wipe", + "brief": "lease6-wipe is designed to remove all leases associated with a given subnet.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "lease_cmds", + "cmd-syntax": "{ + \"command\": \"lease6-wipe\", + \"arguments\": { + \"subnet-id\": 66 + } +}", + "cmd-comment": "Note: not all backends support this command." +} diff --git a/doc/api/leases-reclaim.json b/doc/api/leases-reclaim.json new file mode 100644 index 0000000000000000000000000000000000000000..c6d9b8f2bcb8fb269a8e8d21345746cabc606616 --- /dev/null +++ b/doc/api/leases-reclaim.json @@ -0,0 +1,13 @@ +{ + "name": "leases-reclaim", + "brief": "The leases-reclaim command instructs the server to reclaim all expired leases immediately.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"leases-reclaim\", + \"arguments\": { + \"remove\": true + } +}" +} diff --git a/doc/api/libreload.json b/doc/api/libreload.json new file mode 100644 index 0000000000000000000000000000000000000000..3b881a990a61f57c5b514343629c564cd7bbc506 --- /dev/null +++ b/doc/api/libreload.json @@ -0,0 +1,12 @@ +{ + "name": "libreload", + "brief": "The libreload command will first unload and then load all currently loaded hook libraries.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.2.0", + "cmd-syntax": "{ + \"command\": \"libreload\", + \"arguments\": { } +}", + "cmd-comment": "The server will respond with a result of 0 indicating success, or 1 indicating a failure." +} diff --git a/doc/api/list-commands.json b/doc/api/list-commands.json new file mode 100644 index 0000000000000000000000000000000000000000..0e3928895c15c8ebeb35e467559711542b78b426 --- /dev/null +++ b/doc/api/list-commands.json @@ -0,0 +1,12 @@ +{ + "name": "list-commands", + "brief": "The list-commands command retrieves a list of all commands supported by the server.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" , "kea-ctrl-agent" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"list-commands\", + \"arguments\": { } +}", + "cmd-comment": "The server will respond with a list of all supported commands." +} diff --git a/doc/api/network4-add.json b/doc/api/network4-add.json new file mode 100644 index 0000000000000000000000000000000000000000..c6fc25b814bde66948d77ac49693943f6172aaa0 --- /dev/null +++ b/doc/api/network4-add.json @@ -0,0 +1,46 @@ +{ + "name": "network4-add", + "brief": "The network4-add command is used to add a new shared network.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-add\", + \"arguments\": { + \"shared-networks\": [ { + \"name\": \"floor13\", + \"subnet4\": [ + { + \"id\": 100, + \"pools\": [ { \"pool\": \"192.0.2.2-192.0.2.99\" } ], + \"subnet\": \"192.0.2.0/24\", + \"option-data\": [ + { + \"name\": \"routers\", + \"data\": \"192.0.2.1\" + } + ] + }, + { + \"id\": 101, + \"pools\": [ { \"pool\": \"192.0.3.2-192.0.3.99\" } ], + \"subnet\": \"192.0.3.0/24\", + \"option-data\": [ + { + \"name\": \"routers\", + \"data\": \"192.0.3.1\" + } + ] + } ] + } ] + } +}", + "resp-syntax": "{ + \"arguments\": { + \"shared-networks\": [ { \"name\": \"floor13\" } ] + }, + \"result\": 0, + \"text\": \"A new IPv4 shared network 'floor13' added\" +}" +} diff --git a/doc/api/network4-del.json b/doc/api/network4-del.json new file mode 100644 index 0000000000000000000000000000000000000000..df747a05da415cdda5d66779136f89da54f251b5 --- /dev/null +++ b/doc/api/network4-del.json @@ -0,0 +1,25 @@ +{ + "name": "network4-del", + "brief": "The network4-del command is used to delete existing shared networks.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-del\", + \"arguments\": { + \"name\": \"floor13\" + } +}", + "resp-syntax": "{ + \"arguments\": { + \"shared-networks\": [ + { + \"name\": \"floor13\" + } + ] + }, + \"result\": 0, + \"text\": \"IPv4 shared network 'floor13' deleted\" +}" +} diff --git a/doc/api/network4-get.json b/doc/api/network4-get.json new file mode 100644 index 0000000000000000000000000000000000000000..83c91dd0581d934bf4b553175f659604a47ee754 --- /dev/null +++ b/doc/api/network4-get.json @@ -0,0 +1,47 @@ +{ + "name": "network4-get", + "brief": "The network4-get command is used to retrieve detailed information about shared networks, including subnets currently being part of a given network.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-get\", + \"arguments\": { + \"name\": \"floor13\" + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"Info about IPv4 shared network 'floor13' returned\", + \"arguments\": { + \"shared-networks\": [ + { + \"match-client-id\": true, + \"name\": \"floor13\", + \"option-data\": [ ], + \"rebind-timer\": 90, + \"relay\": { + \"ip-address\": \"0.0.0.0\" + }, + \"renew-timer\": 60, + \"reservation-mode\": \"all\", + \"subnet4\": [ + { + \"subnet\": \"192.0.2.0/24\", + \"id\": 5, + // many other subnet specific details here + }, + { + \"id\": 6, + \"subnet\": \"192.0.3.0/31\", + // many other subnet specific details here + } + ], + \"valid-lifetime\": 120 + } + ] + } +}", + "resp-comment": "Note that the actual response contains many additional fields that are omitted here for clarity." +} diff --git a/doc/api/network4-list.json b/doc/api/network4-list.json new file mode 100644 index 0000000000000000000000000000000000000000..77e8da9412aa04b28119872b70870793baae2d65 --- /dev/null +++ b/doc/api/network4-list.json @@ -0,0 +1,21 @@ +{ + "name": "network4-list", + "brief": "The network4-list command is used to retrieve full list of currently configured shared networks.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-list\" +}", + "resp-syntax": "{ + \"arguments\": { + \"shared-networks\": [ + { \"name\": \"floor1\" }, + { \"name\": \"office\" } + ] + }, + \"result\": 0, + \"text\": \"2 IPv4 network(s) found\" +}" +} diff --git a/doc/api/network4-subnet-add.json b/doc/api/network4-subnet-add.json new file mode 100644 index 0000000000000000000000000000000000000000..f1e326516728c763a7ecdf5cff9524fa2747e718 --- /dev/null +++ b/doc/api/network4-subnet-add.json @@ -0,0 +1,19 @@ +{ + "name": "network4-subnet-add", + "brief": "The network4-subnet-add command is used to add existing subnets to existing shared networks.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-subnet-add\", + \"arguments\": { + \"name\": \"floor13\", + \"id\": 5 + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'\" +}" +} diff --git a/doc/api/network4-subnet-del.json b/doc/api/network4-subnet-del.json new file mode 100644 index 0000000000000000000000000000000000000000..d417f4f66333b65a4c66ee6e4b7e6e9ff1af1f0f --- /dev/null +++ b/doc/api/network4-subnet-del.json @@ -0,0 +1,19 @@ +{ + "name": "network4-subnet-del", + "brief": "The network4-subnet-del command is used to remove a subnet that is part of an existing shared network and demote it to a plain, stand-alone subnet.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-subnet-del\", + \"arguments\": { + \"name\": \"floor13\", + \"id\": 5 + } + }", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'\" +}" +} diff --git a/doc/api/network6-add.json b/doc/api/network6-add.json new file mode 100644 index 0000000000000000000000000000000000000000..b3ddab8e90e4a8dc23d14e5c6e8ffa2861ab267a --- /dev/null +++ b/doc/api/network6-add.json @@ -0,0 +1,47 @@ +{ + "name": "network6-add", + "brief": "The network6-add command is used to add a new shared network.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-add\", + \"arguments\": { + \"shared-networks\": [ { + \"name\": \"floor13\", + \"subnet4\": [ + { + \"id\": 100, + \"pools\": [ { \"pool\": \"192.0.2.2-192.0.2.99\" } ], + \"subnet\": \"192.0.2.0/24\", + \"option-data\": [ + { + \"name\": \"routers\", + \"data\": \"192.0.2.1\" + } + ] + }, + { + \"id\": 101, + \"pools\": [ { \"pool\": \"192.0.3.2-192.0.3.99\" } ], + \"subnet\": \"192.0.3.0/24\", + \"option-data\": [ + { + \"name\": \"routers\", + \"data\": \"192.0.3.1\" + } + ] + } ] + } ] + } +}", + "cmd-comment": "The network6-add uses the same syntax for both the query and the response. However, there are some parameters that are IPv4-only (e.g. match-client-id) and some are IPv6-only (e.g. interface-id).", + "resp-syntax": "{ + \"arguments\": { + \"shared-networks\": [ { \"name\": \"floor13\" } ] + }, + \"result\": 0, + \"text\": \"A new IPv4 shared network 'floor13' added\" +}" +} diff --git a/doc/api/network6-del.json b/doc/api/network6-del.json new file mode 100644 index 0000000000000000000000000000000000000000..7217336f840e5265eb2f7977daa2a0985871eec4 --- /dev/null +++ b/doc/api/network6-del.json @@ -0,0 +1,23 @@ +{ + "name": "network6-del", + "brief": "The network6-del command is used to delete existing shared networks.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-del\", + \"arguments\": { + \"name\": \"floor13\" + } +}", + "cmd-comment": "The network6-del command uses exactly the same syntax for + both the command and the response.", + "resp-syntax": "{ + \"command\": \"network4-del\", + \"arguments\": { + \"name\": \"floor13\", + \"subnets-action\": \"delete\" + } +}" +} diff --git a/doc/api/network6-get.json b/doc/api/network6-get.json new file mode 100644 index 0000000000000000000000000000000000000000..99807eaadc16dccba923e5c6fcd06a2fd723fd32 --- /dev/null +++ b/doc/api/network6-get.json @@ -0,0 +1,47 @@ +{ + "name": "network6-get", + "brief": "The network6-get command is used to retrieve detailed information about shared networks, including subnets currently being part of a given network.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-get\", + \"arguments\": { + \"name\": \"floor13\" + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"Info about IPv4 shared network 'floor13' returned\", + \"arguments\": { + \"shared-networks\": [ + { + \"match-client-id\": true, + \"name\": \"floor13\", + \"option-data\": [ ], + \"rebind-timer\": 90, + \"relay\": { + \"ip-address\": \"0.0.0.0\" + }, + \"renew-timer\": 60, + \"reservation-mode\": \"all\", + \"subnet4\": [ + { + \"subnet\": \"192.0.2.0/24\", + \"id\": 5, + // many other subnet specific details here + }, + { + \"id\": 6, + \"subnet\": \"192.0.3.0/31\", + // many other subnet specific details here + } + ], + \"valid-lifetime\": 120 + } + ] + } +}", + "resp-comment": "Note that the actual response contains many additional fields that are omitted here for clarity." +} diff --git a/doc/api/network6-list.json b/doc/api/network6-list.json new file mode 100644 index 0000000000000000000000000000000000000000..4febd2ce3a9c53292becbc2a73f1bd634e25e4b8 --- /dev/null +++ b/doc/api/network6-list.json @@ -0,0 +1,22 @@ +{ + "name": "network6-list", + "brief": "The network6-list command is used to retrieve full list of currently configured shared networks.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-list\" +}", + "cmd-comment": "network6-list follows exactly the same syntax for both the query and the response.", + "resp-syntax": "{ + \"arguments\": { + \"shared-networks\": [ + { \"name\": \"floor1\" }, + { \"name\": \"office\" } + ] + }, + \"result\": 0, + \"text\": \"2 IPv4 network(s) found\" +}" +} diff --git a/doc/api/network6-subnet-add.json b/doc/api/network6-subnet-add.json new file mode 100644 index 0000000000000000000000000000000000000000..a23a45e6c27dddbaa594f92abfdd05731287f9ae --- /dev/null +++ b/doc/api/network6-subnet-add.json @@ -0,0 +1,20 @@ +{ + "name": "network6-subnet-add", + "brief": "The network6-subnet-add command is used to add existing subnets to existing shared networks.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-subnet-add\", + \"arguments\": { + \"name\": \"floor13\", + \"id\": 5 + } +}", + "cmd-comment": "The network6-subnet-add command uses exactly the same syntax for both the command and the response.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'\" +}" +} diff --git a/doc/api/network6-subnet-del.json b/doc/api/network6-subnet-del.json new file mode 100644 index 0000000000000000000000000000000000000000..4b43e7fce2f374213c381a36e978ae04b26adc0d --- /dev/null +++ b/doc/api/network6-subnet-del.json @@ -0,0 +1,20 @@ +{ + "name": "network6-subnet-del", + "brief": "The network6-subnet-del command is used to remove a subnet that is part of existing shared network and demote it to a plain, stand-alone subnet.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"network4-subnet-del\", + \"arguments\": { + \"name\": \"floor13\", + \"id\": 5 + } + }", + "cmd-comment": "The network6-subnet-del command uses exactly the same syntax for both the command and the response.", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'\" +}" +} diff --git a/doc/api/reservation-add.json b/doc/api/reservation-add.json new file mode 100644 index 0000000000000000000000000000000000000000..17818261ec1b655e2e6d6cc78fc32cd0dcfe4035 --- /dev/null +++ b/doc/api/reservation-add.json @@ -0,0 +1,54 @@ +{ + "name": "reservation-add", + "brief": "adds a new host reservation. The reservation may include IPv4 address, + IPv6 addresses, IPv6 prefixes, various identifiers, a class + the client will be assigned to, DHCPv4 and DHCPv6 options and + more.", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "hook": "host_cmds", + "avail": "1.2.0", + "description": "See ", + + "cmd-syntax": "{ + \"command\": \"reservation-add\", + \"arguments\": { + \"reservation\": { + \"boot-file-name\": , + \"comment\": + \"client-id\": , + \"circuit-id\": , + \"duid\": , + \"flex-id\": , + \"ip-address\": , + \"ip-addresses\": [ ], + \"hw-address\": , + \"hostname\": , + \"next-server\": , + \"option-data-list\": [ ], + \"prefixes\": [ ], + \"reservation-client-classes\": [ ], + \"server-hostname\": , + \"subnet-id\": , + \"user-context\": , + } + } +}", + "cmd-comment": "Note the ip-address, client-id, next-server, server-hostname and +boot-file-name are IPv4 specific. duid, ip-addresses and prefixes are +IPv6 specific.", + + "resp-syntax": " +{ + \"result\": , + \"text\": +}", + "resp-comment": "Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + +" +} + diff --git a/doc/api/reservation-del.json b/doc/api/reservation-del.json new file mode 100644 index 0000000000000000000000000000000000000000..48d5938bc1cc146b8b433892516f602b5a8932b1 --- /dev/null +++ b/doc/api/reservation-del.json @@ -0,0 +1,18 @@ +{ + "name": "reservation-del", + "brief": "Deletes an existing host reservation.", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "hook": "host_cmds", + "avail": "1.2.0", + + "cmd-syntax": "{ + \"command\": \"reservation-del\", + \"arguments\": { + \"subnet-id\": , + \"ip-address\": , + \"identifier-type\": , + \"identifier\": + } +}", + "cmd-comment": "The host reservation can be identified by either (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier)." +} diff --git a/doc/api/reservation-get.json b/doc/api/reservation-get.json new file mode 100644 index 0000000000000000000000000000000000000000..ef359b0928c602ac9caacc45380c9880932100f1 --- /dev/null +++ b/doc/api/reservation-get.json @@ -0,0 +1,45 @@ +{ + "name": "reservation-get", + "brief": "Attempts to retrieve an existing host reservation", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "hook": "host_cmds", + "avail": "1.2.0", + + "cmd-syntax": "{ + \"command\": \"reservation-get\", + \"arguments\": { + \"subnet-id\": , + \"identifier-type\": , + \"identifier\": ; + } +}", + + "cmd-comment": "The host reservation can be identified by either (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier).", + + "resp-syntax": "{ + \"result\": , + \"text\": , + \"arguments\": { + \"boot-file-name\": , + \"comment\": + \"client-id\": , + \"circuit-id\": , + \"duid\": , + \"flex-id\": , + \"ip-address\": , + \"ip-addresses\": [ ], + \"hw-address\": , + \"hostname\": , + \"next-server\": , + \"option-data-list\": [ ], + \"prefixes\": [ ], + \"reservation-client-classes\": [ ], + \"server-hostname\": , + \"subnet-id\": , + \"user-context\": , + } +}", + + "resp-comment": "Arguments object appear only if a host is found. Many fields in the arguments +object appear only if specific field is set." +} diff --git a/doc/api/shutdown.json b/doc/api/shutdown.json new file mode 100644 index 0000000000000000000000000000000000000000..5d2c387ad62482821ead5dbc961709b33bd1fff1 --- /dev/null +++ b/doc/api/shutdown.json @@ -0,0 +1,12 @@ +{ + "name": "shutdown", + "brief": "The shutdown command instructs the server to initiate its shutdown procedure.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6", "kea-ctrl-agent" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"shutdown\" +}", + "cmd-comment": "The server will respond with a confirmation that the shutdown + procedure has been initiated." +} diff --git a/doc/api/stat-lease4-get.json b/doc/api/stat-lease4-get.json new file mode 100644 index 0000000000000000000000000000000000000000..b155d9c7ffaea498cc1105d46f91863317b52ed3 --- /dev/null +++ b/doc/api/stat-lease4-get.json @@ -0,0 +1,29 @@ +{ + "name": "stat-lease4-get", + "brief": "The stat-lease4-get command fetches lease statistics for a range + of known IPv4 subnets.", + "description": "See ", + "support": [ "kea-dhcp4" ], + "avail": "1.4.0", + "hook": "stat_cmds", + "cmd-syntax": "{ + \"command\": \"stat-lease4-get\" +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"stat-lease4-get: 2 rows found\", + \"arguments\": { + \"result-set\": { + \"columns\": [ \"subnet-id\", + \"total-addresses\", + \"assigned-addresses\", + \"declined-addresses\" ] + \"rows\": [ + [ 10, 256, 111, 0 ], + [ 20, 4098, 2034, 4 ] + ], + \"timestamp\": \"2018-05-04 15:03:37.000000\" + } + } + }" +} diff --git a/doc/api/stat-lease6-get.json b/doc/api/stat-lease6-get.json new file mode 100644 index 0000000000000000000000000000000000000000..3834d7320cf78c35a31124c35f4cdd6223de7bec --- /dev/null +++ b/doc/api/stat-lease6-get.json @@ -0,0 +1,30 @@ +{ + "name": "stat-lease6-get", + "brief": "The stat-lease6-get command fetches lease statistics for a range + of known IPv6 subnets.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.4.0", + "hook": "stat_cmds", + "cmd-syntax": "{ + \"command\": \"stat-lease6-get\", + \"arguments\": { + \"subnet-id\" : 10 + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"stat-lease6-get: 2 rows found\", + \"arguments\": { + \"result-set\": { + \"columns\": [ \"subnet-id\", \"total-nas\", \"assigned-nas\", \"declined-nas\", \"total-pds\", \"assigned-pds\" ] + \"rows\": [ + [ 10, 4096, 2400, 3, 0, 0], + [ 20, 0, 0, 0, 1048, 233 ] + [ 30, 256, 60, 0, 1048, 15 ] + ], + \"timestamp\": \"2018-05-04 15:03:37.000000\" + } + } + }" +} diff --git a/doc/api/statistic-get-all.json b/doc/api/statistic-get-all.json new file mode 100644 index 0000000000000000000000000000000000000000..fcfdce1161e36336fcc8aa2547246017d93ac835 --- /dev/null +++ b/doc/api/statistic-get-all.json @@ -0,0 +1,12 @@ +{ + "name": "statistic-get-all", + "brief": "The statistic-get-all command retrieves all statistics recorded.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"statistic-get-all\", + \"arguments\": { } +}", + "cmd-comment": "The server will respond with details of all recorded statistics, with result set to 0 indicating that it iterated over all statistics (even when the total number of statistics is zero)." +} diff --git a/doc/api/statistic-get.json b/doc/api/statistic-get.json new file mode 100644 index 0000000000000000000000000000000000000000..97cf96ef87cb8bec04a3383d48250943a70b8ed1 --- /dev/null +++ b/doc/api/statistic-get.json @@ -0,0 +1,14 @@ +{ + "name": "statistic-get", + "brief": "The statistic-get command retrieves a single statistic. It takes a single string parameter called name that specifies the statistic name.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"statistic-get\", + \"arguments\": { + \"name\": \"pkt4-received\" + } +}", + "cmd-comment": "The server will respond with details of the requested statistic, with a result set to 0 indicating success and the specified statistic as the value of the \"arguments\" parameter." +} diff --git a/doc/api/statistic-remove-all.json b/doc/api/statistic-remove-all.json new file mode 100644 index 0000000000000000000000000000000000000000..b1cae435b3935d81238523a58f63f9278be9fd02 --- /dev/null +++ b/doc/api/statistic-remove-all.json @@ -0,0 +1,12 @@ +{ + "name": "statistic-remove-all", + "brief": "The statistic-remove-all command attempts to delete all statistics.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"statistic-remove-all\", + \"arguments\": { } +}", + "cmd-comment": "If the removal of all statistics was successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered, the server will return a status code of 1 (error) and the text field will contain the error description." +} diff --git a/doc/api/statistic-remove.json b/doc/api/statistic-remove.json new file mode 100644 index 0000000000000000000000000000000000000000..8e3eaa6874b4424ec8edcc1a7ca33f38cdfebba9 --- /dev/null +++ b/doc/api/statistic-remove.json @@ -0,0 +1,14 @@ +{ + "name": "statistic-remove", + "brief": "The statistic-remove command attempts to delete a single statistic. It takes a single string parameter called name that specifies the statistic name.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"statistic-remove\", + \"arguments\": { + \"name\": \"pkt4-received\" + } +}", + "cmd-comment": "If the specific statistic is found and its removal was successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered (e.g. requested statistic was not found), the server will return a status code of 1 (error) and the text field will contain the error description." +} diff --git a/doc/api/statistic-reset-all.json b/doc/api/statistic-reset-all.json new file mode 100644 index 0000000000000000000000000000000000000000..e87ab26c687e64935280b6c44f41ecb26de436f6 --- /dev/null +++ b/doc/api/statistic-reset-all.json @@ -0,0 +1,12 @@ +{ + "name": "statistic-reset-all", + "brief": "The statistic-reset command sets all statistics to their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time duration and \"\" for string type.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"statistic-reset-all\", + \"arguments\": { } +}", + "cmd-comment": "If the operation is successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered, the server will return a status code of 1 (error) and the text field will contain the error description." +} diff --git a/doc/api/statistic-reset.json b/doc/api/statistic-reset.json new file mode 100644 index 0000000000000000000000000000000000000000..c06162aef434c9300d7761bfbb519ae198b368b3 --- /dev/null +++ b/doc/api/statistic-reset.json @@ -0,0 +1,14 @@ +{ + "name": "statistic-reset", + "brief": "The statistic-reset command sets the specified statistic to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time duration and \"\" for string type. It takes a single string parameter called name that specifies the statistic name.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6" ], + "avail": "1.0.0", + "cmd-syntax": "{ + \"command\": \"statistic-reset\", + \"arguments\": { + \"name\": \"pkt4-received\" + } +}", + "cmd-comment": "If the specific statistic is found and reset was successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered (e.g. requested statistic was not found), the server will return a status code of 1 (error) and the text field will contain the error description." +} diff --git a/doc/api/subnet4-add.json b/doc/api/subnet4-add.json new file mode 100644 index 0000000000000000000000000000000000000000..14daab1bb800bc2c918a1dde185d8455b5cf5cdf --- /dev/null +++ b/doc/api/subnet4-add.json @@ -0,0 +1,30 @@ +{ + "name": "subnet4-add", + "brief": "This command is used to create and add a new subnet to the existing server configuration.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet4-add\", + \"arguments\": { + \"subnets\": [ { + \"id\": 123, + \"subnet\": \"10.20.30.0/24\", + ... + } ] + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 subnet added\", + \"arguments\": { + \"subnets\": [ + { + \"id\": 123, + \"subnet\": \"10.20.30.0/24\" + } + ] + } +}" +} diff --git a/doc/api/subnet4-del.json b/doc/api/subnet4-del.json new file mode 100644 index 0000000000000000000000000000000000000000..3adf0d59a7ffb52bd62cf7896265ed2d5e0cb376 --- /dev/null +++ b/doc/api/subnet4-del.json @@ -0,0 +1,26 @@ +{ + "name": "subnet4-del", + "brief": "This command is used to remove a subnet from the server's configuration. This command has no effect on other configured subnets but removing a subnet has certain implications which the server's administrator should be aware of.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet4-del\", + \"arguments\": { + \"id\": 123 + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv4 subnet 192.0.2.0/24 (id 123) deleted\", + \"arguments\": { + \"subnets\": [ + { + \"id\": 123, + \"subnet\": \"192.0.2.0/24\" + } + ] + } +}" +} diff --git a/doc/api/subnet4-get.json b/doc/api/subnet4-get.json new file mode 100644 index 0000000000000000000000000000000000000000..69d52202dc8c4588a4264a8a7ca6afe3285853ff --- /dev/null +++ b/doc/api/subnet4-get.json @@ -0,0 +1,30 @@ +{ + "name": "subnet4-get", + "brief": "This command is used to retrieve detailed information about the specified subnet. This command usually follows the subnet4-list, which is used to discover available subnets with their respective subnet identifiers and prefixes.", + "description": "See ", + "support": [ "kea-dhcp4" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet4-get\", + \"arguments\": { + \"id\": 10 + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"Info about IPv4 subnet 10.0.0.0/8 (id 10) returned\", + \"arguments\": { + \"subnets\": [ + { + \"subnet\": \"10.0.0.0/8\", + \"id\": 1, + \"option-data\": [ + .... + ] + ... + } + ] + } +}" +} diff --git a/doc/api/subnet4-list.json b/doc/api/subnet4-list.json new file mode 100644 index 0000000000000000000000000000000000000000..e514cbfd56c2c520cbd531b794c4b56956341e13 --- /dev/null +++ b/doc/api/subnet4-list.json @@ -0,0 +1,27 @@ +{ + "name": "subnet4-list", + "brief": "This command is used to list all currently configured subnets. The subnets are returned in a brief form, i.e. a subnet identifier and subnet prefix is included for each subnet.", + "description": "See ", + "support": [ "kea-dhcp4"], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet4-list\" +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"2 IPv4 subnets found\", + \"arguments\": { + \"subnets\": [ + { + \"id\": 10, + \"subnet\": \"10.0.0.0/8\" + }, + { + \"id\": 100, + \"subnet\": \"192.0.2.0/24\" + } + ] +}", + "resp-comment": "If no IPv4 subnets are found, an error code is returned along with the error description." +} \ No newline at end of file diff --git a/doc/api/subnet6-add.json b/doc/api/subnet6-add.json new file mode 100644 index 0000000000000000000000000000000000000000..727241f2462d6c689e03954d6480c0c604ca289e --- /dev/null +++ b/doc/api/subnet6-add.json @@ -0,0 +1,30 @@ +{ + "name": "subnet6-add", + "brief": "This command is used to create and add new subnet to the existing server configuration. This operation has no impact on other subnets.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet6-add\", + \"arguments\": { + \"subnet6\": [ { + \"id\": 234, + \"subnet\": \"2001:db8:1::/64\", + ... + } ] + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv6 subnet added\", + \"arguments\": { + \"subnet6\": [ + { + \"id\": 234, + \"subnet\": \"2001:db8:1::/64\" + } + ] + } +}" +} diff --git a/doc/api/subnet6-del.json b/doc/api/subnet6-del.json new file mode 100644 index 0000000000000000000000000000000000000000..d95e48828ce3e7598a3b6c897ae59c9e8ca293e0 --- /dev/null +++ b/doc/api/subnet6-del.json @@ -0,0 +1,24 @@ +{ + "name": "subnet6-del", + "brief": "This command is used to remove a subnet from the server's configuration. This command has no effect on other configured subnets but removing a subnet has certain implications which the server's administrator should be aware of.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet6-del\", + \"arguments\": { + \"id\": 234 + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"IPv6 subnet 2001:db8:1::/64 (id 234) deleted\", + \"subnets\": [ + { + \"id\": 234, + \"subnet\": \"2001:db8:1::/64\" + } + ] +}" +} diff --git a/doc/api/subnet6-get.json b/doc/api/subnet6-get.json new file mode 100644 index 0000000000000000000000000000000000000000..cc9e921677128bb9a0963e1bf7f972c5e97fade5 --- /dev/null +++ b/doc/api/subnet6-get.json @@ -0,0 +1,30 @@ +{ + "name": "subnet6-get", + "brief": "This command is used to retrieve detailed information about the specified subnet. This command usually follows the subnet6-list, which is used to discover available subnets with their respective subnet identifiers and prefixes.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet6-get\", + \"arguments\": { + \"id\": 11 + } +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned\", + \"arguments\": { + \"subnets\": [ + { + \"subnet\": \"2001:db8:1::/64\", + \"id\": 1, + \"option-data\": [ + ... + ] + .... + } + ] + } +}" +} diff --git a/doc/api/subnet6-list.json b/doc/api/subnet6-list.json new file mode 100644 index 0000000000000000000000000000000000000000..fc95177c5791888a5f5147377f74a24626be9227 --- /dev/null +++ b/doc/api/subnet6-list.json @@ -0,0 +1,27 @@ +{ + "name": "subnet6-list", + "brief": "This command is used to list all currently configured subnets. The subnets are returned in a brief form, i.e. a subnet identifier and subnet prefix is included for each subnet.", + "description": "See ", + "support": [ "kea-dhcp6" ], + "avail": "1.3.0", + "hook": "subnet_cmds", + "cmd-syntax": "{ + \"command\": \"subnet6-list\" +}", + "resp-syntax": "{ + \"result\": 0, + \"text\": \"2 IPv6 subnets found\", + \"arguments\": { + \"subnets\": [ + { + \"id\": 11, + \"subnet\": \"2001:db8:1::/64\" + }, + { + \"id\": 233, + \"subnet\": \"3000::/16\" + } + ] +}", + "resp-comment": "If no IPv6 subnets are found, an error code is returned along with the error description." +} \ No newline at end of file diff --git a/doc/api/version-get.json b/doc/api/version-get.json new file mode 100644 index 0000000000000000000000000000000000000000..7822eebabff1cca4703111239c5a0dad9541c74a --- /dev/null +++ b/doc/api/version-get.json @@ -0,0 +1,12 @@ +{ + "name": "version-get", + "brief": "The version-get command returns extended information about + Kea version. The returned string is the same as if Kea would + be run with -V command line option.", + "description": "See ", + "support": [ "kea-dhcp4", "kea-dhcp6", "kea-ctrl-agent" ], + "avail": "1.2.0", + "cmd-syntax": "{ + \"command\": \"version-get\" +}" +} diff --git a/doc/devel/doc.dox b/doc/devel/doc.dox new file mode 100644 index 0000000000000000000000000000000000000000..5af28f24fe6dadb5eda63842ef4b7e39f92b15b9 --- /dev/null +++ b/doc/devel/doc.dox @@ -0,0 +1,78 @@ +// Copyright (C) 2018 Internet Systems Consortium, Inc. ("ISC") +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +/** + + @page docs Building Kea Documentation + + There are several types of documentation for Kea. The primary one, intended to + be read by users, is User's Guide. It comes in HTML, PDF and txt format. All + of them generated from the same sources. To generate this doc, you need to + run configure script with --enable-generate-docs option. Several tools have to + be present in the system: docbook environment, links and several others. + You can generate this by doing: +@code +$ ./configure --enable-generate-docs +$ cd doc/ +$ make guide +@endcode + +The output files will be generated in doc/guide/ directory. + +Since Kea 1.5, this doc has appendix A that lists all Kea commands. That +appendix is generated using a small tool called docgen. The basic principle +is that for every command there is a JSON file that briefly describes the major +aspects of the new command, such as name, short description, expected syntax, +expected response, a hook that needs to be loaded, first Kea version where it +appeared, etc. Those JSON files are loaded by docgen tool that will generate +api.xml that will be used by make guide. There is no need to generate this, +unless you alter description of existing commands or add a new one. + +@section docsNewCommand Documenting new command + +There are several steps needed to document a new API command: + + 1. edit docgen/cmds-list and add the new command + 2. ./configure --enable-generate-docs + 3. make - you need to build the sources first, am afraid. The reason why you + need to do this is that the tool kea-docgen depends on libkea-cc as it + loads JSON files. This means that the libs need to be built first. + 4. (optional) run: make templates + This will go through the list of commands listed in cmds-list + and will check if there are corresponding JSON files in api/name.json + If the file is missing, a new JSON will be created using template. + If you dislike this generator, you can always use api/_template.json + and copy it over under the name of a new command. + 5. Edit api/command-name.json. If the command is provided by the daemon + out of its own (and not via hook), simply delete the hook entry. + If you don't want to provide command syntax (cmd-syntax key), + any comments about the syntax (cmd-comment key) or response syntax + (resp-syntax) or any comment about response (resp-comment), simply + remove those unused keys. The generator will attempt to generate + boilerplates for it. + 6. Generate api.xml: make api + 7. Rebuild User's Guide as usual: make guide + +A word of caution regaring editing JSON files. The files themselves need to be +valid JSON files. They also often contain fields, such as command syntax or +command response, there are themselves a JSON or JSON like structures. That +means that some trickery with escaping double quotes will be involved. Note +there is no need to escape any other character, unless you want to specify +non-printable characters. + +@section docsDevelGuide Generating Developer's Guide + +Generating Developer's Guide is very simple, although you need to have +doxygen installed in your system. If you also have graphviz installed, it will +generate nice diagrams. To generate developer's guide, do the following commands: + +@code +$ ./configure +$ cd doc +$ make devel +@endcode + +*/ \ No newline at end of file diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index 5bed68f9d9ec9bf4f1c63b1d329d1c9a80d99680..92a316c2a1f74699e3135813b66518b8ef995fac 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -141,6 +141,7 @@ * - @subpage logNotes * - @subpage LoggingApi * - @subpage SocketSessionUtility + * - @subpage docs * - Documentation warnings and errors * */ diff --git a/doc/docgen/.gitignore b/doc/docgen/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..568bae86bf7ac5246dc1151d9f99f35b828b6639 --- /dev/null +++ b/doc/docgen/.gitignore @@ -0,0 +1,2 @@ +cmd-docgen +*.json diff --git a/doc/docgen/Makefile.am b/doc/docgen/Makefile.am new file mode 100644 index 0000000000000000000000000000000000000000..72d8bd94c67c840222c3fafa7a9907d12ca52662 --- /dev/null +++ b/doc/docgen/Makefile.am @@ -0,0 +1,20 @@ +SUBDIRS = . + +AM_CPPFLAGS = -I$(top_srcdir)/src/lib -I$(top_builddir)/src/lib +AM_CPPFLAGS += $(BOOST_INCLUDES) + +AM_CXXFLAGS = $(KEA_CXXFLAGS) + +AM_LDFLAGS = -static + +if GENERATE_DOCS +noinst_PROGRAMS = kea-docgen +kea_docgen_SOURCES = kea_docgen.cc + +# For bare distcheck +EXTRA_DIST = cmd_docgen + +kea_docgen_LDADD = $(top_builddir)/src/lib/cc/libkea-cc.la +kea_docgen_LDADD += $(top_builddir)/src/lib/exceptions/libkea-exceptions.la + +endif diff --git a/doc/docgen/cmds-list b/doc/docgen/cmds-list new file mode 100644 index 0000000000000000000000000000000000000000..be78abba5f8baed2408206c8a55eed42a8d6723f --- /dev/null +++ b/doc/docgen/cmds-list @@ -0,0 +1,66 @@ +build-report +cache-clear +cache-get +cache-insert +cache-load +cache-remove +cache-write +config-get +config-reload +config-set +config-test +config-write +dhcp-disable +dhcp-enable +ha-continue +ha-heartbeat +ha-scopes +ha-sync +lease4-add +lease4-del +lease4-get +lease4-get-all +lease4-update +lease4-wipe +lease6-add +lease6-del +lease6-get +lease6-get-all +lease6-update +lease6-wipe +leases-reclaim +libreload +list-commands +network4-add +network4-del +network4-get +network4-list +network4-subnet-add +network4-subnet-del +network6-add +network6-del +network6-get +network6-list +network6-subnet-add +network6-subnet-del +reservation-add +reservation-del +reservation-get +shutdown +stat-lease4-get +stat-lease6-get +statistic-get +statistic-get-all +statistic-remove +statistic-remove-all +statistic-reset +statistic-reset-all +subnet4-add +subnet4-del +subnet4-get +subnet4-list +subnet6-add +subnet6-del +subnet6-get +subnet6-list +version-get diff --git a/doc/docgen/generate-templates b/doc/docgen/generate-templates new file mode 100755 index 0000000000000000000000000000000000000000..762bc1a687cdf7be1d99760390416def9a670b86 --- /dev/null +++ b/doc/docgen/generate-templates @@ -0,0 +1,44 @@ +#!/bin/bash + +# This script generates API documentation templates. +# Usage: +# +# ./generate-templates file +# +# File is expected to have a list of commands, one per line. +# The templates will be created in api/ directory. + +if (( $# != 1 )); then + echo "Usage: ./generate-templates file" + echo + echo "File specifies a plain text file with each line having name of a command" + exit +fi + + +mkdir -p api/ + +while read -r CMD; do + F=api/$CMD.json + + if [ -e $F ]; then + echo "$F exists, skipping" + continue; + fi + echo "{" > $F + echo " \"name\": \"$CMD\"," >> $F + echo " \"brief\": \"a sentence or two explaining what this command does\"," >> $F + echo " \"description\": \"See \"," >> $F + echo " \"support\": [ \"undocumented\" ]," >> $F + echo " \"avail\": \"0.0.0\"," >> $F + echo " \"hook\": \"undocumented\"," >> $F + + echo " \"cmd-syntax\": \"Syntax of the command\"," >> $F + echo " \"cmd-comment\": \"Possibly some extra comments after the syntax.\"," >> $F + + echo " \"resp-syntax\": \"Syntax of the response\"," >> $F + echo " \"resp-comment\": \"Optional extra comments after the resposne syntax.\"" >> $F + echo "}" >> $F + + echo "$CMD generated." +done < $1 diff --git a/doc/docgen/kea_docgen.cc b/doc/docgen/kea_docgen.cc new file mode 100644 index 0000000000000000000000000000000000000000..0ca6f4cc46d8aa1f95a283e065f0a8e1d8af4ebe --- /dev/null +++ b/doc/docgen/kea_docgen.cc @@ -0,0 +1,488 @@ +// Copyright (C) 2018 Internet Systems Consortium, Inc. ("ISC") +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +#include +#include +#include +#include +#include +#include +#include + +#include +#include + +using namespace std; +using namespace isc; +using namespace isc::data; + + +/// @brief API documentation generator +class DocGen { +public: + + /// Output location of a file. + const string OUTPUT = "guide/api.xml"; + + /// Controls whether to print out extra information. + bool verbose = false; + + /// @brief Load JSON files that each contain description of an API command + /// + /// @param files a vector with names of files. + void loadFiles(const vector& files) { + + map commands; + + int cnt = 0; + + int errors = 0; // number of errors encountered + + try { + for (auto f : files) { + string cmd = f; + size_t pos = f.find_last_of('/'); + if (pos != string::npos) { + cmd = f.substr(pos + 1, -1); + } + cmd = cmd.substr(0, cmd.find(".")); + + if (cmd == "_template") { + cout << "Skipping template file (_template.json)" << endl; + continue; + } + + try { + cout << "Loading description of command " << cmd << "... "; + ElementPtr x = Element::fromJSONFile(f, false); + cout << "loaded, sanity check..."; + + sanityCheck(f, x); + + cmds_.insert(make_pair(cmd, x)); + cout << " looks ok." << endl; + + } catch (const exception& e) { + cout << "ERROR: " << e.what() << endl; + errors++; + } + + if (errors) { + continue; + } + + cnt++; + } + } catch (const Unexpected& e) { + isc_throw(Unexpected, e.what() << " while processing " + << cnt + 1 << " file out of " << files.size()); + } + + cout << "Loaded " << cmds_.size() << " commands out of " << files.size() + << " file(s), " << errors << " error(s) detected." << endl; + if (errors) { + isc_throw(Unexpected, errors << " error(s) detected while loading JSON files"); + } + } + + /// @brief checks if mandatory string parameter is specified + /// + /// @param x a map that is being checked + /// @param name name of the string element expected to be there + /// @param fname name of the file (used in error reporting) + /// @throw Unexpected if missing, different type or empty + void requireString(const ElementPtr& x, const string& name, const string& fname) { + if (!x->contains(name)) { + isc_throw(Unexpected, "Mandatory '" + name + " field missing while " + "processing file " + fname); + } + if (x->get(name)->getType() != Element::string) { + isc_throw(Unexpected, "'" + name + " field is present, but is not a string" + " in file " + fname); + } + if (x->get(name)->stringValue().empty()) { + isc_throw(Unexpected, "'" + name + " field is present, is a string, but is " + "empty in file " + fname); + } + } + + /// @brief checks if mandatory list parameter is specified + /// + /// @param x a map that is being checked + /// @param name name of the list element expected to be there + /// @param fname name of the file (used in error reporting) + /// @throw Unexpected if missing, different type or empty + void requireList(const ElementPtr& x, const string& name, const string& fname) { + if (!x->contains(name)) { + isc_throw(Unexpected, "Mandatory '" + name + " field missing while " + "processing file " + fname); + } + if (x->get(name)->getType() != Element::list) { + isc_throw(Unexpected, "'" + name + " field is present, but is not a list " + "in file " + fname); + } + + ConstElementPtr l = x->get(name); + + if (l->size() == 0) { + isc_throw(Unexpected, "'" + name + " field is a list, but is empty in file " + + fname); + } + + // todo: check that every element is a string + } + + /// @brief Checks that the essential parameters for each command are defined + /// + /// @param fname name of the file the data was read from (printed if error is detected) + /// @param x a JSON map that contains content of the file + void sanityCheck(const string& fname, const ElementPtr& x) { + requireString(x, "name", fname); + requireString(x, "brief", fname); + requireList (x, "support", fname); + requireString(x, "avail", fname); + requireString(x, "brief", fname); + + // They're optional. + //requireString(x, "cmd-syntax", fname); + //requireString(x, "cmd-comment", fname); + //requireString(x, "resp-syntax", fname); + //requireString(x, "resp-comment", fname); + } + + /// @brief Writes ISC copyright note to the stream + /// + /// @param f stream to write copyrights to + void generateCopyright(stringstream& f) { + f << "" << endl; + f << endl; + f << "" << endl; + } + + /// @brief generates a link to command + /// + /// @param f stream to write the generated link to + /// @param cmd name of the command + void generateCmdLink(stringstream& f, const string& cmd) { + f << "" << cmd + << "" << endl; + } + + /// @brief generates lists of all commands. + /// + /// Currently there are several lists (or rather lists of lists). They all enumerate + /// commands, but each list serving a different purpose: + /// - list of commands supported by a daemon + /// - list of commands provided by a hook + /// + /// @param f stream to write the generated lists to + void generateLists(stringstream& f) { + // Generate a list of all commands + f << " Kea currently supports " << cmds_.size() << " commands:" << endl; + + bool first = true; + for (auto cmd : cmds_) { + if (!first) { + f << ", "; + } + generateCmdLink(f, cmd.first); + + first = false; + } + + f << "." << endl; + + // Generate a list of components: + set all_daemons; + set all_hooks; + for (auto cmd : cmds_) { + auto daemons = cmd.second->get("support"); + auto hook = cmd.second->get("hook"); + for (int i = 0; i < daemons->size(); i++) { + string daemon = daemons->get(i)->stringValue(); + if (all_daemons.find(daemon) == all_daemons.end()) { + all_daemons.insert(daemon); + } + } + if (hook) { + string hook_txt = hook->stringValue(); + if (all_hooks.find(hook_txt) == all_hooks.end()) { + all_hooks.insert(hook_txt); + } + } + } + + cout << all_daemons.size() << " daemon(s) detected." << endl; + cout << all_hooks.size() << " hook lib(s) detected." << endl; + + for (auto daemon : all_daemons) { + f << "" + << "Commands supported by " << daemon << " daemon: "; + + bool first = true; + for (auto cmd : cmds_) { + + auto daemons = cmd.second->get("support"); + for (auto d : daemons->listValue()) { + if (d->stringValue() == daemon) { + if (!first) { + f << ", "; + } + generateCmdLink(f, cmd.first); + first = false; + break; // get to next command + } + } + } + + f << "." << endl; + } + + + for (auto hook : all_hooks) { + f << "" + << "Commands supported by " << hook << " hook library: "; + + bool first = true; + for (auto cmd : cmds_) { + + auto daemon_hook = cmd.second->get("hook"); + if (!daemon_hook || daemon_hook->stringValue() != hook) { + continue; + } + if (!first) { + f << ", "; + } + generateCmdLink(f, cmd.first); + first = false; + } + + f << "." << endl; + } + + } + + /// @brief generates the whole API documentation + void generateOutput() { + + stringstream f; + + generateCopyright(f); + + f << "" + << endl; + f << " API Reference" << endl; + + + generateLists(f); + + // Generate actual commands references. + generateCommands(f); + + f << "" << endl; + + ofstream file(OUTPUT.c_str(), ofstream::trunc); + file << f.str(); + if (verbose) { + cout << "----------------" << endl; + cout << f.str(); + cout << "----------------" << endl; + } + file.close(); + + cout << "Output written to " << OUTPUT << endl; + } + + /// @brief generate sections for all commands + /// + /// @param f stream to write the commands to + void generateCommands(stringstream& f){ + + for (auto cmd : cmds_) { + f << "" << endl; + f << "
" << endl; + f << "" << cmd.first << " reference" << endl; + generateCommand(f, cmd.second); + f << "
" << endl; + f << "" << endl; + f << endl; + } + } + + /// @brief replace all strings + /// + /// @param str [in,out] this string will have some replacements + /// @param from what to replace + /// @param to what to replace with + void replaceAll(std::string& str, const std::string& from, const std::string& to) { + if(from.empty()) + return; + size_t start_pos = 0; + while((start_pos = str.find(from, start_pos)) != std::string::npos) { + str.replace(start_pos, from.length(), to); + start_pos += to.length(); + } + } + + /// @brief escapes string to be safe for XML (docbook) + /// + /// @param txt string to be escaped + /// @return escaped string + string escapeString(string txt) { + + replaceAll(txt, "<", "<"); + replaceAll(txt, ">", ">"); + return (txt); + } + + /// @brief generates standard description of command's response + /// + /// If a command doesn't have response syntax specified, we will + /// assume it follows the usual syntax and provide the default description. + string standardResponseSyntax() { + stringstream t; + + t << "{" << endl + << " \"result\": ," << endl + << " \"text\": " << endl + << "}" << endl; + return (t.str()); + } + + /// @brief generates standard description of command's comment + /// + /// If a command doesn't have response syntax comment specified, we will + /// assume it follows the usual syntax and provide the default description. + string standardResponseComment() { + stringstream t; + + t << "Result is an integer representation of the status. Currently supported" + << " statuses are:" << endl + << "" << endl + << " 0 - success" << endl + << " 1 - error" << endl + << " 2 - unsupported" << endl + << " 3 - empty (command was completed successfully, but " + << "no data was affected or returned)" + << "" << endl + << "" << endl; + return (t.str()); + } + + /// @brief generates command description + /// + /// @param f stream to write the description to + /// @param cmd pointer to JSON structure that describes the command + void generateCommand(stringstream& f, const ElementPtr& cmd) { + + // command overview + f << "get("name")->stringValue() << "\">" + << cmd->get("name")->stringValue() << " - " + << cmd->get("brief")->stringValue() << "" << endl << endl; + + // command can be issued to the following daemons + f << "Supported by: "; + ConstElementPtr daemons = cmd->get("support"); + for (int i = 0; i < daemons->size(); i++) { + if (i) { + f << ", "; + } + + f << "get(i)->stringValue() + << "\">" << daemons->get(i)->stringValue() << ""; + } + f << "" << endl << endl; + + // availability + f << "Availability: " << cmd->get("avail")->stringValue(); + auto hook = cmd->get("hook"); + if (hook) { + f << " (stringValue() << "-lib\">" + << hook->stringValue() << " hook)"; + } else { + f << " (built-in)"; + } + + f << "" << endl << endl; + + // description and examples + f << "Description and examples: See get("name")->stringValue() << "\"/>" << endl << endl; + + // Command syntax: + f << "Command syntax:" << endl; + if (cmd->contains("cmd-syntax")) { + f << " " << escapeString(cmd->get("cmd-syntax")->stringValue()) + << "" << endl; + } else { + f << " {" << endl + << " \"command\": \"" << cmd->get("name")->stringValue() << "\"" << endl + << "}" << endl; + } + if (cmd->contains("cmd-comment")) { + f << cmd->get("cmd-comment")->stringValue(); + } + f << "" << endl << endl; + + // Response syntax + f << "Response syntax:" << endl + << " "; + + if (cmd->contains("resp-syntax")) { + f << escapeString(cmd->get("resp-syntax")->stringValue()); + } else { + f << escapeString(standardResponseSyntax()); + } + f << "" << endl; + + if (cmd->contains("resp-comment")) { + f << cmd->get("resp-comment")->stringValue(); + } else { + f << standardResponseComment(); + } + f << "" << endl << endl; + } + + map cmds_; +}; + +int main(int argc, const char*argv[]) { + + vector files; + + for (int i = 1; i < argc; i++) { + files.push_back(string(argv[i])); + } + + cout << "Loading " << files.size() << " files(s)." << endl; + + try { + DocGen doc_gen; + + doc_gen.loadFiles(files); + + doc_gen.generateOutput(); + } catch (const exception& e) { + cerr << "ERROR: " << e.what() << endl; + } + + return (0); +} diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index f13cca197b00677ae980a7533f30ab8b981a1ffc..ece9ed07fea82f6fb747b507726965b278fbc086 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -10,6 +10,7 @@ DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging. DOCBOOK += ddns.xml hooks.xml hooks-ha.xml hooks-host-cache.xml hooks-lease-cmds.xml DOCBOOK += hooks-radius.xml hooks-stat-cmds.xml libdhcp.xml lfc.xml stats.xml DOCBOOK += ctrl-channel.xml faq.xml classify.xml shell.xml agent.xml netconf.xml +DOCBOOK += api.xml EXTRA_DIST = $(DOCBOOK) diff --git a/doc/guide/api.xml b/doc/guide/api.xml new file mode 100644 index 0000000000000000000000000000000000000000..67b82676e717ee665d5742bd9032ecc0dca0df77 --- /dev/null +++ b/doc/guide/api.xml @@ -0,0 +1,3012 @@ + + + + + API Reference + Kea currently supports 66 commands: +build-report +, cache-clear +, cache-get +, cache-insert +, cache-load +, cache-remove +, cache-write +, config-get +, config-reload +, config-set +, config-test +, config-write +, dhcp-disable +, dhcp-enable +, ha-continue +, ha-heartbeat +, ha-scopes +, ha-sync +, lease4-add +, lease4-del +, lease4-get +, lease4-get-all +, lease4-update +, lease4-wipe +, lease6-add +, lease6-del +, lease6-get +, lease6-get-all +, lease6-update +, lease6-wipe +, leases-reclaim +, libreload +, list-commands +, network4-add +, network4-del +, network4-get +, network4-list +, network4-subnet-add +, network4-subnet-del +, network6-add +, network6-del +, network6-get +, network6-list +, network6-subnet-add +, network6-subnet-del +, reservation-add +, reservation-del +, reservation-get +, shutdown +, stat-lease4-get +, stat-lease6-get +, statistic-get +, statistic-get-all +, statistic-remove +, statistic-remove-all +, statistic-reset +, statistic-reset-all +, subnet4-add +, subnet4-del +, subnet4-get +, subnet4-list +, subnet6-add +, subnet6-del +, subnet6-get +, subnet6-list +, version-get +. +Commands supported by kea-ctrl-agent daemon: build-report +, config-get +, config-test +, config-write +, list-commands +, shutdown +, version-get +. +Commands supported by kea-dhcp4 daemon: build-report +, cache-clear +, cache-get +, cache-insert +, cache-load +, cache-remove +, cache-write +, config-get +, config-reload +, config-set +, config-test +, config-write +, dhcp-disable +, dhcp-enable +, ha-continue +, ha-heartbeat +, ha-scopes +, ha-sync +, lease4-add +, lease4-del +, lease4-get +, lease4-get-all +, lease4-update +, lease4-wipe +, leases-reclaim +, libreload +, list-commands +, network4-add +, network4-del +, network4-get +, network4-list +, network4-subnet-add +, network4-subnet-del +, reservation-add +, reservation-del +, reservation-get +, shutdown +, stat-lease4-get +, statistic-get +, statistic-get-all +, statistic-remove +, statistic-remove-all +, statistic-reset +, statistic-reset-all +, subnet4-add +, subnet4-del +, subnet4-get +, subnet4-list +, version-get +. +Commands supported by kea-dhcp6 daemon: build-report +, cache-clear +, cache-get +, cache-insert +, cache-load +, cache-remove +, cache-write +, config-get +, config-reload +, config-set +, config-test +, config-write +, dhcp-disable +, dhcp-enable +, ha-continue +, ha-heartbeat +, ha-scopes +, ha-sync +, lease6-add +, lease6-del +, lease6-get +, lease6-get-all +, lease6-update +, lease6-wipe +, leases-reclaim +, libreload +, list-commands +, network6-add +, network6-del +, network6-get +, network6-list +, network6-subnet-add +, network6-subnet-del +, reservation-add +, reservation-del +, reservation-get +, shutdown +, stat-lease6-get +, statistic-get +, statistic-get-all +, statistic-remove +, statistic-remove-all +, statistic-reset +, statistic-reset-all +, subnet6-add +, subnet6-del +, subnet6-get +, subnet6-list +, version-get +. +Commands supported by high_availability hook library: ha-continue +, ha-heartbeat +, ha-scopes +, ha-sync +. +Commands supported by host_cache hook library: cache-clear +, cache-get +, cache-insert +, cache-load +, cache-remove +, cache-write +. +Commands supported by host_cmds hook library: reservation-add +, reservation-del +, reservation-get +. +Commands supported by lease_cmds hook library: lease4-add +, lease4-del +, lease4-get +, lease4-get-all +, lease4-update +, lease4-wipe +, lease6-add +, lease6-del +, lease6-get +, lease6-get-all +, lease6-update +, lease6-wipe +. +Commands supported by stat_cmds hook library: stat-lease4-get +, stat-lease6-get +. +Commands supported by subnet_cmds hook library: network4-add +, network4-del +, network4-get +, network4-list +, network4-subnet-add +, network4-subnet-del +, network6-add +, network6-del +, network6-get +, network6-list +, network6-subnet-add +, network6-subnet-del +, subnet4-add +, subnet4-del +, subnet4-get +, subnet4-list +, subnet6-add +, subnet6-del +, subnet6-get +, subnet6-list +. + +
+build-report reference +build-report - Returns a list of compilation options that this particular binary was built with + +Supported by: kea-dhcp4, kea-dhcp6, kea-ctrl-agent + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "build-report" +} + + +Response syntax: + { + "result": 0, + "text": <string with build details> +} + + +
+ + + +
+cache-clear reference +cache-clear - This command removes all cached host reservations. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (host_cache hook) + +Description and examples: See + +Command syntax: + { + "command": "cache-clear" +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+cache-get reference +cache-get - Returns full content of the host cache. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (host_cache hook) + +Description and examples: See + +Command syntax: + { + "command": "cache-get" +} + + +Response syntax: + { + "result": 0 + "text": "123 entries returned." + "arguments": <list of host reservations> +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+cache-insert reference +cache-insert - This command may be used to manually insert a host into the cache. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (host_cache hook) + +Description and examples: See + +Command syntax: + { + "command": "cache-insert", + "arguments": { + "hw-address": "01:02:03:04:05:06", + "subnet-id4": 4, + "subnet-id6": 0, + "ip-address": "192.0.2.100", + "hostname": "somehost.example.org", + "client-classes4": [ ], + "client-classes6": [ ], + "option-data4": [ ], + "option-data6": [ ], + "next-server": "192.0.0.2", + "server-hostname": "server-hostname.example.org", + "boot-file-name": "bootfile.efi", + "host-id": 0 + } +}, +{ + "command": "cache-insert", + "arguments": { + "hw-address": "01:02:03:04:05:06", + "subnet-id4": 0, + "subnet-id6": 6, + "ip-addresses": [ "2001:db8::cafe:babe" ], + "prefixes": [ "2001:db8:dead:beef::/64" ], + "hostname": "", + "client-classes4": [ ], + "client-classes6": [ ], + "option-data4": [ ], + "option-data6": [ ], + "next-server": "0.0.0.0", + "server-hostname": "", + "boot-file-name": "", + "host-id": 0 + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+cache-load reference +cache-load - This command allows load the contents of a file on disk into an in-memory cache. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (host_cache hook) + +Description and examples: See + +Command syntax: + { + "command": "cache-load", + "arguments": "/tmp/kea-host-cache.json" +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+cache-remove reference +cache-remove - The cache-remove command works similarly to reservation-get command. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (host_cache hook) + +Description and examples: See + +Command syntax: + { + "command": "cache-remove", + "arguments": { + "ip-address": "192.0.2.1", + "subnet-id": 123 + } +} + +Another example that removes IPv6 host identifier by DUID and specific subnet-id is: +{ + "command": "cache-remove", + "arguments": { + "duid": "00:01:ab:cd:f0:a1:c2:d3:e4", + "subnet-id": 123 + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+cache-write reference +cache-write - Instructs Kea to write its host cache content to disk. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (host_cache hook) + +Description and examples: See + +Command syntax: + { + "command": "cache-write", + "arguments": "/path/to/the/file.json" +} +The command takes one mandatory argument that specifies a filename path of a file to be written. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+config-get reference +config-get - Retrieves the current configuration used by the server. The configuration + is roughtly equal to the configuration file, but includes additional + changes made by other commands and due to parameters inheritance. + +Supported by: kea-dhcp4, kea-dhcp6, kea-ctrl-agent + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "config-get" +} +This command takes no parameters. + +Response syntax: + { + "result": <integer>, + "arguments": { + <JSON configuration here, starting with Dhcp4, Dhcp6, or Control-agent object> + } +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+config-reload reference +config-reload - The config-reload command instructs Kea to load again the configuration file that was used previously. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "config-reload" +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+config-set reference +config-set - The config-set command instructs the server to replace its current configuration with the new configuration supplied in the command's arguments. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "config-set", + "arguments": { + "<server>": { + }, + "Logging": { + } + } +} +where <server> is the configuration element name for a given server such as "Dhcp4" or "Dhcp6" + +Response syntax: + {"result": 0, "text": "Configuration successful." } + + or + + {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" } +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+config-test reference +config-test - The config-test command instructs the server to check whether the new configuration supplied in the command's arguments can be loaded. + +Supported by: kea-dhcp4, kea-dhcp6, kea-ctrl-agent + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "config-test", + "arguments": { + "<server>": { + }, + "Logging": { + } + } +} +where >server< is the configuration element name for a given server such as "Dhcp4" or "Dhcp6" + +Response syntax: + {"result": 0, "text": "Configuration seems sane..." } + + or + + {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" } +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+config-write reference +config-write - The config-write command instructs the Kea server to write its + current configuration to a file on disk. + +Supported by: kea-dhcp4, kea-dhcp6, kea-ctrl-agent + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "config-write", + "arguments": { + "filename": "config-modified-2017-03-15.json" + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+dhcp-disable reference +dhcp-disable - The dhcp-disable command globally disables the DHCP service. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "dhcp-disable", + "arguments": { + "max-period": 20 + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+dhcp-enable reference +dhcp-enable - The dhcp-enable command globally enables the DHCP service. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "dhcp-enable" +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+ha-continue reference +ha-continue - This command is used to resume the operation of the paused HA state machine. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (high_availability hook) + +Description and examples: See + +Command syntax: + { + "command": "ha-continue" +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+ha-heartbeat reference +ha-heartbeat - This command is sent internally by Kea partner when operating + in High Availability (HA) mode. It will retrieve the server HA state and clock value. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (high_availability hook) + +Description and examples: See + +Command syntax: + { + "command": "ha-heartbeat", + } + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +The response to this command is different from the typical command response. The response will include server state (see plus the current clock value. + +
+ + + +
+ha-scopes reference +ha-scopes - This command modifies the scope that the server is responsible for serving when operating in High Availability (HA) mode. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (high_availability hook) + +Description and examples: See + +Command syntax: + { + "command": "ha-scopes", + "service": [ <service, typically "dhcp4" or "dhcp6"> ], + "arguments": { + "scopes": [ "HA_server1", "HA_server2" ] + } +In the example given, the arguments configure the server to handle traffic from both HA_server1 and HA_server2 scopes. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+ha-sync reference +ha-sync - The command is issued to instruct the server running in HA mode to + synchronize its local lease database with the selected peer. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.4.0 (high_availability hook) + +Description and examples: See + +Command syntax: + { + "command": "ha-sync", + "service": [ <service affected: "dhcp4" or "dhcp6" ], + "arguments": { + "server-name": <name of the partner server>, + "max-period": <integer, in seconds> + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease4-add reference +lease4-add - The lease4-add command adds a new IPv4 lease administratively. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease4-add", + "arguments": { + "ip-address": "192.0.2.202", + "hw-address": "1a:1b:1c:1d:1e:1f" + } +} +Note that Kea 1.4 requires an additional argument, subnet-ID, which is optional as of Kea 1.5. A number of other more detailed optional arguments are also supported. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease4-del reference +lease4-del - lease4-del can be used to delete a lease from the lease database. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease4-del", + "arguments": { + "ip-address": "192.0.2.202" + } +} +Specify the lease to be deleted either by IP address, or by identifier-type and identifier value. Currently supported identifiers are "hw-address" and "client-id". + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease4-get reference +lease4-get - lease4-get can be used to query the lease database and retrieve existing leases. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease4-get", + "arguments": { + "ip-address": "192.0.2.1" + } +} + + +Response syntax: + { + "arguments": { + "client-id": "42:42:42:42:42:42:42:42", + "cltt": 12345678, + "fqdn-fwd": false, + "fqdn-rev": true, + "hostname": "myhost.example.com.", + "hw-address": "08:08:08:08:08:08", + "ip-address": "192.0.2.1", + "state": 0, + "subnet-id": 44, + "valid-lft": 3600 + }, + "result": 0, + "text": "IPv4 lease found." +} +lease4-get returns a result that indicates a result of the operation and lease details, if found. It has one of the following values: 0 (success), 1 (error) or 2 (empty). + +
+ + + +
+lease4-get-all reference +lease4-get-all - lease4-get-all is used to retrieve all IPv4 leases or all leases for the specified set of subnets. + +Supported by: kea-dhcp4 + +Availability: 1.4.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease4-get-all" + "arguments": "subnets" +} +The lease4-get-all command may result in very large responses. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease4-update reference +lease4-update - The lease4-update command can be used to update existing leases. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease4-update", + "arguments": { + "ip-address": "192.0.2.1", + "hostname": "newhostname.example.org", + "hw-address": "1a:1b:1c:1d:1e:1f", + "subnet-id": 44, + "force-create": true + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease4-wipe reference +lease4-wipe - lease4-wipe is designed to remove all leases associated with a given subnet. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease4-wipe", + "arguments": { + "subnet-id": 44 + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease6-add reference +lease6-add - The lease6-add command creates a new lease administratively. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease6-add", + "arguments": { + "subnet-id": 66, + "ip-address": "2001:db8::3", + "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24", + "iaid": 1234 + } +} +lease6-add can be also used to add leases for IPv6 prefixes.. + +Response syntax: + { "result": 0, "text": "Lease added." } + { "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" } +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease6-del reference +lease6-del - lease6-del can be used to delete a lease from the lease database. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease6-del", + "arguments": { + "ip-address": "192.0.2.202" + } +} +lease6-del returns a result that indicates a outcome of the operation. It has one of the following values: 0 (success), 1 (error) or 3 (empty). + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease6-get reference +lease6-get - lease6-get can be used to query the lease database and retrieve existing leases. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease6-get", + "arguments": { + "ip-address": "2001:db8:1234:ab::", + "type": "IA_PD" + } +} +lease6-get returns a result that indicates a result of the operation and lease details, if found. It has one of the following values: 0 (success), 1 (error) or 2 (empty). + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease6-get-all reference +lease6-get-all - lease6-get-all is used to retrieve all IPv6 leases or all leases for the specified set of subnets. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease6-get-all", + "arguments": { + "subnets": [ 1, 2, 3, 4 ] + } +} + + +Response syntax: + { + "arguments": { + "leases": [ + { + "cltt": 12345678, + "duid": "42:42:42:42:42:42:42:42", + "fqdn-fwd": false, + "fqdn-rev": true, + "hostname": "myhost.example.com.", + "hw-address": "08:08:08:08:08:08", + "iaid": 1, + "ip-address": "2001:db8:2::1", + "preferred-lft": 500, + "state": 0, + "subnet-id": 44, + "type": "IA_NA", + "valid-lft": 3600 + }, + { + "cltt": 12345678, + "duid": "21:21:21:21:21:21:21:21", + "fqdn-fwd": false, + "fqdn-rev": true, + "hostname": "", + "iaid": 1, + "ip-address": "2001:db8:0:0:2::", + "preferred-lft": 500, + "prefix-len": 80, + "state": 0, + "subnet-id": 44, + "type": "IA_PD", + "valid-lft": 3600 + } + ] + }, + "result": 0, + "text": "2 IPv6 lease(s) found." +} +The lease6-get-all command may result in very large responses. + +
+ + + +
+lease6-update reference +lease6-update - The lease6-update command can be used to update existing leases. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease6-update", + "arguments": { + "ip-address": "2001:db8::1", + "duid": "88:88:88:88:88:88:88:88", + "iaid": 7654321, + "hostname": "newhostname.example.org", + "subnet-id": 66, + "force-create": false + } +} + + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+lease6-wipe reference +lease6-wipe - lease6-wipe is designed to remove all leases associated with a given subnet. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (lease_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "lease6-wipe", + "arguments": { + "subnet-id": 66 + } +} +Note: not all backends support this command. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+leases-reclaim reference +leases-reclaim - The leases-reclaim command instructs the server to reclaim all expired leases immediately. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "leases-reclaim", + "arguments": { + "remove": true + } +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+libreload reference +libreload - The libreload command will first unload and then load all currently loaded hook libraries. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "libreload", + "arguments": { } +} +The server will respond with a result of 0 indicating success, or 1 indicating a failure. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+list-commands reference +list-commands - The list-commands command retrieves a list of all commands supported by the server. + +Supported by: kea-dhcp4, kea-dhcp6, kea-ctrl-agent + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "list-commands", + "arguments": { } +} +The server will respond with a list of all supported commands. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network4-add reference +network4-add - The network4-add command is used to add a new shared network. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-add", + "arguments": { + "shared-networks": [ { + "name": "floor13", + "subnet4": [ + { + "id": 100, + "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ], + "subnet": "192.0.2.0/24", + "option-data": [ + { + "name": "routers", + "data": "192.0.2.1" + } + ] + }, + { + "id": 101, + "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ], + "subnet": "192.0.3.0/24", + "option-data": [ + { + "name": "routers", + "data": "192.0.3.1" + } + ] + } ] + } ] + } +} + + +Response syntax: + { + "arguments": { + "shared-networks": [ { "name": "floor13" } ] + }, + "result": 0, + "text": "A new IPv4 shared network 'floor13' added" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network4-del reference +network4-del - The network4-del command is used to delete existing shared networks. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-del", + "arguments": { + "name": "floor13" + } +} + + +Response syntax: + { + "arguments": { + "shared-networks": [ + { + "name": "floor13" + } + ] + }, + "result": 0, + "text": "IPv4 shared network 'floor13' deleted" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network4-get reference +network4-get - The network4-get command is used to retrieve detailed information about shared networks, including subnets currently being part of a given network. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-get", + "arguments": { + "name": "floor13" + } +} + + +Response syntax: + { + "result": 0, + "text": "Info about IPv4 shared network 'floor13' returned", + "arguments": { + "shared-networks": [ + { + "match-client-id": true, + "name": "floor13", + "option-data": [ ], + "rebind-timer": 90, + "relay": { + "ip-address": "0.0.0.0" + }, + "renew-timer": 60, + "reservation-mode": "all", + "subnet4": [ + { + "subnet": "192.0.2.0/24", + "id": 5, + // many other subnet specific details here + }, + { + "id": 6, + "subnet": "192.0.3.0/31", + // many other subnet specific details here + } + ], + "valid-lifetime": 120 + } + ] + } +} +Note that the actual response contains many additional fields that are omitted here for clarity. + +
+ + + +
+network4-list reference +network4-list - The network4-list command is used to retrieve full list of currently configured shared networks. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-list" +} + + +Response syntax: + { + "arguments": { + "shared-networks": [ + { "name": "floor1" }, + { "name": "office" } + ] + }, + "result": 0, + "text": "2 IPv4 network(s) found" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network4-subnet-add reference +network4-subnet-add - The network4-subnet-add command is used to add existing subnets to existing shared networks. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-subnet-add", + "arguments": { + "name": "floor13", + "id": 5 + } +} + + +Response syntax: + { + "result": 0, + "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network4-subnet-del reference +network4-subnet-del - The network4-subnet-del command is used to remove a subnet that is part of an existing shared network and demote it to a plain, stand-alone subnet. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-subnet-del", + "arguments": { + "name": "floor13", + "id": 5 + } + } + + +Response syntax: + { + "result": 0, + "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network6-add reference +network6-add - The network6-add command is used to add a new shared network. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-add", + "arguments": { + "shared-networks": [ { + "name": "floor13", + "subnet4": [ + { + "id": 100, + "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ], + "subnet": "192.0.2.0/24", + "option-data": [ + { + "name": "routers", + "data": "192.0.2.1" + } + ] + }, + { + "id": 101, + "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ], + "subnet": "192.0.3.0/24", + "option-data": [ + { + "name": "routers", + "data": "192.0.3.1" + } + ] + } ] + } ] + } +} +The network6-add uses the same syntax for both the query and the response. However, there are some parameters that are IPv4-only (e.g. match-client-id) and some are IPv6-only (e.g. interface-id). + +Response syntax: + { + "arguments": { + "shared-networks": [ { "name": "floor13" } ] + }, + "result": 0, + "text": "A new IPv4 shared network 'floor13' added" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network6-del reference +network6-del - The network6-del command is used to delete existing shared networks. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-del", + "arguments": { + "name": "floor13" + } +} +The network6-del command uses exactly the same syntax for + both the command and the response. + +Response syntax: + { + "command": "network4-del", + "arguments": { + "name": "floor13", + "subnets-action": "delete" + } +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network6-get reference +network6-get - The network6-get command is used to retrieve detailed information about shared networks, including subnets currently being part of a given network. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-get", + "arguments": { + "name": "floor13" + } +} + + +Response syntax: + { + "result": 0, + "text": "Info about IPv4 shared network 'floor13' returned", + "arguments": { + "shared-networks": [ + { + "match-client-id": true, + "name": "floor13", + "option-data": [ ], + "rebind-timer": 90, + "relay": { + "ip-address": "0.0.0.0" + }, + "renew-timer": 60, + "reservation-mode": "all", + "subnet4": [ + { + "subnet": "192.0.2.0/24", + "id": 5, + // many other subnet specific details here + }, + { + "id": 6, + "subnet": "192.0.3.0/31", + // many other subnet specific details here + } + ], + "valid-lifetime": 120 + } + ] + } +} +Note that the actual response contains many additional fields that are omitted here for clarity. + +
+ + + +
+network6-list reference +network6-list - The network6-list command is used to retrieve full list of currently configured shared networks. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-list" +} +network6-list follows exactly the same syntax for both the query and the response. + +Response syntax: + { + "arguments": { + "shared-networks": [ + { "name": "floor1" }, + { "name": "office" } + ] + }, + "result": 0, + "text": "2 IPv4 network(s) found" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network6-subnet-add reference +network6-subnet-add - The network6-subnet-add command is used to add existing subnets to existing shared networks. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-subnet-add", + "arguments": { + "name": "floor13", + "id": 5 + } +} +The network6-subnet-add command uses exactly the same syntax for both the command and the response. + +Response syntax: + { + "result": 0, + "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+network6-subnet-del reference +network6-subnet-del - The network6-subnet-del command is used to remove a subnet that is part of existing shared network and demote it to a plain, stand-alone subnet. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "network4-subnet-del", + "arguments": { + "name": "floor13", + "id": 5 + } + } +The network6-subnet-del command uses exactly the same syntax for both the command and the response. + +Response syntax: + { + "result": 0, + "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'" +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+reservation-add reference +reservation-add - adds a new host reservation. The reservation may include IPv4 address, + IPv6 addresses, IPv6 prefixes, various identifiers, a class + the client will be assigned to, DHCPv4 and DHCPv6 options and + more. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.2.0 (host_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "reservation-add", + "arguments": { + "reservation": { + "boot-file-name": <string>, + "comment": <string> + "client-id": <string>, + "circuit-id": <string>, + "duid": <string>, + "flex-id": <string>, + "ip-address": <string (IPv4 address)>, + "ip-addresses": [ <comma separated strings> ], + "hw-address": <string>, + "hostname": <string>, + "next-server": <string (IPv4 address)>, + "option-data-list": [ <comma separated structures defining options> ], + "prefixes": [ <comma separated IPv6 prefixes> ], + "reservation-client-classes": [ <comma separated strings> ], + "server-hostname": <string>, + "subnet-id": <integer>, + "user-context": <any valid JSON>, + } + } +} +Note the ip-address, client-id, next-server, server-hostname and +boot-file-name are IPv4 specific. duid, ip-addresses and prefixes are +IPv6 specific. + +Response syntax: + +{ + "result": <integer>, + "text": <string> +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+reservation-del reference +reservation-del - Deletes an existing host reservation. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.2.0 (host_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "reservation-del", + "arguments": { + "subnet-id": <integer>, + "ip-address": <string>, + "identifier-type": <one of "hw-address", "duid", "circuit-id", "client-id" and "flex-id">, + "identifier": <string> + } +} +The host reservation can be identified by either (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier). + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+reservation-get reference +reservation-get - Attempts to retrieve an existing host reservation + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.2.0 (host_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "reservation-get", + "arguments": { + "subnet-id": <integer>, + "identifier-type": <string with one value out of: hw-address|duid|circuit-id|client-id|flex-id>, + "identifier": <string>; + } +} +The host reservation can be identified by either (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier). + +Response syntax: + { + "result": <integer>, + "text": <string>, + "arguments": { + "boot-file-name": <string>, + "comment": <string> + "client-id": <string>, + "circuit-id": <string>, + "duid": <string>, + "flex-id": <string>, + "ip-address": <string (IPv4 address)>, + "ip-addresses": [ <comma separated strings> ], + "hw-address": <string>, + "hostname": <string>, + "next-server": <string (IPv4 address)>, + "option-data-list": [ <comma separated structures defining options> ], + "prefixes": [ <comma separated IPv6 prefixes> ], + "reservation-client-classes": [ <comma separated strings> ], + "server-hostname": <string>, + "subnet-id": <integer>, + "user-context": <any valid JSON>, + } +} +Arguments object appear only if a host is found. Many fields in the arguments +object appear only if specific field is set. + +
+ + + +
+shutdown reference +shutdown - The shutdown command instructs the server to initiate its shutdown procedure. + +Supported by: kea-dhcp4, kea-dhcp6, kea-ctrl-agent + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "shutdown" +} +The server will respond with a confirmation that the shutdown + procedure has been initiated. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+stat-lease4-get reference +stat-lease4-get - The stat-lease4-get command fetches lease statistics for a range + of known IPv4 subnets. + +Supported by: kea-dhcp4 + +Availability: 1.4.0 (stat_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "stat-lease4-get" +} + + +Response syntax: + { + "result": 0, + "text": "stat-lease4-get: 2 rows found", + "arguments": { + "result-set": { + "columns": [ "subnet-id", + "total-addresses", + "assigned-addresses", + "declined-addresses" ] + "rows": [ + [ 10, 256, 111, 0 ], + [ 20, 4098, 2034, 4 ] + ], + "timestamp": "2018-05-04 15:03:37.000000" + } + } + } +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+stat-lease6-get reference +stat-lease6-get - The stat-lease6-get command fetches lease statistics for a range + of known IPv6 subnets. + +Supported by: kea-dhcp6 + +Availability: 1.4.0 (stat_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "stat-lease6-get", + "arguments": { + "subnet-id" : 10 + } +} + + +Response syntax: + { + "result": 0, + "text": "stat-lease6-get: 2 rows found", + "arguments": { + "result-set": { + "columns": [ "subnet-id", "total-nas", "assigned-nas", "declined-nas", "total-pds", "assigned-pds" ] + "rows": [ + [ 10, 4096, 2400, 3, 0, 0], + [ 20, 0, 0, 0, 1048, 233 ] + [ 30, 256, 60, 0, 1048, 15 ] + ], + "timestamp": "2018-05-04 15:03:37.000000" + } + } + } +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+statistic-get reference +statistic-get - The statistic-get command retrieves a single statistic. It takes a single string parameter called name that specifies the statistic name. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "statistic-get", + "arguments": { + "name": "pkt4-received" + } +} +The server will respond with details of the requested statistic, with a result set to 0 indicating success and the specified statistic as the value of the "arguments" parameter. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+statistic-get-all reference +statistic-get-all - The statistic-get-all command retrieves all statistics recorded. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "statistic-get-all", + "arguments": { } +} +The server will respond with details of all recorded statistics, with result set to 0 indicating that it iterated over all statistics (even when the total number of statistics is zero). + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+statistic-remove reference +statistic-remove - The statistic-remove command attempts to delete a single statistic. It takes a single string parameter called name that specifies the statistic name. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "statistic-remove", + "arguments": { + "name": "pkt4-received" + } +} +If the specific statistic is found and its removal was successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered (e.g. requested statistic was not found), the server will return a status code of 1 (error) and the text field will contain the error description. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+statistic-remove-all reference +statistic-remove-all - The statistic-remove-all command attempts to delete all statistics. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "statistic-remove-all", + "arguments": { } +} +If the removal of all statistics was successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered, the server will return a status code of 1 (error) and the text field will contain the error description. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+statistic-reset reference +statistic-reset - The statistic-reset command sets the specified statistic to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time duration and "" for string type. It takes a single string parameter called name that specifies the statistic name. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "statistic-reset", + "arguments": { + "name": "pkt4-received" + } +} +If the specific statistic is found and reset was successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered (e.g. requested statistic was not found), the server will return a status code of 1 (error) and the text field will contain the error description. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+statistic-reset-all reference +statistic-reset-all - The statistic-reset command sets all statistics to their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time duration and "" for string type. + +Supported by: kea-dhcp4, kea-dhcp6 + +Availability: 1.0.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "statistic-reset-all", + "arguments": { } +} +If the operation is successful, the server will respond with a status of 0, indicating success and an empty parameters field. If an error is encountered, the server will return a status code of 1 (error) and the text field will contain the error description. + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+subnet4-add reference +subnet4-add - This command is used to create and add a new subnet to the existing server configuration. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet4-add", + "arguments": { + "subnets": [ { + "id": 123, + "subnet": "10.20.30.0/24", + ... + } ] + } +} + + +Response syntax: + { + "result": 0, + "text": "IPv4 subnet added", + "arguments": { + "subnets": [ + { + "id": 123, + "subnet": "10.20.30.0/24" + } + ] + } +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+subnet4-del reference +subnet4-del - This command is used to remove a subnet from the server's configuration. This command has no effect on other configured subnets but removing a subnet has certain implications which the server's administrator should be aware of. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet4-del", + "arguments": { + "id": 123 + } +} + + +Response syntax: + { + "result": 0, + "text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted", + "arguments": { + "subnets": [ + { + "id": 123, + "subnet": "192.0.2.0/24" + } + ] + } +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+subnet4-get reference +subnet4-get - This command is used to retrieve detailed information about the specified subnet. This command usually follows the subnet4-list, which is used to discover available subnets with their respective subnet identifiers and prefixes. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet4-get", + "arguments": { + "id": 10 + } +} + + +Response syntax: + { + "result": 0, + "text": "Info about IPv4 subnet 10.0.0.0/8 (id 10) returned", + "arguments": { + "subnets": [ + { + "subnet": "10.0.0.0/8", + "id": 1, + "option-data": [ + .... + ] + ... + } + ] + } +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+subnet4-list reference +subnet4-list - This command is used to list all currently configured subnets. The subnets are returned in a brief form, i.e. a subnet identifier and subnet prefix is included for each subnet. + +Supported by: kea-dhcp4 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet4-list" +} + + +Response syntax: + { + "result": 0, + "text": "2 IPv4 subnets found", + "arguments": { + "subnets": [ + { + "id": 10, + "subnet": "10.0.0.0/8" + }, + { + "id": 100, + "subnet": "192.0.2.0/24" + } + ] +} +If no IPv4 subnets are found, an error code is returned along with the error description. + +
+ + + +
+subnet6-add reference +subnet6-add - This command is used to create and add new subnet to the existing server configuration. This operation has no impact on other subnets. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet6-add", + "arguments": { + "subnet6": [ { + "id": 234, + "subnet": "2001:db8:1::/64", + ... + } ] + } +} + + +Response syntax: + { + "result": 0, + "text": "IPv6 subnet added", + "arguments": { + "subnet6": [ + { + "id": 234, + "subnet": "2001:db8:1::/64" + } + ] + } +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+subnet6-del reference +subnet6-del - This command is used to remove a subnet from the server's configuration. This command has no effect on other configured subnets but removing a subnet has certain implications which the server's administrator should be aware of. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet6-del", + "arguments": { + "id": 234 + } +} + + +Response syntax: + { + "result": 0, + "text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted", + "subnets": [ + { + "id": 234, + "subnet": "2001:db8:1::/64" + } + ] +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+subnet6-get reference +subnet6-get - This command is used to retrieve detailed information about the specified subnet. This command usually follows the subnet6-list, which is used to discover available subnets with their respective subnet identifiers and prefixes. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet6-get", + "arguments": { + "id": 11 + } +} + + +Response syntax: + { + "result": 0, + "text": "Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned", + "arguments": { + "subnets": [ + { + "subnet": "2001:db8:1::/64", + "id": 1, + "option-data": [ + ... + ] + .... + } + ] + } +} +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + +
+subnet6-list reference +subnet6-list - This command is used to list all currently configured subnets. The subnets are returned in a brief form, i.e. a subnet identifier and subnet prefix is included for each subnet. + +Supported by: kea-dhcp6 + +Availability: 1.3.0 (subnet_cmds hook) + +Description and examples: See + +Command syntax: + { + "command": "subnet6-list" +} + + +Response syntax: + { + "result": 0, + "text": "2 IPv6 subnets found", + "arguments": { + "subnets": [ + { + "id": 11, + "subnet": "2001:db8:1::/64" + }, + { + "id": 233, + "subnet": "3000::/16" + } + ] +} +If no IPv6 subnets are found, an error code is returned along with the error description. + +
+ + + +
+version-get reference +version-get - The version-get command returns extended information about + Kea version. The returned string is the same as if Kea would + be run with -V command line option. + +Supported by: kea-dhcp4, kea-dhcp6, kea-ctrl-agent + +Availability: 1.2.0 (built-in) + +Description and examples: See + +Command syntax: + { + "command": "version-get" +} + + +Response syntax: + { + "result": <integer>, + "text": <string> +} + +Result is an integer representation of the status. Currently supported statuses are: + + 0 - success + 1 - error + 2 - unsupported + 3 - empty (command was completed successfully, but no data was affected or returned) + + + +
+ + + diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 93de5ce2dfeae3e1eb4311b251a9b3f29ccc4853..7407c5d31334ffa262fe093670dd606fea9dbbdc 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -601,11 +601,10 @@ $ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get"
version-get - The version-get command returns on the control - channel what the command line -v argument - displays with in arguments the extended version, i.e., what - the command line -V argument displays. This command - does not take any parameters. + The version-get command returns an + extended information about Kea version. It is the same + information as Kea caled with -V command + line argument. This command does not take any parameters. { diff --git a/doc/guide/hooks-ha.xml b/doc/guide/hooks-ha.xml index a7af55c78a4c9942221cedee5f1cb1d59efe14dc..164483a63487a332c7475b37581b1ca718a5318c 100644 --- a/doc/guide/hooks-ha.xml +++ b/doc/guide/hooks-ha.xml @@ -139,7 +139,8 @@
Server States - The DHCP server operating within an HA setup runs a state machine + The DHCP server operating + within an HA setup runs a state machine and the state of the server can be retrieved by its peers using the ha-heartbeat command sent over the RESTful API. If the partner server doesn't respond to the ha-heartbeat @@ -1292,7 +1293,7 @@ HA hook library which are available for the administrator. -
+
ha-sync command The ha-sync is issued to instruct the server to synchronize its local lease database with the @@ -1346,7 +1347,7 @@
-
+
ha-scopes command This command allows for modifying the HA scopes that the server is serving. Consult @@ -1357,7 +1358,7 @@ { "command": "ha-scopes", - "service": [ "dhcp4 "], + "service": [ "dhcp4" ], "arguments": { "scopes": [ "HA_server1", "HA_server2" ] } @@ -1381,7 +1382,7 @@
-
+
ha-continue command This command is used to resume the operation of the paused HA state machine as described in the . diff --git a/doc/guide/hooks-host-cache.xml b/doc/guide/hooks-host-cache.xml index eb6ef01740efebd8ddca98c347ab69e874b073ea..a71905db0b768cc28c3334c6545289e7a1c9d0fc 100644 --- a/doc/guide/hooks-host-cache.xml +++ b/doc/guide/hooks-host-cache.xml @@ -60,7 +60,7 @@ sections describe the commands available. -
+
cache-flush command This command allows removal of specified number of cached host entries. It takes one parameter which defines the number of @@ -76,7 +76,7 @@ in FIFO order, so always the oldest entries are removed.
-
+
cache-clear command This command allows removal of all cached host entries. An example usage looks as follows: @@ -89,7 +89,7 @@ certain number of cached hosts, please use cache-flush instead.
-
+
cache-write command In general case the cache content is considered a run-time state and the server can be shutdown or restarted as usual. The @@ -121,7 +121,7 @@ any other tool that is able to understand JSON format.
-
+
cache-load command See previous section for a discussion regarding use cases where it may be useful to write and load contents of the host @@ -142,7 +142,7 @@ any other tool that is able to understand JSON format.
-
+
cache-get command This command is similar to cache-write, but instead of writing the cache contents to disk, it returns the contents to @@ -159,7 +159,7 @@ may be large.
-
+
cache-insert command This command may be used to manually insert a host into the cache. There are very few use cases when this command could be @@ -220,7 +220,7 @@ may be large.
-
+
cache-remove command Sometimes it is useful to remove a single entry from the host cache. A good use case is a situation where the device is up, diff --git a/doc/guide/hooks-lease-cmds.xml b/doc/guide/hooks-lease-cmds.xml index 557ada805ce3972bff6b6411149040a82330688e..fefa0249155079146f72ffea7a3ffd4259686fda 100644 --- a/doc/guide/hooks-lease-cmds.xml +++ b/doc/guide/hooks-lease-cmds.xml @@ -124,9 +124,9 @@ -
+
lease4-add, lease6-add commands - + lease4-add and lease6-add commands allow for the creation of a new lease. Typically Kea creates a lease on its own, when it first sees a new device. However, @@ -284,9 +284,10 @@ The commands can take a number of additional optional parameters: -
+
lease4-get, lease6-get commands - lease4-get or lease6-get + + lease4-get or lease6-get can be used to query the lease database and retrieve existing leases. There are two types of parameters the lease4-get supports: (address) or (subnet-id, @@ -401,9 +402,9 @@ An example result returned when the host was found:
-
+
lease4-get-all, lease6-get-all commands - lease4-get-all and + lease4-get-all and lease6-get-all are used to retrieve all IPv4 or IPv6 leases or all leases for the specified set of subnets. All leases are returned when there are no arguments @@ -610,9 +611,10 @@ An example result returned when the host was found:
-
+
lease4-del, lease6-del commands - leaseX-del can be used to delete a lease from + + leaseX-del can be used to delete a lease from the lease database. There are two types of parameters this command supports, similar to leaseX-get commands: (address) for both v4 and v6, (subnet-id, identifier-type, identifier) for v4 and (subnet-id, @@ -658,9 +660,9 @@ An example IPv4 lease deletion by "hw-address" looks as follows:
-
+
lease4-update, lease6-update commands - lease4-update and + lease4-update and lease6-update commands can be used to update existing leases. Since all lease database backends are indexed by IP addresses, it is not possible to update an address. All other fields @@ -713,9 +715,9 @@ An example IPv4 lease deletion by "hw-address" looks as follows:
-
+
lease4-wipe, lease6-wipe commands - lease4-wipe and + lease4-wipe and lease6-wipe are designed to remove all leases associated with a given subnet. This administrative task is expected to be used when existing subnet is being diff --git a/doc/guide/hooks-stat-cmds.xml b/doc/guide/hooks-stat-cmds.xml index 549f6f1b98d285a306e2df79cf2616a99f8ff714..d4604c47371eb86365bb305b05c2111f817f5a6f 100644 --- a/doc/guide/hooks-stat-cmds.xml +++ b/doc/guide/hooks-stat-cmds.xml @@ -74,9 +74,9 @@ will not retrieve statistics for it. -
+
stat-lease4-get, stat-lease6-get commands - + The stat-lease4-get and stat-lease6-get commands fetch lease statistics for a range of known subnets. The range of subnets is determined through the use of optional command diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 3d48fd9ecccc46a5ba0fadc22f870a6e19dccfb5..7f739930d8fc1252cfcd4a2edb6f64ea1a517044 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -1432,7 +1432,7 @@ Requirements document.
-
+
reservation-add command reservation-add allows for the insertion of a new host. It @@ -1524,7 +1524,7 @@ Here is an example of complex IPv6 reservation:
-
+
reservation-get command reservation-get can be used to query the host database and retrieve existing reservations. There are two types of @@ -1560,7 +1560,7 @@ An example query by (subnet-id, identifier-type, identifier) looks as follows: { "command": "reservation-get", - "arguments": + "arguments": { "subnet-id": 4, "identifier-type": "hw-address", "identifier": "01:02:03:04:05:06" @@ -1602,7 +1602,7 @@ An example result returned when the query was malformed:
-
+
reservation-del command reservation-del can be used to delete a reservation from the host database. There are two types of parameters @@ -1766,7 +1766,7 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows -
+
subnet4-list command This command is used to list all currently configured subnets. The @@ -1810,7 +1810,7 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows
-
+
subnet6-list command This command is used to list all currently configured subnets. The @@ -1854,7 +1854,7 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows
-
+
subnet4-get command This command is used to retrieve detailed information about the specified subnet. This command usually follows the @@ -1906,7 +1906,7 @@ or
-
+
subnet6-get command This command is used to retrieve detailed information about the specified subnet. This command usually follows the @@ -1955,7 +1955,7 @@ If the subnet exists the response will be similar to this:
-
+
subnet4-add This command is used to create and add new subnet to the existing @@ -2004,7 +2004,7 @@ If the subnet exists the response will be similar to this:
-
+
subnet6-add This command is used to create and add new subnet to the existing @@ -2083,7 +2083,7 @@ If the subnet exists the response will be similar to this:
-
+
subnet4-del command This command is used to remove a subnet from the server's configuration. @@ -2143,7 +2143,7 @@ If the subnet exists the response will be similar to this:
-
+
subnet6-del command This command is used to remove a subnet from the server's configuration. @@ -2201,9 +2201,9 @@ If the subnet exists the response will be similar to this:
-
+
network4-list, network6-list commands - + These commands are used to retrieve full list of currently configured shared networks. The list contains only very basic information about each shared network. If more details are needed, please use @@ -2232,9 +2232,9 @@ both the query and the response.
-
+
network4-get, network6-get commands - + These commands are used to retrieve detailed information about shared networks, including subnets currently being part of a given network. Both commands take one @@ -2291,9 +2291,9 @@ shared networks information.
-
+
network4-add, network6-add commands - + These commands are used to add a new shared network. New network has to have unique name. This command requires one parameter shared-networks, which is a list and @@ -2366,9 +2366,9 @@ the response. However, there are some parameters that are IPv4-only applies to subnets within the network.
-
+
network4-del, network6-del commands - + These commands are used to delete existing shared networks. Both commands take exactly one parameter 'name' that specifies the name of the network to be removed. An example invocation @@ -2424,9 +2424,9 @@ both the command and the response. subnet6-del commands.
-
+
network4-subnet-add, network6-subnet-add commands - + These commands are used to add existing subnets to existing shared networks. There are several ways to add new shared network. System administrator can add the whole shared network at once, either by @@ -2483,9 +2483,9 @@ both the command and the response. filled with default values, rather than inherited from global scope or from the shared network.
-
+
network4-subnet-del, network6-subnet-del commands - + These commands are used to remove a subnet that is part of existing shared network and demote it to a plain, stand-alone subnet. If you want to remove a subnet completely, use subnet4-del or @@ -2568,4 +2568,4 @@ both the command and the response. of server id which is DHCPv6 only.
- + diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index f0e42a47ed2fa698e0705a8a0699a98ce7627396..2424beaa9ac56307ed96586a3a923a1214d93345 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -92,9 +92,12 @@ - + - + + + Acknowledgments Kea is an open source project designed, developed, and maintained by Internet Systems @@ -118,7 +121,7 @@ within the BIND 10 framework. We thank the founding sponsors of the BIND10 project: Afilias, IIS.SE, - Nominet, + Nominet, SIDN, JPRS, CIRA; and additional sponsors @@ -133,8 +136,7 @@ Technical Center of Internet . - - +