Commit 3d76d8f1 authored by Marcin Siodelski's avatar Marcin Siodelski

[#1041] Updated docs about status-get

Added new HA specific section too.
parent cf7f6c97
"avail": "1.7.3",
"brief": [
"This command returns server runtime information.",
"This command returns server's runtime information.",
"It takes no arguments."
"cmd-syntax": [
......@@ -12,16 +12,28 @@
"description": "See <xref linkend=\"command-status-get\"/>",
"name": "status-get",
"resp-comment": [
"If the HA hook is loaded it adds HA servers info to the response."
"If the libdhcp_ha (High Availability) hooks library is loaded by the DHCP server receiving this command the response also includes the HA specific status information of the server receiving the command and its partner's status."
"resp-syntax": [
" \"result\": 0,",
" \"result\": <integer>,",
" \"arguments\": {",
" \"pid\": 1234,",
" \"uptime\": 59,",
" \"reload\": 10,",
" ...",
" \"pid\": <integer>,",
" \"uptime\": <uptime in seconds>,",
" \"reload\": <time since reload in seconds>,",
" \"ha-servers\": {",
" \"local\": {",
" \"role\": <role of this server as in the configuration file>,",
" \"scopes\": <list of scope names served by this server>,",
" \"state\": <HA state name of the server receiving the command>,",
" },",
" \"remote\": {",
" \"in-touch\": <indicates if this server communicated with remote>,",
" \"last-scopes\": <list of scopes served by partner>,",
" \"last-state\": <HA state name of the partner>,",
" \"role\": <partner role>",
" }",
" }",
" }",
......@@ -543,7 +543,7 @@ The ``dhcp-enable`` command globally enables the DHCP service.
The status-get Command
The ``status-get`` command returns server runtime information:
The ``status-get`` command returns server's runtime information:
- pid: process id.
......@@ -551,20 +551,25 @@ The ``status-get`` command returns server runtime information:
- reload: number of seconds since the last configuration (re)load.
- ha-servers: HA hook information when the hook was loaded:
- ha-servers: HA specific status information about the DHCP servers
configured to use HA hooks library:
* local: for the local server the state, the role (primary,
secondary, ...) and scopes (i.e. what the server is actually
* remote: for the remote server the last known state and the role
(scopes should be available in a future release)
* remote: for the remote server the last known state, served
HA scopes and the role of the server in HA relationship.
.. note::
The ``ha-servers`` information is only returned when the command is
sent to the DHCP servers being in the HA setup. This parameter is
never returned when the ``status-get`` command is sent to the
Control Agent or DDNS deamon.
To learn more about the HA status information returned by the
``status-get`` command please refer to the the :ref:`command-ha-status-get`
The HA local server does not always know the current state of the
HA remote server. The command (or the ``ha-heartbeat``) should be
sent to the remote server as explained in HA :ref:`ha-server-states`.
.. _command-server-tag-get:
......@@ -1299,3 +1299,63 @@ to the failing server allows for detecting the failure.
servers may not reflect issues with one of the servers that just began.
.. _command-ha-status-get:
The status-get Command
The ``status-get`` is the general purpose command supported by several Kea deamons,
not only DHCP servers. However, when sent to the DHCP server with HA enabled, it
can be used to get insight into the details of the HA specific status information
of the servers being in the HA configuration. Not only does the response contain
the status information of the server receiving this command but also the
information about its partner, if this information is available.
The following is the example response to the ``status-get`` command including
the HA status of two load balancing servers:
"result": 0,
"text": "",
"arguments": {
"pid": 1234,
"uptime": 3024,
"reload": 1111,
"ha-servers": {
"local": {
"role": "primary",
"scopes": [ "server1" ],
"state": "load-balancing"
"remote": {
"in-touch": true,
"role": "secondary",
"last-scopes": [ "server2" ],
"last-state": "load-balancing"
The ``ha-servers`` map contains two structures: ``local`` and ``remote``. The former
contains the status information of the server which received the command. The
latter contains the status information known to the local server about the
partner. The ``role`` of the partner server is gathered from the local
configuration file, therefore it should always be available. The remaining
status information such as ``last-scopes`` and ``last-state`` is not available
until the local server communicates with the remote by successfully sending
the ``ha-heartbeat`` command. If at least one such communication took place,
the returned value of ``in-touch`` parameter is set to ``true``. By examining
this value, the command sender can determine whether the information about
the remote server is reliable.
The ``last-scopes`` and ``last-state`` contain the information about the
HA scopes served by the partner and its state. Note that this information
is gathered during the heartbeat command exchange, so it may not be
accurate if the communication problem occur between the partners and this
status information is not refreshed. In such case, it may be useful to
send the ``status-get`` command to the partner server directly to check
its current state.
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment