pfSense

Hello,

Environment¶

• pfSense CE version: 2.8.1-RELEASE
• DHCP backend: Kea DHCPv4
• High Availability: Enabled, hot-standby mode ** Primary node: pfmaster ** Standby node: pfbackup
• DNS service in use: DNS Forwarder (dnsmasq)
• DNS Resolver (Unbound): Disabled
• Kea DNS Registration: Disabled
• Kea Early DNS Registration: Disabled

Summary¶

On pfSense CE 2.8.1, the system generates and executes /conf/kea4_scripts.d/kea2unbound.sh even though:

• DNS Resolver / Unbound is disabled;
• DNS Forwarder / dnsmasq is the only active DNS service;
• Kea DNS Registration is unchecked in the WebUI;
• Kea Early DNS Registration is unchecked in the WebUI;
• no explicit non-default DNS Registration policy was found in the collected config.xml output.

As a result, Kea lease events invoke kea2unbound, which attempts to contact an inactive Unbound instance through unbound-control on 127.0.0.1:953.

This causes repeated errors, concurrent script executions, lock failures, and Text file busy messages.

Expected Behavior¶

When DNS Resolver / Unbound is disabled and both Kea DNS Registration options are disabled, pfSense should not generate or execute kea2unbound.sh.

Kea should continue serving DHCP leases without attempting to synchronize lease information with Unbound.

Actual Behavior¶

The following automatically generated script exists:

/conf/kea4_scripts.d/kea2unbound.sh

Actual file content:

#!/bin/sh
# Automatically generated! DO NOT EDIT!

case "$1" in
    hook_load)
        ;&
    lease4_add)
        ;&
    lease4_delete)
        ;&
    lease4_update)
        /usr/local/bin/kea2unbound --kea-conf /usr/local/etc/kea/kea-dhcp4.conf --unbound-conf /var/unbound/unbound.conf --include-file /var/unbound/leases/leases4.conf sync 
        ;;
esac

The script is executed during Kea lease processing:

/bin/sh /usr/local/bin/kea_run4 lease4_update
/bin/sh /conf/kea4_scripts.d/kea2unbound.sh lease4_update
php /usr/local/bin/kea2unbound --kea-conf /usr/local/etc/kea/kea-dhcp4.conf --unbound-conf /var/unbound/unbound.conf --include-file /var/unbound/leases/leases4.conf sync

Since Unbound is not running, the following messages are produced repeatedly:

unbound-control error: connect: Connection refused for 127.0.0.1 port 953

In kea2unbound line 543:

  Unable to query Unbound Control: /var/unbound/unbound.conf

/conf/kea4_scripts.d/kea2unbound.sh: /usr/local/bin/kea2unbound: Text file busy

In kea2unbound line 220:

  Unable to obtain lock after 5 seconds: /usr/local/bin/kea2unbound

DNS Service Verification¶

Only dnsmasq is listening on DNS port 53:

root@pfmaster: sockstat -4l | egrep '(:53|:953)\b'

nobody   dnsmasq    85646 4   udp4   *:53                  *:*
nobody   dnsmasq    85646 5   tcp4   *:53                  *:*

No Unbound process is listening on port 53 or on the control port 127.0.0.1:953.

The following command did not display a running Unbound daemon; it only displayed the scripts attempting to communicate with Unbound:

root@pfmaster: ps auxww | grep '[u]nbound'

root   91012   0.0  0.0  14644   2460  -  S    13:27        0:00.00 /bin/sh /conf/kea4_scripts.d/kea2unbound.sh lease4_update
root   91062   0.0  0.2  62064  29596  -  S    13:27        0:00.13 php /usr/local/bin/kea2unbound --kea-conf /usr/local/etc/kea/kea-dhcp4.conf --unbound-conf /var/unbound/unbound.conf --include-file /var/unbound/leases/leases4.conf sync

WebUI Configuration¶

In Services > DHCP Server > Settings:

• DNS Registration: unchecked
• Early DNS Registration: unchecked

In Services > DNS Resolver:

• DNS Resolver / Unbound: disabled

In Services > DNS Forwarder:

• DNS Forwarder / dnsmasq: enabled and actively used

Screenshots showing these settings can be attached to this ticket.

Persistent Configuration Verification¶

The DHCP backend is Kea:

<dhcpbackend>kea</dhcpbackend>

The collected search of /conf/config.xml displayed only default DNS registration policies, for example:

<dnsregpolicy>default</dnsregpolicy>
<earlydnsregpolicy>default</earlydnsregpolicy>

The command used was:

/bin/sh -c 'grep -niE "dnsreg|early|unbound|kea" /conf/config.xml | head -200'

The custom Kea configuration stored in config.xml contains PXE client classes and expired lease processing tuning. It does not configure Unbound integration or explicitly request execution of kea2unbound.

Relevant generated-script search result:

/bin/sh -c 'grep -RniE "kea2unbound|unbound|leases4.conf" /conf/config.xml /usr/local/etc/kea/kea-dhcp4.conf /conf/kea4_scripts.d 2>/dev/null'

/conf/config.xml:20974:    <unbound>
/conf/config.xml:21002:    </unbound>
/conf/kea4_scripts.d/kea2unbound.sh:12:        /usr/local/bin/kea2unbound --kea-conf /usr/local/etc/kea/kea-dhcp4.conf --unbound-conf /var/unbound/unbound.conf --include-file /var/unbound/leases/leases4.conf sync 

Kea Runtime Status¶

The Kea DHCPv4 daemon itself is active and listening on DHCP and HA ports:

root@pfmaster: keactrl status

DHCPv4 server: active
DHCPv6 server: inactive
DHCP DDNS: inactive
Control Agent: inactive
Kea DHCPv4 configuration file: /usr/local/etc/kea/kea-dhcp4.conf

root@pfmaster: sockstat -4l | egrep '(:67|:8765)\b'

root     kea-dhcp4  57830 16  udp4   172.16.0.2:67         *:*
root     kea-dhcp4  57830 20  udp4   10.60.0.2:67          *:*
root     kea-dhcp4  57830 84  udp4   10.53.0.2:67          *:*
root     kea-dhcp4  57830 110 udp4   172.19.0.4:67         *:*
root     kea-dhcp4  57830 127 tcp4   10.11.1.3:8765        *:*

The Kea control socket reports a healthy hot-standby HA relationship at the time of testing:

root@pfmaster: php -r '$s=stream_socket_client("unix:///var/run/kea4-ctrl-socket",$e,$m,5); if($s === false){fwrite(STDERR,"Falha no socket: ".$m." (".$e.")\n"); exit(1);} fwrite($s,"{\"command\":\"status-get\"}\n"); fflush($s); stream_set_timeout($s,5); echo fgets($s),"\n"; fclose($s);'

{ "arguments": { "dhcp-state": { "disabled-by-db-connection": [  ], "disabled-by-local-command": [  ], "disabled-by-remote-command": [  ], "disabled-by-user": false, "globally-disabled": false }, "high-availability": [ { "ha-mode": "hot-standby", "ha-servers": { "local": { "role": "primary", "scopes": [ "pfmaster" ], "server-name": "pfmaster", "state": "hot-standby" }, "remote": { "age": 2, "analyzed-packets": 0, "communication-interrupted": false, "connecting-clients": 0, "in-touch": true, "last-scopes": [  ], "last-state": "hot-standby", "role": "standby", "server-name": "pfbackup", "unacked-clients": 0, "unacked-clients-left": 0 } } } ], "multi-threading-enabled": true, "packet-queue-size": 64, "packet-queue-statistics": [ 1.0, 1.00003, 0.996216 ], "pid": 57830, "reload": 2075, "sockets": { "status": "ready" }, "thread-pool-size": 8, "uptime": 2077 }, "result": 0 }

TCP connectivity from the primary node to the standby Kea HA endpoint also succeeds:

root@pfmaster: nc -vz 10.11.1.4 8765

