diff options
Diffstat (limited to 'doc/sphinx/man')
| -rw-r--r-- | doc/sphinx/man/kea-admin.8.rst | 159 | ||||
| -rw-r--r-- | doc/sphinx/man/kea-ctrl-agent.8.rst | 100 | ||||
| -rw-r--r-- | doc/sphinx/man/kea-dhcp-ddns.8.rst | 100 | ||||
| -rw-r--r-- | doc/sphinx/man/kea-dhcp4.8.rst | 106 | ||||
| -rw-r--r-- | doc/sphinx/man/kea-dhcp6.8.rst | 106 | ||||
| -rw-r--r-- | doc/sphinx/man/kea-lfc.8.rst | 131 | ||||
| -rw-r--r-- | doc/sphinx/man/kea-netconf.8.rst | 95 | ||||
| -rw-r--r-- | doc/sphinx/man/kea-shell.8.rst | 128 | ||||
| -rw-r--r-- | doc/sphinx/man/keactrl.8.rst | 126 | ||||
| -rw-r--r-- | doc/sphinx/man/man8s.mk | 10 | ||||
| -rw-r--r-- | doc/sphinx/man/perfdhcp.8.rst | 548 | ||||
| -rw-r--r-- | doc/sphinx/man/rst_man_sources.mk | 10 |
12 files changed, 1619 insertions, 0 deletions
diff --git a/doc/sphinx/man/kea-admin.8.rst b/doc/sphinx/man/kea-admin.8.rst new file mode 100644 index 0000000..9de0a0f --- /dev/null +++ b/doc/sphinx/man/kea-admin.8.rst @@ -0,0 +1,159 @@ +.. + Copyright (C) 2019-2022 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-admin`` - Shell script for managing Kea databases +------------------------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`kea-admin` [command] [backend] [**-h** database_host] +[**-P** database_port] [**-u** database_username] +[**-p** [database_password]] [**-n** database_name] [**-d** script_directory] +[**-v**] [**-x** extra_argument [**-x** extra_argument ...]] +[**-4** | **-6**] [**-i** input_file] [**-o** output_file] [**-y**] + +Description +~~~~~~~~~~~ + +``kea-admin`` is a shell script that offers database maintenance. In +particular, it features database initialization, database version +checking, and database schema upgrading. + +Arguments +~~~~~~~~~ + +``command`` + Specifies the command to be issued to the servers. It can be one of the + following: + + ``db-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. + + ``db-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. + + ``db-upgrade`` + Conducts a database schema upgrade. This is useful when upgrading Kea. + + ``lease-dump`` + Dumps the contents of the lease database (for MySQL or + PostgreSQL backends) to a CSV (comma-separated values) text file. (Support + for the Cassandra backend has been deprecated.) + The first line of the file contains the column names. This can be used + as a way to switch from a database backend to a memfile backend. + Alternatively, it can be used as a diagnostic tool, so it provides a + portable form of the lease data. + + ``lease-upload`` + Uploads leases from a CSV (comma-separated values) text file to a MySQL or + a PostgreSQL lease database. The CSV file needs to be in memfile format. + + ``stats-recount`` + Recounts lease statistics for a MySQL or PostgreSQL database. + +``backend`` + Specifies the backend type. Currently allowed backends are: memfile, + mysql, and pgsql; cql has been deprecated. + +``-h|--host hostname`` + Specifies the hostname when connecting to a database. + The default value is ``localhost``. + +``-P|--port port`` + Specifies the port when connecting to a database. If not specified, + the default value chosen by the database client is used. + +``-u|--user username`` + Specifies the username when connecting to a database. + The default value is ``keatest``. + +``-p|--password password`` + Specifies the password when connecting to a database. + If only ``-p`` or ``--password`` is given, the user is prompted for a password. + If not specified at all, the ``KEA_ADMIN_DB_PASSWORD`` environment variable + is checked for a value and used if it exists. + Otherwise the default value of ``keatest`` is used. + +``-n|--name database-name`` + Specifies the name of the database to connect to. The + default value is ``keatest``. + +``-d|--directory script-directory`` + Specifies the override scripts directory. That script is used during + upgrades, database initialization, and possibly other operations. + The default value is ``(prefix)/share/kea/scripts/``. + +``-o|--output output_file`` + Specifies the file to which the lease data will be dumped. Required for + ``lease-dump``. + +``-v|--version`` + Prints the ``kea-admin`` version and quits. + +``-4`` + Directs ``kea-admin`` to lease-dump the DHCPv4 leases. Incompatible with + the -6 option. + +``-6`` + Directs ``kea-admin`` to lease-dump the DHCPv6 leases. Incompatible with + the -4 option. + +``-x|--extra`` + Specifies an extra argument to pass to the database command tool e.g. + to invoke ``mysql`` with the ``--ssl`` argument. This can be repeated + to pass more than one argument. Quotes are not preserved. Avoid commands + containing spaces. + +``-y|--yes`` + Assume yes on overwriting temporary files. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, +:manpage:`kea-dhcp-ddns(8)`, :manpage:`kea-ctrl-agent(8)`, +:manpage:`keactrl(8)`, :manpage:`perfdhcp(8)`, :manpage:`kea-netconf(8)`, +Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/kea-ctrl-agent.8.rst b/doc/sphinx/man/kea-ctrl-agent.8.rst new file mode 100644 index 0000000..48212cc --- /dev/null +++ b/doc/sphinx/man/kea-ctrl-agent.8.rst @@ -0,0 +1,100 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-ctrl-agent`` - Control Agent process in Kea +------------------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`kea-ctrl-agent` [**-v**] [**-V**] [**-W**] [**-d**] [**-c** config-file] [**-t** config-file] + +Description +~~~~~~~~~~~ + +The ``kea-ctrl-agent`` provides a REST service for controlling Kea +services. The received HTTP requests are decapsulated and forwarded to +the respective Kea services in JSON format. Received JSON responses are +encapsulated within HTTP responses and returned to the controlling +entity. Some commands may be handled by the Control Agent directly, and +not forwarded to any Kea service. + +Arguments +~~~~~~~~~ + +The arguments are as follows: + +``-v`` + Displays the version. + +``-V`` + Displays the extended version. + +``-W`` + Displays the configuration report. + +``-d`` + Sets the logging level to debug with extra verbosity. This is primarily for + development purposes in stand-alone mode. + +``-c config-file`` + Specifies the file with the configuration for the Control Agent + server. It may also contain configuration entries for other Kea + services. + +``-t config-file`` + Checks the syntax of the configuration file and reports the first error, + if any. Note that not all parameters are completely checked; in + particular, service and client sockets are not opened, and hook + libraries are not loaded. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +The ``kea-ctrl-agent`` was first coded in December 2016 by Marcin +Siodelski. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, +:manpage:`kea-dhcp-ddns(8)`, :manpage:`kea-admin(8)`, :manpage:`keactrl(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-lfc(8)`, Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/kea-dhcp-ddns.8.rst b/doc/sphinx/man/kea-dhcp-ddns.8.rst new file mode 100644 index 0000000..4b1841a --- /dev/null +++ b/doc/sphinx/man/kea-dhcp-ddns.8.rst @@ -0,0 +1,100 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-dhcp-ddns`` - DHCP-DDNS process in Kea +-------------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`kea-dhcp-ddns` [**-v**] [**-V**] [**-W**] [**-d**] [**-c** config-file] [**-t** config-file] + +Description +~~~~~~~~~~~ + +The ``kea-dhcp-ddns`` service process requests an update of DNS mapping +based on DHCP lease-change events. It runs as a separate process that +expects to receive Name Change Requests from Kea DHCP servers. + +Arguments +~~~~~~~~~ + +The arguments are as follows: + +``-v`` + Displays the version. + +``-V`` + Displays the extended version. + +``-W`` + Displays the configuration report. + +``-d`` + Sets the logging level to debug with extra verbosity. This is primarily for + development purposes in stand-alone mode. + +``-c config-file`` + Specifies the configuration file with the configuration for the DHCP-DDNS server. It + may also contain configuration entries for other Kea services. + +``-t config-file`` + Checks the syntax of the configuration file and reports the first error, + if any. Note that not all parameters are completely checked; in + particular, a service socket is not opened. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +The ``b10-dhcp-ddns`` process was first coded in May 2013 by Thomas +Markwalder. + +Kea became a standalone server and the BIND 10 framework was removed. The +DHCP-DDNS server binary was renamed to kea-dhcp-ddns in July 2014. Kea +1.0.0 was released in December 2015. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`keactrl(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-netconf(8)`, :manpage:`kea-lfc(8)`, +Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/kea-dhcp4.8.rst b/doc/sphinx/man/kea-dhcp4.8.rst new file mode 100644 index 0000000..be59b0f --- /dev/null +++ b/doc/sphinx/man/kea-dhcp4.8.rst @@ -0,0 +1,106 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-dhcp4`` - DHCPv4 server in Kea +------------------------------------ + +Synopsis +~~~~~~~~ + +:program:`kea-dhcp4` [**-v**] [**-V**] [**-W**] [**-d**] [**-c** config-file] [**-t** config-file] [**-p** server-port-number] [**-P** client-port-number] + +Description +~~~~~~~~~~~ + +The ``kea-dhcp4`` daemon provides the DHCPv4 server implementation. + +Arguments +~~~~~~~~~ + +The arguments are as follows: + +``-v`` + Displays the version. + +``-V`` + Displays the extended version. + +``-W`` + Displays the configuration report. + +``-d`` + Enables the debug mode with extra verbosity. + +``-c config-file`` + Specifies the configuration file with the configuration for the DHCPv4 server. It + may also contain configuration entries for other Kea services. + +``-t config-file`` + Checks the configuration file and reports the first error, if any. Note + that not all parameters are completely checked; in particular, + service and control channel sockets are not opened, and hook + libraries are not loaded. + +``-p server-port-number`` + Specifies the server port number (1-65535) on which the server listens. This is + useful for testing purposes only. + +``-P client-port-number`` + Specifies the client port number (1-65535) to which the server responds. This is + useful for testing purposes only. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +The ``b10-dhcp4`` daemon was first coded in November 2011 by Tomek +Mrugalski. + +In mid-2014, Kea was decoupled from the BIND 10 framework and became a +standalone DHCP server. The DHCPv4 server binary was renamed to +``kea-dhcp4``. Kea 1.0.0 was released in December 2015. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp6(8)`, :manpage:`kea-dhcp-ddns(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`keactrl(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-netconf(8)`, :manpage:`kea-lfc(8)`, +Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/kea-dhcp6.8.rst b/doc/sphinx/man/kea-dhcp6.8.rst new file mode 100644 index 0000000..19ec5e8 --- /dev/null +++ b/doc/sphinx/man/kea-dhcp6.8.rst @@ -0,0 +1,106 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-dhcp6`` - DHCPv6 server in Kea +------------------------------------ + +Synopsis +~~~~~~~~ + +:program:`kea-dhcp6` [**-v**] [**-V**] [**-W**] [**-d**] [**-c** config-file] [**-t** config-file] [**-p** server-port-number] [**-P** client-port-number] + +Description +~~~~~~~~~~~ + +The ``kea-dhcp6`` daemon provides the DHCPv6 server implementation. + +Arguments +~~~~~~~~~ + +The arguments are as follows: + +``-v`` + Displays the version. + +``-V`` + Displays the extended version. + +``-W`` + Displays the configuration report. + +``-d`` + Enables the debug mode with extra verbosity. + +``-c config-file`` + Specifies the configuration file with the configuration for the DHCPv6 server. It + may also contain configuration entries for other Kea services. + +``-t config-file`` + Checks the configuration file and reports the first error, if any. Note + that not all parameters are completely checked; in particular, + service and control channel sockets are not opened, and hook + libraries are not loaded. + +``-p server-port-number`` + Specifies the server port number (1-65535) on which the server listens. This is + useful for testing purposes only. + +``-P client-port-number`` + Specifies the client port number (1-65535) to which the server responds. This is + useful for testing purposes only. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +The ``b10-dhcp6`` daemon was first coded in June 2011 by Tomek +Mrugalski. + +In mid-2014, Kea was decoupled from the BIND 10 framework and became a +standalone DHCP server. The DHCPv6 server binary was renamed to +``kea-dhcp6``. Kea 1.0.0 was released in December 2015. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp-ddns(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`keactrl(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-netconf(8)`, :manpage:`kea-lfc(8)`, +Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/kea-lfc.8.rst b/doc/sphinx/man/kea-lfc.8.rst new file mode 100644 index 0000000..d4082b5 --- /dev/null +++ b/doc/sphinx/man/kea-lfc.8.rst @@ -0,0 +1,131 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-lfc`` - Lease File Cleanup process in Kea +----------------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`kea-lfc` [**-4**|**-6**] [**-c** config-file] [**-p** pid-file] [**-x** previous-file] [**-i** copy-file] [**-o** output-file] [**-f** finish-file] [**-v**] [**-V**] [**-W**] [**-d**] [**-h**] + +Description +~~~~~~~~~~~ + +The ``kea-lfc`` service process removes redundant information from the +files used to provide persistent storage for the memfile database +backend. The service is written to run as a stand-alone process. While +it can be started externally, there is usually no need to do this. It +is run periodically by the Kea DHCP servers. + +Arguments +~~~~~~~~~ + +The arguments are as follows: + +``-4 | -6`` + Indicates the protocol version of the lease files; must be either 4 or 6. + +``-c config-file`` + Specifies the file with the configuration for the ``kea-lfc`` + process. It may also contain configuration entries for other Kea + services. Currently ``kea-lfc`` gets all of its arguments from the + command line. + +``-p pid-file`` + Specifies the PID file. When the ``kea-lfc`` process starts, it attempts to + determine if another instance of the process is already running, by + examining the PID file. If one is already running, the new process is + terminated. If one is not running, Kea writes its PID into the PID file. + +``-x previous-file`` + Specifies the previous or ex-lease file. When ``kea-lfc`` starts, this is the + result of any previous run of ``kea-lfc``; when ``kea-lfc`` finishes, + it is the result of the current run. If ``kea-lfc`` is interrupted before + completing, this file may not exist. + +``-i copy-file`` + Specifies the input or copy of lease file. Before the DHCP server invokes + ``kea-lfc``, it moves the current lease file here and then calls + ``kea-lfc`` with this file. + +``-o output-file`` + Specifies the output lease file, which is the temporary file ``kea-lfc`` should use to + write the leases. Once this file is finished writing, it is + moved to the finish file (see below). + +``-f finish-file`` + Specifies the finish or completion file, another temporary file ``kea-lfc`` uses + for bookkeeping. When ``kea-lfc`` finishes writing the output file, + it moves it to this file name. After ``kea-lfc`` finishes deleting + the other files (previous and input), it moves this file to the previous + lease file. By moving the files in this fashion, the ``kea-lfc`` and + the DHCP server processes can determine the correct file to use even + if one of the processes was interrupted before completing its task. + +``-v`` + Causes the version stamp to be printed. + +``-V`` + Causes a longer form of the version stamp to be printed. + +``-W`` + Displays the configuration report. + +``-d`` + Sets the logging level to debug with extra verbosity. This is primarily for + development purposes in stand-alone mode. + +``-h`` + Causes the usage string to be printed. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +The ``kea-lfc`` process was first coded in January 2015 by the ISC +Kea/DHCP team. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, :manpage:`kea-dhcp-ddns(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`keactrl(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-netconf(8)`, Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/kea-netconf.8.rst b/doc/sphinx/man/kea-netconf.8.rst new file mode 100644 index 0000000..9029d01 --- /dev/null +++ b/doc/sphinx/man/kea-netconf.8.rst @@ -0,0 +1,95 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-netconf`` - NETCONF agent for configuring Kea +--------------------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`kea-netconf` [**-v**] [**-V**] [**-W**] [**-d**] [**-c** config-file] [**-t** config-file] + +Description +~~~~~~~~~~~ + +The ``kea-netconf`` agent provides a YANG/NETCONF interface for the Kea +environment. + +Arguments +~~~~~~~~~ + +The arguments are as follows: + +``-v`` + Displays the version. + +``-V`` + Displays the extended version. + +``-W`` + Displays the configuration report. + +``-d`` + Enables the debug mode with extra verbosity. + +``-c config-file`` + Specifies the file with the configuration for the NETCONF agent. + +``-t config-file`` + Checks the syntax of the configuration file and reports the first error, + if any. Note that not all parameters are completely checked; in + particular, service and client sockets are not opened, and hook + libraries are not loaded. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +Early prototypes of ``kea-netconf`` implementation were written during IETF +Hackathons in Berlin, London, and Montreal. An actual production-ready +implementation was started in August 2018 by Tomek Mrugalski and Francis +Dupont. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, :manpage:`kea-dhcp-ddns(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`keactrl(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-lfc(8)`, Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/kea-shell.8.rst b/doc/sphinx/man/kea-shell.8.rst new file mode 100644 index 0000000..0f468f1 --- /dev/null +++ b/doc/sphinx/man/kea-shell.8.rst @@ -0,0 +1,128 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``kea-shell`` - Text client for Control Agent process +----------------------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`kea-shell` [**-h**] [**-v**] [**--host**] [**--port**] [**--path**] [**--ca**] [**--cert**] [**--key**] [**--auth-user**] [**--auth-password**] [**--timeout**] [**--service**] [command] + +Description +~~~~~~~~~~~ + +The ``kea-shell`` provides a REST client for the Kea Control Agent (CA). +It takes commands as a command-line parameter that is sent to the CA +with proper JSON encapsulation. Optional arguments may be specified on +the standard input. The request is sent via HTTP and a response is +retrieved, displayed on the standard output. Basic HTTP authentication +and HTTPS, i.e. TLS transport, are supported. + + +Arguments +~~~~~~~~~ + +The arguments are as follows: + +``-h`` + Displays help regarding command-line parameters. + +``-v`` + Displays the version. + +``--host`` + Specifies the host to connect to. The Control Agent must be running at the + specified host. If not specified, 127.0.0.1 is used. + +``--port`` + Specifies the TCP port to connect to. Control Agent must be listening + at the specified port. If not specified, 8000 is used. + +``--path`` + Specifies the path in the URL to connect to. If not specified, an empty + path is used. As Control Agent listens at the empty path, this + parameter is useful only with a reverse proxy. + +``--ca`` + Specifies the file or directory name of the Certification Authority. + If not specified, HTTPS is not used. + +``--cert`` + Specifies the file name of the user end-entity public key certificate. + If specified, the file name of the user key must also be specified. + +``--key`` + Specifies the file name of the user key file. If specified, the file + name of the user certificate must also be specified. + Encrypted key files are not supported. + +``--auth-user`` + Specifies the user ID for basic HTTP authentication. If not specified, + or specified as the empty string, authentication is not used. + +``--auth-password`` + Specifies the password for basic HTTP authentication. If not specified + but the user ID is specified, an empty password is used. + +``--timeout`` + Specifies the connection timeout, in seconds. The default is 10. + +``--service`` + Specifies the service that is the target of a command. If not + specified, the Control Agent itself is targeted. May be used more than once + to specify multiple targets. + +``command`` + Specifies the command to be sent to the CA. If not specified, + ``list-commands`` is used. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +The ``kea-shell`` was first coded in March 2017 by Tomek Mrugalski. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, :manpage:`kea-dhcp-ddns(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`keactrl(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-lfc(8)`, Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/keactrl.8.rst b/doc/sphinx/man/keactrl.8.rst new file mode 100644 index 0000000..67727f3 --- /dev/null +++ b/doc/sphinx/man/keactrl.8.rst @@ -0,0 +1,126 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``keactrl`` - Shell script for managing Kea +------------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`keactrl` [**command**] [**-c** keactrl-config-file] [**-s** server[,server,...]] [**-v**] + +Description +~~~~~~~~~~~ + +``keactrl`` is a shell script which controls the startup, shutdown, and +reconfiguration of the Kea servers (``kea-dhcp4``, ``kea-dhcp6``, +``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``). It also +provides a way to check the current status of the servers and +determine the configuration files in use. + +Configuration File +~~~~~~~~~~~~~~~~~~ + +Depending on the user's requirements, not all of the available servers need be run. +The ``keactrl`` configuration file specifies which servers are enabled and which +are disabled. By default the configuration file is +``[kea-install-dir]/etc/kea/keactrl.conf``. + +See the Kea Administrator Reference Manual for documentation of the +parameters in the ``keactrl`` configuration file. + +Options +~~~~~~~ + +``command`` + Specifies the command to be issued to the servers. It can be one of the following: + + ``start`` + Starts the servers. + + ``stop`` + Stops the servers. + + ``reload`` + Instructs the servers to re-read the Kea configuration file. This + command is not supported by the NETCONF agent. + + ``status`` + Prints the status of the servers. + +``-c|--ctrl-config keactrl-config-file`` + Specifies the ``keactrl`` configuration file. Without this switch, + ``keactrl`` uses the file + ``[kea-install-dir]/etc/kea/keactrl.conf``. + +``-s|--server server[,server,...]`` + Specifies a subset of the enabled servers to which the command should + be issued. The list of servers should be separated by commas, with no + intervening spaces. Acceptable values are: + + ``dhcp4`` + DHCPv4 server (``kea-dhcp4``). + + ``dhcp6`` + DHCPv6 server (``kea-dhcp6``). + + ``dhcp_ddns`` + DHCP DDNS server (``kea-dhcp-ddns``). + + ``ctrl_agent`` + Control Agent (``kea-ctrl-agent``). + + ``netconf`` + NETCONF agent (``kea-netconf``). + + ``all`` + All servers, including NETCONF if it was configured to be + built. This is the default. + +``-v|--version`` + Prints the ``keactrl`` version and quits. + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, :manpage:`kea-dhcp-ddns(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`kea-netconf(8)`, +:manpage:`perfdhcp(8)`, :manpage:`kea-lfc(8)`, Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/man8s.mk b/doc/sphinx/man/man8s.mk new file mode 100644 index 0000000..7af7c1f --- /dev/null +++ b/doc/sphinx/man/man8s.mk @@ -0,0 +1,10 @@ +man8s += $(sphinxbuilddir)/man/kea-admin.8 +man8s += $(sphinxbuilddir)/man/kea-ctrl-agent.8 +man8s += $(sphinxbuilddir)/man/kea-dhcp4.8 +man8s += $(sphinxbuilddir)/man/kea-dhcp6.8 +man8s += $(sphinxbuilddir)/man/kea-dhcp-ddns.8 +man8s += $(sphinxbuilddir)/man/kea-lfc.8 +man8s += $(sphinxbuilddir)/man/kea-netconf.8 +man8s += $(sphinxbuilddir)/man/kea-shell.8 +man8s += $(sphinxbuilddir)/man/keactrl.8 +man8s += $(sphinxbuilddir)/man/perfdhcp.8 diff --git a/doc/sphinx/man/perfdhcp.8.rst b/doc/sphinx/man/perfdhcp.8.rst new file mode 100644 index 0000000..75c371c --- /dev/null +++ b/doc/sphinx/man/perfdhcp.8.rst @@ -0,0 +1,548 @@ +.. + Copyright (C) 2019-2021 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/. + + See the COPYRIGHT file distributed with this work for additional + information regarding copyright ownership. + + +``perfdhcp`` - DHCP benchmarking tool +------------------------------------- + +Synopsis +~~~~~~~~ + +:program:`perfdhcp` [**-1**] [**-4** | **-6**] [**-A** encapsulation-level] [**-b** base] [**-B**] [**-c**] [**-C** separator] [**-d** drop-time] [**-D** max-drop] [-e lease-type] [**-E** time-offset] [**-f** renew-rate] [**-F** release-rate] [**-g** thread-mode] [**-h**] [**-i**] [**-I** ip-offset] [**-J** remote-address-list-file] [**-l** local-address|interface] [**-L** local-port] [**-M** mac-list-file] [**-n** num-request] [**-N** remote-port] [**-O** random-offset] [**-o** code,hexstring] [**-p** test-period] [**-P** preload] [**-r** rate] [**-R** num-clients] [**-s** seed] [**-S** srvid-offset] [**--scenario** name] [**-t** report] [**-T** template-file] [**-u**] [**-v**] [**-W** exit-wait-time] [**-w** script_name] [**-x** diagnostic-selector] [**-X** xid-offset] [server] + +Description +~~~~~~~~~~~ + +``perfdhcp`` is a DHCP benchmarking tool. It provides a way to measure +the performance of DHCP servers by generating large amounts of traffic +from multiple simulated clients. It is able to test both IPv4 and IPv6 +servers, and provides statistics concerning response times and the +number of requests that are dropped. + +The tool supports two different scenarios, which offer certain behaviors to be tested. +By default (the basic scenario), tests are run using the full four-packet exchange sequence +(DORA for DHCPv4, SARR for DHCPv6). An option is provided to run tests +using the initial two-packet exchange (DO and SA) instead. It is also +possible to configure ``perfdhcp`` to send DHCPv6 RENEW and RELEASE messages +at a specified rate, in parallel with the DHCPv6 four-way exchanges. By +default, if there is no response received with one second, a response is +considered lost and ``perfdhcp`` continues with other transactions. + +A second scenario, called avalanche, is selected via ``--scenario avalanche``. +It first sends the number of Discovery or Solicit messages specified by the ``-R`` option; then +a retransmission (with an exponential back-off mechanism) is used for each simulated client, until all requests are +answered. It generates a report when all clients receive their addresses, or when +it is manually stopped. This scenario attempts to replicate a +case where the server is not able to handle the traffic swiftly +enough. Real clients will assume the packet or response was lost +and will retransmit, further increasing DHCP traffic. This is +sometimes called an avalanche effect, thus the scenario name. +Option ``-p`` is ignored in the avalanche scenario. + +When running a performance test, ``perfdhcp`` exchanges packets with +the server under test as quickly as possible, unless the ``-r`` parameter is used to +limit the request rate. The length of the test can be limited by setting +a threshold on any or all of the number of requests made by +``perfdhcp``, the elapsed time, or the number of requests dropped by the +server. + +Templates +~~~~~~~~~ + +To allow the contents of packets sent to the server to be customized, +``perfdhcp`` allows the specification of template files that determine +the contents of the packets. For example, the customized packet may +contain a DHCPv6 ORO to request a set of options to be returned by the +server, or it may contain the Client FQDN option to request that the server +perform DNS updates. This may be used to discover performance +bottlenecks for different server configurations (e.g. DDNS enabled or +disabled). + +Up to two template files can be specified on the command line, with each file +representing the contents of a particular type of packet, and the type being +determined by the test being carried out. For example, if testing +DHCPv6: + +- With no template files specified on the command line, ``perfdhcp`` + generates both Solicit and Request packets. + +- With one template file specified, that file is used as the + pattern for Solicit packets: ``perfdhcp`` generates the Request + packets. + +- With two template files given on the command line, the first is + used as the pattern for Solicit packets, and the second as the pattern + for Request packets. + +(A similar determination applies to DHCPv4's DHCPDISCOVER and DHCPREQUEST +packets.) + +The template file holds the DHCP packet, represented as a stream of ASCII +hexadecimal digits; it excludes any IP/UDP stack headers. The +template file must not contain any characters other than hexadecimal +digits and spaces. Spaces are discarded when the template file is parsed; +in the file, ``12B4`` is the same as ``12 B4``, which is the same as +``1 2 B 4``. + +The template files should be used in conjunction with the command-line +parameters which specify offsets of the data fields being modified in +outbound packets. For example, the ``-E time-offset`` switch specifies +the offset of the DHCPv6 Elapsed Time option in the packet template. +If the offset is specified, ``perfdhcp`` injects the current elapsed-time +value into this field before sending the packet to the server. + +In many scenarios, ``perfdhcp`` needs to simulate multiple clients, +each having a unique client identifier. Since packets for each client are +generated from the same template file, it is necessary to randomize the +client identifier (or HW address in DHCPv4) in the packet created from +it. The ``-O random-offset`` option allows specification of the offset in +the template where randomization should be performed. It is important to +note that this offset points to the end (not the beginning) of the +client identifier (or HW address field). The number of bytes being +randomized depends on the number of simulated clients. If the number of +simulated clients is between 1 and 255, only one byte (to which the +randomization offset points) is randomized. If the number of +simulated clients is between 256 and 65535, two bytes are +randomized. Note that the last two bytes of the client identifier are +randomized in this case: the byte which the randomization offset parameter +points to, and the one which precedes it (random-offset - 1). If the +number of simulated clients exceeds 65535, three bytes are +randomized, and so on. + +``perfdhcp`` can simulate traffic from multiple subnets by enabling option +``-J`` and passing a path to a file that contains v4 or v6 addresses to be +used as relays in generated messages. That enables testing of vast numbers +of Kea shared networks. While testing DHCPv4, Kea should be started with the +``KEA_TEST_SEND_RESPONSES_TO_SOURCE`` environment variable, to force Kea +to send generated messages to the source address of the incoming packet. + +Templates may currently be used to generate packets being sent to the +server in 4-way exchanges, i.e. Solicit, Request (DHCPv6) and DHCPDISCOVER, +DHCPREQUEST (DHCPv4). They cannot be used when Renew or DHCPRELEASE packets are +being sent. + +Options +~~~~~~~ + +``-1`` + Takes the ``server-id`` option from the first received message. + +``-4`` + Establishes DHCPv4 operation; this is the default. It is incompatible with the + ``-6`` option. + +``-6`` + Establishes DHCPv6 operation. It is incompatible with the ``-4`` option. + +``-b basetype=value`` + Indicates the base MAC or DUID used to simulate different clients. The basetype + may be "mac" or "duid". (The keyword "ether" may alternatively used + for MAC.) The ``-b`` option can be specified multiple times. The MAC + address must consist of six octets separated by single (:) or double + (::) colons; for example: mac=00:0c:01:02:03:04. The DUID value is a + hexadecimal string; it must be at least six octets long and not + longer than 64 bytes, and the length must be less than 128 + hexadecimal digits. For example: duid=0101010101010101010110111F14. + +``-d drop-time`` + Specifies the time after which a request is treated as having been + lost. The value is given in seconds and may contain a fractional + component. The default is 1. + +``-e lease-type`` + Specifies the type of lease being requested from the server. It may + be one of the following: + + ``address-only`` + Only regular addresses (v4 or v6) are requested. + + ``prefix-only`` + Only IPv6 prefixes are requested. + + ``address-and-prefix`` + Both IPv6 addresses and prefixes are requested. + + The ``-e prefix-only`` and ``-e address-and-prefix`` forms may not be used + with the ``-4`` option. + +``-F release-rate`` + Specifies the rate at which DHCPv4 DHCPRELEASE or DHCPv6 Release requests are sent to a server. This value + is only valid when used in conjunction with the exchange rate (given + by ``-r rate``). Furthermore, the sum of this value and the renew-rate + (given by ``-f rate``) must be equal to or less than the exchange + rate value. + +``-f renew-rate`` + Specifies the rate at which DHCPv4 DHCPREQUEST or DHCPv6 Renew requests are sent to a server. + This value is only valid when used in conjunction with the exchange + rate (given by ``-r rate``). Furthermore, the sum of this value and + the release-rate (given by ``-F rate``) must be equal to or less than the + exchange rate. + +``-g thread-mode`` + Allows selection of thread-mode, which can be either ``single`` or ``multi``. In multi-thread mode, + packets are received in a separate thread, which allows better + utilisation of CPUs. In a single-CPU system it is better to run in one + thread, to avoid threads blocking each other. If more than one CPU is + present in the system, multi-thread mode is the default; otherwise + single-thread is the default. + +``-h`` + Prints help and exits. + +``-i`` + Performs only the initial part of the exchange: DISCOVER-OFFER if ``-4`` is + selected, Solicit-Advertise if ``-6`` is chosen. + + ``-i`` is incompatible with the following options: ``-1``, ``-d``, + ``-D``, ``-E``, ``-S``, ``-I`` and ``-F``. In addition, it cannot be + used with multiple instances of ``-O``, ``-T``, and ``-X``. + +``-J remote-address-list-file`` + Specifies a text file that includes multiple addresses, and is + designed to test shared networks. If provided, ``perfdhcp`` + randomly chooses one of the addresses for each exchange, to generate traffic + from multiple subnets. When testing DHCPv4, it + should be started with the ``KEA_TEST_SEND_RESPONSES_TO_SOURCE=ENABLE`` + environment variable; otherwise, ``perfdhcp`` will not be able to receive responses. + +``-l local-addr|interface`` + For DHCPv4 operation, specifies the local hostname/address to use when + communicating with the server. By default, the interface address + through which traffic would normally be routed to the server is used. + For DHCPv6 operation, specifies the name of the network interface + through which exchanges are initiated. + +``-L local-port`` + Specifies the local port to use. This must be zero or a positive + integer up to 65535. A value of 0 (the default) allows ``perfdhcp`` + to choose its own port. + +``-M mac-list-file`` + Specifies a text file containing a list of MAC addresses, one per line. If + provided, a MAC address is chosen randomly from this list for + every new exchange. In DHCPv6, MAC addresses are used to + generate DUID-LLs. This parameter must not be used in conjunction + with the ``-b`` parameter. + +``-N remote-port`` + Specifies the remote port to use. This must be zero or a positive + integer up to 65535. A value of 0 (the default) allows ``perfdhcp`` + to choose the standard service port. + +``-o code,hexstring`` + Forces ``perfdhcp`` to insert the specified extra option (or options if + used several times) into packets being transmitted. The code + specifies the option code and the hexstring is a hexadecimal string that + defines the content of the option. Care should be taken as ``perfdhcp`` + does not offer any kind of logic behind those options; they are simply + inserted into packets and sent as is. Be careful not to duplicate + options that are already inserted. For example, to insert client + class identifier (option code 60) with a string "docsis", use + "-o 60,646f63736973". The ``-o`` may be used multiple times. It is + necessary to specify the protocol family (either ``-4`` or ``-6``) before + using ``-o``. + +``-P preload`` + Initiates preload exchanges back-to-back at startup. Must be 0 + (the default) or a positive integer. + +``-r rate`` + Initiates the rate of DORA/SARR (or if ``-i`` is given, DO/SA) exchanges per + second. A periodic report is generated showing the number of + exchanges which were not completed, as well as the average response + latency. The program continues until interrupted, at which point a + final report is generated. + +``-R num-clients`` + Specifies how many different clients are used. With a value of 1 (the + default), all requests appear to come from the same client. + Must be a positive number. + +``-s seed`` + Specifies the seed for randomization, making runs of ``perfdhcp`` + repeatable. This must be 0 or a positive integer. The value 0 means that a + seed is not used; this is the default. + +``--scenario name`` + Specifies the type of scenario, and can be ``basic`` (the default) or ``avalanche``. + +``-T template-file`` + Specifies a file containing the template to use as a stream of + hexadecimal digits. This may be specified up to two times and + controls the contents of the packets sent (see the "Templates" + section above). + +``-u`` + Enables checks for address uniqueness. The lease valid-lifetime should not be shorter + than the test duration, and clients should not request an address more than once without + releasing it. + +``-v`` + Prints the version of this program. + +``-W exit-wait-time`` + Specifies the exit-wait-time parameter, which causes ``perfdhcp`` to wait for + a certain amount of time after an exit condition has been met, to receive all + packets without sending any new packets. Expressed in microseconds. + If not specified, 0 is used (i.e. exit immediately after exit + conditions are met). + +``-w script_name`` + Specifies the name of the script to be run before/after ``perfdhcp``. + When called, the script is passed a single parameter, either "start" or + "stop", indicating whether it is being called before or after ``perfdhcp``. + +``-x diagnostic-selector`` + Includes extended diagnostics in the output. This is a + string of single keywords specifying the operations for which verbose + output is desired. The selector key letters are: + + ``a`` + Prints the decoded command-line arguments. + + ``e`` + Prints the exit reason. + + ``i`` + Prints the rate-processing details. + + ``l`` + Prints the received leases. + + ``s`` + Prints the first server ID. + + ``t`` + When finished, prints timers of all successful exchanges. + + ``T`` + When finished, prints templates. + +``-y seconds`` + Time in seconds after which ``perfdhcp`` starts simulating the client waiting longer for server responses. This increases the + ``secs`` field in DHCPv4 and sends increased values in the ``Elapsed Time`` option in DHCPv6. Must be used with ``-Y``. + +``-Y seconds`` + Time in seconds during which ``perfdhcp`` simulates the client waiting longer for server responses. This increases + the ``secs`` field in DHCPv4 and sends increased values in the ``Elapsed Time`` option in DHCPv6. Must be used with ``-y``. + +DHCPv4-Only Options +~~~~~~~~~~~~~~~~~~~ + +The following options only apply for DHCPv4 (i.e. when ``-4`` is given). + +``-B`` + Forces broadcast handling. + +DHCPv6-Only Options +~~~~~~~~~~~~~~~~~~~ + +The following options only apply for DHCPv6 (i.e. when ``-6`` is given). + +``-c`` + Adds a rapid-commit option (exchanges are Solicit-Advertise). + +``-A encapsulation-level`` + Specifies that relayed traffic must be generated. The argument + specifies the level of encapsulation, i.e. how many relay agents are + simulated. Currently the only supported encapsulation-level value is + 1, which means that the generated traffic is equivalent to the amount of + traffic passing through a single relay agent. + +Template-Related Options +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following options may only be used in conjunction with ``-T`` and +control how ``perfdhcp`` modifies the template. The options may be +specified multiple times on the command line; each occurrence affects +the corresponding template file (see "Templates" above). + +``-E time-offset`` + Specifies the offset of the ``secs`` field (DHCPv4) or ``Elapsed Time`` option (DHCPv6) in the + second (i.e. Request) template; must be 0 or a positive integer. A + value of 0 disables this. + +``-I ip-offset`` + Specifies the offset of the IP address (DHCPv4) in the ``requested-ip`` + option or ``IA_NA`` option (DHCPv6) in the second (Request) template. + +``-O random-offset`` + Specifies the offset of the last octet to randomize in the template. This + must be an integer greater than 3. The ``-T`` switch must be given to + use this option. + +``-S srvid-offset`` + Specifies the offset of the ``server-id`` option in the second (Request) template. + This must be a positive integer, and the switch can only be used + when the template option (``-T``) is also given. + +``-X xid-offset`` + Specifies the offset of the transaction ID (xid) in the template. This must be a + positive integer, and the switch can only be used when the template + option (``-T``) is also given. + +Options Controlling a Test +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``-D max-drop`` + Aborts the test immediately if "max-drop" requests have been dropped. + Use ``-D 0`` to abort if even a single request has + been dropped. "max-drop" must be a positive integer. If "max-drop" + includes the suffix ``%``, it specifies the maximum percentage of + requests that may be dropped before aborting. In this case, testing of + the threshold begins after 10 requests are expected to have been + received. + +``-n num-requests`` + Initiates "num-request" transactions. No report is generated until all + transactions have been initiated/waited-for, after which a report is + generated and the program terminates. + +``-p test-period`` + Sends requests for "test-period", which is specified in the same manner + as ``-d``. This can be used as an alternative to ``-n``, or both + options can be given, in which case the testing is completed when + either limit is reached. + +``-t interval`` + Sets the delay (in seconds) between two successive reports. + +``-C separator`` + Suppresses the preliminary output and causes the interim data to + only contain the values delimited by ``separator``. Used in + conjunction with ``-t`` to produce easily parsable + reports at ``-t`` intervals. + +Arguments +~~~~~~~~~ + +``server`` + Indicates the server to test, specified as an IP address. In the DHCPv6 case, the + special name ``all`` can be used to refer to + ``All_DHCP_Relay_Agents_and_Servers`` (the multicast address FF02::1:2), + or the special name ``servers`` to refer to ``All_DHCP_Servers`` (the + multicast address FF05::1:3). The server is mandatory except where + the ``-l`` option is given to specify an interface, in which case it + defaults to ``all``. + +Errors +~~~~~~ + +``perfdhcp`` can report the following errors in the packet exchange: + +tooshort + A message was received that was too short. + +orphans + A message was received which does not match one sent to the server (i.e. + it is a duplicate message, a message that has arrived after an + excessive delay, or one that is just not recognized). + +locallimit + Local system limits have been reached when sending a message. + +Exit Status +~~~~~~~~~~~ + +``perfdhcp`` exits with one of the following status codes: + +0 + Success. + +1 + General error. + +2 + Error in command-line arguments. + +3 + No general failures in operation, but one or more exchanges were + unsuccessful. + +Usage Examples +~~~~~~~~~~~~~~ + +Here is an example that simulates regular DHCPv4 traffic of 100 DHCPv4 devices (-R 100), +10 packets per second (-r 10), shows the query/response rate details (-xi), +shows a report every 2 seconds (-t 2), and sends the packets to the IP 192.0.2.1: + +.. code-block:: console + + sudo perfdhcp -xi -t 2 -r 10 -R 100 192.0.2.1 + +Here's a similar case, but for DHCPv6. Note that the DHCPv6 protocol uses link-local +addresses, so the interface (eth0 in this example) must be specified on which to send the +traffic. ``all`` is a convenience alias for ``All_DHCP_Relay_Agents_and_Servers`` +(the multicast address FF02::1:2). It is also possible to use the ``servers`` alias +to refer to ``All_DHCP_Servers`` (the multicast address FF05::1:3). The default is ``all``. + +.. code-block:: console + + sudo perfdhcp -6 -xi -t 1 -r 1 -R 10 -l eth0 all + +The following examples simulate normal DHCPv4 and DHCPv6 traffic that, after 3 seconds, +starts pretending not to receive any responses from the server for 10 seconds. The +DHCPv4 protocol signals this by an increased ``secs`` field, while DHCPv6 uses the +``Elapsed Time`` option. In real networks, this indicates that clients are not getting +responses in a timely matter. This can be used to simulate some HA scenarios, as Kea +uses the ``secs`` field and ``Elapsed Time`` option value as one of the indicators +that the HA partner is not responding. When enabled with ``-y`` and ``-Y``, the ``secs`` +and ``Elapsed Time`` values increase steadily. + +.. code-block:: console + + sudo perfdhcp -xi -t 1 -r 1 -y 10 -Y 3 192.0.2.1 + + sudo perfdhcp -6 -xi -t 1 -r 1 -y 10 -Y 3 2001:db8::1 + +Documentation +~~~~~~~~~~~~~ + +Kea comes with an extensive Kea Administrator Reference Manual that covers +all aspects of running the Kea software - compilation, installation, +configuration, configuration examples, and much more. Kea also features a +Kea Messages Manual, which lists all possible messages Kea can print +with a brief description for each of them. Both documents are +available in various formats (.txt, .html, .pdf) with the Kea +distribution. The Kea documentation is available at +https://kea.readthedocs.io. + +Kea source code is documented in the Kea Developer's Guide, +available at https://reports.kea.isc.org/dev_guide/. + +The Kea project website is available at https://kea.isc.org. + +Mailing Lists and Support +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two public mailing lists available for the Kea project. **kea-users** +(kea-users at lists.isc.org) is intended for Kea users, while **kea-dev** +(kea-dev at lists.isc.org) is intended for Kea developers, prospective +contributors, and other advanced users. Both lists are available at +https://lists.isc.org. The community provides best-effort support +on both of those lists. + +ISC provides professional support for Kea services. See +https://www.isc.org/kea/ for details. + +History +~~~~~~~ + +The ``perfdhcp`` tool was initially coded in October 2011 by John +DuBois, Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which +included ``perfdhcp``, was released in December 2015. + +See Also +~~~~~~~~ + +:manpage:`kea-dhcp4(8)`, :manpage:`kea-dhcp6(8)`, :manpage:`kea-dhcp-ddns(8)`, +:manpage:`kea-ctrl-agent(8)`, :manpage:`kea-admin(8)`, :manpage:`kea-netconf(8)`, +:manpage:`keactrl(8)`, :manpage:`kea-lfc(8)`, Kea Administrator Reference Manual. diff --git a/doc/sphinx/man/rst_man_sources.mk b/doc/sphinx/man/rst_man_sources.mk new file mode 100644 index 0000000..933fafe --- /dev/null +++ b/doc/sphinx/man/rst_man_sources.mk @@ -0,0 +1,10 @@ +rst_man_sources += man/kea-admin.8.rst +rst_man_sources += man/kea-ctrl-agent.8.rst +rst_man_sources += man/kea-dhcp4.8.rst +rst_man_sources += man/kea-dhcp6.8.rst +rst_man_sources += man/kea-dhcp-ddns.8.rst +rst_man_sources += man/kea-lfc.8.rst +rst_man_sources += man/kea-netconf.8.rst +rst_man_sources += man/kea-shell.8.rst +rst_man_sources += man/keactrl.8.rst +rst_man_sources += man/perfdhcp.8.rst |