diff options
Diffstat (limited to 'docs/services/dns-forwarding.rst')
| -rw-r--r-- | docs/services/dns-forwarding.rst | 163 |
1 files changed, 118 insertions, 45 deletions
diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst index fbfac6c9..a4fbdd9f 100644 --- a/docs/services/dns-forwarding.rst +++ b/docs/services/dns-forwarding.rst @@ -1,72 +1,145 @@ +.. _dns-forwarding: + +############## DNS Forwarding --------------- +############## -Use DNS forwarding if you want your router to function as a DNS server for the -local network. There are several options, the easiest being 'forward all -traffic to the system DNS server(s)' (defined with set system name-server): +Configuration +============= -.. code-block:: none +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls, for this we utilize PowerDNS recursor. - set service dns forwarding system +VyOS DNS forwarder does not require an upstream DNS server. It can serve as a +full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid to be tracked by the provider of your upstream DNS server. -Manually setting DNS servers for forwarding: +.. cfgcmd:: set service dns forwarding system -.. code-block:: none +Forward incoming DNS queries to the DNS servers configured under the ``system +name-server`` nodes. - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 +.. cfgcmd:: set service dns forwarding name-server <address> -Manually setting DNS servers with IPv6 connectivity: +Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. +You can configure multiple nameservers here. -.. code-block:: none +.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 +Forward received queries for a particular domain (specified via `domain-name`) +to a given name-server. Multiple nameservers can be specified. -Setting a forwarding DNS server for a specific domain: +.. note:: This also works for reverse-lookup zones e.g. ``18.172.in-addr.arpa``. -.. code-block:: none +.. cfgcmd:: set service dns forwarding allow-from <network> - set service dns forwarding domain example.com server 192.0.2.1 +Given the fact that open DNS recursors could be used on DDOS amplification +attacts, you must configure the networks which are allowed to use this recursor. +A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and IPv6 networks +to query this server. This is on general a bad idea. -Set which networks or clients are allowed to query the DNS Server. Allow from all: +.. cfgcmd:: set service dns forwarding dnssec <off | process-no-validate | process | log-fail | validate> -.. code-block:: none +The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can +be set with the dnssec setting. In order from least to most processing, these +are: - set service dns forwarding allow-from 0.0.0.0/0 +* **off** In this mode, no DNSSEC processing takes place. The recursor will not + set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the DO and + AD bits in queries. -Example 1 -^^^^^^^^^ +* **process-no-validate** In this mode the Recursor acts as a "security aware, + non-validating" nameserver, meaning it will set the DO-bit on outgoing queries + and will provide DNSSEC related RRsets (NSEC, RRSIG) to clients that ask for + them (by means of a DO-bit in the query), except for zones provided through + the auth-zones setting. It will not do any validation in this mode, not even + when requested by the client. -Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. +* **process** When dnssec is set to process the behaviour is similar to + process-no-validate. However, the recursor will try to validate the data if + at least one of the DO or AD bits is set in the query; in that case, it will + set the AD-bit in the response when the data is validated successfully, or + send SERVFAIL when the validation comes up bogus. -* DNS request for a local domain (example.com) get forwarded to 192.0.2.1 -* Other DNS requests are forwarded to Google's DNS servers. -* The IP address for the LAN interface is 192.168.0.1. +* **log-fail** In this mode, the recursor will attempt to validate all data it + retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before turning + on full-blown validation. Responses to client queries are the same as with + process. -.. code-block:: none +* **validate** The highest mode of DNSSEC processing. In this mode, all queries + will be be validated and will be answered with a SERVFAIL in case of bogus + data, regardless of the client's request. + +.. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. This + might lead to unexpected query results when testing. Set ``+noad`` on the + ``dig`` commandline when this is the case. + +.. note:: The ``CD``-bit is honored correctly for process and validate. For + log-fail, failures will be logged too. + +.. cfgcmd:: set service dns forwarding ignore-hosts-file + +Do not use local ``/etc/hosts`` file in name resolution. VyOS DHCP server will +use this file to add resolvers to assigned addresses. - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 +.. cfgcmd:: set service dns forwarding max-cache-entries -Example 2 -^^^^^^^^^ +Maximum number of DNS cache entries. 1 million per CPU core will generally +suffice for most installations. -Same as example 1 but with additional IPv6 addresses for Google's public DNS -servers. +.. cfgcmd:: set service dns forwarding negative-ttl -The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 +A query for which there is authoritatively no answer is cached to quickly deny +a record's existence later on, without putting a heavy load on the remote +server. In practice, caches can become saturated with hundreds of thousands of +hosts which are tried only once. This setting, which defaults to 3600 seconds, +puts a maximum on the amount of time negative entries are cached. + +.. cfgcmd:: set service dns forwarding listen-address + +Local IPv4 or IPv6 addresses to bind to - waiting on this address for incoming +connections. + +Example +======= + +Router with two interfaces eth0 (WAN link) and eth1 (LAN) does want to make +use of DNS split-horizon for example.com. + +* DNS request for example.com need to get forwarded to IPv4 address 192.0.2.254 + and IPv6 address 2001:db8:cafe::1 +* All other DNS requests are forwarded to DNS server listening on 192.0.2.1, + 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +* DNS server is listening on the LAN interface addresses only, 192.168.1.254 + for IPv4 and 2001:db8::ffff for IPv6 +* Only clients from the LAN segment (192.168.1.0/24) are allowed to use this + server .. code-block:: none - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - set service dns forwarding listen-address 2001:db8::1 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 + set service dns forwarding domain example.com server 192.0.2.254 + set service dns forwarding domain example.com server 2001:db8:cafe::1 + set service dns forwarding name-server 192.0.2.1 + set service dns forwarding name-server 192.0.2.2 + set service dns forwarding name-server 2001:db8::1:ffff + set service dns forwarding name-server 2001:db8::2:ffff + set service dns forwarding listen-address 192.168.1.254 + set service dns forwarding listen-address 2001:db8::ffff + set service dns forwarding allow-from 192.168.1.0/24 + set service dns forwarding allow-from 2001:db8::/64 + +Operation +========= + +.. opcmd:: reset dns forwarding <all | domain> + +Reset local DNS forwarding cache database. You can reset the cache for all +entries or only for entries to a specific domain. + +.. opcmd:: restart dns forwarding + +Restart DNS recursor process which also invalidates the cache. |