Include Hostname and Gateway for each DNS server in getSystemDNSEndpoint / patchSystemDNSEndpoint

[sherif-fanous]

Is your feature request related to existing pfSense functionality that is missing from the API? Please describe.

Yes. Under System > General Setup > DNS Server Settings, pfSense allows each configured DNS server to specify not just an IP address, but also a Hostname (used for TLS certificate validation when DNS over TLS is enabled) and an outbound Gateway.

• pfSense GUI: /system.php (DNS Server Settings)
• Netgate DNS over TLS documentation: https://docs.netgate.com/pfsense/en/latest/recipes/dns-over-tls.html#figure-dot-servers

The Hostname field is required to validate the TLS certificate presented by the upstream DNS server when using DNS over TLS. The Gateway field controls which gateway is used to reach a given DNS server.

Is your feature request related to a problem? Please describe.

The getSystemDNSEndpoint (GET /api/v2/system/dns) currently only returns the list of DNS server IP addresses in data.dnsserver. It does not expose the per-server Hostname or Gateway values, so there is no way to read or manage the TLS hostname or gateway assignment via the API.

Current response:

{
    "code": 200,
    "status": "ok",
    "response_id": "SUCCESS",
    "message": "",
    "data": {
        "dnsallowoverride": false,
        "dnslocalhost": "local",
        "dnsserver": [
            "1.1.1.1",
            "1.0.0.1",
            "2606:4700:4700::1111",
            "2606:4700:4700::1001"
        ]
    }
}

Because data.dnsserver is just a flat list of addresses, the corresponding Hostname (used for DNS over TLS certificate validation) and Gateway values that exist in the pfSense configuration cannot be retrieved or set through the API.

Describe the solution you'd like

Introduce two new list fields — dnshost (Hostname) and dnsgw (Gateway) — that run parallel to the existing dnsserver list and are matched by index. Entry i in dnshost/dnsgw corresponds to the DNS server at entry i in dnsserver. This keeps dnsserver as a plain list of addresses (no breaking change for existing consumers) while adding the missing per-server attributes.

To keep the parallel lists unambiguous:

• When present, dnshost and dnsgw should have the same length as dnsserver.
• Use null (or an empty string) for entries where no Hostname / Gateway is set, so indexes stay aligned.

1. GET /api/v2/system/dns (getSystemDNSEndpoint) — Return the new dnshost and dnsgw lists alongside the existing dnsserver list. For example:

{
    "code": 200,
    "status": "ok",
    "response_id": "SUCCESS",
    "message": "",
    "data": {
        "dnsallowoverride": false,
        "dnslocalhost": "local",
        "dnsserver": [
            "1.1.1.1",
            "1.0.0.1",
            "9.9.9.9"
        ],
        "dnshost": [
            "cloudflare-dns.com",
            "cloudflare-dns.com",
            "dns.quad9.net"
        ],
        "dnsgw": [
            "none",
            "none",
            "WAN_DHCP"
        ]
    }
}

2. PATCH /api/v2/system/dns (patchSystemDNSEndpoint) — Accept dnshost and dnsgw lists in the input payload and apply them to the pfSense configuration, matched by index to dnsserver. For example:

{
    "dnsserver": ["1.1.1.1", "1.0.0.1"],
    "dnshost": ["cloudflare-dns.com", "cloudflare-dns.com"],
    "dnsgw": ["none", "none"]
}

Why parallel lists rather than a list of objects

An alternative would be to change dnsserver into a list of objects (e.g. {"address": ..., "hostname": ..., "gateway": ...}). That is arguably a cleaner data model, but it would change the type of the existing dnsserver field from a list of strings to a list of objects, breaking every current consumer of this endpoint. The parallel-list approach is purely additive, preserves backward compatibility, and mirrors how pfSense itself stores the data (see below).

Describe alternatives you've considered

• A list of objects on dnsserver (cleaner, but a breaking change to the existing response shape — described above).
• Continuing to manage the Hostname/Gateway values manually through the pfSense web GUI, which defeats the purpose of automating DNS configuration via the API.
• Editing config.xml directly, which is fragile and bypasses validation.

Additional context

The relevant pfSense configuration values live under <system> in config.xml (see src/usr/local/www/system.php):

• dnsserver — an array of DNS server Addresses.
• dns{N}host (e.g. dns1host, dns2host, …) — the Hostname for the Nth DNS server, used for DNS over TLS certificate validation. Note these are 1-indexed per server, not a single dnshost field.
• dns{N}gw (e.g. dns1gw, dns2gw, …) — the Gateway for the Nth DNS server, likewise 1-indexed.

The proposed dnshost / dnsgw API lists map naturally onto these indexed config keys, and exposing all three (Address, Hostname, Gateway) would bring the API in line with what the pfSense GUI supports and enable full DNS over TLS configuration via the API.