# pfSense DNS - Resolver, Forwarder, and Overrides

> Configuring DNS in pfSense - Unbound DNS Resolver, DNS Forwarder (dnsmasq), host overrides, DNSSEC, and DHCP integration

Source: https://opennix.org/en/docs/pfsense/services/pfsense-dns/


pfSense provides two built-in DNS services for name resolution - DNS Resolver based on Unbound and DNS Forwarder based on dnsmasq. Both services offer DNS query caching, record overrides, and DHCP integration, but they differ in architecture and intended use. DNS Resolver is the recommended solution and is enabled by default in current pfSense versions. DNS Forwarder should only be used in specific scenarios where simultaneous querying of multiple DNS servers is required.

## DNS Resolver vs DNS Forwarder

Before configuration, it is essential to determine which service meets the infrastructure requirements.

| Characteristic | DNS Resolver (Unbound) | DNS Forwarder (dnsmasq) |
|---|---|---|
| Operating mode | Recursive resolver or forwarder | Forwarder only |
| DNSSEC | Supported | Not supported |
| DNS over TLS | Supported | Not supported |
| Caching | Yes | Yes |
| Host overrides | Yes | Yes |
| Domain overrides | Yes | Yes |
| DHCP hostname registration | Yes | Yes |
| Parallel DNS server queries | No (sequential) | Yes (all servers simultaneously) |
| Enabled by default | Yes | No |

> **Warning**:
>
> Two DNS services cannot operate simultaneously on the same port. When enabling one service, the other must be disabled or assigned an alternative port.

### When to Use DNS Resolver

DNS Resolver (Unbound) is the preferred choice for most scenarios:

- Standard corporate or home networks requiring DNSSEC validation
- Environments requiring DNS query encryption through DNS over TLS
- Infrastructure needing direct recursive resolution without dependency on external forwarders
- Networks with DHCP registration and local DNS record integration

### When to Use DNS Forwarder

DNS Forwarder (dnsmasq) is justified in a limited number of situations:

- Multi-WAN configurations where parallel DNS server queries across all links provide faster responses
- Environments with unstable or high-latency DNS servers where parallel queries reduce latency
- Compatibility with legacy configurations previously using dnsmasq

## Configuring DNS Resolver

DNS Resolver configuration is performed through **Services > DNS Resolver**.

### General Settings

| Parameter | Description | Default Value |
|---|---|---|
| **Enable** | Enable DNS Resolver | Enabled |
| **Listen Port** | Listening port (TCP/UDP) | 53 |
| **Network Interfaces** | Interfaces for accepting queries | All interfaces |
| **Outgoing Network Interfaces** | Interfaces for sending queries | All interfaces |
| **System Domain Local Zone Type** | Zone type for the system domain | Transparent |
| **DNSSEC** | DNS response authenticity verification | Enabled |
| **DNS Query Forwarding** | Forwarding mode instead of recursion | Disabled |
| **DHCP Registration** | Register DHCP hostnames in DNS | Disabled |
| **Static DHCP** | Register DHCP static mapping hostnames | Disabled |
| **OpenVPN Clients** | Register OpenVPN client names | Disabled |

### Operating Mode - Resolver and Forwarding

By default, DNS Resolver operates in recursive resolver mode - it independently queries root DNS servers and sequentially follows the delegation chain until obtaining an answer. This mode does not depend on external forwarders and provides complete DNSSEC validation.

When **DNS Query Forwarding** is enabled, the Resolver switches to forwarder mode - queries are forwarded to DNS servers specified in **System > General Setup** or automatically obtained from the ISP. Forwarding mode is useful when:

- Corporate policy requires using specific DNS servers
- The ISP blocks direct DNS queries to root servers
- Content-filtering DNS servers are required (OpenDNS, Cloudflare for Families)

> **Warning**:
>
> When enabling DNS Query Forwarding in combination with DNSSEC, the upstream DNS servers must support DNSSEC. Otherwise, validation will fail and legitimate queries will be rejected.

### SSL/TLS Service (DNS over TLS)

DNS Resolver supports receiving encrypted queries from clients through DNS over TLS on port 853. To enable:

1. Check **SSL/TLS Service** in DNS Resolver settings
2. Ensure a valid certificate is configured on pfSense
3. Configure client devices to use pfSense as a DoT server

### Outgoing DNS over TLS

To encrypt outgoing DNS queries from pfSense to upstream servers:

1. Enable **DNS Query Forwarding**
2. Check **Use SSL/TLS for outgoing DNS Queries to Forwarding Servers**
3. Specify DNS servers with DoT support in **System > General Setup** (e.g., 1.1.1.1, 8.8.8.8, 9.9.9.9)

Encrypting outgoing queries prevents DNS traffic interception by the ISP or intermediate nodes.

## Host Overrides

Host Overrides create local DNS records that redirect resolution of specific hostnames to designated IP addresses. This functions as a network-wide equivalent of `/etc/hosts` entries managed at the DNS server level.

### Creating a Record

