Configuring the CoreDNS Service

This recipe walks through the procedure to enable the Netgate Nexus CoreDNS service for local client DNS filtering and resolution.

See also

Move DNS Resolver Port

Only one service can use TCP and UDP port 53 at a time. By default, the DNS Resolver service is running on these ports. Before the CoreDNS service can attach to the ports, the existing DNS service on that port must either be disabled or moved to an alternate port.

Note

Older upgraded configurations may be using the DNS Forwarder instead. This recipe only covers the DNS Resolver. If the DNS Forwarder is in use, change to the DNS Resolver before proceeding.

In some rare configurations, the add-on BIND package may be bound to this port. It must also be moved, but doing so is left to the reader.

This recipe assumes the DNS Resolver is active and that the administrator wants it to remain active as the primary upstream DNS source for CoreDNS. This gives additional flexibility in controlling DNS resolution behavior. With this configuration, existing behavior for upstream DNS remains the same, e.g. DNSSEC or DNS over TLS.

Warning

Local client DNS resolution will fail from this point until the recipe is completed. Perform this configuration during a maintenance window or whenever such disruption is acceptable.

Relocate the DNS Resolver service as follows:

  • Open the pfSense Plus GUI

  • Navigate to Services > DNS Resolver

  • Set Listen Port to 5353

  • Click Save

  • Click Apply Changes

Configure DHCP DNS Server

In certain cases the automatic DHCP server DNS server population will have the correct configuration, but it’s safe to manually configure the addresses to ensure clients are receiving the expected DNS configuration.

  • Open the pfSense Plus GUI

  • Navigate to Services > DHCP Server

  • Change to the tab for the LAN interface

  • Set DNS Server to the interface address only

  • Click Save

  • Repeat those actions for each local interface tab

  • Click Apply Changes

Configure System DNS

The system DNS configuration depends upon how administrators want it to behave.

  • Open the pfSense Plus GUI

  • Navigate to System > General Setup

  • Configure the DNS Servers list according to local preferences

    If the system should use specific upstream DNS servers, enter them here.

    Note

    This function does not support using alternate ports, so it cannot directly use the DNS resolver when the DNS Resolver is bound to port 5353.

  • Uncheck DNS Server Override if using specific remote DNS servers

  • Set DNS Resolution Behavior according to local preferences

    To have the system use CoreDNS, but still attempt others if CoreDNS is unavailable, pick Use local DNS (127.0.0.1), fall back to remote DNS Servers (Default).

    To have the system only ever use CoreDNS, choose Use local DNS (127.0.0.1), ignore remote DNS Servers

    Tip

    When the system itself is using CoreDNS, it need not be subject to all the same restrictions as other clients. Use a CoreDNS group for 127.0.0.0/8 with no fallback or blocks to allow full access.

    To have the system ignore CoreDNS and only use the listed remote servers, choose Use remote DNS Servers, ignore local DNS.

Enable and Configure Nexus

CoreDNS is only available through the Netgate Nexus GUI. To use that GUI, Netgate Nexus must be enabled and configured.

Before proceeding:

After following those procedures, access the GUI as described in Access the Netgate Nexus GUI.

Access Instance Configuration GUI

The CoreDNS configuration is located within the instance configuration GUI within Netgate Nexus.

Follow Configuring pfSense Plus Software Instances to access this GUI for the instance where CoreDNS will run.

Configure CoreDNS

Now it is time to configure the CoreDNS service itself.

Starting from within the Nexus instance configuration GUI, configure the service as follows:

  • Navigate to Services > CoreDNS

  • Set the Enable CoreDNS slider to On

  • Set Listen Port to 53

  • Set Interface to LAN and any other local interfaces

  • Set DNS Servers to 127.0.0.1:5353

    This instructs CoreDNS to use the DNS Resolver as its only DNS server.

  • Add Groups, Blocks, Forwards, and Resolver content if necessary

    Tip

    A good practice is to add a Resolver entry for a test host that otherwise would not resolve, e.g. doesnotexist.example.com. This way a client can try to resolve that host to confirm it is sending its queries to CoreDNS.

  • Click Save

CoreDNS is now enabled and fully configured!

Test Clients

With all changes in place, the best practice is to test at least one client to ensure it is properly communicating with CoreDNS:

  • Reboot the client and check that it receives the correct DNS server entry.

  • Attempt to resolve hosts and check that the results match expectations.