[Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent

[Ben Scott]

On 12/9/25 03:31, Oliver wrote:
 > echo '{ "command": "list-commands" }' | \ kea-shell --host 127.0.0.1 --
 > port 8000 \ --auth-user xxx \ --auth-password-file /etc/kea/kea-api-
 > password \ --service dhcp4

   The above is not correct usage.  The API command has to be provided 
on the command line.  The API arguments are provided on standard input. 
So one should not give "command" in standard input, but rather, whatever 
one would put inside the "arguments" map (object).  If no arguments are 
needed, the input should be empty/null.

   The documentation could be clearer in this regard.  In particular, 
the man page should make this explicit.  The ARM does a better job but 
could still stand some improvement.  I will try to get some changes 
submitted for that soon.

	https://kea.readthedocs.io/en/latest/arm/shell.html

 >     This also hangs with no output:
 > kea-shell --host 127.0.0.1 --port 8000 \ --service dhcp4 \ list-commands

   It is not "hung" (in the sense of improperly functioning).  It is 
blocked on standard input.  You are not providing anything as input, so 
it sits there waiting for you to do so.

   kea-shell is a very simple program.  It has no knowledge of the Kea 
API; it simply passes what you give it on to Kea.  As such, it still 
expects an API argument payload -- it does not "know" if an API command 
needs arguments or not.

   The simplest possible invocation of kea-shell looks like:

	kea-shell < /dev/null

   The defaults are:

	host = localhost
	port = 8000
	API command = list-commands
	service = none
	authentication = none

   Thus, the above command is equivalent to:

	kea-shell --host 127.0.0.1 --port 8000 list-commands < /dev/null

   Either of the above two command lines will invoke "list-commands" 
against whatever is listening on port 8000.  If that is kea-ctrl-agent 
(the only supported scenario before 3.0), you get the commands available 
on the Kea Control Agent.  On Kea 3.0, you get the commands for whatever 
daemon you are talking to (kea-ctrl-agent or kea-dhcp4 or whatever).

   For your case, you probably want something like:

	kea-shell --service dhcp4 \
		--auth-user xxx \
		--auth-password-file /etc/kea/kea-api-password \
		< /dev/null

   For API commands which do take input, it might look like this:

	echo ' "ip-address": "192.0.2.202" ' |\
		kea-shell --service dhcp4 lease4-del

   Note how the input is just the arguments to the API (without the API 
command name).  Note also that the API command name is specified as an 
argument to "kea-shell" itself.

 >     Is it expected behavior that |kea-shell| ignores HTTP/authentication
 >     parameters in the ISC Debian packages?

   No.  In my experience, it does not ignore these parameters.

 >     Should |kea-shell| be able to communicate with an authenticated
 >     Control Agent, or is this a known limitation?

   Yes, kea-shell supports both HTTP basic authentication as well as TLS 
client certificates.

 >     Is |kea-shell| still supposed to use the UNIX control socket even
 >     when HTTP parameters are explicitly provided?

   No.  kea-shell never uses the control sockets.  It either talks to 
kea-ctrl-agent, or in 3.0 and later, it can talk to the services 
directly (if the services are configured with HTTP listeners).

   Hope this helps,

   -- Ben

-- 
Any opinions expressed in this message are those of the author alone.
All information is provided without warranty of any kind.