Stork 2.4 and Kea socket permissions

Updated
  • Updated on Mar 31, 2026
  • Published on Mar 6, 2026
  • 6 minute(s) read
  • Ben Scott
 Prev Next

Summary

Stork 2.4 with Kea 3.0 may have issues due to default permissions of the Kea control sockets. The underlying issue is corrected in Kea 3.0.3; upgrading Kea is the recommended solution. Workarounds are possible for earlier version of Kea.

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.

Solution

Upgrade to Kea 3.0.3 or later.

Workarounds

The following are offered as potential workarounds, for older versions of Kea. 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

Configuring systemd to fix-up permissions on the control socket after starting Kea will allow the Stork agent to connect.

Advantages

  • Keeps the Kea API entirely within the local Unix filesystem, with no network or TCP exposure
  • Easy to implement with systemd

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.

Wrapper script

Wrapping Kea in a shell script that fixes-up permissions on the control socket after starting Kea will allow the Stork agent to connect.

Advantages

  • Keeps the Kea API entirely within the local Unix filesystem, with no network or TCP exposure
  • Works without systemd

Disadvantages

  • Requires scripting knowledge
  • Will be sensitive to Kea startup timings

Description

Wrap each Kea daemon in a script that starts the daemon, sleeps for a few seconds, and then runs chmod to fix up permissions on the socket. If Kea is being started or supervised from an init system that already uses scripts, one can modify that existing script.

Specifics will be dependent on the local environment. Implementation will require scripting knowledge by the installation administrator(s).

More information

Kea API connection architecture

Stork uses the Kea API for almost all interaction with Kea.

Prior to Kea 3.0, the only supported method to access the Kea API was via the Kea Control Agent (KCA). The KCA acted as an HTTP front-end to the control sockets presented in the Unix filesystem by the other Kea daemons. Stork thus connected to the Kea KCA, as did any other API client.

Kea 3.0 introduced direct API access. In this concept, all Kea daemons provide their own HTTP listeners. API clients then connect directly to the individual daemons. This eliminates the need for the KCA. (The KCA is optional in Kea 3.0; it is planned for removal in the future.)

Stork 2.4.0 introduced support for the new direct API of Kea. The Stork agent will attempt to connect to the various Kea daemons directly, without the KCA.

The problem

Security hardening introduced to Kea in 2025 May (Kea 3.0.0 and 2.6.3) included more restrictive permissions on the Kea control sockets. Specifically, when a named socket is created in the filesystem, Kea sets permission mode 750: User read + write + execute, group read + execute, and others none. The ownership is a user and group dedicated to Kea, named kea or _kea for both.

Meanwhile, the Stork agent is configured to run as a dedicated user and group as well, named stork-agent for both. The stork-agent user is placed into the appropriate Kea group. The intent is for the group membership to grant access to the Kea control sockets. However, because the group permissions on the socket do not include write, the Stork agent cannot send API commands to that socket.

The problem is documented in Stork issue #2223 and Kea issue #4260. To correct the problem, Kea has been changed to use mode 770 (user+group read/write/exec, other none). This fix is included in the following Kea versions:

  • Kea 3.0.3 - 2026 March 25
  • Kea 3.1.5 (development branch - not for production) - 2026 January 28
  • Kea 3.2.0 (planned)