From: Michal Nowikowski Date: Thu, 6 Jun 2019 16:25:46 +0000 (+0200) Subject: initial conversion of kea guide from docbook to rst/sphinx X-Git-Tag: Kea-1.6.1~10^2~103 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=60b0e6e7bfe5523ad3d8acfb4b4739984b41a2e2;p=thirdparty%2Fkea.git initial conversion of kea guide from docbook to rst/sphinx --- diff --git a/doc/guide/.gitignore b/doc/guide/.gitignore index 388591cece..44b013d498 100644 --- a/doc/guide/.gitignore +++ b/doc/guide/.gitignore @@ -4,3 +4,4 @@ /kea-messages.xml /kea-guide.pdf /kea-messages.pdf +/_build \ No newline at end of file diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index 4363fff2b6..755fbd24d2 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -1,78 +1,47 @@ -# generated documentation -HTMLDOCS = kea-guide.html kea-messages.html -DOCS = kea-guide.txt -dist_doc_DATA = $(DOCS) -dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png - -DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml -DOCBOOK += config-backend.xml keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml -DOCBOOK += logging.xml ddns.xml hooks.xml hooks-class-cmds.xml hooks-cb-cmds.xml -DOCBOOK += hooks-ha.xml hooks-host-cache.xml hooks-lease-cmds.xml hooks-radius.xml -DOCBOOK += hooks-stat-cmds.xml lfc.xml stats.xml ctrl-channel.xml classify.xml shell.xml -DOCBOOK += agent.xml netconf.xml api.xml congestion-handling.xml hammer.xml - -EXTRA_DIST = $(DOCBOOK) kea-docbook.xsl - -DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml - -kea-messages.xml: - $(top_builddir)/tools/system_messages -o $@ \ - `find $(top_srcdir) -name "*.mes" -print` - -# This is not a "man" manual, but reuse this for now for docbook. -if GENERATE_DOCS - -kea-guide.html: $(DOCBOOK) - @XSLTPROC@ --novalid --xinclude @NONET@ \ - --path $(top_builddir)/doc \ - -o $@ \ - --stringparam section.autolabel 1 \ - --stringparam section.label.includes.component.label 1 \ - --stringparam html.stylesheet kea-guide.css \ - $(srcdir)/kea-docbook.xsl \ - $(srcdir)/kea-guide.xml - -kea-guide.txt: kea-guide.html - @ELINKS@ -dump -no-numbering -no-references kea-guide.html > $@ - -kea-messages.html: kea-messages.xml - @XSLTPROC@ --novalid --xinclude @NONET@ \ - --path $(top_builddir)/doc \ - -o $@ \ - --stringparam generate.toc "book toc" \ - --stringparam html.stylesheet kea-guide.css \ - $(srcdir)/kea-docbook.xsl \ - kea-messages.xml - -else - -$(HTMLDOCS) $(DOCS): - @echo Doc generation disabled. Creating dummy $@. Configure with --enable-generate-docs to enable it. - @echo Doc generation disabled. Remove this file, configure with --enable-generate-docs, and rebuild Kea > $@ - -endif - -if HAVE_DBLATEX - -CLEANFILES = kea-guide.pdf kea-messages.pdf - -DBLATEX_FLAGS = --xslt-opts=--path --xslt-opts=$(abs_top_builddir)/doc \ - -P doc.collab.show=0 -P latex.output.revhistory=0 \ - -P term.breakline=1 -P filename.as.url=0 \ - -P imagedata.default.scale="maxwidth=50px,maxheight=35px" - -pdf: kea-guide.pdf kea-messages.pdf - -kea-guide.pdf: $(DOCBOOK) - @DBLATEX@ $(DBLATEX_FLAGS) kea-guide.xml - -kea-messages.pdf: kea-messages.xml - @DBLATEX@ $(DBLATEX_FLAGS) kea-messages.xml - -else - -pdf kea-guide.pdf kea-messages.pdf: - @echo Install dblatex tool and rerun ./configure to be able to generate documentation in PDF format. - -endif +rst_sources=admin.rst +rst_sources+=agent.rst +rst_sources+=api.rst +rst_sources+=classify.rst +rst_sources+=config-backend.rst +rst_sources+=config.rst +rst_sources+=congestion-handling.rst +rst_sources+=ctrl-channel.rst +rst_sources+=ddns.rst +rst_sources+=dhcp4-srv.rst +rst_sources+=dhcp6-srv.rst +rst_sources+=hammer.rst +rst_sources+=hooks-cb-cmds.rst +rst_sources+=hooks-class-cmds.rst +rst_sources+=hooks-ha.rst +rst_sources+=hooks-host-cache.rst +rst_sources+=hooks-lease-cmds.rst +rst_sources+=hooks-radius.rst +rst_sources+=hooks.rst +rst_sources+=hooks-stat-cmds.rst +rst_sources+=install.rst +rst_sources+=intro.rst +rst_sources+=keactrl.rst +rst_sources+=kea-guide.rst +rst_sources+=lease-expiration.rst +rst_sources+=lfc.rst +rst_sources+=logging.rst +rst_sources+=netconf.rst +rst_sources+=quickstart.rst +rst_sources+=shell.rst +rst_sources+=stats.rst + + +sphinxbuild = sphinx-build +sphinxopts = -E + +kea-guide.pdf: $(rst_sources) + @$(sphinxbuild) -M latexpdf $(srcdir) $(builddir)/_build $(sphinxopts) + +kea-guide.html: $(rst_sources) + @$(sphinxbuild) -M singlehtml $(srcdir) $(builddir)/_build $(sphinxopts) + + +EXTRA_DIST = $(rst_sources) + +# TODO: here should ba added some stuff for DIST, etc to be consumed by automake/autoconf diff --git a/doc/guide/kea-logo-100x70.png b/doc/guide/_static/kea-logo-100x70.png similarity index 100% rename from doc/guide/kea-logo-100x70.png rename to doc/guide/_static/kea-logo-100x70.png diff --git a/doc/guide/admin.rst b/doc/guide/admin.rst new file mode 100644 index 0000000000..ef085128aa --- /dev/null +++ b/doc/guide/admin.rst @@ -0,0 +1,550 @@ +.. _admin: + +*************************** +Kea Database Administration +*************************** + +.. _kea-database-version: + +Databases and Database Version Numbers +====================================== + +Kea may be configured to use a database as a storage for leases, a +source of servers' configurations and host reservations (i.e. static +assignments of addresses, prefixes, options etc.). Subsequent Kea +releases introduce changes to the database schemas to faciliate new +features and correct discovered issues with the existing schemas. + +A given version of Kea expects a particular structure in the backend and +checks for this by examining the version of database it is using. +Separate version numbers are maintained for backends, independent of the +version of Kea itself. It is possible that the backend version will stay +the same through several Kea revisions; similarly, it is possible that +the version of the backend may go up several revisions during a Kea +upgrade. Versions for each backend are independent, so an increment in +the MySQL backend version does not imply an increment in that of +PostgreSQL. + +Backend versions are specified in a major.minor format. The minor number +is increased when there are backward-compatible changes introduced; for +example, the addition of a new index. It is desirable but not mandatory +to apply such a change; you can run an older backend version if you want +to. (Although, in the example given, running without the new index may +be at the expense of a performance penalty.) On the other hand, the +major number is increased when an incompatible change is introduced: for +example, an extra column is added to a table. If you try to run Kea on a +backend that is too old (as signified by a mismatched backend major +version number), Kea will refuse to run; administrative action will be +required to upgrade the backend. + +.. _kea-admin: + +The kea-admin Tool +================== + +To manage the databases, Kea provides the ``kea-admin`` tool. It is able +to initialize a new backend, check its version number, perform a backend +upgrade, and dump lease data to a text file. + +``kea-admin`` takes two mandatory parameters: ``command`` and +``backend``. Additional, non-mandatory options may be specified. The +currently supported commands are: + +- ``lease-init`` — Initializes a new database schema. This is useful + during a new Kea installation. The database is initialized to the + latest version supported by the version of the software being + installed. + +- ``lease-version`` — Reports the database backend version number. This + is not necessarily equal to the Kea version number as each backend + has its own versioning scheme. + +- ``lease-upgrade`` — Conducts a database schema upgrade. This is + useful when upgrading Kea. + +- ``lease-dump`` — Dumps the contents of the lease database (for MySQL, + PostgreSQL, or CQL backends) to a CSV (comma-separated values) text + file. The first line of the file contains the column names. This is + meant to be used as a diagnostic tool, so it provides a portable, + human-readable form of the lease data. + +``backend`` specifies the type of backend database. The currently +supported types are: + +- ``memfile`` — Lease information is stored on disk in a text file. + +- ``mysql`` — Information is stored in a MySQL relational database. + +- ``pgsql`` — Information is stored in a PostgreSQL relational + database. + +- ``cql`` — Information is stored in an Apache Cassandra database. + +Additional parameters may be needed, depending on your setup and +specific operation: username, password, and database name or the +directory where specific files are located. See the appropriate manual +page for details (``man 8 kea-admin``). + +.. _supported-databases: + +Supported Backends +================== + +The following table presents the capabilities of available backends. +Please refer to the specific sections dedicated to each backend to +better understand their capabilities and limitations. Choosing the right +backend may be essential for the success of your deployment. + +.. table:: List of available backends + + +-------------+-------------+-------------+-------------+-------------+ + | Feature | Memfile | MySQL | PostgreSQL | CQL | + | | | | | (Cassandra) | + +=============+=============+=============+=============+=============+ + | Status | Stable | Stable | Stable | Experimenta | + | | | | | l | + +-------------+-------------+-------------+-------------+-------------+ + | Data format | CSV file | SQL RMDB | SQL RMDB | NoSQL | + | | | | | database | + | | | | | (Cassandra) | + +-------------+-------------+-------------+-------------+-------------+ + | Leases | yes | yes | yes | yes | + +-------------+-------------+-------------+-------------+-------------+ + | Host | no | yes | yes | yes | + | Reservation | | | | | + | s | | | | | + +-------------+-------------+-------------+-------------+-------------+ + | Options | no | yes | yes | yes | + | defined on | | | | | + | per host | | | | | + | basis | | | | | + +-------------+-------------+-------------+-------------+-------------+ + | Configurati | no | yes | no | no | + | on | | | | | + | Backend | | | | | + +-------------+-------------+-------------+-------------+-------------+ + +memfile +------- + +The memfile backend is able to store lease information, but is not able +to store host reservation details; these must be stored in the +configuration file. (There are no plans to add a host reservations +storage capability to this backend.) + +No special initialization steps are necessary for the memfile backend. +During the first run, both ``kea-dhcp4`` and ``kea-dhcp6`` will create +an empty lease file if one is not present. Necessary disk-write +permission is required. + +.. _memfile-upgrade: + +Upgrading Memfile Lease Files from an Earlier Version of Kea +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are no special steps required to upgrade memfile lease files from +an earlier version of Kea to a new version of Kea. During startup the +servers will check the schema version of the lease files against their +own. If there is a mismatch, the servers will automatically launch the +LFC process to convert the files to the server's schema version. While +this mechanism is primarily meant to ease the process of upgrading to +newer versions of Kea, it can also be used for downgrading should the +need arise. When upgrading, any values not present in the original lease +files will be assigned appropriate default values. When downgrading, any +data present in the files but not in the server's schema will be +dropped. If you wish to convert the files manually prior to starting the +servers, you may do so by running the LFC process yourself. See +`??? <#kea-lfc>`__ for more information. + +.. _mysql-database: + +MySQL +----- + +MySQL is able to store leases, host reservations, options defined on a +per-host basis and a subset of the server configuration parameters +(serving as a configuration backend). This section can be safely ignored +if you choose to store the data in other backends. + +.. _mysql-database-create: + +First-Time Creation of the MySQL Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are setting the MySQL database for the first time, you need to +create the database area within MySQL and set up the MySQL user ID under +which Kea will access the database. This needs to be done manually; +``kea-admin`` is not able to do this for you. + +To create the database: + +1. Log into MySQL as "root": + + :: + + $ mysql -u root -p + Enter password: + mysql> + +2. Create the MySQL database: + + :: + + mysql> CREATE DATABASE database-name; + + (database-name is the name you have chosen for the database.) + +3. Create the user under which Kea will access the database (and give it + a password), then grant it access to the database tables: + + :: + + mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password'; + mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost'; + + (user-name and password are the user ID and password you are using to + allow Kea's access to the MySQL instance. All apostrophes in the + command lines above are required.) + +4. At this point, you may elect to create the database tables. + (Alternatively, you can exit MySQL and create the tables using the + ``kea-admin`` tool, as explained below.) To do this: + + :: + + mysql> CONNECT database-name; + mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql + + (path-to-kea is the location where you installed Kea.) + +5. Exit MySQL: + + :: + + mysql> quit + Bye + $ + +If you elected not to create the tables in Step 4, you can do so now by +running the ``kea-admin`` tool: + +:: + + $ kea-admin lease-init mysql -u database-user -p database-password -n database-name + +(Do not do this if you did create the tables in Step 4.) ``kea-admin`` +implements rudimentary checks; it will refuse to initialize a database +that contains any existing tables. If you want to start from scratch, +you must remove all data manually. (This process is a manual operation +on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.) + +.. _mysql-upgrade: + +Upgrading a MySQL Database from an Earlier Version of Kea +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes a new Kea version may use a newer database schema, so the +existing database will need to be upgraded. This can be done using the +``kea-admin lease-upgrade`` command. + +To check the current version of the database, use the following command: + +:: + + $ kea-admin lease-version mysql -u database-user -p database-password -n database-name + +(See `Databases and Database Version Numbers <#kea-database-version>`__ +for a discussion about versioning.) If the version does not match the +minimum required for the new version of Kea (as described in the release +notes), the database needs to be upgraded. + +Before upgrading, please make sure that the database is backed up. The +upgrade process does not discard any data, but depending on the nature +of the changes, it may be impossible to subsequently downgrade to an +earlier version. To perform an upgrade, issue the following command: + +:: + + $ kea-admin lease-upgrade mysql -u database-user -p database-password -n database-name + +.. _pgsql-database: + +PostgreSQL +---------- + +PostgreSQL is able to store leases, host reservations, and options +defined on a per-host basis. This step can be safely ignored if you are +using other database backends. + +.. _pgsql-database-create: + +First-Time Creation of the PostgreSQL Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first task is to create both the lease database and the user under +which the servers will access it. A number of steps are required: + +1. Log into PostgreSQL as "root": + + :: + + $ sudo -u postgres psql postgres + Enter password: + postgres=# + +2. Create the database: + + :: + + postgres=# CREATE DATABASE database-name; + CREATE DATABASE + postgres=# + + (database-name is the name you have chosen for the database.) + +3. Create the user under which Kea will access the database (and give it + a password), then grant it access to the database: + + :: + + postgres=# CREATE USER user-name WITH PASSWORD 'password'; + CREATE ROLE + postgres=# GRANT ALL PRIVILEGES ON DATABASE database-name TO user-name; + GRANT + postgres=# + +4. Exit PostgreSQL: + + :: + + postgres=# \q + Bye + $ + +5. At this point you are ready to create the database tables. This can + be done using the ``kea-admin`` tool as explained in the next section + (recommended), or manually. To create the tables manually, enter the + following command. Note that PostgreSQL will prompt you to enter the + new user's password you specified in Step 3. When the command + completes, you will be returned to the shell prompt. You should see + output similar to the following: + + :: + + $ psql -d database-name -U user-name -f path-to-kea/share/kea/scripts/pgsql/dhcpdb_create.pgsql + Password for user user-name: + CREATE TABLE + CREATE INDEX + CREATE INDEX + CREATE TABLE + CREATE INDEX + CREATE TABLE + START TRANSACTION + INSERT 0 1 + INSERT 0 1 + INSERT 0 1 + COMMIT + CREATE TABLE + START TRANSACTION + INSERT 0 1 + COMMIT + $ + + (path-to-kea is the location where you installed Kea.) + + If instead you encounter an error like: + + :: + + psql: FATAL: no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off + + ... you will need to alter the PostgreSQL configuration. Kea uses + password authentication when connecting to the database and must have + the appropriate entries added to PostgreSQL's pg_hba.conf file. This + file is normally located in the primary data directory for your + PostgreSQL server. The precise path may vary depending on your + operating system and version, but the default location for PostgreSQL + 9.3 on Centos 6.5 is: ``/var/lib/pgsql/9.3/data/pg_hba.conf``. + + Assuming Kea is running on the same host as PostgreSQL, adding lines + similar to the following should be sufficient to provide + password-authenticated access to Kea's database: + + :: + + local database-name user-name password + host database-name user-name 127.0.0.1/32 password + host database-name user-name ::1/128 password + + These edits are primarily intended as a starting point, and are not a + definitive reference on PostgreSQL administration or database + security. Please consult your PostgreSQL user manual before making + these changes, as they may expose other databases that you run. It + may be necessary to restart PostgreSQL in order for the changes to + take effect. + +Initialize the PostgreSQL Database Using kea-admin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you elected not to create the tables manually, you can do so now by +running the ``kea-admin`` tool: + +:: + + $ kea-admin lease-init pgsql -u database-user -p database-password -n database-name + +Do not do this if you already created the tables manually. ``kea-admin`` +implements rudimentary checks; it will refuse to initialize a database +that contains any existing tables. If you want to start from scratch, +you must remove all data manually. (This process is a manual operation +on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.) + +.. _pgsql-upgrade: + +Upgrading a PostgreSQL Database from an Earlier Version of Kea +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The PostgreSQL database schema can be upgraded using the same tool and +commands as described in `Upgrading a MySQL Database from an Earlier +Version of Kea <#mysql-upgrade>`__, with the exception that the "pgsql" +database backend type must be used in the commands. + +Use the following command to check the current schema version: + +:: + + $ kea-admin lease-version pgsql -u database-user -p database-password -n database-name + +Use the following command to perform an upgrade: + +:: + + $ kea-admin lease-upgrade pgsql -u database-user -p database-password -n database-name + +.. _cql-database: + +Cassandra +--------- + +Cassandra (sometimes for historical reasons referred to in documentation +and commands as CQL) is the newest backend added to Kea; initial +development was contributed by Deutsche Telekom. The Cassandra backend +is able to store leases, host reservations, and options defined on a +per-host basis. + +Cassandra must be properly set up if you want Kea to store information +in it. This section can be safely ignored if you choose to store the +data in other backends. + +.. _cql-database-create: + +First-Time Creation of the Cassandra Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are setting up the Cassandra database for the first time, you +need to create the keyspace area within it. This needs to be done +manually; ``kea-admin`` cannot do this for you. + +To create the database: + +1. Export CQLSH_HOST environment variable: + + :: + + $ export CQLSH_HOST=localhost + +2. Log into CQL: + + :: + + $ cqlsh + cql> + +3. Create the CQL keyspace: + + :: + + cql> CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1}; + + (keyspace-name is the name you have chosen for the keyspace) + +4. At this point, you may elect to create the database tables. + (Alternatively, you can exit Cassandra and create the tables using + the ``kea-admin`` tool, as explained below.) To do this: + + :: + + cqslh -k keyspace-name -f path-to-kea/share/kea/scripts/cql/dhcpdb_create.cql + + (path-to-kea is the location where you installed Kea) + +If you elected not to create the tables in Step 4, you can do so now by +running the ``kea-admin`` tool: + +:: + + $ kea-admin lease-init cql -n database-name + +(Do not do this if you did create the tables in Step 4.) ``kea-admin`` +implements rudimentary checks; it will refuse to initialize a database +that contains any existing tables. If you want to start from scratch, +you must remove all data manually. (This process is a manual operation +on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.) + +.. _cql-upgrade: + +Upgrading a Cassandra Database from an Earlier Version of Kea +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes a new Kea version may use a newer database schema, so the +existing database will need to be upgraded. This can be done using the +``kea-admin lease-upgrade`` command. + +To check the current version of the database, use the following command: + +:: + + $ kea-admin lease-version cql -n database-name + +(See `Databases and Database Version Numbers <#kea-database-version>`__ +for a discussion about versioning.) If the version does not match the +minimum required for the new version of Kea (as described in the release +notes), the database needs to be upgraded. + +Before upgrading, please make sure that the database is backed up. The +upgrade process does not discard any data, but depending on the nature +of the changes, it may be impossible to subsequently downgrade to an +earlier version. To perform an upgrade, issue the following command: + +:: + + $ kea-admin lease-upgrade cql -n database-name + +Using Read-Only Databases with Host Reservations +------------------------------------------------ + +If a read-only database is used for storing host reservations, Kea must +be explicitly configured to operate on the database in read-only mode. +Sections `??? <#read-only-database-configuration4>`__ and +`??? <#read-only-database-configuration6>`__ describe when such +configuration may be required and how to configure Kea to operate in +this way. + +Limitations Related to the Use of SQL Databases +----------------------------------------------- + +Year 2038 Issue +~~~~~~~~~~~~~~~ + +The lease expiration time is stored in the SQL database for each lease +as a timestamp value. Kea developers observed that the MySQL database +doesn't accept timestamps beyond 2147483647 seconds (maximum signed +32-bit number) from the beginning of the Unix epoch (00:00:00 on 1 +January 1970). Some versions of PostgreSQL do accept greater values, but +the value is altered when it is read back. For this reason, the lease +database backends put a restriction on the maximum timestamp to be +stored in the database, which is equal to the maximum signed 32-bit +number. This effectively means that the current Kea version cannot store +leases whose expiration time is later than 2147483647 seconds since the +beginning of the epoch (around year 2038). This will be fixed when the +database support for longer timestamps is available. diff --git a/doc/guide/agent.rst b/doc/guide/agent.rst new file mode 100644 index 0000000000..1d21ca98a0 --- /dev/null +++ b/doc/guide/agent.rst @@ -0,0 +1,274 @@ +.. _kea-ctrl-agent: + +********************* +The Kea Control Agent +********************* + +.. _agent-overview: + +Overview +======== + +The Kea Control Agent (CA) is a daemon which exposes a RESTful control +interface for managing Kea servers. The daemon can receive control +commands over HTTP and either forward these commands to the respective +Kea servers or handle these commands on its own. The determination +whether the command should be handled by the CA or forwarded is made by +checking the value of the "service" parameter, which may be included in +the command from the controlling client. The details of the supported +commands, as well as their structures, are provided in +`??? <#ctrl-channel>`__. + +The CA can use hook libraries to provide support for additional commands +or custom behavior of existing commands. Such hook libraries must +implement callouts for the "control_command_receive" hook point. Details +about creating new hook libraries and supported hook points can be found +in the `Kea Developer's +Guide `__. + +The CA processes received commands according to the following algorithm: + +- Pass command into any installed hooks (regardless of service + value(s)). If the command is handled by a hook, return the response. + +- If the service specifies one more or services, forward the command to + the specified services and return the accumulated responses. + +- If the service is not specified or is an empty list, handle the + command if the CA supports it. + +.. _agent-configuration: + +Configuration +============= + +The following example demonstrates the basic CA configuration. + +:: + + { + "Control-agent": { + "http-host": "10.20.30.40", + "http-port": 8080, + + "control-sockets": { + "dhcp4": { + "comment": "main server", + "socket-type": "unix", + "socket-name": "/path/to/the/unix/socket-v4" + }, + "dhcp6": { + "socket-type": "unix", + "socket-name": "/path/to/the/unix/socket-v6", + "user-context": { "version": 3 } + }, + "d2": { + "socket-type": "unix", + "socket-name": "/path/to/the/unix/socket-d2" + }, + }, + + "hooks-libraries": [ + { + "library": "/opt/local/control-agent-commands.so", + "parameters": { + "param1": "foo" + } + } ], + + "loggers": [ { + "name": "kea-ctrl-agent", + "severity": "INFO" + } ] + } + } + +The ``http-host`` and ``http-port`` parameters specify an IP address and +port to which HTTP service will be bound. In the example configuration +provided above, the RESTful service will be available under the URL of +``http://10.20.30.40:8080/``. If these parameters are not specified, the +default URL is http://127.0.0.1:8000/ + +As mentioned in `Overview <#agent-overview>`__, the CA can forward +received commands to the Kea servers for processing. For example, +``config-get`` is sent to retrieve the configuration of one of the Kea +services. When the CA receives this command, including a ``service`` +parameter indicating that the client desires to retrieve the +configuration of the DHCPv4 server, the CA forwards this command to that +server and passes the received response back to the client. More about +the ``service`` parameter and the general structure of commands can be +found in `??? <#ctrl-channel>`__. + +The CA uses UNIX domain sockets to forward control commands and receive +responses from other Kea services. The ``dhcp4``, ``dhcp6``, and ``d2`` +maps specify the files to which UNIX domain sockets are bound. In the +configuration above, the CA will connect to the DHCPv4 server via +``/path/to/the/unix/socket-v4`` to forward the commands to it. +Obviously, the DHCPv4 server must be configured to listen to connections +via this same socket. In other words, the command socket configuration +for the DHCPv4 server and the CA (for this server) must match. Consult +`??? <#dhcp4-ctrl-channel>`__, `??? <#dhcp6-ctrl-channel>`__ and +`??? <#d2-ctrl-channel>`__ to learn how the socket configuration is +specified for the DHCPv4, DHCPv6 and D2 services. + + **Warning** + + "dhcp4-server", "dhcp6-server" and "d2-server" were renamed to + "dhcp4", "dhcp6" and "d2" respectively in Kea 1.2. If you are + migrating from Kea 1.2, you must modify your CA configuration to use + this new naming convention. + +User contexts can store arbitrary data as long as they are in valid JSON +syntax and their top-level element is a map (i.e. the data must be +enclosed in curly brackets). Some hook libraries may expect specific +formatting; please consult the relevant hook library documentation for +details. + +User contexts can be specified on either global scope, control socket, +or loggers. One other useful feature is the ability to store comments or +descriptions; the parser translates a "comment" entry into a user +context with the entry, which allows a comment to be attached within the +configuration itself. + +Hooks libraries can be loaded by the Control Agent in the same way as +they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently +supports one hook point - 'control_command_receive' - which makes it +possible to delegate processing of some commands to the hooks library. +The ``hooks-libraries`` list contains the list of hooks libraries that +should be loaded by the CA, along with their configuration information +specified with ``parameters``. + +Please consult `??? <#logging>`__ for the details how to configure +logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in +the example above. + +.. _agent-secure-connection: + +Secure Connections +================== + +The Control Agent does not natively support secure HTTP connections like +SSL or TLS. In order to setup a secure connection, please use one of the +available third-party HTTP servers and configure it to run as a reverse +proxy to the Control Agent. Kea has been tested with two major HTTP +server implentations working as a reverse proxy: Apache2 and nginx. +Example configurations, including extensive comments, are provided in +the ``doc/examples/https/`` directory. + +The reverse proxy forwards HTTP requests received over a secure +connection to the Control Agent using unsecured HTTP. Typically, the +reverse proxy and the Control Agent are running on the same machine, but +it is possible to configure them to run on separate machines as well. In +this case, security depends on the protection of the communications +between the reverse proxy and the Control Agent. + +Apart from providing the encryption layer for the control channel, a +reverse proxy server is also often used for authentication of the +controlling clients. In this case, the client must present a valid +certificate when it connects via reverse proxy. The proxy server +authenticates the client by checking whether the presented certificate +is signed by the certificate authority used by the server. + +To illustrate this, the following is a sample configuration for the +nginx server running as a reverse proxy to the Kea Control Agent. The +server enables authentication of the clients using certificates. + +:: + + # The server certificate and key can be generated as follows: + # + # openssl genrsa -des3 -out kea-proxy.key 4096 + # openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt + # + # The CA certificate and key can be generated as follows: + # + # openssl genrsa -des3 -out ca.key 4096 + # openssl req -new -x509 -days 365 -key ca.key -out ca.crt + # + # + # The client certificate needs to be generated and signed: + # + # openssl genrsa -des3 -out kea-client.key 4096 + # openssl req -new -key kea-client.key -out kea-client.csr + # openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \ + # -CAkey ca.key -set_serial 01 -out kea-client.crt + # + # Note that the 'common name' value used when generating the client + # and the server certificates must differ from the value used + # for the CA certificate. + # + # The client certificate must be deployed on the client system. + # In order to test the proxy configuration with 'curl' run + # command similar to the following: + # + # curl -k --key kea-client.key --cert kea-client.crt -X POST \ + # -H Content-Type:application/json -d '{ "command": "list-commands" }' \ + # https://kea.example.org/kea + # + # + # + # nginx configuration starts here. + + events { + } + + http { + # HTTPS server + server { + # Use default HTTPS port. + listen 443 ssl; + # Set server name. + server_name kea.example.org; + + # Server certificate and key. + ssl_certificate /path/to/kea-proxy.crt; + ssl_certificate_key /path/to/kea-proxy.key; + + # Certificate Authority. Client certificate must be signed by the CA. + ssl_client_certificate /path/to/ca.crt; + + # Enable verification of the client certificate. + ssl_verify_client on; + + # For URLs such as https://kea.example.org/kea, forward the + # requests to http://127.0.0.1:8080. + location /kea { + proxy_pass http://127.0.0.1:8080; + } + } + } + +.. + + **Note** + + Note that the configuration snippet provided above is for testing + purposes only. It should be modified according to the security + policies and best practices of your organization. + +When you use an HTTP client without TLS support as ``kea-shell``, you +can use an HTTP/HTTPS translator such as stunnel in client mode. A +sample configuration is provided in the ``doc/examples/https/shell/`` +directory. + +.. _agent-launch: + +Starting the Control Agent +========================== + +The CA is started by running its binary and specifying the configuration +file it should use. For example: + +:: + + $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf + +It can be started by keactrl as well (see `??? <#keactrl>`__). + +.. _agent-clients: + +Connecting to the Control Agent +=============================== + +For an example of a tool that can take advantage of the RESTful API, see +`??? <#kea-shell>`__. diff --git a/doc/guide/api.rst b/doc/guide/api.rst new file mode 100644 index 0000000000..eac8a9e243 --- /dev/null +++ b/doc/guide/api.rst @@ -0,0 +1,6800 @@ +.. _api: + +************* +API Reference +************* + +Kea currently supports 121 commands: ``build-report`` , ``cache-clear`` +, ``cache-get`` , ``cache-get-by-id`` , ``cache-insert`` , +``cache-load`` , ``cache-remove`` , ``cache-size`` , ``cache-write`` , +``class-add`` , ``class-del`` , ``class-get`` , ``class-list`` , +``class-update`` , ``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`` , +``remote-global-parameter4-del`` , ``remote-global-parameter4-get`` , +``remote-global-parameter4-get-all`` , ``remote-global-parameter4-set`` +, ``remote-global-parameter6-del`` , ``remote-global-parameter6-get`` , +``remote-global-parameter6-get-all`` , ``remote-global-parameter6-set`` +, ``remote-network4-del`` , ``remote-network4-get`` , +``remote-network4-list`` , ``remote-network4-set`` , +``remote-network6-del`` , ``remote-network6-get`` , +``remote-network6-list`` , ``remote-network6-set`` , +``remote-option-def4-del`` , ``remote-option-def4-get`` , +``remote-option-def4-get-all`` , ``remote-option-def4-set`` , +``remote-option-def6-del`` , ``remote-option-def6-get`` , +``remote-option-def6-get-all`` , ``remote-option-def6-set`` , +``remote-option4-global-del`` , ``remote-option4-global-get`` , +``remote-option4-global-get-all`` , ``remote-option4-global-set`` , +``remote-option6-global-del`` , ``remote-option6-global-get`` , +``remote-option6-global-get-all`` , ``remote-option6-global-set`` , +``remote-subnet4-del-by-id`` , ``remote-subnet4-del-by-prefix`` , +``remote-subnet4-get-by-id`` , ``remote-subnet4-get-by-prefix`` , +``remote-subnet4-list`` , ``remote-subnet4-set`` , +``remote-subnet6-del-by-id`` , ``remote-subnet6-del-by-prefix`` , +``remote-subnet6-get-by-id`` , ``remote-subnet6-get-by-prefix`` , +``remote-subnet6-list`` , ``remote-subnet6-set`` , ``reservation-add`` , +``reservation-del`` , ``reservation-get`` , ``reservation-get-all`` , +``reservation-get-page`` , ``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`` , ``subnet4-update`` , +``subnet6-add`` , ``subnet6-del`` , ``subnet6-get`` , ``subnet6-list`` , +``subnet6-update`` , ``version-get`` . + +Commands supported by kea-ctrl-agent daemon: ``build-report`` , +``config-get`` , ``config-reload`` , ``config-set`` , ``config-test`` , +``config-write`` , ``list-commands`` , ``shutdown`` , ``version-get`` . + +Commands supported by kea-dhcp-ddns daemon: ``build-report`` , +``config-get`` , ``config-reload`` , ``config-set`` , ``config-test`` , +``config-write`` , ``list-commands`` , ``shutdown`` , ``version-get`` . + +Commands supported by kea-dhcp4 daemon: ``build-report`` , +``cache-clear`` , ``cache-get`` , ``cache-get-by-id`` , ``cache-insert`` +, ``cache-load`` , ``cache-remove`` , ``cache-size`` , ``cache-write`` , +``class-add`` , ``class-del`` , ``class-get`` , ``class-list`` , +``class-update`` , ``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`` , ``remote-global-parameter4-del`` , +``remote-global-parameter4-get`` , ``remote-global-parameter4-get-all`` +, ``remote-global-parameter4-set`` , ``remote-network4-del`` , +``remote-network4-get`` , ``remote-network4-list`` , +``remote-network4-set`` , ``remote-option-def4-del`` , +``remote-option-def4-get`` , ``remote-option-def4-get-all`` , +``remote-option-def4-set`` , ``remote-option4-global-del`` , +``remote-option4-global-get`` , ``remote-option4-global-get-all`` , +``remote-option4-global-set`` , ``remote-subnet4-del-by-id`` , +``remote-subnet4-del-by-prefix`` , ``remote-subnet4-get-by-id`` , +``remote-subnet4-get-by-prefix`` , ``remote-subnet4-list`` , +``remote-subnet4-set`` , ``reservation-add`` , ``reservation-del`` , +``reservation-get`` , ``reservation-get-all`` , ``reservation-get-page`` +, ``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`` , +``subnet4-update`` , ``version-get`` . + +Commands supported by kea-dhcp6 daemon: ``build-report`` , +``cache-clear`` , ``cache-get`` , ``cache-get-by-id`` , ``cache-insert`` +, ``cache-load`` , ``cache-remove`` , ``cache-size`` , ``cache-write`` , +``class-add`` , ``class-del`` , ``class-get`` , ``class-list`` , +``class-update`` , ``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`` , ``remote-global-parameter6-del`` , +``remote-global-parameter6-get`` , ``remote-global-parameter6-get-all`` +, ``remote-global-parameter6-set`` , ``remote-network6-del`` , +``remote-network6-get`` , ``remote-network6-list`` , +``remote-network6-set`` , ``remote-option-def6-del`` , +``remote-option-def6-get`` , ``remote-option-def6-get-all`` , +``remote-option-def6-set`` , ``remote-option6-global-del`` , +``remote-option6-global-get`` , ``remote-option6-global-get-all`` , +``remote-option6-global-set`` , ``remote-subnet6-del-by-id`` , +``remote-subnet6-del-by-prefix`` , ``remote-subnet6-get-by-id`` , +``remote-subnet6-get-by-prefix`` , ``remote-subnet6-list`` , +``remote-subnet6-set`` , ``reservation-add`` , ``reservation-del`` , +``reservation-get`` , ``reservation-get-all`` , ``reservation-get-page`` +, ``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`` , +``subnet6-update`` , ``version-get`` . + +Commands supported by cb_cmds hook library: +``remote-global-parameter4-del`` , ``remote-global-parameter4-get`` , +``remote-global-parameter4-get-all`` , ``remote-global-parameter4-set`` +, ``remote-global-parameter6-del`` , ``remote-global-parameter6-get`` , +``remote-global-parameter6-get-all`` , ``remote-global-parameter6-set`` +, ``remote-network4-del`` , ``remote-network4-get`` , +``remote-network4-list`` , ``remote-network4-set`` , +``remote-network6-del`` , ``remote-network6-get`` , +``remote-network6-list`` , ``remote-network6-set`` , +``remote-option-def4-del`` , ``remote-option-def4-get`` , +``remote-option-def4-get-all`` , ``remote-option-def4-set`` , +``remote-option-def6-del`` , ``remote-option-def6-get`` , +``remote-option-def6-get-all`` , ``remote-option-def6-set`` , +``remote-option4-global-del`` , ``remote-option4-global-get`` , +``remote-option4-global-get-all`` , ``remote-option4-global-set`` , +``remote-option6-global-del`` , ``remote-option6-global-get`` , +``remote-option6-global-get-all`` , ``remote-option6-global-set`` , +``remote-subnet4-del-by-id`` , ``remote-subnet4-del-by-prefix`` , +``remote-subnet4-get-by-id`` , ``remote-subnet4-get-by-prefix`` , +``remote-subnet4-list`` , ``remote-subnet4-set`` , +``remote-subnet6-del-by-id`` , ``remote-subnet6-del-by-prefix`` , +``remote-subnet6-get-by-id`` , ``remote-subnet6-get-by-prefix`` , +``remote-subnet6-list`` , ``remote-subnet6-set`` . + +Commands supported by class_cmds hook library: ``class-add`` , +``class-del`` , ``class-get`` , ``class-list`` , ``class-update`` . + +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-get-by-id`` , ``cache-insert`` , ``cache-load`` +, ``cache-remove`` , ``cache-size`` , ``cache-write`` . + +Commands supported by host_cmds hook library: ``reservation-add`` , +``reservation-del`` , ``reservation-get`` , ``reservation-get-all`` , +``reservation-get-page`` . + +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`` , +``subnet4-update`` , ``subnet6-add`` , ``subnet6-del`` , ``subnet6-get`` +, ``subnet6-list`` , ``subnet6-update`` . + +.. _reference-build-report: + +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-dhcp-ddns``, +``kea-ctrl-agent`` + +Availability: 1.2.0 (built-in) + +Description and examples: See `??? <#command-build-report>`__ + +Command syntax: + +:: + + { + "command": "build-report" + } + +Response syntax: + +:: + + { + "result": 0, + "text": + } + +.. _reference-cache-clear: + +cache-clear reference +===================== + +``cache-clear`` - This command removes all cached host reservations. + +Supported by: ``kea-dhcp4``, ``kea-dhcp6`` + +Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-clear>`__ + +Command syntax: + +:: + + { + "command": "cache-clear" + } + +Response syntax: + +:: + + { + "result": , + "text": + } + +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) + +.. _reference-cache-get: + +cache-get reference +=================== + +``cache-get`` - Returns full content of the host cache. + +Supported by: ``kea-dhcp4``, ``kea-dhcp6`` + +Availability: 1.4.0 (`host_cache <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-get>`__ + +Command syntax: + +:: + + { + "command": "cache-get" + } + +Response syntax: + +:: + + { + "result": 0 + "text": "123 entries returned." + "arguments": + } + +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) + +.. _reference-cache-get-by-id: + +cache-get-by-id reference +========================= + +``cache-get-by-id`` - Returns entries matching the given identifier from +the host cache. + +Supported by: ``kea-dhcp4``, ``kea-dhcp6`` + +Availability: 1.6.0 (`host_cache <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-get-by-id>`__ + +Command syntax: + +:: + + { + "command": "cache-get-by-id", + "arguments": { + "hw-address": "01:02:03:04:05:06" + } + +Response syntax: + +:: + + { + "result": 0 + "text": "2 entries returned." + "arguments": + } + +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) + +.. _reference-cache-insert: + +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 <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-insert>`__ + +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": , + "text": + } + +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) + +.. _reference-cache-load: + +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 <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-load>`__ + +Command syntax: + +:: + + { + "command": "cache-load", + "arguments": "/tmp/kea-host-cache.json" + } + +Response syntax: + +:: + + { + "result": , + "text": + } + +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) + +.. _reference-cache-remove: + +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 <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-remove>`__ + +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": , + "text": + } + +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) + +.. _reference-cache-size: + +cache-size reference +==================== + +``cache-size`` - Returns number of entries of the host cache. + +Supported by: ``kea-dhcp4``, ``kea-dhcp6`` + +Availability: 1.6.0 (`host_cache <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-size>`__ + +Command syntax: + +:: + + { + "command": "cache-size" + } + +Response syntax: + +:: + + { + "result": 0 + "text": "123 entries." + "arguments": { "size": 123 } + } + +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) + +.. _reference-cache-write: + +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 <#commands-host_cache-lib>`__ hook) + +Description and examples: See `??? <#command-cache-write>`__ + +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": , + "text": + } + +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) + +.. _reference-class-add: + +class-add reference +=================== + +``class-add`` - This command is used to create and add a new class to +the existing server configuration. + +Supported by: ``kea-dhcp4``, ``kea-dhcp6`` + +Availability: 1.5.0 (`class_cmds <#commands-class_cmds-lib>`__ hook) + +Description and examples: See `??? <#command-class-add>`__ + +Command syntax: + +:: + + { + "command": "class-add", + "arguments": { + "client-classes": [ { + "name": , + "test": , + "option-data": [