-:orphan:
-
-kea-shell
-8
-Kea
-kea-shell
-Text client for Control Agent process
-2017-2018
-Internet Systems Consortium, Inc. ("ISC")
-kea-shell
--h
--v
---host
---port
---path
---timeout
---service
-command
-DESCRIPTION
-===========
+..
+ Copyright (C) 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.
+
+.. highlight: console
+
+.. kea-shell:
+
+kea-shell - Text client for Control Agent process
+-------------------------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`kea-shell [**-h**] [**-v**] [**--host**] [**--port**] [**--path**] [**--timeout**] [**--service**] [**command**]
+
+Description
+~~~~~~~~~~~
The ``kea-shell`` provides a REST client for the Kea Control Agent (CA).
It takes command as a command-line parameter that is being sent to CA
with proper JSON encapsulation. Optional arguments may be specified on
-the standard input. The request it sent of HTTP and a response is
-retrieved. That response is displayed out on the standard output.
+the standard input. The request is sent via HTTP and a response is
+retrieved, displayed on the standard output.
-ARGUMENTS
-=========
+Arguments
+~~~~~~~~~
The arguments are as follows:
``-h``
- Displays help regarding command line parameters.
+ Displays help regarding command-line parameters.
``-v``
- Display the version.
+ Displays the version.
``--host``
- Specifies the host to connect to. Control Agent must be running at
+ Specifies the host to connect to. 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 specified port. If not specified, 8000 is used.
+ at the specified port. If not specified, 8000 is used.
``--path``
- Specifies the path in the URL to connect to. If not specified, empty
- path is used. As Control Agent listens at the empty path this
+ 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.
``--timeout``
Specifies the command to be sent to CA. If not specified,
"list-commands" is used.
-DOCUMENTATION
-=============
+Documentation
+~~~~~~~~~~~~~
-Kea comes with an extensive Kea User's Guide documentation that covers
+Kea comes with an extensive Kea Administrator Reference Manual that covers
all aspects of running the Kea software - compilation, installation,
-configuration, configuration examples and many more. Kea also features a
+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 typically
-available in various formats (txt, html, pdf) with your Kea
+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://kb.isc.org/docs/kea-administrator-reference-manual .
-Kea source code is documented in the Kea Developer's Guide. Its on-line
+Kea source code is documented in the Kea Developer's Guide. Its online
version is available at https://jenkins.isc.org/job/Kea_doc/doxygen/.
-Kea project website is available at:
-https://gitlab.isc.org/isc-projects/kea.
+The Kea project website is available at https://kea.isc.org.
-MAILING LISTS AND SUPPORT
-=========================
+Mailing Lists and Support
+~~~~~~~~~~~~~~~~~~~~~~~~~
-There are two mailing lists available for Kea project. kea-users
-(kea-users at lists.isc.org) is intended for Kea users, while kea-dev
+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
-http://lists.isc.org. The community provides best effort type of support
+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
-=======
+History
+~~~~~~~
The ``kea-shell`` was first coded in March 2017 by Tomek Mrugalski.
-SEE ALSO
-========
+See Also
+~~~~~~~~
-kea-ctrl-agent 8, kea-dhcp4 8, kea-dhcp6 8, kea-dhcp-ddns 8, kea-admin
-8, keactrl 8, perfdhcp 8, kea-lfc 8, Kea Administrator's Guide.
+: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.
-:orphan:
-
-keactrl
-8
-Kea
-keactrl
-Shell script for managing Kea
-2014-2018
-Internet Systems Consortium, Inc. ("ISC")
-keactrl
-command
--c
-keactrl-config-file
--s
-server[,server,...]
--v
-DESCRIPTION
-===========
-
-keactrl is a shell script which controls the startup, shutdown and
+..
+ Copyright (C) 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.
+
+.. highlight: console
+
+.. _keactrl:
+
+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
+``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``). It also
provides the means for checking the current status of the servers and
determining the configuration files in use.
-CONFIGURATION FILE
-==================
+Configuration File
+~~~~~~~~~~~~~~~~~~
-Depending on requirements, not all of the available servers need be run.
-The keactrl configuration file sets which servers are enabled and which
+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's Guide for the documentation of the
+See the Kea Administrator Reference Manual for documentation of the
parameters in the ``keactrl`` configuration file.
-OPTIONS
-=======
+Options
+~~~~~~~
``command``
- Command to be issued to the servers. It can be one of the following:
+ Specifies the command to be issued to the servers. It can be one of the following:
- start
- Start the servers.
+ **start**
+ Starts the servers.
- stop
- Stop the servers.
+ **stop**
+ Stops the servers.
- reload
- Instructs the servers to re-read the kea configuration file. This
+ **reload**
+ Instructs the servers to re-read the Kea configuration file. This
command is not supported by the Netconf agent.
- status
- Print the status of the servers.
+ **status**
+ Prints the status of the servers.
``-c|--ctrl-config keactrl-config-file``
- Specify the ``keactrl`` configuration file. Without this switch, the
- ``keactrl`` will attempt to use the file
+ Specifies the ``keactrl`` configuration file. Without this switch,
+ ``keactrl`` attempts to use the file
``[kea-install-dir]/etc/kea/keactrl.conf``.
``-s|--server server[,server,...]``
be issued. The list of servers should be separated by commas with no
intervening spaces. Acceptable values are:
- dhcp4
+ **dhcp4**
DHCPv4 server (``kea-dhcp4``).
- dhcp6
+ **dhcp6**
DHCPv6 server (``kea-dhcp6``).
- dhcp_ddns
+ **dhcp_ddns**
DHCP DDNS server (``kea-dhcp-ddns``).
- ctrl_agent
+ **ctrl_agent**
Control Agent (``kea-ctrl-agent``).
- netconf
+ **netconf**
Netconf agent (``kea-netconf``).
- all
- All servers (default) including Netconf if it was configured to be
- built.
+ **all**
+ All servers, including Netconf if it was configured to be
+ built. This is the default.
``-v|--version``
- Prints keactrl version and quits.
+ Prints the ``keactrl`` version and quits.
-DOCUMENTATION
-=============
+Documentation
+~~~~~~~~~~~~~
-Kea comes with an extensive Kea User's Guide documentation that covers
+Kea comes with an extensive Kea Administrator Reference Manual that covers
all aspects of running the Kea software - compilation, installation,
-configuration, configuration examples and many more. Kea also features a
+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 typically
-available in various formats (txt, html, pdf) with your Kea
+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://kb.isc.org/docs/kea-administrator-reference-manual .
-Kea source code is documented in the Kea Developer's Guide. Its on-line
+Kea source code is documented in the Kea Developer's Guide. Its online
version is available at https://jenkins.isc.org/job/Kea_doc/doxygen/.
-The Kea project website is available at: https://kea.isc.org.
+The Kea project website is available at https://kea.isc.org.
-MAILING LISTS AND SUPPORT
-=========================
+Mailing Lists and Support
+~~~~~~~~~~~~~~~~~~~~~~~~~
-There are two mailing lists available for Kea project. kea-users
-(kea-users at lists.isc.org) is intended for Kea users, while kea-dev
+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
-http://lists.isc.org. The community provides best effort type of support
+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
-========
+See Also
+~~~~~~~~
-kea-dhcp4 8, kea-dhcp6 8, kea-dhcp-ddns 8, kea-ctrl-agent 8, kea-netconf
-8, kea-admin 8, kea-netconf 8, perfdhcp 8, kea-lfc 8, Kea
-Administrator's Guide.
+: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.
-:orphan:
-
-perfdhcp
-8
-Kea
-perfdhcp
-DHCP benchmarking tool
-2016-2018
-Internet Systems Consortium, Inc. ("ISC")
-perfdhcp
--1
--4|-6
--A
-encapsulation-level
--b
-base
--B
--c
--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
--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
--t
-report
--T
-template-file
--v
--W
-exit-wait-time
--w
-wrapped
--x
-diagnostic-selector
--X
-xid-offset
-server
-DESCRIPTION
-===========
+..
+ Copyright (C) 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.
+
+.. highlight: console
+
+.. _perfdhcp:
+
+perfdhcp - DHCP benchmarking tool
+---------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`perfdhcp` [**-1**] [**-4**|**-6**] [**-A** encapsulation-level] [**-b** base] [**-B**] [**-c**] [**-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] [**-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] [-t report] [-T template-file] [-v] [-W exit-wait-time] [-w wrapped] [-x diagnostic-selector] [-X xid-offset] [server]
+
+Description
+~~~~~~~~~~~
``perfdhcp`` is a DHCP benchmarking tool. It provides a way of measuring
the performance of DHCP servers by generating large amounts of traffic
By default, 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
+possible to configure ``perfdhcp`` to send DHCPv6 RENEW and RELEASE messages
at a specified rate in parallel with the DHCPv6 four-way exchanges.
When running a performance test, ``perfdhcp`` will exchange packets with
-the server under test as fast as possible unless the ``-r`` is given to
+the server under test as fast 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
-=========
+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 server
-performs DNS updates. This may be used to discover performance
+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).
The template file holds the DHCP packet represented as a stream of ASCII
hexadecimal digits and 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
-(so in the file, '12B4' is the same as '12 B4' which is the same as '1 2
-B 4')
+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
+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 will inject the current elapsed
-time value into this field before sending the packet to the server.
+If the offset is specified, ``perfdhcp`` will inject the current elapsed-time
+value into this field before sending the packet to the server.
-In many scenarios, ``perfdhcp`` needs to simulate multiple clients
-(having unique client identifier). Since packets for each client are
+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
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
+simulated clients is between 1 and 255, only one byte (to which the
randomization offset points) will be randomized. If the number of
simulated clients is between 256 and 65535, two bytes will be
-randomized. Note, that two last bytes of the client identifier will be
-randomized in this case: the byte which randomization offset parameter
+randomized. Note that the last two bytes of the client identifier will be
+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 will be
-randomized; and so on.
+randomized, and so on.
-Templates may be currently used to generate packets being sent to the
+Templates may currently be used to generate packets being sent to the
server in 4-way exchanges, i.e. SOLICIT, REQUEST (DHCPv6) and DISCOVER,
REQUEST (DHCPv4). They cannot be used when RENEW or RELEASE packets are
being sent.
-OPTIONS
-=======
+Options
+~~~~~~~
``-1``
- Take the server-ID option from the first received message.
+ Takes the server-ID option from the first received message.
``-4``
- DHCPv4 operation; this is the default. It is incompatible with the
+ Establishes DHCPv4 operation; this is the default. It is incompatible with the
``-6`` option.
``-6``
- DHCPv6 operation. This is incompatible with the ``-4`` option.
+ Establishes DHCPv6 operation. This is incompatible with the ``-4`` option.
``-b basetype=value``
- The base MAC or DUID used to simulate different clients. The basetype
+ 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 must not
- be longer than 64 bytes and the length must be less than 128
+ 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``
- Specify the time after which a request is treated as having been
+ 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 second.
Specifies the type of lease being requested from the server. It may
be one of the following:
- address-only
+ **address-only**
Only regular addresses (v4 or v6) will be requested.
- prefix-only
+ **prefix-only**
Only IPv6 prefixes will be requested.
- address-and-prefix
+ **address-and-prefix**
Both IPv6 addresses and prefixes will be requested.
The ``-e prefix-only`` and ``-e address-and-prefix`` forms may not be used
with the ``-4`` option.
``-f renew-rate``
- Rate at which DHCPv4 or DHCPv6 renew requests are sent to a server.
+ Specifies the rate at which DHCPv4 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
+ 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``
- thread-mode can be either 'single' or 'multi'. In multi-thread mode
- packets are received in separate thread. This allows better
- utilisation of CPUs. In single CPU system it is better to run in 1
- thread to avoid blocking of threads each other. If more than 1 CPU is
- present in the system then multi-thread mode is default otherwise
- single-thread is default.
+ 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``
- Print help and exit.
+ Prints help and exits.
``-i``
- Do only the initial part of the exchange: DISCOVER-OFFER if ``-4`` is
+ 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``,
used with multiple instances of ``-O``, ``-T`` and ``-X``.
``-l local-addr|interface``
- For DHCPv4 operation, specify the local hostname/address to use when
+ 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, specify the name of the network interface
+ For DHCPv6 operation, specifies the name of the network interface
through which exchanges are initiated.
``-L local-port``
- Specify the local port to use. This must be zero or a positive
+ 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``
- A text file containing a list of MAC addresses, one per line. If
+ Specifies a text file containing a list of MAC addresses, one per line. If
provided, a MAC address will be chosen randomly from this list for
- every new exchange. In the DHCPv6 case, MAC addresses are used to
+ 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``
- Specify the remote port to use. This must be zero or a positive
+ 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``
- This forces perfdhcp to insert specified extra option (or options if
+ Forces ``perfdhcp`` to insert the specified extra option (or options if
used several times) into packets being transmitted. The code
- specifies 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're simply
- inserted into packets being sent as is. Be careful not to insert
+ 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', you can use
+ 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 protocol family (either ``-4`` or ``-6``) before
+ necessary to specify the protocol family (either ``-4`` or ``-6``) before
using ``-o``.
``-P preload``
- Initiate preload exchanges back to back at startup. preload must be 0
+ Initiates preload exchanges back-to-back at startup. Must be 0
(the default) or a positive integer.
``-r rate``
- Initiate rate DORA/SARR (or if ``-i`` is given, DO/SA) exchanges per
+ 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``
- Specify how many different clients are used. With a value of 1 (the
- default), all requests seem to come from the same client. num-clients
- must be a positive number.
+ Specifies how many different clients are used. With a value of 1 (the
+ default), all requests seem to come from the same client.
+ Must be a positive number.
``-s seed``
- Specify the seed for randomization, making runs of ``perfdhcp``
- repeatable. seed is 0 or a positive integer. The value 0 means that a
+ 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.
``-T template-file``
- The name of a file containing the template to use as a stream of
+ 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"
+ controls the contents of the packets sent (see the "Templates"
section above).
``-v``
- Print the version of this program.
+ Prints the version of this program.
``-W exit-wait-time``
- Specifies exit-wait-time parameter, that makes perfdhcp wait for
- exit-wait-time us after an exit condition has been met to receive all
+ Specifies the exit-wait-time parameter, which causes ``perfdhcp`` to wait for
+ exit-wait-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 wrapped``
- Command to call with a single parameter of "start" or "stop" at the
- beginning/end of the program.
+``-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``
- Include extended diagnostics in the output. diagnostic-selector is a
- string of single-keywords specifying the operations for which verbose
+ 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
- Print the decoded command line arguments.
+ **a**
+ Prints the decoded command line arguments.
- e
- Print the exit reason.
+ **e**
+ Prints the exit reason.
- i
- Print rate processing details.
+ **i**
+ Prints the rate processing details.
- s
- Print the first server-ID.
+ **s**
+ Prints the first server-ID.
- t
- When finished, print timers of all successful exchanges.
+ **t**
+ When finished, prints timers of all successful exchanges.
- T
- When finished, print templates
+ **T**
+ When finished, prints templates.
DHCPv4-Only Options
-------------------
The following options only apply for DHCPv4 (i.e. when ``-4`` is given).
``-B``
- Force broadcast handling.
+ Forces broadcast handling.
DHCPv6-Only Options
-------------------
The following options only apply for DHCPv6 (i.e. when ``-6`` is given).
``-c``
- Add a rapid commit option (exchanges will be SOLICIT-ADVERTISE).
+ Adds a rapid-commit option (exchanges will be SOLICIT-ADVERTISE).
``-F release-rate``
- Rate at which IPv6 RELEASE requests are sent to a server. This value
+ Specifies the rate at which IPv6 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
+ 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.
+ rate value.
``-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 an equivalent of the
+ 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
-Offset of the (DHCPv4) secs field or (DHCPv6) elapsed-time option in the
-(second i.e. REQUEST) template and must be 0 or a positive integer: a
-value of 0 disables this.
-
--I
-ip-offset
-Offset of the (DHCPv4) IP address in the requested-IP option / (DHCPv6)
-IA_NA option in the (second/request) template.
-
--O
-random-offset
-Offset of the last octet to randomize in the template. random-offset
-must be an integer greater than 3. The ``-T`` switch must be given to
-use this option.
-
--S
-srvid-offset
-Offset of the server-ID option in the (second/request) template.
-srvid-offset must be a positive integer, and the switch can only be used
-when the template option (``-T``) is also given.
-
--X
-xid-offset
-Offset of the transaction ID (xid) in the template. xid-offset must be a
-positive integer, and the switch can only be used when the template
-option (``-T``) is also given.
+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``
- Abort the test immediately if max-drop requests have been dropped.
+ 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
+ been dropped. **max-drop** must be a positive integer. If **max-drop**
includes the suffix '%', it specifies a maximum percentage of
requests that may be dropped before abort. In this case, testing of
the threshold begins after 10 requests have been expected to be
received.
``-n num-requests``
- Initiate num-request transactions. No report is generated until all
+ 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``
- Send requests for test-period, which is specified in the same manner
- as ``-d``. This can be used as an alternative to ``-n``, or both
+ 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.
---------
server
- Server to test, specified as an IP address. In the DHCPv6 case, the
+ 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
the ``-l`` option is given to specify an interface, in which case it
defaults to 'all'.
-ERRORS
-======
+Errors
+~~~~~~
``perfdhcp`` can report the following errors in the packet exchange:
A message was received that was too short.
orphans
- Received a message which doesn't match one sent to the server (i.e.
+ 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
- Reached local system limits when sending a message.
+ Local system limits have been reached when sending a message.
-EXIT STATUS
-===========
+Exit Status
+~~~~~~~~~~~
``perfdhcp`` can exit with one of the following status codes:
No general failures in operation, but one or more exchanges were
unsuccessful.
-MAILING LISTS AND SUPPORT
-=========================
+Mailing Lists and Support
+~~~~~~~~~~~~~~~~~~~~~~~~~
-There are two mailing lists available for Kea project. kea-users
-(kea-users at lists.isc.org) is intended for Kea users, while kea-dev
+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
-http://lists.isc.org. The community provides best effort type of support
+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
-=======
+History
+~~~~~~~
The ``perfdhcp`` tool was initially coded in October 2011 by John
-DuBois, Francis Dupont and Marcin Siodelski of ISC. Kea 1.0.0 that
-included perfdhcp was released in December 2015.
+DuBois, Francis Dupont, and Marcin Siodelski of ISC. Kea 1.0.0, which
+included ``perfdhcp``, was released in December 2015.
-SEE ALSO
-========
+See Also
+~~~~~~~~
-kea-dhcp4 8, kea-dhcp6 8, kea-dhcp-ddns 8, kea-ctrl-agent 8, kea-admin
-8, kea-netconf 8, keactrl 8, kea-lfc 8, Kea Administrator's Guide.
+: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.
projects / thirdparty / kea.git / commitdiff
