mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-29 13:07:50 +00:00
Code Issues Releases Wiki Activity

[#1041] Updated docs about status-get

Browse Source 
Added new HA specific section too.
This commit is contained in:
Marcin Siodelski 2019-12-13 16:03:05 +01:00
parent cf7f6c97ea
commit 3d76d8f1a0
3 changed files with 92 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/sphinx/api/status-get.json
View File

@ -1,7 +1,7 @@
{
"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>",
" }",
" }",
" }",
"}"
],

21
doc/sphinx/arm/ctrl-channel.rst
View File

@ -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
processing).
* 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`
section.
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:

60
doc/sphinx/arm/hooks-ha.rst
View File

@ -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.