Enable DNS forwarding
This page describes the process to enable DNS forwarding to Consul servers.
You can apply these operations on every node where a Consul agent is running.
Requirements
To enable DNS forwarding, your deployment must have the following:
- A running Consul server instance
- One or more Consul client nodes with registered services in the Consul catalog
- The
iptables
command available, or one of the following local DNS servers:
Network address configuration
The example configurations on this page assumes Consul's DNS server is listening on the loopback interface on the same node of the local DNS server.
If Consul is not listening on the loopback IP, replace the references to localhost
and 120.0.0.1
in the configuration and commands with the appropriate IP address for your environment.
systemd-resolved
systemd-resolved
is a system service that provides network name resolution to local applications. It is the default local DNS server for many Linux distributions.
To configure the systemd-resolved
service so that it sends .consul
domain queries to Consul, create a consul.conf
file located in the /etc/systemd/resolved.conf.d/
directory.
Add a [Resolve]
section to your resolved configuration.
Define port for Consul DNS server
When using systemd 245 and older, you cannot specify port numbers in the DNS
configuration field. systemd-resolved only uses port 53
, which is a privileged port.
When you cannot specify ports for the system's configuration, there are two workarounds:
- Configure Consul DNS service to listen on port
53
instead of8600
. - Map port
53
to8600
usingiptables
.
Binding to port 53
usually requires running Consul as a privileged user or running Linux with the CAP_NET_BIND_SERVICE
capability.
When using the Consul Docker image, add the following to the environment to allow Consul to use the port: CONSUL_ALLOW_PRIVILEGED_PORTS=yes
.
To avoid running Consul as a privileged user, the following iptables
commands are sufficient to map port 53
to 8600
and redirect DNS queries to Consul.
PTR record queries are still sent to the other configured resolvers, in addition to Consul.
After creating the resolved configuration, restart systemd-resolved
.
The command produces no output.
Validate the systemd-resolved configuration
Validate that systemd-resolved
is active.
Verify that systemd-resolved
is configured to forward queries for the consul
domain to Consul.
Verify that systemd-resolved
is able to resolve the Consul server address.
Confirm that /etc/resolv.conf
points to the stub-resolv.conf
file managed by systemd-resolved
.
Confirm that the IP address for systemd-resolved
's stub resolver is the configured nameserver
.
Ensure that the operating system can resolve DNS queries to the .consul
domain.
Using any local resolver with systemd
By default, the local resolver stub in the resolved.conf
file is configured to listen for UDP and TCP requests at 127.0.0.53:53
. However, you can set the DNSStubListener
option to false
so that your system can use any DNS configuration, as long as it loads earlier than resolved
.
Dnsmasq
Use dnsmasq if you have a small network and need a lightweight DNS solution.
Note
If your distribution uses systemd, disable systemd-resolved
before you follow these steps.
Configure the dnsmasq.conf
file or a series of files in the /etc/dnsmasq.d
directory. Add server settings to your configuration file so that requests for the consul
domain are forwarded to Consul DNS.
Restart the dnsmasq
service after creating the configuration.
Refer to dnsmasq(8)
for additional configuration settings such as specifying IP addresses for queries not handled directly by Consul.
BIND
BIND is a robust DNS system. Its most prominent component, named
, performs both of the main DNS server roles, acts as an authoritative name server for DNS zones, and is a recursive resolver in the network.
Note
If your distribution uses systemd, disable systemd-resolved
before you follow these steps.
To configure the BIND service to send .consul
domain queries to Consul:
- Create a
named
configuration file withDNSSEC
disabled. - Create a zone configuration file to manage the
.consul
domain.
Named configuration file
Edit the /etc/named.conf
to configure your BIND instance. Remember to disable DNSSEC
so that Consul and BIND can communicate. Add an include
section to include the zone file that you create in the next step.
The following example shows a BIND configuration with DNSSEC
disabled.
Zone configuration file
Set up a zone for your Consul-managed records in consul.conf
.
Unbound
Use Unbound when you need a fast and lean DNS resolver for Linux and macOS.
Note
If your distribution uses systemd, disable systemd-resolved
before you follow these steps.
The following example demonstrates a configuration for the consul.conf
file in the /etc/unbound/unbound.conf.d
directory.
Add server
and stub-zone
settings to your Unbound configuration file.
You may have to add the following line to the bottom of your /etc/unbound/unbound.conf
file for the new configuration to be included.
iptables
iptables is a generic firewalling software that allows you to define traffic rules for your system.
If you do not have a local DNS server on the Consul agent node, use iptables
to forward DNS requests on port 53
to the Consul agent running on the same machine without using a secondary service.
This configuration realizes full DNS forwarding, which means that all DNS queries for the host are forwarded to Consul, not just the ones for the .consul
top level domain. Consul's default configuration resolves only the .consul
top level domain, so you must set the recursors
flag if you want your node to be able to resolve other domains when using iptables
configuration.
If you use DNS relay hosts in your network, do not place them on the same host as Consul. The redirects may intercept the traffic.
Configure Consul recursors
Add recursors to your Consul configuration.
Recursors should not include the localhost
address because the iptables
redirects would intercept the requests.
You can replace the 1.1.1.1
address in the example with another DNS server address. This is suitable for situations where an external DNS
service is already running in your infrastructure and is used as the recursor.
Create iptables rules
After you configure Consul to use a valid recursor, add rules to iptables
to redirect traffic from port 53
to port 8600
.
macOS
On macOS systems, use the macOS system resolver to point all .consul
requests to Consul.
The man 5 resolver
command describes this feature in more detail.
The following instructions require sudo
or root access.
To configure the macOS system resolver to forward DNS queries to Consul, add a resolver entry in the /etc/resolver/
directory that points at the Consul agent.
If you do not have this folder, create it.
Create a new file /etc/resolver/consul
with nameserver
and port
entries.
The configuration informs the macOS resolver daemon to forward all .consul
TLD requests to 127.0.0.1
on port 8600
.
Next steps
This instructions on this page helped you configure your node to forward DNS requests to Consul.
To learn more on how to query Consul DNS once forwarding is enabled, refer to DNS forwarding workflow.
For more information on other DNS features and configurations available in Consul, refer to DNS usage overview.