Unbound DNS: not properly forwarding

[phreed]

Important notices

Before you add a new report, we ask you kindly to acknowledge the following:

• I have read the contributing guide lines at https://github.com/opnsense/core/blob/master/CONTRIBUTING.md
• I am convinced that my issue is new after having checked both open and closed issues at https://github.com/opnsense/core/issues?q=is%3Aissue
  I have looked at the following issues and believe them to be different but they might be the result of not fully processing the unbound.conf :
  • Unbound: DNSBL: Anything is whitelisted if there is a Source Net(s) Entry in Config #9630
  • Unbound DNS overrides not resolving until next Unbound restart #9587
  • Unbound is not able to resolve some hosts in root server mode #9572

Describe the bug

The generated /var/unbound/unbound.conf contains a relative path for the python module that fails to resolve:

python:
python-script: unbound-dnsbl/dnsbl_module.py

While this script is for DNSBL it seems to be present whether the DNSBL is enabled or not.

This causes Unbound to fail silently.
The service starts but DNS forwarding does not fully work.
External domain queries return empty answers dispite the upstream DNS servers being reachable and functional.

To Reproduce

1. Go to Services → Unbound DNS → Query Forwarding
2. Configure forwarding to upstream DNS servers
3. Click Apply
4. SSH to router and run: unbound-checkconf /var/unbound/unbound.conf
5. See error:

   error: pythonmod: can't open file unbound-dnsbl/dnsbl_module.py for reading
   fatal error: bad config during init for python module
   

I suspect that only steps 4 & 5 are actually necessary.

Expected behavior

The generated unbound.conf could use an absolute path that resolves correctly:

python:
python-script: /var/unbound/unbound-dnsbl/dnsbl_module.py

Or the relative path should resolve correctly within the configured chroot environment.

Describe alternatives you considered

1. Manual edit: Editing /var/unbound/unbound.conf to use the absolute path /var/unbound/unbound-dnsbl/dnsbl_module.py passes validation, but configctl unbound restart regenerates the config with the broken relative path.

2. Disable DNSBL: Disabling the Blocklist feature should remove the python module directive thus allowing DNS forwarding to work correctly. This does not seem to have an effect on the python-script element.

3. Symlink: Creating a symlink to make the relative path resolve - not fully tested.

Screenshots

Config validation failure:

root@mesolab-router:~ # unbound-checkconf /var/unbound/unbound.conf
[1769108850] unbound-checkconf[71749:0] error: pythonmod: can't open file unbound-dnsbl/dnsbl_module.py for reading
[1769108850] unbound-checkconf[71749:0] fatal error: bad config during init for python module

Manual fix passes validation:

root@mesolab-router:~ # vi /var/unbound/unbound.conf  # change to absolute path
root@mesolab-router:~ # unbound-checkconf /var/unbound/unbound.conf
unbound-checkconf: no errors in /var/unbound/unbound.conf

Restart reverts the fix:

root@mesolab-router:~ # configctl unbound restart
OK
root@mesolab-router:~ # unbound-checkconf /var/unbound/unbound.conf
[1769109579] unbound-checkconf[54582:0] error: pythonmod: can't open file unbound-dnsbl/dnsbl_module.py for reading
[1769109579] unbound-checkconf[54582:0] fatal error: bad config during init for python module

DNS symptom - query via Unbound returns empty:

root@mesolab-router:~ # drill @127.0.0.1 cloud.foo.edu
;; ANSWER SECTION:
(empty)

Direct query to upstream works:

root@mesolab-router:~ # drill @10.2.189.78 cloud.foo.edu
;; ANSWER SECTION:
cloud.foo.edu.	300	IN	A	10.2.218.115

Generated config shows correct chroot but broken python path:

server:
chroot: /var/unbound
directory: /var/unbound
...
python:
python-script: unbound-dnsbl/dnsbl_module.py

Additional context

The forwarding configuration itself is correct:

forward-zone:
    name: "."
    forward-addr: 10.4.162.82
    forward-addr: 10.2.189.78

The issue is isolated to the DNSBL python module path preventing Unbound from initializing properly.
As this interfers with the full processing of unbound.conf it may affect other settings from working as well.

Environment

OPNsense 25.7.11_2 (amd64)

Hardware:
Protectli
Model: V1410
Intel ® N5105 Quad Core CPU at 2.0 GHz
Intel® I226-V 2.5Gigabit Ethernet NIC

[phreed]

