From ea6ad9a31b4e67a35ff3de992991a51c329e6246 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 24 Apr 2026 05:15:33 +0000
Subject: [PATCH] home: add tls.admin_listen_addr for separate https admin
 listener

Add an optional tls.admin_listen_addr (netip.AddrPort) that, when set,
runs a dedicated HTTPS server for the admin UI/API on that address,
while the HTTPS server on tls.port_https serves DoH only.  Both servers
share the same TLS certificate.  When unset the previous single-server
behavior is preserved, so existing installs are unaffected and DNS
clients using DoH see no change.

Port conflicts involving admin_listen_addr are validated at config
parse time (including --check-config), not only as a runtime bind
failure.  HTTP/3 on tls.port_https mirrors the HTTPS mux split so
DoH-over-HTTP/3 clients are not forced through the admin auth
middleware and admin routes are not exposed on the DoH port.
validateTLSSettings reads AdminListenAddr from the server-side config
snapshot, not the frontend payload (the field is json:"-"), so UI
port_https changes still trigger the admin-port conflict check.
checkPortAvailability validates the admin HTTPS port on its own IP
(which may differ from the web API bind host).  tlsConfigChanged uses
a fresh shutdown context for each HTTPS server so the admin server is
not handed an already-cancelled context.  registerDoHHandlers reads
the admin listen address under config.RLock.

Backend + YAML only; no UI changes in this commit.  See the CHANGELOG
entry for user-facing details.

Addresses #7424 and #7598.

Co-Authored-By: raviu <raviu@protonmail.com>
---
 CHANGELOG.md                                  |   6 +
 .../home/adminlistenaddr_internal_test.go     | 237 ++++++++++++++++++
 internal/home/config.go                       |  24 +-
 internal/home/control.go                      |  41 ++-
 internal/home/dns.go                          |  21 +-
 internal/home/home.go                         |  37 +++
 internal/home/tls.go                          |  34 ++-
 internal/home/web.go                          | 191 +++++++++++++-
 8 files changed, 564 insertions(+), 27 deletions(-)
 create mode 100644 internal/home/adminlistenaddr_internal_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 395a029676a..16c51ab548b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,10 @@ See also the [v0.107.75 GitHub milestone][ms-v0.107.75].
 NOTE: Add new changes BELOW THIS COMMENT.
 -->
 
