feat(dns): resolve network-local names

- remove no longer needed DNS_KEEP_NAMESERVER
- add DNS_LOCAL_RESOLVERS which defaults to private nameservers found in etc/resolv.conf at start
- ⚠️ turning DOT=off will cause the local resolution to no longer work

Author: qdm12

Dockerfile

@@ -178,7 +178,7 @@ ENV VPN_SERVICE_PROVIDER=pia \
     UNBLOCK= \
     DNS_UPDATE_PERIOD=24h \
     DNS_ADDRESS=127.0.0.1 \
-    DNS_KEEP_NAMESERVER=off \
+    DNS_LOCAL_RESOLVERS= \
     # HTTP proxy
     HTTPPROXY= \
     HTTPPROXY_LOG=off \

go.mod

@@ -9,7 +9,7 @@ require (
 	github.com/klauspost/compress v1.18.1
 	github.com/klauspost/pgzip v1.2.6
 	github.com/pelletier/go-toml/v2 v2.2.4
-	github.com/qdm12/dns/v2 v2.0.0-rc8
+	github.com/qdm12/dns/v2 v2.0.0-rc8.0.20251105160351-52207aa09672
 	github.com/qdm12/gosettings v0.4.4
 	github.com/qdm12/goshutdown v0.3.0
 	github.com/qdm12/gosplash v0.2.0
@@ -47,7 +47,7 @@ require (
 	github.com/prometheus/client_model v0.6.1 // indirect
 	github.com/prometheus/common v0.60.1 // indirect
 	github.com/prometheus/procfs v0.15.1 // indirect
-	github.com/qdm12/goservices v0.1.0 // indirect
+	github.com/qdm12/goservices v0.1.1-0.20251104135713-6bee97bd4978 // indirect
 	github.com/riobard/go-bloom v0.0.0-20200614022211-cdc8013cb5b3 // indirect
 	github.com/vishvananda/netns v0.0.5 // indirect
 	golang.org/x/crypto v0.43.0 // indirect

go.sum

@@ -53,10 +53,10 @@ github.com/prometheus/common v0.60.1 h1:FUas6GcOw66yB/73KC+BOZoFJmbo/1pojoILArPA
 github.com/prometheus/common v0.60.1/go.mod h1:h0LYf1R1deLSKtD4Vdg8gy4RuOvENW2J/h19V5NADQw=
 github.com/prometheus/procfs v0.15.1 h1:YagwOFzUgYfKKHX6Dr+sHT7km/hxC76UB0learggepc=
 github.com/prometheus/procfs v0.15.1/go.mod h1:fB45yRUv8NstnjriLhBQLuOUt+WW4BsoGhij/e3PBqk=
-github.com/qdm12/dns/v2 v2.0.0-rc8 h1:kbgKPkbT+79nScfuZ0ZcVhksTGo8IUqQ8TTQGnQlZ18=
-github.com/qdm12/dns/v2 v2.0.0-rc8/go.mod h1:VaF02KWEL7xNV4oKfG4N9nEv/kR6bqyIcBReCV5NJhw=
-github.com/qdm12/goservices v0.1.0 h1:9sODefm/yuIGS7ynCkEnNlMTAYn9GzPhtcK4F69JWvc=
-github.com/qdm12/goservices v0.1.0/go.mod h1:/JOFsAnHFiSjyoXxa5FlfX903h20K5u/3rLzCjYVMck=
+github.com/qdm12/dns/v2 v2.0.0-rc8.0.20251105160351-52207aa09672 h1:SL4ofJRf8ftAY3VvXnUi+XQaUFLpsWFWVaty8PJMJK8=
+github.com/qdm12/dns/v2 v2.0.0-rc8.0.20251105160351-52207aa09672/go.mod h1:98foWgXJZ+g8gJIuO+fdO+oWpFei5WShMFTeN4Im2lE=
+github.com/qdm12/goservices v0.1.1-0.20251104135713-6bee97bd4978 h1:TRGpCU1l0lNwtogEUSs5U+RFceYxkAJUmrGabno7J5c=
+github.com/qdm12/goservices v0.1.1-0.20251104135713-6bee97bd4978/go.mod h1:D1Po4CRQLYjccnAR2JsVlN1sBMgQrcNLONbvyuzcdTg=
 github.com/qdm12/gosettings v0.4.4 h1:SM6tOZDf6k8qbjWU8KWyBF4mWIixfsKCfh9DGRLHlj4=
 github.com/qdm12/gosettings v0.4.4/go.mod h1:CPrt2YC4UsURTrslmhxocVhMCW03lIrqdH2hzIf5prg=
 github.com/qdm12/goshutdown v0.3.0 h1:pqBpJkdwlZlfTEx4QHtS8u8CXx6pG0fVo6S1N0MpSEM=

internal/configuration/settings/dns.go

@@ -1,9 +1,11 @@
 package settings
 
 import (
+	"errors"
 	"fmt"
 	"net/netip"
 
+	"github.com/qdm12/dns/v2/pkg/nameserver"
 	"github.com/qdm12/gosettings"
 	"github.com/qdm12/gosettings/reader"
 	"github.com/qdm12/gotree"
@@ -17,36 +19,38 @@ type DNS struct {
 	// DoT server. It cannot be the zero value in the internal
 	// state.
 	ServerAddress netip.Addr
-	// KeepNameserver is true if the existing DNS server
-	// found in /etc/resolv.conf should be used
-	// Note setting this to true will likely DNS traffic
-	// outside the VPN tunnel since it would go through
-	// the local DNS server of your Docker/Kubernetes
-	// configuration, which is likely not going through the tunnel.
-	// This will also disable the DNS over TLS server and the
-	// `ServerAddress` field will be ignored.
-	// It defaults to false and cannot be nil in the
-	// internal state.
-	KeepNameserver *bool
 	// DOT contains settings to configure the DoT
 	// server.
 	DoT DoT
+	// LocalResolvers are IP:port addresses of local DNS resolvers
+	// to which queries for local domains should be sent.
+	// By default, it is the private nameservers found in /etc/resolv.conf
+	// at container start, before the DNS is setup.
+	LocalResolvers []netip.AddrPort
 }
 
+var ErrLocalResolverNotPrivate = errors.New("local resolver is not a private IP address")
+
 func (d DNS) validate() (err error) {
 	err = d.DoT.validate()
 	if err != nil {
 		return fmt.Errorf("validating DoT settings: %w", err)
 	}
 
+	for _, resolver := range d.LocalResolvers {
+		if !resolver.Addr().IsPrivate() && !resolver.Addr().IsLoopback() {
+			return fmt.Errorf("%w: %s", ErrLocalResolverNotPrivate, resolver)
+		}
+	}
+
 	return nil
 }
 
 func (d *DNS) Copy() (copied DNS) {
 	return DNS{
 		ServerAddress:  d.ServerAddress,
-		KeepNameserver: gosettings.CopyPointer(d.KeepNameserver),
 		DoT:            d.DoT.copy(),
+		LocalResolvers: gosettings.CopySlice(d.LocalResolvers),
 	}
 }
 
@@ -55,15 +59,15 @@ func (d *DNS) Copy() (copied DNS) {
 // settings.
 func (d *DNS) overrideWith(other DNS) {
 	d.ServerAddress = gosettings.OverrideWithValidator(d.ServerAddress, other.ServerAddress)
-	d.KeepNameserver = gosettings.OverrideWithPointer(d.KeepNameserver, other.KeepNameserver)
 	d.DoT.overrideWith(other.DoT)
+	d.LocalResolvers = gosettings.OverrideWithSlice(d.LocalResolvers, other.LocalResolvers)
 }
 
 func (d *DNS) setDefaults() {
 	localhost := netip.AddrFrom4([4]byte{127, 0, 0, 1})
 	d.ServerAddress = gosettings.DefaultValidator(d.ServerAddress, localhost)
-	d.KeepNameserver = gosettings.DefaultPointer(d.KeepNameserver, false)
 	d.DoT.setDefaults()
+	d.LocalResolvers = gosettings.DefaultSlice(d.LocalResolvers, nameserver.GetPrivateDNSServers())
 }
 
 func (d DNS) String() string {
@@ -72,12 +76,13 @@ func (d DNS) String() string {
 
 func (d DNS) toLinesNode() (node *gotree.Node) {
 	node = gotree.New("DNS settings:")
-	node.Appendf("Keep existing nameserver(s): %s", gosettings.BoolToYesNo(d.KeepNameserver))
-	if *d.KeepNameserver {
-		return node
-	}
 	node.Appendf("DNS server address to use: %s", d.ServerAddress)
 	node.AppendNode(d.DoT.toLinesNode())
+	localResolversNode := gotree.New("Local resolvers:")
+	for _, resolver := range d.LocalResolvers {
+		localResolversNode.Appendf("%s", resolver.String())
+	}
+	node.AppendNode(localResolversNode)
 	return node
 }
 
@@ -87,14 +92,14 @@ func (d *DNS) read(r *reader.Reader) (err error) {
 		return err
 	}
 
-	d.KeepNameserver, err = r.BoolPtr("DNS_KEEP_NAMESERVER")
+	err = d.DoT.read(r)
 	if err != nil {
-		return err
+		return fmt.Errorf("DNS over TLS settings: %w", err)
 	}
 
-	err = d.DoT.read(r)
+	d.LocalResolvers, err = r.CSVNetipAddrPorts("DNS_LOCAL_RESOLVERS")
 	if err != nil {
-		return fmt.Errorf("DNS over TLS settings: %w", err)
+		return err
 	}
 
 	return nil

internal/configuration/settings/settings_test.go

@@ -1,6 +1,7 @@
 package settings
 
 import (
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -38,19 +39,19 @@ func Test_Settings_String(t *testing.T) {
 |       ├── Run OpenVPN as: root
 |       └── Verbosity level: 1
 ├── DNS settings:
-|   ├── Keep existing nameserver(s): no
 |   ├── DNS server address to use: 127.0.0.1
-|   └── DNS over TLS settings:
-|       ├── Enabled: yes
-|       ├── Update period: every 24h0m0s
-|       ├── Upstream resolvers:
-|       |   └── Cloudflare
-|       ├── Caching: yes
-|       ├── IPv6: no
-|       └── DNS filtering settings:
-|           ├── Block malicious: yes
-|           ├── Block ads: no
-|           └── Block surveillance: yes
+|   ├── DNS over TLS settings:
+|   |   ├── Enabled: yes
+|   |   ├── Update period: every 24h0m0s
+|   |   ├── Upstream resolvers:
+|   |   |   └── Cloudflare
+|   |   ├── Caching: yes
+|   |   ├── IPv6: no
+|   |   └── DNS filtering settings:
+|   |       ├── Block malicious: yes
+|   |       ├── Block ads: no
+|   |       └── Block surveillance: yes
+|   └── Local resolvers: [private nameservers found in /etc/resolv.conf]
 ├── Firewall settings:
 |   └── Enabled: yes
 ├── Log settings:
@@ -91,6 +92,17 @@ func Test_Settings_String(t *testing.T) {
 
 			s := testCase.settings.String()
 
+			lines := strings.Split(s, "\n")
+			for i := range lines {
+				const subPart = "Local resolvers:"
+				j := strings.Index(lines[i], subPart)
+				if j == -1 {
+					continue
+				}
+				lines[i] = lines[i][:j+len(subPart)] + " [private nameservers found in /etc/resolv.conf]"
+			}
+			s = strings.Join(lines, "\n")
+
 			assert.Equal(t, testCase.s, s)
 		})
 	}

internal/dns/plaintext.go

@@ -27,14 +27,15 @@ func (l *Loop) useUnencryptedDNS(fallback bool) {
 	}
 
 	const dialTimeout = 3 * time.Second
+	const defaultDNSPort = 53
 	settingsInternalDNS := nameserver.SettingsInternalDNS{
-		IP:      targetIP,
-		Timeout: dialTimeout,
+		AddrPort: netip.AddrPortFrom(targetIP, defaultDNSPort),
+		Timeout:  dialTimeout,
 	}
 	nameserver.UseDNSInternally(settingsInternalDNS)
 
 	settingsSystemWide := nameserver.SettingsSystemDNS{
-		IP:         targetIP,
+		IPs:        []netip.Addr{targetIP},
 		ResolvPath: l.resolvConf,
 	}
 	err := nameserver.UseDNSSystemWide(settingsSystemWide)

internal/dns/run.go

@@ -10,14 +10,8 @@ import (
 func (l *Loop) Run(ctx context.Context, done chan<- struct{}) {
 	defer close(done)
 
-	if *l.GetSettings().KeepNameserver {
-		l.logger.Warn("⚠️⚠️⚠️  keeping the default container nameservers, " +
-			"this will likely leak DNS traffic outside the VPN " +
-			"and go through your container network DNS outside the VPN tunnel!")
-	} else {
-		const fallback = false
-		l.useUnencryptedDNS(fallback)
-	}
+	const fallback = false
+	l.useUnencryptedDNS(fallback)
 
 	select {
 	case <-l.start:
@@ -31,7 +25,7 @@ func (l *Loop) Run(ctx context.Context, done chan<- struct{}) {
 		var runError <-chan error
 
 		settings := l.GetSettings()
-		for !*settings.KeepNameserver && *settings.DoT.Enabled {
+		for *settings.DoT.Enabled {
 			var err error
 			runError, err = l.setupServer(ctx)
 			if err == nil {
@@ -56,7 +50,7 @@ func (l *Loop) Run(ctx context.Context, done chan<- struct{}) {
 		}
 
 		settings = l.GetSettings()
-		if !*settings.KeepNameserver && !*settings.DoT.Enabled {
+		if !*settings.DoT.Enabled {
 			const fallback = false
 			l.useUnencryptedDNS(fallback)
 		}

internal/dns/settings.go

@@ -9,6 +9,7 @@ import (
 	"github.com/qdm12/dns/v2/pkg/middlewares/cache/lru"
 	filtermiddleware "github.com/qdm12/dns/v2/pkg/middlewares/filter"
 	"github.com/qdm12/dns/v2/pkg/middlewares/filter/mapfilter"
+	"github.com/qdm12/dns/v2/pkg/middlewares/localdns"
 	"github.com/qdm12/dns/v2/pkg/provider"
 	"github.com/qdm12/dns/v2/pkg/server"
 	"github.com/qdm12/gluetun/internal/configuration/settings"
@@ -70,5 +71,17 @@ func buildDoTSettings(settings settings.DNS,
 	}
 	serverSettings.Middlewares = append(serverSettings.Middlewares, filterMiddleware)
 
+	localDNSMiddleware, err := localdns.New(localdns.Settings{
+		Resolvers: settings.LocalResolvers, // auto-detected at container start only
+		Logger:    logger,
+	})
+	if err != nil {
+		return server.Settings{}, fmt.Errorf("creating local DNS middleware: %w", err)
+	}
+	// Place after cache middleware, since we want to avoid caching for local
+	// hostnames that may change regularly.
+	// Place after filter middleware to avoid conflicts with the rebinding protection.
+	serverSettings.Middlewares = append(serverSettings.Middlewares, localDNSMiddleware)
+
 	return serverSettings, nil
 }

internal/dns/setup.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/netip"
 
 	"github.com/qdm12/dns/v2/pkg/check"
 	"github.com/qdm12/dns/v2/pkg/nameserver"
@@ -37,11 +38,12 @@ func (l *Loop) setupServer(ctx context.Context) (runError <-chan error, err erro
 	l.server = server
 
 	// use internal DNS server
+	const defaultDNSPort = 53
 	nameserver.UseDNSInternally(nameserver.SettingsInternalDNS{
-		IP: settings.ServerAddress,
+		AddrPort: netip.AddrPortFrom(settings.ServerAddress, defaultDNSPort),
 	})
 	err = nameserver.UseDNSSystemWide(nameserver.SettingsSystemDNS{
-		IP:         settings.ServerAddress,
+		IPs:        []netip.Addr{settings.ServerAddress},
 		ResolvPath: l.resolvConf,
 	})
 	if err != nil {