Summary
Stork 2.4 with Kea 3.0 may have issues due to default permissions of the Kea control sockets. Fixes are planned for future release(s), but some workarounds are possible immediately.
Environment
- Stork 2.4.0 or later
- Kea 3.0.0 or later
Symptoms
The Stork agent (stork-agent) running on a Kea server will fail to connect to the Kea API offered by the Kea daemons.
The Stork server web UI will show messages about daemon communication problems, such as:
- Stork server reports communication problems for number daemons on the monitored machines
- There is a communication issue with the daemon.
The Stork agent will repeatedly produce a large log message with the key phrases failed to connect to unix socket and permission denied. A complete log sample is provided below.
Click to see original log message
Mar 05 17:17:23 luke stork-agent[5298]: time="2026-03-05 17:17:23" level="debug" msg="Connection to Kea failed, trying another control socket" file=" kea.go:751 " error="failed to connect to unix socket: /var/run/kea/kea-dhcp4-socket: dial unix /var/run/kea/kea-dhcp4-socket: connect: permission denied" index="0" stackTrace="dial unix /var/run/kea/kea-dhcp4-socket: connect: permission denied\nfailed to connect to unix socket: /var/run/kea/kea-dhcp4-socket\nisc.org/stork/agent.(*keaSocketConnector).sendPayload\n\t/builds/isc-projects/stork/backend/agent/kea.go:664\nisc.org/stork/agent.(*multiConnector).sendPayload\n\t/builds/isc-projects/stork/backend/agent/kea.go:747\nisc.org/stork/agent.(*keaDaemon).sendCommand\n\t/builds/isc-projects/stork/backend/agent/kea.go:67\nisc.org/stork/agent.(*keaDaemon).fetchConfig\n\t/builds/isc-projects/stork/backend/agent/kea.go:113\nisc.org/stork/agent.(*keaDaemon).RefreshState\n\t/builds/isc-projects/stork/backend/agent/kea.go:524\nisc.org/stork/agent.(*monitor).refreshDaemons\n\t/builds/isc-projects/stork/backend/agent/monitor.go:484\nisc.org/stork/agent.(*monitor).run\n\t/builds/isc-projects/stork/backend/agent/monitor.go:302\nruntime.goexit\n\t/builds/isc-projects/stork/tools/golang/go/src/runtime/asm_amd64.s:1693"
Click to see readable log message
Mar 05 17:17:23 luke stork-agent[5298]
time = 2026-03-05 17:17:23
level = debug
msg = Connection to Kea failed, trying another control socket
file = kea.go:751
error =
failed to connect to unix socket: /var/run/kea/kea-dhcp4-socket:
dial unix /var/run/kea/kea-dhcp4-socket:
connect: permission denied
index = 0
stackTrace =
dial unix /var/run/kea/kea-dhcp4-socket: connect: permission denied
failed to connect to unix socket: /var/run/kea/kea-dhcp4-socket
isc.org/stork/agent.(*keaSocketConnector).sendPayload
/builds/isc-projects/stork/backend/agent/kea.go:664
isc.org/stork/agent.(*multiConnector).sendPayload
/builds/isc-projects/stork/backend/agent/kea.go:747
isc.org/stork/agent.(*keaDaemon).sendCommand
/builds/isc-projects/stork/backend/agent/kea.go:67
isc.org/stork/agent.(*keaDaemon).fetchConfig
/builds/isc-projects/stork/backend/agent/kea.go:113
isc.org/stork/agent.(*keaDaemon).RefreshState
/builds/isc-projects/stork/backend/agent/kea.go:524
isc.org/stork/agent.(*monitor).refreshDaemons
/builds/isc-projects/stork/backend/agent/monitor.go:484
isc.org/stork/agent.(*monitor).run
/builds/isc-projects/stork/backend/agent/monitor.go:302
runtime.goexit
/builds/isc-projects/stork/tools/golang/go/src/runtime/asm_amd64.s:1693
Cause
The default ownership and permissions of the control socket for the Kea daemon deny write permission to the Stork agent process.
Workarounds
The following are offered as potential workarounds. These workarounds have received limited testing and may have disadvantages. Be sure to read the description and consider the implications for your environment before implementing any of these workarounds.
Kea HTTP listener
Configuring the Kea daemon(s) to provide an additional control socket in the form of an HTTP listener on a TCP port will allow the Stork agent to connect.
Advantages
- Entirely within the scope of standard Kea configuration
- Can be protected with passwords or TLS certificates
- Robust in the face of performance changes
Disadvantages
- Potentially adds exposure of the Kea API to the network
- Any other process on the same server will also be able to connect to that socket
- If you use a non-local address, any remote system will also be able to connect to that socket
- If a bad actor can submit API commands, they can tell Kea to do anything they want
Procedure
Modify the Kea daemon config file (for example, /etc/kea/kea-dhcp4.conf) to include an appropriate listener in the control-sockets section. For example, the end result might appear as follows:
"control-sockets": [
{
"socket-type": "http",
"socket-address": "127.0.0.1",
"socket-port": 8000,
},
{
"socket-type": "unix",
"socket-name": "/var/run/kea/kea-dhcp4-socket"
}
],
In the above, note how the HTTP socket specifies the loopback address (127.0.0.1) to limit connections to clients on the same machine as the Kea daemon.
The socket type can be specified as https to use SSL/TLS, but this will require configuration of certificates for authentication. See the Kea ARM for more on configuring Kea to use TLS certificates.
systemd ExecStartPost
Advantages
- Keeps the Kea API entirely within the local Unix filesystem, with no network or TCP exposure
Disadvantages
- Only works with systemd
- Will be sensitive to Kea startup timings
Procedure
On the machine with the Kea server and Stork agent, invoke the command: sudo systemctl edit isc-kea-dhcp4-server
In the above, adjust the unit name as appropriate. The dhcp4 part may need to be dhcp6 or dhcp-ddns, depending on which daemon you are configuring. Depending on distribution and packaging, you may need to omit the isc- prefix and/or -server suffix.
Once you have the editor open, add the following two lines in the indicated space in the file:
[Service]
ExecStartPost=sleep 5 ; chmod g+w /var/run/kea/kea-dhcp4-socket
In the above, sleep 5 forces a delay before attempting the chmod command. This is needed because it takes a few moments for the Kea daemon to read its config and create the socket. If your Kea config is more large/complex/slow, you may need to increase the sleep time.