diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/resolvectl.xml | 23 | ||||
| -rw-r--r-- | man/systemd-resolved.service.xml | 62 | ||||
| -rw-r--r-- | man/systemd.network.xml | 11 |
3 files changed, 76 insertions, 20 deletions
diff --git a/man/resolvectl.xml b/man/resolvectl.xml index e07893dd1..defd592aa 100644 --- a/man/resolvectl.xml +++ b/man/resolvectl.xml @@ -241,6 +241,7 @@ <varlistentry> <term><option>dns [<replaceable>LINK</replaceable> [<replaceable>SERVER</replaceable>…]]</option></term> <term><option>domain [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</option></term> + <term><option>default-route [<replaceable>LINK</replaceable> [<replaceable>BOOL</replaceable>…]]</option></term> <term><option>llmnr [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term> <term><option>mdns [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term> <term><option>dnssec [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term> @@ -248,18 +249,21 @@ <term><option>nta [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</option></term> <listitem> - <para>Get/set per-interface DNS configuration. These commands may be used to configure various DNS - settings for network interfaces that aren't managed by + <para>Get/set per-interface DNS configuration. These commands may be used to configure various DNS settings + for network interfaces that aren't managed by <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. (These commands will fail when used on interfaces that are managed by <command>systemd-networkd</command>, please configure their DNS settings directly inside the <filename>.network</filename> files instead.) These commands may be used to inform <command>systemd-resolved</command> about per-interface DNS configuration determined through external means. The <option>dns</option> command expects IPv4 or IPv6 address specifications of DNS servers to use. The <option>domain</option> command expects valid DNS domains, possibly prefixed with - <literal>~</literal>, and configures a per-interface search or route-only domain. The <option>llmnr</option>, - <option>mdns</option>, <option>dnssec</option> and <option>dnsovertls</option> commands may be used to configure - the per-interface LLMNR, MulticastDNS, DNSSEC and DNSOverTLS settings. Finally, <option>nta</option> command - may be used to configure additional per-interface DNSSEC NTA domains.</para> + <literal>~</literal>, and configures a per-interface search or route-only domain. The + <option>default-route</option> command expects a boolean paremeter, and configures whether the link may be + used as default route for DNS lookups, i.e. if it is suitable for lookups on domains no other link explicitly + is configured for. The <option>llmnr</option>, <option>mdns</option>, <option>dnssec</option> and + <option>dnsovertls</option> commands may be used to configure the per-interface LLMNR, MulticastDNS, DNSSEC + and DNSOverTLS settings. Finally, <option>nta</option> command may be used to configure additional + per-interface DNSSEC NTA domains.</para> <para>Options <option>dns</option>, <option>domain</option> and <option>nta</option> can take a single empty string argument to clear their respective value lists.</para> @@ -274,9 +278,10 @@ <listitem><para>Revert the per-interface DNS configuration. If the DNS configuration is reverted all per-interface DNS setting are reset to their defaults, undoing all effects of <option>dns</option>, - <option>domain</option>, <option>llmnr</option>, <option>mdns</option>, <option>dnssec</option>, - <option>dnsovertls</option>, <option>nta</option>. Note that when a network interface disappears all - configuration is lost automatically, an explicit reverting is not necessary in that case.</para></listitem> + <option>domain</option>, <option>default-route</option>, <option>llmnr</option>, <option>mdns</option>, + <option>dnssec</option>, <option>dnsovertls</option>, <option>nta</option>. Note that when a network interface + disappears all configuration is lost automatically, an explicit reverting is not necessary in that + case.</para></listitem> </varlistentry> </variablelist> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 71593686a..d7334e01e 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -66,14 +66,21 @@ <filename>/etc/systemd/resolved.conf</filename>, the per-link static settings in <filename>/etc/systemd/network/*.network</filename> files (in case <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> is - used), the per-link dynamic settings received over DHCP, and any DNS server information made available by other - system services. See + used), the per-link dynamic settings received over DHCP, user request made via + <citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and any DNS server + information made available by other system services. See <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> and <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details about systemd's own configuration files for DNS servers. To improve compatibility, <filename>/etc/resolv.conf</filename> is read in order to discover configured system DNS servers, but only if it is - not a symlink to <filename>/run/systemd/resolve/stub-resolv.conf</filename> or - <filename>/run/systemd/resolve/resolv.conf</filename> (see below).</para> + not a symlink to <filename>/run/systemd/resolve/stub-resolv.conf</filename>, + <filename>/usr/lib/systemd/resolv.conf</filename> or <filename>/run/systemd/resolve/resolv.conf</filename> (see + below).</para> + + </refsect1> + + <refsect1> + <title>Synthetic Records</title> <para><command>systemd-resolved</command> synthesizes DNS resource records (RRs) for the following cases:</para> @@ -99,6 +106,10 @@ to their configured addresses and back, but they will not affect lookups for non-address types (like MX).</para></listitem> </itemizedlist> + </refsect1> + + <refsect1> + <title>Protocols and Routing</title> <para>Lookup requests are routed to the available DNS servers, LLMNR and MulticastDNS interfaces according to the following rules:</para> @@ -132,16 +143,45 @@ lookup zones on all matching interfaces). If the lookup failed on all interfaces, the last failing response is returned.</para> - <para>Routing of lookups may be influenced by configuring - per-interface domain names. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Lookups for a hostname ending in one of the - per-interface domains are exclusively routed to the matching - interfaces.</para> + <para>Routing of lookups may be influenced by configuring per-interface domain names and other settings. See + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> and + <citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details. The + following query routing logic applies for unicast DNS traffic:</para> + + <itemizedlist> + <listitem><para>If a name to look up matches (that is: is equal to or has as suffix) any of the configured search + or route-only domains of any link (or the globally configured DNS settings), the "best matching" + search/route-only domain is determined: the matching one with the most labels. The query is then sent to all DNS + servers of any links or the globally configured DNS servers associated with this "best matching" + search/route-only domain. (Note that more than one link might have this same "best matching" search/route-only + domain configured, in which case the query is sent to all of them in parallel).</para></listitem> + + <listitem><para>If a query does not match any configured search/route-only domain (neither per-link nor global), + it is sent to all DNS servers that are configured on links with the "DNS default route" option set, as well as + the globally configured DNS server.</para></listitem> + + <listitem><para>If there is no link configured as "DNS default route" and no global DNS server configured, the + compiled-in fallback DNS server is used.</para></listitem> + + <listitem><para>Otherwise the query is failed as no suitable DNS servers could be determined.</para></listitem> + </itemizedlist> + + <para>The "DNS default route" option is a boolean setting configureable with <command>resolvectl</command> or in + <filename>.network</filename> files. If not set, it is implicitly determined based on the configured DNS domains + for a link: if there's any route-only domain (not matching <literal>~.</literal>) it defaults to false, otherwise + to true.</para> + + <para>Effectively this means: in order to preferably route all DNS queries not explicitly matched by + search/route-only domain configuration to a specific link, configure a <literal>~.</literal> route-only domain on + it. This will ensure that other links will not be considered for the queries (unless they too carry such a + route-only domain). In order to route all such DNS queries to a specific link only in case no other link is + preferable, then set the "DNS default route" option for the link to true, and do not configure a + <literal>~.</literal> route-only domain on it. Finally, in order to ensure that a specific link never receives any + DNS traffic not matching any of its configured search/route-only domains, set the "DNS default route" option for it + to false.</para> <para>See the <ulink url="https://www.freedesktop.org/wiki/Software/systemd/resolved"> resolved D-Bus API Documentation</ulink> for information about the APIs <filename>systemd-resolved</filename> provides.</para> - </refsect1> <refsect1> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 865b46f40..ee464ffff 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -548,6 +548,17 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>DNSDefaultRoute=</varname></term> + <listitem> + <para>Takes a boolean argument. If true, this link's configured DNS servers are used for resolving domain + names that do not match any link's configured <varname>Domains=</varname> setting. If false, this link's + configured DNS servers are never used for such domains, and are exclusively used for resolving names that + match at least one of the domains configured on this link. If not specified defaults to an automatic mode: + queries not matching any link's configured domains will be routed to this link if it has no routing-only + domains configured.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>NTP=</varname></term> <listitem> <para>An NTP server address. This option may be specified more than once. This setting is read by |