I was unsure where this issue belongs (core vs. plugins).
The problem appears to be with the generation of the unbound.conf.

[phreed]

core/src/etc/inc/plugins.inc.d/unbound.inc

Line 388 in 3668d87

python-script: unbound-dnsbl/dnsbl_module.py

Appears to be the problematic line.
This may be two separate bugs, one related to the unbound-checkconf program, and one related to the DNS forwarding.

[AdSchellevis]

you need to chroot properly when trying this via the command line, best use the gui as this will use the proper sequence.

[ijujigthb]

Confirming this issue on OPNsense 26.1

Same problem here after upgrading to 26.1. DNS resolution was unstable on client VMs (intermittent EAI_AGAIN / temporary DNS failures). After applying this fix, DNS became stable. This confirms the bug affects both 25.7 and 26.1.

Root Cause

The issue is in /usr/local/etc/inc/plugins.inc.d/unbound.inc at line 206:

$module_config = 'python ';

This unconditionally adds python to module-config regardless of whether DNSBL/Blocklist is enabled. When the python module tries to load but the DNSBL scripts aren't properly initialized, Unbound fails.

Workaround

Patch the PHP file to not load python module by default:

# Backup first
cp /usr/local/etc/inc/plugins.inc.d/unbound.inc /usr/local/etc/inc/plugins.inc.d/unbound.inc.bak

# Patch line 206
sed -i '' 's/\$module_config = '"'"'python '"'"';/\$module_config = '"'"''"'"';/' /usr/local/etc/inc/plugins.inc.d/unbound.inc

# Restart Unbound
pluginctl dns restart

Verification:

grep "module-config" /var/unbound/unbound.conf
# Should show: module-config: "iterator" (without "python")

unbound-checkconf /var/unbound/unbound.conf
# Should show: unbound-checkconf: no errors in /var/unbound/unbound.conf

Notes:

• This patch survives GUI saves/applies (since we patched the generator, not the config)
• May be overwritten by future OPNsense firmware updates

Suggested Fix for Developers

Make python module conditional on DNSBL being enabled. Change line 206 from:

$module_config = 'python ';

To something like:

$module_config = !empty($dnsbl['enabled']) ? 'python ' : '';

[AdSchellevis]

The python module is used to gather statistics as well, it’s intentionally always loaded.

[ijujigthb]

The python module is used to gather statistics as well, it’s intentionally always loaded.

Thanks for the clarification. However, the python module fails to initialize:

unbound-checkconf /var/unbound/unbound.conf
error: pythonmod: can't open file unbound-dnsbl/dnsbl_module.py for reading
fatal error: bad config during init for python module

If python is intentionally always loaded, shouldn't it initialize without errors? After removing python from module-config, DNS became stable and unbound-checkconf passes.

Is there a configuration step we're missing, or is there a bug in the module initialization?

[fichtner]

First of all what are you doing?

# configctl unbound check

[ijujigthb]

First of all what are you doing?

# configctl unbound check

Thanks, configctl unbound check passes. I was using unbound-checkconf directly which fails outside chroot.

After reverting my patch and restarting Unbound properly, DNS is now stable. The initial instability may have been a post-upgrade initialization issue rather than the python module itself.

Will monitor and report back if issues return.

[rbnhln]

I updated my opnSense to 26.1 and see the same behavior. I never used unbound before. I did not tried your fix so far, but it does not work out of the box, as your final comment suggests.

# configctl unbound check
no errors in /var/unbound/unbound.conf

but

unbound-checkconf /var/unbound/unbound.conf
[1772020498] unbound-checkconf[79518:0] error: pythonmod: can't open file unbound-dnsbl/dnsbl_module.py for reading
[1772020498] unbound-checkconf[79518:0] fatal error: bad config during init for python module

I get the following error message in the GUI -> Backend logs:

3b992a1f-6023-4778-895e-e45e579c2823] Script action failed with Command '/usr/local/opnsense/scripts/unbound/wrapper.py -s ' returned non-zero exit status 1. at Traceback (most recent call last): File "/usr/local/opnsense/service/modules/actions/script_output.py", line 89, in execute subprocess.run(script_command, env=self.config_environment, shell=True, File "/usr/local/lib/python3.11/subprocess.py", line 571, in run raise CalledProcessError(retcode, process.args, subprocess.CalledProcessError: Command '/usr/local/opnsense/scripts/unbound/wrapper.py -s ' returned non-zero exit status 1.