diff --git a/website/content/docs/services/discovery/dns-forwarding.mdx b/website/content/docs/services/discovery/dns-forwarding.mdx new file mode 100644 index 000000000000..7a3067ebb73c --- /dev/null +++ b/website/content/docs/services/discovery/dns-forwarding.mdx @@ -0,0 +1,455 @@ +--- +layout: docs +page_title: DNS Forwarding +description: -> + Learn how to configure your local DNS servers to perform DNS forwarding to Consul servers. +--- + +# DNS Forwarding + +Test content + +## Background + +## Requirements + +## DNS forwarding + + + + + +You can use the [`systemd-resolved`](https://www.freedesktop.org/wiki/Software/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: + + + +```ini +[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](/consul/docs/agent/config/config-files#dns_port) +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. + +```shell-session +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. + + + + + +If your distribution uses systemd 246 and newer, you can specify the DNS port directly in the `systemd-resolved` configuration file. +Previous versions of systemd required iptables rules to direct DNS traffic to Consul. + + + +```ini +[Resolve] +DNS=127.0.0.1:8600 +DNSSEC=false +Domains=~consul +``` + + + + + + + + + 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`. + +```shell-session +# systemctl restart systemd-resolved +``` + +### Validate the systemd-resolved configuration + +Validate that systemd-resolved has restarted and is configured to forward +queries to Consul. + +```shell-session hideClipboard +# 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`. + + + +```shell-session +$ 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. + +```shell-session +$ 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`. + + + +```plaintext +DNSStubListener=false +``` + + + +Disabling the local resolver stub can also solve other DNS configuration issues. + +{/* */} + + + + +In this example, BIND and Consul are running on the same machine. + + + + If your distribution uses systemd, you may need to disable `systemd-resolved` prior to following this example. + + + + {/* */} + +First, disable DNSSEC so that Consul and [BIND](https://www.isc.org/downloads/bind/) can communicate. The following example shows a BIND configuration with DNSSEC disabled. + + + +```plaintext +options { + listen-on port 53 { 127.0.0.1; }; + listen-on-v6 port 53 { ::1; }; + directory "/var/named"; + dump-file "/var/named/data/cache_dump.db"; + statistics-file "/var/named/data/named_stats.txt"; + memstatistics-file "/var/named/data/named_mem_stats.txt"; + allow-query { localhost; }; + recursion yes; + + dnssec-enable no; + dnssec-validation no; + + /* Path to ISC DLV key */ + bindkeys-file "/etc/named.iscdlv.key"; + + managed-keys-directory "/var/named/dynamic"; +}; + +include "/etc/named/consul.conf"; +``` + + + +### Zone file + +Next, set up a zone for your Consul managed records in `consul.conf`. + + + +```dns-zone-file +zone "consul" IN { + type forward; + forward only; + forwarders { 127.0.0.1 port 8600; }; +}; +``` + + + + + + + + + If your distribution uses systemd, you may need to disable `systemd-resolved` prior to following this example. + + + + {/* */} + +[Dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html) is typically configured via a `dnsmasq.conf` or a series of files in +the `/etc/dnsmasq.d` directory. Add the following settings to your dnsmasq configuration file +(e.g., `/etc/dnsmasq.d/10-consul`): + + + +```plaintext +# Enable forward lookup of the 'consul' domain: +server=/consul/127.0.0.1#8600 + +# Uncomment and modify as appropriate to enable reverse DNS lookups for +# common netblocks found in RFC 1918, 5735, and 6598: +#rev-server=0.0.0.0/8,127.0.0.1#8600 +#rev-server=10.0.0.0/8,127.0.0.1#8600 +#rev-server=100.64.0.0/10,127.0.0.1#8600 +#rev-server=127.0.0.1/8,127.0.0.1#8600 +#rev-server=169.254.0.0/16,127.0.0.1#8600 +#rev-server=172.16.0.0/12,127.0.0.1#8600 +#rev-server=192.168.0.0/16,127.0.0.1#8600 +#rev-server=224.0.0.0/4,127.0.0.1#8600 +#rev-server=240.0.0.0/4,127.0.0.1#8600 +``` + + + +Restart the `dnsmasq` service after creating the configuration. + +You can configure additional settings in `dnsmasq` that may be useful in your environments. See +[`dnsmasq(8)`](http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html) +for additional details. + + + +```plaintext +# Accept DNS queries only from hosts whose address is on a local subnet. +#local-service + +# Don't poll /etc/resolv.conf for changes. +#no-poll + +# Don't read /etc/resolv.conf. Get upstream servers only from the command +# line or the dnsmasq configuration file (see the "server" directive below). +#no-resolv + +# Specify IP address(es) of other DNS servers for queries not handled +# directly by consul. There is normally one 'server' entry set for every +# 'nameserver' parameter found in '/etc/resolv.conf'. See dnsmasq(8)'s +# 'server' configuration option for details. +#server=1.2.3.4 +#server=208.67.222.222 +#server=8.8.8.8 + +# Set the size of dnsmasq's cache. The default is 150 names. Setting the +# cache size to zero disables caching. +#cache-size=65536 +``` + + + + + + + + + + If your distribution uses systemd, you may need to disable `systemd-resolved` prior to following this example. + + + + {/* */} + +[Unbound](https://www.unbound.net/) is typically configured in a `unbound.conf` file or a series of files in +the `/etc/unbound/unbound.conf.d` directory. Add the following settings to your Unbound configuration file +(e.g., `/etc/unbound/unbound.conf.d/consul.conf`): + + + +```plaintext +#Allow insecure queries to local resolvers +server: + do-not-query-localhost: no + domain-insecure: "consul" + +#Add consul as a stub-zone +stub-zone: + name: "consul" + stub-addr: 127.0.0.1@8600 +``` + + + +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. + + + +```plaintext +include: "/etc/unbound/unbound.conf.d/*.conf" +``` + + + + + + + +The rules must be set on the same host as the Consul instance. Relay hosts _should not_ be on the same host, otherwise the redirects will intercept the traffic. + +On Linux systems that support it, incoming requests and requests to +the local host can use [`iptables`](http://www.netfilter.org/) to forward to ports on the same machine +without using a secondary service. The [`recursors`](/consul/docs/agent/config/config-files#recursors) flag is especially important for resolving other domains with `iptables`. +This is because Consul only resolves the `.consul` TLD by default. +Recursors should not include the local host address because the `iptables` redirects would intercept the requests. + +The `iptables` method is suitable for situations where an external DNS +service is already running in your infrastructure and is used as the +recursor. It is also a suitable method if you want to use an existing DNS server as your query +endpoint and forward requests for the `consul` domain to the Consul +server. In both cases, you may want to query the Consul server without the overhead of running a separate service on the Consul host. + +```shell-session +iptables -t nat -A PREROUTING -p udp -m udp --dport 53 -j REDIRECT --to-ports 8600 +iptables -t nat -A PREROUTING -p tcp -m tcp --dport 53 -j REDIRECT --to-ports 8600 +iptables -t nat -A OUTPUT -d localhost -p udp -m udp --dport 53 -j REDIRECT --to-ports 8600 +iptables -t nat -A OUTPUT -d localhost -p tcp -m tcp --dport 53 -j REDIRECT --to-ports 8600 +``` + + + + +On macOS systems, you can use the macOS system resolver to point all `.consul` requests to Consul. +Documentation for this feature is available via: `man 5 resolver`. +You must add a resolver entry in `/etc/resolver/` to point at Consul. If you do not have this folder, create it. +To configure a resolver entry, you will need sudo/root access. Create a new file `/etc/resolver/consul`, +and add the following text to the file: + + + +```plaintext +nameserver 127.0.0.1 +port 8600 +``` + + + +The configuration informs the macOS resolver daemon to forward all `.consul` TLD requests to 127.0.0.1 on port 8600. + + + + +{/* */} + +> **Tutorial**: Learn how to perform this task in a [tutorial](link). + +## 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. + +1. 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](link): + + ``` + + + ``` + + Provide any additional context about the step as either a new paragraph in the step or as a list nested within the step. + +1. The next step may require the user to configure a file. Always link to the relevant [reference documentation](link). Use appropriate code blocks as necessary: + + + + ```lang + Some.code = value + ``` + + + +1. The final step may require another command. Always link to the relevant [reference documentation](link): + + `` + + If the response or outcome requires additional explanation, describe it as part of the step: + + `` + +### 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: + +- [Title of the topic]() +- [Title of the topic]() diff --git a/website/content/docs/services/discovery/dns-overview.mdx b/website/content/docs/services/discovery/dns-overview.mdx index 34e92e5fe8a2..dd2b22bcf113 100644 --- a/website/content/docs/services/discovery/dns-overview.mdx +++ b/website/content/docs/services/discovery/dns-overview.mdx @@ -30,6 +30,12 @@ If you are using Consul for service mesh on VMs, you can use upstreams or DNS. W If you are using Consul on Kubernetes, refer to [the upstreams annotation documentation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) for additional information. +## DNS forwarding + +You can configure your local DNS servers to use Consul. + +Refer to [DNS Forwarding](/consul/docs/services/discovery/dns-forwarding) for additional information. + ## Static queries Node lookups and service lookups are the fundamental types of static queries. Depending on your use case, you may need to use different query methods and syntaxes to query the DNS for services and nodes. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 6f44bfd9830a..83effdb9e6cb 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -389,6 +389,10 @@ "title": "Configure DNS behavior", "path": "services/discovery/dns-configuration" }, + { + "title": "Configure DNS forwarding", + "path": "services/discovery/dns-forwarding" + }, { "title": "Perform static DNS lookups", "path": "services/discovery/dns-static-lookups"