Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent
[laugh] Vadim Yakovenko reacted to your message: From: Kea-users on behalf of Ben Scott Sent: Wednesday, December 10, 2025 4:56:20 AM To: [email protected] Subject: Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent CAUTION: This email is from an external source. Do not click links or open attachments unless you recognize the sender and know the content is safe. 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. -- ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information. To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users. [email protected] -- ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information. To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users. [email protected]
Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent
On 12/10/25 03:35, Oliver wrote: > Thanks for the detailed explanation. Everything makes sense now. After > following your examples, |kea-shell| works correctly. Great! You're welcome, and I'm glad I could help. > One small note: |--auth-password| works fine, but |--auth-password-file| > still results in 401 responses on my setup. I'll add that to my list of things to look into. Thanks for the tip. -- Ben -- Any opinions expressed in this message are those of the author alone. All information is provided without warranty of any kind. -- ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information. To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users. [email protected]
Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent
Hi Ben,
Thanks for the detailed explanation. Everything makes sense now. After
following your examples, kea-shell works correctly.
One small note: --auth-password works fine, but --auth-password-file still
results in 401 responses on my setup. My guess is that it may be related to
how the tool parses certain characters from the file (the same password
works when passed directly). Not a big issue — I’ll just use --auth-password
.
Thanks again for your help.
Oliver
El mié, 10 dic 2025 a las 4:56, Ben Scott () escribió:
> 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.
>
> --
> ISC funds the development of this software with paid support
> subscriptions. Contact us at https://www.isc.org/contact/ for more
> information.
>
> To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users.
> [email protected]
>
>
--
ISC funds the development of this software with paid support subscriptions.
Contact us at https://www.isc.org/contact/ for more information.
To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users.
[email protected]
Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent
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.
--
ISC funds the development of this software with paid support subscriptions.
Contact us at https://www.isc.org/contact/ for more information.
To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users.
[email protected]
Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent
Hi Ben,
Thanks for the clarification. I did some additional testing today and can
now provide complete examples of what I’m seeing.
Environment details:
1.
Debian 12
2.
Kea installed from official ISC packages (isc-kea-admin, isc-kea-dhcp4,
etc.)
3.
kea-shell located at /usr/sbin/kea-shell
4.
kea-shell --help shows support for HTTP, authentication and Control
Agent parameters, including:
-
--host
-
--port
-
--service
-
--auth-user
-
--auth-password-file
The issue is that kea-shell appears to ignore these parameters at runtime.
Examples:
1.
This command hangs indefinitely and produces no output until I press
Ctrl-C:
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
2.
This also hangs with no output:
kea-shell --host 127.0.0.1 --port 8000 \
--service dhcp4 \
list-commands
3.
Even running the simplest possible HTTP-based invocation results in the
same hanging behavior.
In contrast, using curl with the same Control Agent, host/port and
authentication works perfectly. For example:
curl -u xxx:"$(cat /etc/kea/kea-api-password)" \
-H "Content-Type: application/json" \
-X POST \
-d '{ "command": "version-get", "service": [ "dhcp4" ] }' \
http://127.0.0.1:8000/
returns the expected JSON response immediately.
This leads me to wonder:
1.
Is it expected behavior that kea-shell ignores HTTP/authentication
parameters in the ISC Debian packages?
2.
Should kea-shell be able to communicate with an authenticated Control
Agent, or is this a known limitation?
3.
Is kea-shell still supposed to use the UNIX control socket even when
HTTP parameters are explicitly provided?
Any clarification would be appreciated.
Thanks again for the guidance.
Oliver
El vie, 5 dic 2025 a las 22:15, Ben Scott () escribió:
> Hello,
>
> On 12/5/25 07:01, Oliver wrote:
> > kea-shell --auth-user ... lease4-del ...
>
>That above, of course, not a valid kea-shell command. It is *part*
> of a command. The parts you omitted are likely necessary for us to
> understand what is going on. By all means, substitute placeholders for
> things like passwords and names and such, but please provide complete
> information. We cannot diagnose a partial command. We need to know all
> the kea-shell options you used, and the API content you fed into it.
>
>A complete invocation of kea-shell, with HTTP authentication, is
> generally going to look something like this (all one line):
>
> echo ' "ip-address": "192.0.2.202" ' | kea-shell --service dhcp4
> --auth-user bscott --auth-pass drowssap
>
> > I also noticed that the Control Agent rejects attempts to use absolute
> > paths (e.g., /run/kea/kea4-ctrl-socket) with the error:> “invalid
> path specified, supported path is /etc/kea”
> > so I cannot use explicit absolute socket paths.
>
>Well, you can use absolute paths, but they are restricted to the
> directory acceptable for the type of file in question. These and other
> restrictions were introduced in Kea 2.6.3, 2.7.8, and 3.0.0, in an
> effort to harden Kea against abuse. The acceptable directories are set
> at build time, but can be overridden with environment variables. See
> the release notes for more information.
>
>For example, see the following page, starting at item #32:
>
>
> https://gitlab.isc.org/isc-projects/kea/-/wikis/Release-Notes/release-notes-3.0.0
>
>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.
>
> --
> ISC funds the development of this software with paid support
> subscriptions. Contact us at https://www.isc.org/contact/ for more
> information.
>
> To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users.
> [email protected]
>
>
--
ISC funds the development of this software with paid support subscriptions.
Contact us at https://www.isc.org/contact/ for more information.
To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users.
[email protected]
Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent
Hello, On 12/5/25 07:01, Oliver wrote: kea-shell --auth-user ... lease4-del ... That above, of course, not a valid kea-shell command. It is *part* of a command. The parts you omitted are likely necessary for us to understand what is going on. By all means, substitute placeholders for things like passwords and names and such, but please provide complete information. We cannot diagnose a partial command. We need to know all the kea-shell options you used, and the API content you fed into it. A complete invocation of kea-shell, with HTTP authentication, is generally going to look something like this (all one line): echo ' "ip-address": "192.0.2.202" ' | kea-shell --service dhcp4 --auth-user bscott --auth-pass drowssap I also noticed that the Control Agent rejects attempts to use absolute > paths (e.g., /run/kea/kea4-ctrl-socket) with the error:> “invalid path specified, supported path is /etc/kea” so I cannot use explicit absolute socket paths. Well, you can use absolute paths, but they are restricted to the directory acceptable for the type of file in question. These and other restrictions were introduced in Kea 2.6.3, 2.7.8, and 3.0.0, in an effort to harden Kea against abuse. The acceptable directories are set at build time, but can be overridden with environment variables. See the release notes for more information. For example, see the following page, starting at item #32: https://gitlab.isc.org/isc-projects/kea/-/wikis/Release-Notes/release-notes-3.0.0 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. -- ISC funds the development of this software with paid support subscriptions. Contact us at https://www.isc.org/contact/ for more information. To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users. [email protected]
Re: [Kea-users] Kea 3.0.1 (Debian) – kea-shell hangs when executing lease4 commands through Control Agent
Just to add more detail: in my setup kea-shell hangs immediately when I run
it locally on the server, and it never responds unless I interrupt it.
The Control Agent is configured with HTTP basic authentication, and
kea-shell on Debian doesn’t seem to handle this scenario. Stork works fine
with the same authentication, and I can successfully send commands using curl
-u user:password, so the Control Agent API itself is functioning correctly.
Is this the expected behavior? In other words, is it normal that kea-shell
cannot send commands when Control Agent authentication is enabled? Thanks
beforehand.
Cheers...
El vie, 5 dic 2025 a las 12:01, Oliver () escribió:
> Hello,
>
> I am using Kea 3.0.1 on Debian with the default Debian packages, and I am
> experiencing an issue where *kea-shell hangs indefinitely* when I try to
> execute any commands that should go through the Control Agent, such as:
>
> lease4-get
> lease4-del
> list-commands
>
> *What triggered this:*
> I needed to delete an active lease because a printer was replaced, and Kea
> was still holding a lease for the old MAC address. When I tried to run:
>
> kea-shell --auth-user ... lease4-del ...
>
> the command never returned. It authenticates successfully, but just hangs
> forever.
>
> *Relevant details:*
>
>-
>
>Kea DHCPv4 is working normally.
>-
>
>Stork also works normally.
>-
>
>Control Agent starts successfully and listens on port 8000.
>-
>
>Authentication works (I get 401 if wrong credentials).
>-
>
>The DHCPv4 control socket exists at:
>/var/run/kea/kea4-ctrl-socket
>-
>
>In kea-ctrl-agent.conf I have:
>
>"control-sockets": {
> "dhcp4": {
>"socket-type": "unix",
>"socket-name": "kea4-ctrl-socket"
> }}
>
>-
>
>However, kea-shell hangs as soon as the Control Agent tries to forward
>the request to DHCPv4. No errors appear, just an indefinite wait.
>
> I also noticed that the Control Agent rejects attempts to use absolute
> paths (e.g., /run/kea/kea4-ctrl-socket) with the error:
> *“invalid path specified, supported path is /etc/kea”*
> so I cannot use explicit absolute socket paths.
>
> *Question:*
> How can I correctly configure the Control Agent in Kea 3.0.1 (Debian
> packaging) so that lease-related commands (lease4-get, lease4-del) work
> through kea-shell without hanging?
> Is there an officially supported way to specify the socket directory/path
> for the DHCPv4 control socket in this version?
>
> Thank you very much.
> Oliver
>
--
ISC funds the development of this software with paid support subscriptions.
Contact us at https://www.isc.org/contact/ for more information.
To unsubscribe visit https://lists.isc.org/mailman/listinfo/kea-users.
[email protected]