Configuration is performed in the **Host Overrides** section on the **Services > DNS Resolver** page.

| Field | Description | Example |
|---|---|---|
| **Host** | Hostname (without domain) | `intranet` |
| **Domain** | Domain name | `corp.local` |
| **IP Address** | IPv4 or IPv6 address | `192.168.1.100` |
| **Description** | Record description | `Corporate intranet server` |

Resulting DNS record: `intranet.corp.local` -> `192.168.1.100`

### Additional Names (Aliases)

Each Host Override supports adding alternative names through the **Additional Names for this Host** section. This is equivalent to CNAME records, allowing multiple names to point to a single address.

### Common Scenarios

- Redirecting internal traffic for company public services to local servers (split DNS / hairpin NAT)
- Creating short names for frequently accessed internal network resources
- Blocking access to specific domains (redirecting to 127.0.0.1)
- Testing web applications with DNS record substitution without modifying public DNS

## Domain Overrides

Domain Overrides redirect DNS queries for specific domains to designated DNS servers. Unlike Host Overrides that specify concrete IP addresses, Domain Overrides define the server responsible for resolving all records within a domain.

### Creating a Record

Configuration is performed in the **Domain Overrides** section on the **Services > DNS Resolver** page.

| Field | Description | Example |
|---|---|---|
| **Domain** | Domain name for redirection | `internal.corp.com` |
| **IP Address** | DNS server address for this domain | `10.0.0.53` |
| **TLS Queries** | Use DNS over TLS when querying | No |
| **TLS Hostname** | Hostname for TLS certificate verification | - |
| **Description** | Rule description | `Internal AD DNS` |

### Common Scenarios

- Forwarding Active Directory domain queries to domain controllers
- Resolving internal infrastructure zones through dedicated DNS servers
- Integration with branch office DNS servers over VPN
- Forwarding reverse DNS zones (in-addr.arpa) to authoritative servers

## DNSSEC

DNSSEC (Domain Name System Security Extensions) provides authenticity and integrity verification of DNS responses using cryptographic signatures. DNS Resolver in pfSense supports DNSSEC validation by default.

### How It Works

With DNSSEC enabled, the Resolver verifies the chain of trust from root servers down to the requested domain. If a DNS response signature fails verification, the response is rejected and the client receives a SERVFAIL error. This protects against:

- DNS spoofing (forged DNS responses)
- Cache poisoning (DNS cache corruption)
- Man-in-the-middle attacks at the DNS level

### DNSSEC Limitations

Not all domains are DNSSEC-signed. When querying an unsigned domain, validation is skipped and the response is processed normally.

When using DNS Query Forwarding, upstream servers must support passing DNSSEC records (DO bit). Most public DNS servers (Google DNS, Cloudflare, Quad9) handle DNSSEC correctly.

### DNSSEC Diagnostics

To verify DNSSEC operation, perform a query against a known signed domain through **Diagnostics > DNS Lookup**:

- `dnssec-failed.org` - a domain with an intentionally invalid signature; with working DNSSEC, the query should fail
- `dnssec.works` - a domain with a valid signature; the query should resolve successfully

## DHCP Integration

DNS Resolver supports automatic registration of hostnames obtained through DHCP, enabling devices on the network to be reached by name.

### Registration Configuration

The following options are available in **Services > DNS Resolver**:

| Parameter | Description |
|---|---|
| **DHCP Registration** | Register dynamic DHCP client hostnames |
| **Static DHCP** | Register hostnames from DHCP static mappings |
| **OpenVPN Clients** | Register connected OpenVPN client Common Names |

When DHCP Registration is enabled, a client requesting an address with hostname `workstation1` in domain `corp.local` automatically receives a DNS record `workstation1.corp.local` pointing to its DHCP address.

### Requirements

- The DHCP server and DNS Resolver must run on the same pfSense instance
- The client must transmit a hostname in the DHCP request (most operating systems do this by default)
- The pfSense system domain must be properly configured in **System > General Setup**

Detailed DHCP server configuration is covered in [pfSense DHCP Server](/docs/pfsense/services/pfsense-dhcp/).

## Access Lists

DNS Resolver access lists determine which clients are permitted to send DNS queries.

### Creating an Access List

Configuration is performed through the **Access Lists** tab on the **Services > DNS Resolver** page.

| Field | Description |
|---|---|
| **Access List Name** | Rule name |
| **Action** | Action: Allow, Deny, Refuse, Allow Snoop |
| **Networks** | Subnets to which the rule applies |
| **Description** | Rule description |

### Actions

| Action | Behavior |
|---|---|
| **Allow** | Permit recursive queries |
| **Deny** | Drop the query without response |
| **Refuse** | Reject the query with a REFUSED response |
| **Allow Snoop** | Permit all queries including non-recursive (for diagnostics) |

By default, DNS Resolver permits queries from all subnets assigned to pfSense interfaces. Additional access lists are necessary when serving clients from subnets not directly attached to interfaces (for example, clients behind an upstream router).