+### Added
+
+- New optional `tls.admin_listen_addr` configuration setting (an `IP:port` listen address, e.g. `127.0.0.1:4443`).  When set, AdGuard Home starts a second HTTPS server on this address dedicated to the admin UI and API, while the HTTPS server on `tls.port_https` serves DNS-over-HTTPS only.  Both servers share the same TLS certificate.  When unset (the default), behavior is unchanged: one HTTPS server on `tls.port_https` serves both admin UI and DoH ([#7424], [#7598]).
+
 ### Changed
 
 - `enable_dnssec` in `dns` configuration now defines whether the proxy should set the DO flag in the upstream requests, the default is `true` ([#7046]).
@@ -27,6 +31,8 @@ NOTE: Add new changes BELOW THIS COMMENT.
 - Safe Browsing and Parental Control labels on the General Settings page not updating after changing the UI language.
 
 [#7046]: https://github.com/AdguardTeam/AdGuardHome/issues/7046
+[#7424]: https://github.com/AdguardTeam/AdGuardHome/issues/7424
+[#7598]: https://github.com/AdguardTeam/AdGuardHome/issues/7598
 
 <!--
 NOTE: Add new changes ABOVE THIS COMMENT.
diff --git a/internal/home/adminlistenaddr_internal_test.go b/internal/home/adminlistenaddr_internal_test.go
new file mode 100644
index 00000000000..1815d751383
--- /dev/null
+++ b/internal/home/adminlistenaddr_internal_test.go
@@ -0,0 +1,237 @@
+package home
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestAdminListenAddr verifies that [adminListenAddr] returns the configured
+// address only when it is valid and has a non-zero port.
+func TestAdminListenAddr(t *testing.T) {
+	t.Parallel()
+
+	testCases := []struct {
+		name string
+		in   netip.AddrPort
+		want netip.AddrPort
+	}{{
+		name: "zero",
+		in:   netip.AddrPort{},
+		want: netip.AddrPort{},
+	}, {
+		name: "zero_port",
+		in:   netip.AddrPortFrom(netip.MustParseAddr("127.0.0.1"), 0),
+		want: netip.AddrPort{},
+	}, {
+		name: "loopback_port",
+		in:   netip.MustParseAddrPort("127.0.0.1:4443"),
+		want: netip.MustParseAddrPort("127.0.0.1:4443"),
+	}, {
+		name: "unspecified_port",
+		in:   netip.MustParseAddrPort("0.0.0.0:8443"),
+		want: netip.MustParseAddrPort("0.0.0.0:8443"),
+	}}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			conf := &tlsConfigSettings{AdminListenAddr: tc.in}
+			assert.Equal(t, tc.want, adminListenAddr(conf))
+		})
+	}
+
+	t.Run("nil", func(t *testing.T) {
+		t.Parallel()
+
+		assert.Equal(t, netip.AddrPort{}, adminListenAddr(nil))
+	})
+}
+
+// TestValidatePorts_adminHTTPS verifies that [validatePorts] includes the
+// optional dedicated admin HTTPS port in its uniqueness check.
+func TestValidatePorts_adminHTTPS(t *testing.T) {
+	t.Parallel()
+
+	// Baseline ports used below.  These are non-overlapping so that the test
+	// cases below fail or pass solely based on the admin HTTPS port.
+	const (
+		bindPort        tcpPort = 3000
+		dohPort         tcpPort = 443
+		dotPort         tcpPort = 853
+		dnscryptTCPPort tcpPort = 5443
+		dnsPort         udpPort = 53
+		doqPort         udpPort = 784
+	)
+
+	testCases := []struct {
+		name           string
+		adminHTTPSPort tcpPort
+		wantErr        bool
+	}{{
+		name:           "unused",
+		adminHTTPSPort: 0,
+		wantErr:        false,
+	}, {
+		name:           "unique",
+		adminHTTPSPort: 4443,
+		wantErr:        false,
+	}, {
+		name:           "conflicts_with_doh",
+		adminHTTPSPort: dohPort,
+		wantErr:        true,
+	}, {
+		name:           "conflicts_with_webapi",
+		adminHTTPSPort: bindPort,
+		wantErr:        true,
+	}, {
+		name:           "conflicts_with_dot",
+		adminHTTPSPort: dotPort,
+		wantErr:        true,
+	}, {
+		name:           "conflicts_with_plain_dns",
+		adminHTTPSPort: tcpPort(dnsPort),
+		wantErr:        true,
+	}}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := validatePorts(
+				bindPort,
+				dohPort,
+				dotPort,
+				dnscryptTCPPort,
+				tc.adminHTTPSPort,
+				dnsPort,
+				doqPort,
+			)
+			if tc.wantErr {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+// TestSetPrivateFieldsAndCompare_adminListenAddr verifies that
+// [tlsConfigSettings.setPrivateFieldsAndCompare] preserves the server-side
+// [tlsConfigSettings.AdminListenAddr] value across updates from the frontend
+// and that [cmp.Equal] is able to compare the field.
+func TestSetPrivateFieldsAndCompare_adminListenAddr(t *testing.T) {
+	t.Parallel()
+
+	const testAddr = "127.0.0.1:4443"
+
+	server := &tlsConfigSettings{
+		Enabled:         true,
+		PortHTTPS:       443,
+		AdminListenAddr: netip.MustParseAddrPort(testAddr),
+	}
+
+	// Simulate the frontend sending a new TLS config that does not include
+	// AdminListenAddr (since it is not exposed in the UI).  The server-side
+	// value must be preserved.
+	fromFrontend := &tlsConfigSettings{
+		Enabled:   true,
+		PortHTTPS: 443,
+	}
+
+	equal := server.setPrivateFieldsAndCompare(fromFrontend)
+	assert.True(
+		t,
+		equal,
+		"configs should be equal when only AdminListenAddr is missing from the frontend",
+	)
+	assert.Equal(
+		t,
+		netip.MustParseAddrPort(testAddr),
+		fromFrontend.AdminListenAddr,
+		"server-side AdminListenAddr should be copied into frontend payload",
+	)
+
+	// If the frontend changes an actual user-editable field, the configs must
+	// compare unequal.
+	fromFrontend2 := &tlsConfigSettings{
+		Enabled:   true,
+		PortHTTPS: 8443,
+	}
+
+	equal = server.setPrivateFieldsAndCompare(fromFrontend2)
+	assert.False(t, equal, "configs should be unequal when PortHTTPS differs")
+}
+
+// TestRegisterDoHHandlers_muxSplit verifies that when
+// [tlsConfigSettings.AdminListenAddr] is configured, [registerDoHHandlers]
+// registers DoH routes on the dedicated DoH mux rather than on the shared
+// admin mux.
+func TestRegisterDoHHandlers_muxSplit(t *testing.T) {
+	// Save and restore the globals touched by this test.  The global
+	// [homeContext] cannot be copied by value because it contains mutexes,
+	// so save only the single field that is overwritten.
+	prevWeb := globalContext.web
+	prevConfig := config
+	t.Cleanup(func() {
+		globalContext.web = prevWeb
+		config = prevConfig
+	})
+
+	const dohRoute = "/dns-query"
+
+	testCases := []struct {
+		name            string
+		adminListenAddr netip.AddrPort
+		wantOnAdmin     bool
+		wantOnDoH       bool
+	}{{
+		name:            "disabled",
+		adminListenAddr: netip.AddrPort{},
+		wantOnAdmin:     true,
+		wantOnDoH:       false,
+	}, {
+		name:            "enabled",
+		adminListenAddr: netip.MustParseAddrPort("127.0.0.1:4443"),
+		wantOnAdmin:     false,
+		wantOnDoH:       true,
+	}}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			config = &configuration{
+				TLS: tlsConfigSettings{
+					AdminListenAddr: tc.adminListenAddr,
+				},
+			}
+
+			adminMux := http.NewServeMux()
+			dohMux := http.NewServeMux()
+
+			globalContext.web = &webAPI{
+				conf: &webAPIConfig{
+					mux:    adminMux,
+					dohMux: dohMux,
+				},
+			}
+
+			registerDoHHandlers([]string{dohRoute})
+
+			assert.Equal(t, tc.wantOnAdmin, hasPattern(adminMux, dohRoute))
+			assert.Equal(t, tc.wantOnDoH, hasPattern(dohMux, dohRoute))
+		})
+	}
+}
+
+// hasPattern returns true if pattern is registered on mux, as determined by
+// [http.ServeMux.Handler].
+func hasPattern(mux *http.ServeMux, pattern string) (ok bool) {
+	req := httptest.NewRequest(http.MethodGet, pattern, nil)
+	_, p := mux.Handler(req)
+
+	return p == pattern
+}
diff --git a/internal/home/config.go b/internal/home/config.go
index 7f633c5070a..5f7ca4f9096 100644
--- a/internal/home/config.go
+++ b/internal/home/config.go
@@ -29,6 +29,7 @@ import (
 	"github.com/AdguardTeam/golibs/netutil"
 	"github.com/AdguardTeam/golibs/timeutil"
 	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/google/renameio/v2/maybe"
 	yaml "go.yaml.in/yaml/v4"
 )
@@ -312,6 +313,18 @@ type tlsConfigSettings struct {
 	// PortHTTPS is the HTTPS port.  If 0, HTTPS will be disabled.
 	PortHTTPS uint16 `yaml:"port_https" json:"port_https,omitempty"`
 
+	// AdminListenAddr is the optional dedicated listen address (IP and port)
+	// for the HTTPS admin UI and API.  When it is valid and non-zero, a
+	// separate HTTPS server is started on this address that serves only admin
+	// UI and API requests, and the HTTPS server on [PortHTTPS] serves DNS-over-
+	// HTTPS only.  Both servers share the same TLS certificate.  When unset,
+	// admin UI and DoH continue to share the HTTPS server on [PortHTTPS].
+	//
+	// This field is intended to be configured via YAML only; it is not exposed
+	// in the web UI.  See https://github.com/AdguardTeam/AdGuardHome/issues/7424
+	// and https://github.com/AdguardTeam/AdGuardHome/issues/7598.
+	AdminListenAddr netip.AddrPort `yaml:"admin_listen_addr" json:"-"`
+
 	// PortDNSOverTLS is the DNS-over-TLS port.  If 0, DoT will be disabled.
 	PortDNSOverTLS uint16 `yaml:"port_dns_over_tls" json:"port_dns_over_tls,omitempty"`
 
@@ -382,6 +395,7 @@ func (c *tlsConfigSettings) clone() (clone *tlsConfigSettings) {
 //	[tlsConfigSettings.DNSCryptConfigFile]
 //	[tlsConfigSettings.OverrideTLSCiphers]
 //	[tlsConfigSettings.PortDNSCrypt]
+//	[tlsConfigSettings.AdminListenAddr]
 //
 // The following properties are skipped as they are set by
 // [tlsManager.loadTLSConfig]:
@@ -393,9 +407,13 @@ func (c *tlsConfigSettings) setPrivateFieldsAndCompare(conf *tlsConfigSettings)
 
 	conf.DNSCryptConfigFile = c.DNSCryptConfigFile
 	conf.PortDNSCrypt = c.PortDNSCrypt
+	conf.AdminListenAddr = c.AdminListenAddr
 
 	// TODO(a.garipov): Define a custom comparer.
-	return cmp.Equal(c, conf)
+	//
+	// [netip.AddrPort] contains unexported fields, so it needs an explicit
+	// equality option.
+	return cmp.Equal(c, conf, cmpopts.EquateComparable(netip.AddrPort{}))
 }
 
 type queryLogConfig struct {
@@ -803,6 +821,10 @@ func validateConfig(ctx context.Context, l *slog.Logger, fileData []byte) (err e
 			tcpPort(config.TLS.PortDNSCrypt),
 		)
 
+		if adminAddr := adminListenAddr(&config.TLS); adminAddr != (netip.AddrPort{}) {
+			addPorts(tcpPorts, tcpPort(adminAddr.Port()))
+		}
+
 		// TODO(e.burkov):  Consider adding a udpPort with the same value when
 		// we add support for HTTP/3 for web admin interface.
 		addPorts(udpPorts, udpPort(config.TLS.PortDNSOverQUIC))
diff --git a/internal/home/control.go b/internal/home/control.go
index 3a60ad42a62..3598f2d5cde 100644
--- a/internal/home/control.go
+++ b/internal/home/control.go
@@ -368,18 +368,7 @@ func (web *webAPI) handleHTTPSRedirect(w http.ResponseWriter, r *http.Request) (
 		return false
 	}
 
-	var (
-		forceHTTPS bool
-		serveHTTP3 bool
-		portHTTPS  uint16
-	)
-	func() {
-		config.RLock()
-		defer config.RUnlock()
-
-		serveHTTP3, portHTTPS = config.DNS.ServeHTTP3, config.TLS.PortHTTPS
-		forceHTTPS = config.TLS.ForceHTTPS && config.TLS.Enabled && config.TLS.PortHTTPS != 0
-	}()
+	forceHTTPS, serveHTTP3, portHTTPS, redirectPort := readHTTPSRedirectConfig()
 
 	respHdr := w.Header()
 
@@ -396,7 +385,7 @@ func (web *webAPI) handleHTTPSRedirect(w http.ResponseWriter, r *http.Request) (
 
 	if forceHTTPS {
 		if r.TLS == nil {
-			u := httpsURL(r.URL, host, portHTTPS)
+			u := httpsURL(r.URL, host, redirectPort)
 			http.Redirect(w, r, u.String(), http.StatusTemporaryRedirect)
 
 			return false
@@ -423,6 +412,32 @@ func (web *webAPI) handleHTTPSRedirect(w http.ResponseWriter, r *http.Request) (
 	return true
 }
 
+// readHTTPSRedirectConfig reads the configuration fields used by
+// [webAPI.handleHTTPSRedirect] under a single read-lock.  redirectPort is the
+// destination port for the plain HTTP → HTTPS redirect: the dedicated admin
+// HTTPS listen address port when configured, and [tlsConfigSettings.PortHTTPS]
+// otherwise.
+func readHTTPSRedirectConfig() (forceHTTPS, serveHTTP3 bool, portHTTPS, redirectPort uint16) {
+	config.RLock()
+	defer config.RUnlock()
+
+	serveHTTP3 = config.DNS.ServeHTTP3
+	portHTTPS = config.TLS.PortHTTPS
+	redirectPort = portHTTPS
+	tlsEnabled := config.TLS.Enabled
+
+	if a := adminListenAddr(&config.TLS); a != (netip.AddrPort{}) {
+		redirectPort = a.Port()
+		forceHTTPS = config.TLS.ForceHTTPS && tlsEnabled
+
+		return forceHTTPS, serveHTTP3, portHTTPS, redirectPort
+	}
+
+	forceHTTPS = config.TLS.ForceHTTPS && tlsEnabled && portHTTPS != 0
+
+	return forceHTTPS, serveHTTP3, portHTTPS, redirectPort
+}
+
 // httpsURL returns a copy of u for redirection to the HTTPS version, taking the
 // hostname and the HTTPS port into account.
 func httpsURL(u *url.URL, host string, portHTTPS uint16) (redirectURL *url.URL) {
diff --git a/internal/home/dns.go b/internal/home/dns.go
index dc776088d78..fc29aec6578 100644
--- a/internal/home/dns.go
+++ b/internal/home/dns.go
@@ -591,9 +591,26 @@ func checkDir(path string) (err error) {
 	return nil
 }
 
-// registerDoHHandlers registers DoH handlers on the given routes.
+// registerDoHHandlers registers DoH handlers on the given routes.  When a
+// dedicated HTTPS admin listen address is configured (see
+// [tlsConfigSettings.AdminListenAddr]), DoH routes are registered on the
+// dedicated DoH multiplexer instead of the shared admin multiplexer, so that
+// admin UI and API endpoints are not reachable on the DoH port and vice versa.
 func registerDoHHandlers(routes []string) {
+	var adminSet bool
+	func() {
+		config.RLock()
+		defer config.RUnlock()
+
+		adminSet = adminListenAddr(&config.TLS) != (netip.AddrPort{})
+	}()
+
+	mux := globalContext.web.conf.mux
+	if adminSet {
+		mux = globalContext.web.conf.dohMux
+	}
+
 	for _, route := range routes {
-		globalContext.web.conf.mux.Handle(route, globalContext.dnsServer)
+		mux.Handle(route, globalContext.dnsServer)
 	}
 }
diff --git a/internal/home/home.go b/internal/home/home.go
index e60d4c195f4..fbc0848da5a 100644
--- a/internal/home/home.go
+++ b/internal/home/home.go
@@ -544,6 +544,10 @@ func checkPorts() (err error) {
 			tcpPort(config.TLS.PortDNSCrypt),
 		)
 
+		if adminAddr := adminListenAddr(&config.TLS); adminAddr != (netip.AddrPort{}) {
+			addPorts(tcpPorts, tcpPort(adminAddr.Port()))
+		}
+
 		addPorts(udpPorts, udpPort(config.TLS.PortDNSOverQUIC))
 	}
 
@@ -617,6 +621,11 @@ type webConfig struct {
 	// must not be nil.
 	mux *http.ServeMux
 
+	// dohMux is a dedicated *http.ServeMux used only when a separate HTTPS
+	// admin listen address is configured (see
+	// [tlsConfigSettings.AdminListenAddr]).  It must not be nil.
+	dohMux *http.ServeMux
+
 	// configModifier is used to update the global configuration.
 	configModifier agh.ConfigModifier
 
@@ -666,6 +675,7 @@ func newWeb(ctx context.Context, conf *webConfig) (web *webAPI, err error) {
 		tlsManager:         conf.tlsManager,
 		auth:               conf.auth,
 		mux:                conf.mux,
+		dohMux:             conf.dohMux,
 
 		clientFS: clientFS,
 
@@ -750,6 +760,7 @@ func run(
 
 	mw := &webMw{}
 	mux := http.NewServeMux()
+	dohMux := http.NewServeMux()
 	httpReg := aghhttp.NewDefaultRegistrar(mux, mw.wrap)
 
 	err := setupContext(ctx, baseLogger, opts, workDir, confPath, isFirstRun)
@@ -809,6 +820,7 @@ func run(
 		tlsManager:     tlsMgr,
 		auth:           auth,
 		mux:            mux,
+		dohMux:         dohMux,
 		configModifier: confModifier,
 		httpReg:        httpReg,
 		workDir:        workDir,
@@ -1285,6 +1297,7 @@ func printHTTPAddresses(ctx context.Context, l *slog.Logger, proto string, tlsMg
 
 	if proto == urlutil.SchemeHTTPS && tlsConf.ServerName != "" {
 		printWebAddrs(ctx, l, proto, tlsConf.ServerName, tlsConf.PortHTTPS)
+		printAdminHTTPSAddr(ctx, l, proto, tlsConf)
 
 		return
 	}
@@ -1292,6 +1305,7 @@ func printHTTPAddresses(ctx context.Context, l *slog.Logger, proto string, tlsMg
 	bindHost := config.HTTPConfig.Address.Addr()
 	if !bindHost.IsUnspecified() {
 		printWebAddrs(ctx, l, proto, bindHost.String(), port)
+		printAdminHTTPSAddr(ctx, l, proto, tlsConf)
 
 		return
 	}
@@ -1312,6 +1326,29 @@ func printHTTPAddresses(ctx context.Context, l *slog.Logger, proto string, tlsMg
 			printWebAddrs(ctx, l, proto, addr.String(), port)
 		}
 	}
+
+	printAdminHTTPSAddr(ctx, l, proto, tlsConf)
+}
+
+// printAdminHTTPSAddr logs the configured dedicated HTTPS admin listen
+// address, if any.  It is a no-op when proto is not HTTPS or when no admin
+// listen address is configured.
+func printAdminHTTPSAddr(
+	ctx context.Context,
+	l *slog.Logger,
+	proto string,
+	tlsConf *tlsConfigSettings,
+) {
+	if proto != urlutil.SchemeHTTPS {
+		return
+	}
+
+	adminAddr := adminListenAddr(tlsConf)
+	if adminAddr == (netip.AddrPort{}) {
+		return
+	}
+
+	printWebAddrs(ctx, l, proto, adminAddr.Addr().String(), adminAddr.Port())
 }
 
 // detectFirstRun returns true if this is the first run of AdGuard Home.  l must
diff --git a/internal/home/tls.go b/internal/home/tls.go
index ffabd18d907..6f092ad7f08 100644
--- a/internal/home/tls.go
+++ b/internal/home/tls.go
@@ -681,11 +681,21 @@ func (m *tlsManager) validateTLSSettings(setts tlsConfigSettingsExt) (err error)
 		plainDNSPort = config.DNS.Port
 	}()
 
+	// AdminListenAddr has json:"-" and so is never present in the frontend
+	// payload setts.  Read it from the server-side tlsConf snapshot to
+	// detect conflicts when the UI changes port_https to a value equal to
+	// the YAML-configured admin listen port.
+	adminPort := tcpPort(0)
+	if adminAddr := adminListenAddr(&tlsConf); adminAddr != (netip.AddrPort{}) {
+		adminPort = tcpPort(adminAddr.Port())
+	}
+
 	err = validatePorts(
 		tcpPort(webAPIPort),
 		tcpPort(setts.PortHTTPS),
 		tcpPort(setts.PortDNSOverTLS),
 		tcpPort(setts.PortDNSCrypt),
+		adminPort,
 		udpPort(plainDNSPort),
 		udpPort(setts.PortDNSOverQUIC),
 	)
@@ -699,9 +709,10 @@ func (m *tlsManager) validateTLSSettings(setts tlsConfigSettingsExt) (err error)
 }
 
 // validatePorts validates the uniqueness of TCP and UDP ports for AdGuard Home
-// DNS protocols.
+// DNS protocols.  adminHTTPSPort is the optional dedicated admin HTTPS port
+// (see [tlsConfigSettings.AdminListenAddr]); pass 0 if unused.
 func validatePorts(
-	bindPort, dohPort, dotPort, dnscryptTCPPort tcpPort,
+	bindPort, dohPort, dotPort, dnscryptTCPPort, adminHTTPSPort tcpPort,
 	dnsPort, doqPort udpPort,
 ) (err error) {
 	tcpPorts := aghalg.UniqChecker[tcpPort]{}
@@ -713,6 +724,9 @@ func validatePorts(
 		dnscryptTCPPort,
 		tcpPort(dnsPort),
 	)
+	if adminHTTPSPort != 0 {
+		addPorts(tcpPorts, adminHTTPSPort)
+	}
 
 	err = tcpPorts.Validate()
 	if err != nil {
@@ -817,7 +831,7 @@ func (m *tlsManager) checkPortAvailability(
 	var errs []error
 	for _, v := range needBindingCheck {
 		port := v.newPort
-		if v.currPort == port {
+		if v.currPort == port || port == 0 {
 			continue
 		}
 
@@ -828,6 +842,20 @@ func (m *tlsManager) checkPortAvailability(
 		}
 	}
 
+	// The dedicated admin HTTPS listener binds on its own configured IP
+	// address, which may differ from the main web API bind host, so it must
+	// be checked separately using its own [netip.AddrPort].
+	const protoAdminHTTPS = "admin HTTPS"
+	currAdmin := adminListenAddr(&currConf)
+	newAdmin := adminListenAddr(&newConf)
+	if newAdmin != (netip.AddrPort{}) && currAdmin != newAdmin {
+		if err = aghnet.CheckPort(networkTCP, newAdmin); err != nil {
+			errs = append(errs, fmt.Errorf(
+				"port %d for %s is not available", newAdmin.Port(), protoAdminHTTPS,
+			))
+		}
+	}
+
 	return errors.Join(errs...)
 }
 
diff --git a/internal/home/web.go b/internal/home/web.go
index 3bda3e3fb56..35e5cea9ccf 100644
--- a/internal/home/web.go
+++ b/internal/home/web.go
@@ -74,6 +74,12 @@ type webAPIConfig struct {
 	// must not be nil.
 	mux *http.ServeMux
 
+	// dohMux is the dedicated multiplexer used when a separate HTTPS admin
+	// listen address is configured (see [tlsConfigSettings.AdminListenAddr]).
+	// It contains only DoH routes and is used by the HTTPS server on
+	// [tlsConfigSettings.PortHTTPS] in that mode.  It must not be nil.
+	dohMux *http.ServeMux
+
 	// clientFS is used to initialize file server.  It must not be nil.
 	clientFS fs.FS
 
@@ -163,12 +169,37 @@ type webAPI struct {
 
 	// httpsServer is the server that handles HTTPS traffic.  If it is not nil,
 	// [Web.http3Server] must also not be nil.
+	//
+	// When [tlsConfigSettings.AdminListenAddr] is unset, this server handles
+	// both admin UI/API and DoH requests.  Otherwise, it handles DoH requests
+	// only, and admin UI/API requests are handled by [webAPI.adminHTTPSServer].
 	httpsServer httpsServer
 
+	// adminHTTPSServer is the HTTPS server that serves only the admin UI and
+	// API on [tlsConfigSettings.AdminListenAddr].  It is only started when
+	// [tlsConfigSettings.AdminListenAddr] is valid and has a non-zero port.
+	adminHTTPSServer httpsServer
+
 	// startTime is the start time of the web API server in Unix milliseconds.
 	startTime time.Time
 }
 
+// adminListenAddr returns the currently configured dedicated HTTPS admin
+// listen address, if any.  It returns the zero value if the feature is
+// disabled.
+func adminListenAddr(tlsConf *tlsConfigSettings) (addr netip.AddrPort) {
+	if tlsConf == nil {
+		return netip.AddrPort{}
+	}
+
+	a := tlsConf.AdminListenAddr
+	if !a.IsValid() || a.Port() == 0 {
+		return netip.AddrPort{}
+	}
+
+	return a
+}
+
 // newWebAPI creates a new instance of the web UI and API server.  conf must be
 // valid.
 //
@@ -208,6 +239,7 @@ func newWebAPI(ctx context.Context, conf *webAPIConfig) (w *webAPI) {
 	}
 
 	w.httpsServer.cond = sync.NewCond(&w.httpsServer.condLock)
+	w.adminHTTPSServer.cond = sync.NewCond(&w.adminHTTPSServer.condLock)
 
 	return w
 }
@@ -234,10 +266,9 @@ func (web *webAPI) tlsConfigChanged(ctx context.Context, tlsConf *tlsConfigSetti
 
 	web.httpsServer.cond.L.Lock()
 	if web.httpsServer.server != nil {
-		var cancel context.CancelFunc
-		ctx, cancel = context.WithTimeout(ctx, shutdownTimeout)
-		shutdownSrv(ctx, web.logger, web.httpsServer.server)
-		shutdownSrv3(ctx, web.logger, web.httpsServer.server3)
+		shutCtx, cancel := context.WithTimeout(ctx, shutdownTimeout)
+		shutdownSrv(shutCtx, web.logger, web.httpsServer.server)
+		shutdownSrv3(shutCtx, web.logger, web.httpsServer.server3)
 
 		cancel()
 	}
@@ -246,6 +277,23 @@ func (web *webAPI) tlsConfigChanged(ctx context.Context, tlsConf *tlsConfigSetti
 	web.httpsServer.cert = cert
 	web.httpsServer.cond.Broadcast()
 	web.httpsServer.cond.L.Unlock()
+
+	// The admin HTTPS server shares its cert with the DoH HTTPS server and is
+	// only enabled when a dedicated admin listen address is configured.
+	adminEnabled := enabled && adminListenAddr(tlsConf) != (netip.AddrPort{})
+
+	web.adminHTTPSServer.cond.L.Lock()
+	if web.adminHTTPSServer.server != nil {
+		shutCtx, cancel := context.WithTimeout(ctx, shutdownTimeout)
+		shutdownSrv(shutCtx, web.logger, web.adminHTTPSServer.server)
+
+		cancel()
+	}
+
+	web.adminHTTPSServer.enabled = adminEnabled
+	web.adminHTTPSServer.cert = cert
+	web.adminHTTPSServer.cond.Broadcast()
+	web.adminHTTPSServer.cond.L.Unlock()
 }
 
 // loggerKeyServer is the key used by [webAPI] to identify servers.
@@ -259,6 +307,7 @@ func (web *webAPI) start(ctx context.Context) {
 
 	// for https, we have a separate goroutine loop
 	go web.tlsServerLoop(ctx)
+	go web.adminTLSServerLoop(ctx)
 
 	// this loop is used as an ability to change listening host and/or port
 	for !web.httpsServer.inShutdown {
@@ -315,14 +364,21 @@ func (web *webAPI) close(ctx context.Context) {
 
 	web.httpsServer.cond.L.Lock()
 	web.httpsServer.inShutdown = true
+	web.httpsServer.cond.Broadcast()
 	web.httpsServer.cond.L.Unlock()
 
+	web.adminHTTPSServer.cond.L.Lock()
+	web.adminHTTPSServer.inShutdown = true
+	web.adminHTTPSServer.cond.Broadcast()
+	web.adminHTTPSServer.cond.L.Unlock()
+
 	var cancel context.CancelFunc
 	ctx, cancel = context.WithTimeout(ctx, shutdownTimeout)
 	defer cancel()
 
 	shutdownSrv(ctx, web.logger, web.httpsServer.server)
 	shutdownSrv3(ctx, web.logger, web.httpsServer.server3)
+	shutdownSrv(ctx, web.logger, web.adminHTTPSServer.server)
 	shutdownSrv(ctx, web.logger, web.httpServer)
 
 	if web.auth != nil {
@@ -351,12 +407,16 @@ func (web *webAPI) serveTLS(ctx context.Context) (next bool) {
 		return false
 	}
 
-	var portHTTPS uint16
+	var (
+		portHTTPS   uint16
+		adminListen netip.AddrPort
+	)
 	func() {
 		config.RLock()
 		defer config.RUnlock()
 
 		portHTTPS = config.TLS.PortHTTPS
+		adminListen = adminListenAddr(&config.TLS)
 	}()
 
 	addr := netip.AddrPortFrom(web.conf.BindAddr.Addr(), portHTTPS).String()
@@ -364,11 +424,21 @@ func (web *webAPI) serveTLS(ctx context.Context) (next bool) {
 
 	// TODO(a.garipov):  Remove other logs like this in other code.
 	logMw := httputil.NewLogMiddleware(logger, slog.LevelDebug)
-	hdlr := logMw.Wrap(withMiddlewares(web.conf.mux, limitRequestBody))
+
+	// When a dedicated admin HTTPS listen address is configured, this server
+	// serves DoH only and must not require web-UI authentication.  Otherwise,
+	// it continues to serve both admin UI and DoH on the same port.
+	var hdlr http.Handler
+	if adminListen != (netip.AddrPort{}) {
+		hdlr = logMw.Wrap(withMiddlewares(web.conf.dohMux, limitRequestBody))
+	} else {
+		hdlr = logMw.Wrap(withMiddlewares(web.conf.mux, limitRequestBody))
+		hdlr = web.auth.middleware().Wrap(hdlr)
+	}
 
 	web.httpsServer.server = &http.Server{
 		Addr:    addr,
-		Handler: web.auth.middleware().Wrap(hdlr),
+		Handler: hdlr,
 		TLSConfig: &tls.Config{
 			Certificates: []tls.Certificate{web.httpsServer.cert},
 			RootCAs:      web.tlsManager.rootCerts,
@@ -397,6 +467,93 @@ func (web *webAPI) serveTLS(ctx context.Context) (next bool) {
 	return true
 }
 
+// adminTLSServerLoop implements retry logic for the dedicated admin HTTPS
+// server.  The loop is a no-op while [tlsConfigSettings.AdminListenAddr] is
+// unset.
+func (web *webAPI) adminTLSServerLoop(ctx context.Context) {
+	defer slogutil.RecoverAndExit(ctx, web.logger, osutil.ExitCodeFailure)
+
+	for {
+		shouldContinue := web.serveAdminTLS(ctx)
+		if !shouldContinue {
+			return
+		}
+	}
+}
+
+// serveAdminTLS initializes and starts the dedicated admin HTTPS server on
+// [tlsConfigSettings.AdminListenAddr], if configured.  It returns true when
+// another retry is required.
+func (web *webAPI) serveAdminTLS(ctx context.Context) (next bool) {
+	if !web.waitForAdminTLSReady() {
+		return false
+	}
+
+	var adminListen netip.AddrPort
+	func() {
+		config.RLock()
+		defer config.RUnlock()
+
+		adminListen = adminListenAddr(&config.TLS)
+	}()
+
+	if adminListen == (netip.AddrPort{}) {
+		// The feature was disabled between ready-broadcast and here.  Loop
+		// back and wait again.
+		return true
+	}
+
+	logger := web.baseLogger.With(loggerKeyServer, "admin-https")
+
+	// TODO(a.garipov):  Remove other logs like this in other code.
+	logMw := httputil.NewLogMiddleware(logger, slog.LevelDebug)
+	hdlr := logMw.Wrap(withMiddlewares(web.conf.mux, limitRequestBody))
+
+	web.adminHTTPSServer.server = &http.Server{
+		Addr:    adminListen.String(),
+		Handler: web.auth.middleware().Wrap(hdlr),
+		TLSConfig: &tls.Config{
+			Certificates: []tls.Certificate{web.adminHTTPSServer.cert},
+			RootCAs:      web.tlsManager.rootCerts,
+			CipherSuites: web.tlsManager.customCipherIDs,
+			MinVersion:   tls.VersionTLS12,
+		},
+		ReadTimeout:       web.conf.ReadTimeout,
+		ReadHeaderTimeout: web.conf.ReadHeaderTimeout,
+		WriteTimeout:      web.conf.WriteTimeout,
+		ErrorLog:          slog.NewLogLogger(logger.Handler(), slog.LevelError),
+	}
+
+	logger.InfoContext(ctx, "starting admin https server", "addr", adminListen.String())
+	err := web.adminHTTPSServer.server.ListenAndServeTLS("", "")
+	if !errors.Is(err, http.ErrServerClosed) {
+		cleanupAlways()
+		panic(fmt.Errorf("admin https: %w", err))
+	}
+
+	return true
+}
+
+// waitForAdminTLSReady blocks until the admin HTTPS server is enabled or a
+// shutdown signal is received.  Returns true when the server is ready.
+func (web *webAPI) waitForAdminTLSReady() (ok bool) {
+	web.adminHTTPSServer.cond.L.Lock()
+	defer web.adminHTTPSServer.cond.L.Unlock()
+
+	if web.adminHTTPSServer.inShutdown {
+		return false
+	}
+
+	for !web.adminHTTPSServer.enabled {
+		web.adminHTTPSServer.cond.Wait()
+		if web.adminHTTPSServer.inShutdown {
+			return false
+		}
+	}
+
+	return true
+}
+
 // waitForTLSReady blocks until the HTTPS server is enabled or a shutdown signal
 // is received.  Returns true when server is ready.
 func (web *webAPI) waitForTLSReady() (ok bool) {
@@ -422,6 +579,24 @@ func (web *webAPI) waitForTLSReady() (ok bool) {
 func (web *webAPI) mustStartHTTP3(ctx context.Context, address string) {
 	defer slogutil.RecoverAndExit(ctx, web.logger, osutil.ExitCodeFailure)
 
+	var adminListen netip.AddrPort
+	func() {
+		config.RLock()
+		defer config.RUnlock()
+
+		adminListen = adminListenAddr(&config.TLS)
+	}()
+
+	// Mirror [webAPI.serveTLS]: when a dedicated admin HTTPS listen address
+	// is configured, HTTP/3 on [tlsConfigSettings.PortHTTPS] serves DoH only
+	// and must not require web-UI authentication.
+	var hdlr http.Handler
+	if adminListen != (netip.AddrPort{}) {
+		hdlr = withMiddlewares(web.conf.dohMux, limitRequestBody)
+	} else {
+		hdlr = web.auth.middleware().Wrap(withMiddlewares(web.conf.mux, limitRequestBody))
+	}
+
 	web.httpsServer.server3 = &http3.Server{
 		// TODO(a.garipov): See if there is a way to use the error log as
 		// well as timeouts here.
@@ -432,7 +607,7 @@ func (web *webAPI) mustStartHTTP3(ctx context.Context, address string) {
 			CipherSuites: web.tlsManager.customCipherIDs,
 			MinVersion:   tls.VersionTLS12,
 		},
-		Handler: web.auth.middleware().Wrap(withMiddlewares(web.conf.mux, limitRequestBody)),
+		Handler: hdlr,
 	}
 
 	web.logger.DebugContext(ctx, "starting http/3 server")