Connection to 10.11.1.4 8765 port [tcp/*] succeeded!

Therefore, this report is specifically about the unexpected generation and execution of kea2unbound.sh while Unbound integration is disabled, independently of the HA state.

Steps to Reproduce¶

1. Install or upgrade to pfSense CE 2.8.1-RELEASE.

1. Configure the DHCP backend as Kea DHCPv4.

1. Configure and use DNS Forwarder / dnsmasq as the active DNS service.

1. Disable DNS Resolver / Unbound.

1. In the Kea DHCP settings, leave the following options unchecked:

1. DNS Registration

1. Early DNS Registration

1. Ensure there are no intentionally enabled interface-level DNS Registration overrides.

1. Apply or reload the Kea configuration, or restart the Kea DHCP service through the WebUI.

1. Inspect the generated script directory:

ls -lah /conf/kea4_scripts.d/
cat /conf/kea4_scripts.d/kea2unbound.sh

1. Trigger a DHCP lease event, such as a client renewal or a new lease.

1. Inspect running processes and DHCP/system logs:

pgrep -alf 'kea-dhcp4|kea2unbound|kea_run4'

Observed Result¶

kea2unbound.sh exists and is executed for lease events, causing repeated attempts to contact inactive Unbound and producing error storms.

Example running processes observed:

php /usr/local/bin/kea2unbound --kea-conf /usr/local/etc/kea/kea-dhcp4.conf --unbound-conf /var/unbound/unbound.conf --include-file /var/unbound/leases/leases4.conf sync
/bin/sh /conf/kea4_scripts.d/kea2unbound.sh lease4_update
/bin/sh /usr/local/bin/kea_run4 lease4_update
/usr/local/sbin/kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf

Workaround Tested¶

Moving the generated script out of /conf/kea4_scripts.d/ and terminating the running kea2unbound processes immediately stops the kea2unbound executions:

/bin/sh -c 'mkdir -p /conf/kea4_scripts.d.disabled && cp -p /conf/kea4_scripts.d/kea2unbound.sh /conf/kea4_scripts.d.disabled/kea2unbound.sh.regenerated.$(date +%Y%m%d-%H%M%S) && mv /conf/kea4_scripts.d/kea2unbound.sh /conf/kea4_scripts.d.disabled/kea2unbound.sh.disabled.$(date +%Y%m%d-%H%M%S)'

pkill -f '/usr/local/bin/kea2unbound'
pkill -f '/conf/kea4_scripts.d/kea2unbound.sh'

After applying this workaround:

root@pfmaster: pgrep -alf 'kea-dhcp4|kea2unbound|kea_run4'

37274 /bin/sh /usr/local/bin/kea_run4 lease4_expire
57830 /usr/local/sbin/kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf

No active kea2unbound process remained.

However, this is only a temporary workaround because kea2unbound.sh is automatically generated and may be recreated during subsequent DHCP service reloads or WebUI configuration operations.

Additional Logs Collected During Investigation¶

During the investigation, the following errors were also observed:

Jun  3 13:24:41 pfmaster kea-dhcp4[92014]: ERROR [kea-dhcp4.commands.0x366f5612000] COMMAND_WATCH_SOCKET_MARK_READY_ERROR watch socket failed to mark ready: WatchSocket markReady failed: select_fd was closed!
Jun  3 13:24:41 pfmaster kea-dhcp4[92014]: ERROR [kea-dhcp4.commands.0x366f5612000] COMMAND_SOCKET_WRITE_FAIL Error while writing to command socket -1 : Bad file descriptor
Jun  3 13:30:39 pfmaster kea-dhcp4[43775]: WARN  [kea-dhcp4.ha-hooks.0x3754fd617400] HA_LEASE_UPDATE_COMMUNICATIONS_FAILED pfmaster: failed to send lease update [hwtype=1 42:fc:51:9a:88:11], cid=[01:42:fc:51:9a:88:11], tid=0x782f14b1 to pfbackup (http://10.11.1.4:8765/): End of file
Jun  3 13:37:20 pfmaster kea-dhcp4[43775]: ERROR [kea-dhcp4.commands.0x3754fd612000] COMMAND_WATCH_SOCKET_MARK_READY_ERROR watch socket failed to mark ready: WatchSocket markReady failed: select_fd was closed!
Jun  3 13:37:20 pfmaster kea-dhcp4[43775]: ERROR [kea-dhcp4.commands.0x3754fd612000] COMMAND_SOCKET_WRITE_FAIL Error while writing to command socket -1 : Bad file descriptor

At the time of a later status-get test, HA reported a healthy hot-standby state. These additional messages are provided as context and may or may not be related to the unexpected kea2unbound behavior.

Impact¶

This behavior causes:

• repeated failed calls to an inactive Unbound service;
• repeated kea2unbound process creation during DHCP lease activity;
• lock contention and Text file busy messages;
• noisy DHCP/system logs;
• operational difficulty while troubleshooting Kea DHCP health;
• potential resource consumption or service instability during high lease activity.

Intermittent DHCP service issues were observed while investigating this condition. This report does not assert that kea2unbound is the sole cause of all DHCP delivery failures; however, it is clearly being executed while its required backend service is disabled.

Requested Resolution¶

Please verify the logic responsible for generating /conf/kea4_scripts.d/kea2unbound.sh in pfSense CE 2.8.1.

The script should not be generated or executed when all of the following conditions are true:

• DNS Resolver / Unbound is disabled;
• Kea DNS Registration is disabled;
• Kea Early DNS Registration is disabled;
• no interface-level configuration explicitly enables DNS registration through Unbound.

Alternatively, the generated hook should safely skip execution when Unbound is disabled or unavailable.

Additional Related Observation¶

During the same investigation, a separate issue was observed when replacing an access point that uses a DHCP static mapping.

The previous access point used the reserved IP 172.19.0.148. After replacing the device and editing only the MAC address in the DHCP static mapping, Kea logged conflicts indicating that the reserved IP was still associated with the old MAC address in its lease data:

ALLOC_ENGINE_V4_DISCOVER_ADDRESS_CONFLICT
conflicting reservation for address 172.19.0.148 with existing lease
new device MAC: ac:8b:a9:2b:b9:09
previous lease MAC: e4:38:83:72:aa:7d

This appears to be separate from the kea2unbound issue described in this report and is included only as additional context from the troubleshooting activity.