## Configuring DNS Forwarder

DNS Forwarder is configured through **Services > DNS Forwarder**. Before enabling, the DNS Resolver must be disabled or assigned a different port.

### Core Parameters

| Parameter | Description |
|---|---|
| **Enable** | Enable DNS Forwarder |
| **Network Interfaces** | Interfaces for accepting queries |
| **Query DNS servers sequentially** | Sequential queries instead of parallel |

By default, DNS Forwarder sends queries to all configured DNS servers simultaneously and uses the first received response. This minimizes latency but generates additional traffic. Enabling **Query DNS servers sequentially** causes servers to be queried in order.

DNS servers for forwarding are sourced from **System > General Setup** and from parameters automatically obtained from the ISP (DHCP, PPPoE).

### Host Overrides and Domain Overrides

DNS Forwarder supports the same host and domain override functionality as DNS Resolver. The syntax and operational logic are identical to those described above.

## Advanced Unbound Settings

The **Advanced Settings** tab allows passing arbitrary Unbound configuration directives through the **Custom Options** text field. This feature is intended for experienced administrators and enables:

- Configuring non-standard caching parameters
- Defining private domains (private-domain)
- Setting local zones and records
- Adjusting performance parameters (num-threads, msg-cache-size, rrset-cache-size)

Example of adding a local zone:

```text
server:
local-zone: "internal.example.com" static
local-data: "server1.internal.example.com A 10.0.0.10"
local-data: "server2.internal.example.com A 10.0.0.11"
```

> **Warning**:
>
> Incorrect directives in Custom Options will cause a DNS Resolver startup failure. It is advisable to verify configuration syntax before saving.

## Troubleshooting

### DNS Not Resolving Names

1. Verify that DNS Resolver or Forwarder is enabled (**Services > DNS Resolver** or **Services > DNS Forwarder**)
2. Confirm that the client is using the pfSense IP address as its DNS server
3. Perform a test query through **Diagnostics > DNS Lookup**
4. Verify that upstream DNS servers are reachable (**System > General Setup**)
5. Review logs: **Status > System Logs > Resolver** (or **Forwarder**)
6. Check firewall rules - DNS uses TCP/UDP port 53

### Slow DNS Resolution

1. In Resolver mode - verify root DNS server reachability; switch to Forwarding mode if necessary
2. In Forwarding mode - test latency to upstream servers using **Diagnostics > Ping**
3. Consider enabling DNS over TLS - encryption adds minimal latency but prevents interception
4. Check cache size - for frequent identical queries, increasing the cache through Advanced Settings reduces latency

### DNSSEC Errors

1. Verify that pfSense system time is correctly synchronized (DNSSEC signatures contain timestamps)
2. Check whether upstream DNS servers support DNSSEC (when using Forwarding)
3. Test with `dnssec-failed.org` - if it resolves, DNSSEC is not functioning
4. Temporarily disable DNSSEC to isolate the issue: if resolution works without DNSSEC, the problem lies in the chain of trust

### Host Override Not Working

1. Verify that the domain in Host Override matches what the client is requesting
2. Clear the DNS cache on the client device
3. Confirm that the client is using pfSense as its DNS server and not querying external servers directly
4. Check that firewall rules are not redirecting DNS traffic around pfSense

## Migration Notes

### Migration from Cisco DNS

In Cisco IOS, DNS settings are configured globally through `ip name-server` and `ip domain-name`. pfSense provides substantially more capabilities:

| Cisco IOS | pfSense |
|---|---|
| `ip name-server 8.8.8.8` | System > General Setup > DNS Servers |
| `ip domain-name corp.local` | System > General Setup > Domain |
| `ip host server1 192.168.1.10` | Host Overrides in DNS Resolver |
| `ip dns server` | Enable DNS Resolver |

### Migration from FortiGate DNS

FortiGate supports DNS Database with zones and records. In pfSense, equivalent functionality is implemented through Host Overrides and Domain Overrides:

- DNS Database records -> Host Overrides
- Conditional Forwarding -> Domain Overrides
- FortiGuard DNS Filter -> External DNS servers with filtering (Cloudflare for Families, OpenDNS)

### Migration from MikroTik DNS

MikroTik DNS is configured through `/ip dns`. Key mappings:

| MikroTik | pfSense |
|---|---|
| `/ip dns set servers=8.8.8.8` | System > General Setup > DNS Servers |
| `/ip dns set allow-remote-requests=yes` | Enable DNS Resolver on interface |
| `/ip dns static add` | Host Overrides |
| `/ip dns cache flush` | Diagnostics > DNS Lookup > Clear Cache |

## Related Sections

- [pfSense DHCP Server](/docs/pfsense/services/pfsense-dhcp/) - DHCP configuration with DNS hostname registration
- [Firewall Rules](/docs/pfsense/firewall/pfsense-firewall-rules/) - controlling DNS traffic and redirecting queries
- [VLAN Setup](/docs/pfsense/vlans/pfsense-vlan-setup/) - separate DNS configuration for different network segments