bind dns address/port optionally, no fatal error when at least one bind address works

[kuvaldini]

Prerequisites

• I have checked the Wiki and Discussions and found no answer

• I have searched other issues and found no duplicates

• I want to request a feature or enhancement and not ask a question

The problem

while at least one address:port can be bound, another one isn't AdguardHome exits with fatal error. please let's lazy-load it once it become available.

...
 AdGuardHome[1430]: 2026/03/05 19:08:28.994482 [info] dnsproxy: starting dns proxy server
 AdGuardHome[1430]: 2026/03/05 19:08:28.994757 [info] dnsproxy: creating udp server socket addr=127.0.0.1:53
 AdGuardHome[1430]: 2026/03/05 19:08:28.995267 [info] dnsproxy: listening to udp addr=127.0.0.1:53
 AdGuardHome[1430]: 2026/03/05 19:08:28.995295 [info] dnsproxy: creating udp server socket addr=[::1]:53
 AdGuardHome[1430]: 2026/03/05 19:08:28.995376 [info] dnsproxy: listening to udp addr=[::1]:53
 AdGuardHome[1430]: 2026/03/05 19:08:28.995395 [info] dnsproxy: creating udp server socket addr=172.17.0.1:53
 AdGuardHome[1430]: 2026/03/05 19:08:28.995469 [info] dnsproxy: warning: binding attempt=1 err="listen udp 172.17.0.1:53: bind: cannot assign requested address"
 AdGuardHome[1430]: 2026/03/05 19:08:29.019288 [error] closing query log: flushing log buffer: nothing to write to a file
 AdGuardHome[1430]: 2026/03/05 19:08:29.024189 [fatal] starting dns server: configuring listeners: listening on udp addr 172.17.0.1:53: listening to udp socket: li>
 systemd[1]: adguardhome.service: Main process exited, code=exited, status=1/FAILURE
 systemd[1]: adguardhome.service: Failed with result 'exit-code'.

http:
  address: 127.0.0.1:3080
  session_ttl: 720h
dns:
  bind_hosts:
    - 127.0.0.1
    - ::1
    - 172.17.0.1
  port: 53
...

Proposed solution

• keep warning about failed to bind address/port
• no fatal error when at least one address/port bound successfully

to keep compatibility for users who consider one of many address bound error is critical, let's create yet another key:value list in config file.

dns:
  bind_hosts_nonfatal:
  - [::1]:53
  - 192.168.99.87:1553

Alternatives considered and additional information

current workaround, in systemd service preexec script-checker and editor:

• check ip -br a for existing interfaces/addresses
• check port is free
• exclude from config unbindable addresses

[tjharman]

You want the software to be told "bind to these interfaces, but if one is in use, keep trying to bind until it's available" is that correct?

Can you explain the use case for this feature please?

Keep in mind that AdGuardHome is aimed at home users - most are going to have a single interface/IP to bind to.

[kuvaldini]

@tjharman yep

some interfaces/addresses are changed at system runtime. e.g. wifi networks are changed, eth is connected/disconnected, virtual networks (like vpn,docker,podman,vagrant,etc) appear and disappear. currently need to reconfigure and restart adguard on network change. finally pls do not suggest to listen on 0.0.0.0.