DNS Forwarding
Test content
Background
Requirements
DNS forwarding
You can use the systemd-resolved
service to resolve local application names in your network. To use the service, configure systemd-resolved
to send .consul
domain queries to Consul by creating consul.conf
file located in the /etc/systemd/resolved.conf.d/ directory.
Add the following settings to your resolved configuration file:
/etc/systemd/resolved.conf.d/consul.conf
[Resolve]
DNS=127.0.0.1
DNSSEC=false
Domains=~consul
The main limitation with this configuration is that systemd 245 and older does not support configuring port numbers in the DNS field. You can either configure Consul to listen on port 53
instead of 8600, or map port 53 to 8600 using iptables
.
Binding to port 53 usually requires running systemd-resolved
as a privileged user or running Linux with the
CAP_NET_BIND_SERVICE capability. If you are using the Consul Docker image, then you will need to add the following to the environment to allow Consul to use the port: CONSUL_ALLOW_PRIVILEGED_PORTS=yes
The following iptables
commands are sufficient to map the ports.
iptables --table nat --append OUTPUT --destination localhost --protocol udp --match udp --dport 53 --jump REDIRECT --to-ports 8600
iptables --table nat --append OUTPUT --destination localhost --protocol tcp --match tcp --dport 53 --jump REDIRECT --to-ports 8600
The above configuration assumes Consul's DNS server is listening on the loopback address. If Consul is not listening on the loopback IP, replace the references to 'localhost' and '127.0.0.1' with the appropriate IP address for your environment.
Note
PTR record queries will still be sent out to the other configured resolvers, in addition to Consul.
After creating the resolved configuration, restart systemd-resolved
.
# systemctl restart systemd-resolved
Validate the systemd-resolved configuration
Validate that systemd-resolved has restarted and is configured to forward queries to Consul.
# systemctl is-active systemd-resolved
active
# resolvectl domain
Global: ~consul
Link 2 (eth0):
# resolvectl query consul.service.consul
consul.service.consul: 127.0.0.1
-- Information acquired via protocol DNS in 6.6ms.
-- Data is authenticated: no
Confirm that /etc/resolv.conf
points to the stub-resolv.conf
file managed by
systemd-resolved, and that the IP address for systemd-resolved's stub resolver
is the configured nameserver
.
$ ls -l /etc/resolv.conf
lrwxrwxrwx 1 root root 37 Aug 20 22:50 /etc/resolv.conf -> /run/systemd/resolve/stub-resolv.conf
$ cat /etc/resolv.conf
# This file is managed by man:systemd-resolved(8). Do not edit.
#
# This is a dynamic resolv.conf file for connecting local clients to the
# internal DNS stub resolver of systemd-resolved. This file lists all
# configured search domains.
#
# Run "resolvectl status" to see details about the uplink DNS servers
# currently in use.
#
# Third party programs must not access this file directly, but only through the
# symlink at /etc/resolv.conf. To manage man:resolv.conf(5) in a different way,
# replace this symlink by a static file or a different symlink.
#
# See man:systemd-resolved.service(8) for details about the supported modes of
# operation for /etc/resolv.conf.
nameserver 127.0.0.53
options edns0
Ensure that the operating system can resolve DNS queries to the .consul
domain.
$ host consul.service.consul
consul.service.consul has address 127.0.0.1
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, but you can set the DNSStubListener
option to false
, which disables the stub. As a result, your system will be able to use any DNS configuration as long as it loads earlier than resolved
.
/etc/systemd/resolved.conf
DNSStubListener=false
Disabling the local resolver stub can also solve other DNS configuration issues.
{/ /}
{/ /}
Tutorial: Learn how to perform this task in a tutorial.
Background
By default, DNS is served from port 53. On most operating systems, this requires elevated privileges. Rather than running Consul with an administrative or root account, you can forward appropriate queries to Consul (running on an unprivileged port) from another DNS server or port redirect.
Requirements
To complete this tutorial, you will need a running Consul agent. Consul should be running with default settings and serving DNS on port 8600.
By default, Consul does not resolve DNS records outside the .consul. zone unless the recursors configuration option has been set. For example, if a Consul DNS reply includes a CNAME record pointing outside the .consul top level domain (TLD), then the DNS reply will only include CNAME records by default. When recursors is set and the upstream resolver is functioning correctly, however, Consul will try to resolve CNAMEs and include any records (e.g., A, AAAA, PTR) for them in its DNS reply.
The requirements block describes the following information necessary to operate the product as described in the topic:
- system
- environment
- software requirements
- product version: Note that because we have versioned docs, specifying the core product version is not as important as version requirements for ancillary software, such as
kubectl
.
Sub requirement
The requirements section may include the following information:
- prerequisites
- constraints
- any other conditions or operating parameters
Multi-step procedure
Depending on the context, you can either add an introduction statement about the procedure or begin describing the procedure directly.
If the procedure describes a series of commands, we recommend setting environment variables as the first step so that you can use the variable name in subsequent commands. In some cases, you can place the response or output into the same code block. Always link to the relevant reference documentation:
<COMMAND> <RESPONSE>
Provide any additional context about the step as either a new paragraph in the step or as a list nested within the step.
The next step may require the user to configure a file. Always link to the relevant reference documentation. Use appropriate code blocks as necessary:
Some.code = value
The final step may require another command. Always link to the relevant reference documentation:
<COMMAND>
If the response or outcome requires additional explanation, describe it as part of the step:
<RESPONSE>
Single-step procedure
The single-step procedure (SSP) block describes a procedure or group of procedures that result in a specific outcome. Use SSP blocks when step-by-step instructions are not feasible.
Next steps
Introduce related tasks that either enhance this topic or are necessary to achieve a larger goal. Next steps link to other usage pages, rather than additional conceptual or reference information: