man/resolved.conf.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2014 Tom Gundersen
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="resolved.conf" conditional='ENABLE_RESOLVED'
  25     xmlns:xi="http://www.w3.org/2001/XInclude">
  26   <refentryinfo>
  27     <title>resolved.conf</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Tom</firstname>
  34         <surname>Gundersen</surname>
  35         <email>teg@jklm.no</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>resolved.conf</refentrytitle>
  42     <manvolnum>5</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>resolved.conf</refname>
  47     <refname>resolved.conf.d</refname>
  48     <refpurpose>Network Name Resolution configuration files</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <para><filename>/etc/systemd/resolved.conf</filename></para>
  53     <para><filename>/etc/systemd/resolved.conf.d/*.conf</filename></para>
  54     <para><filename>/run/systemd/resolved.conf.d/*.conf</filename></para>
  55     <para><filename>/usr/lib/systemd/resolved.conf.d/*.conf</filename></para>
  56   </refsynopsisdiv>
  57
  58   <refsect1>
  59     <title>Description</title>
  60
  61     <para>These configuration files control local DNS and LLMNR
  62     name resolution.</para>
  63
  64   </refsect1>
  65
  66   <xi:include href="standard-conf.xml" xpointer="main-conf" />
  67
  68   <refsect1>
  69     <title>Options</title>
  70
  71     <para>The following options are available in the <literal>[Resolve]</literal> section:</para>
  72
  73     <variablelist class='network-directives'>
  74
  75       <varlistentry>
  76         <term><varname>DNS=</varname></term>
  77         <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. DNS requests
  78         are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from
  79         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> or
  80         set at runtime by external applications.  For compatibility reasons, if this setting is not specified, the DNS
  81         servers listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any servers
  82         are configured in it. This setting defaults to the empty list.</para></listitem>
  83       </varlistentry>
  84
  85       <varlistentry>
  86         <term><varname>FallbackDNS=</varname></term>
  87         <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Any
  88         per-link DNS servers obtained from
  89         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  90         take precedence over this setting, as do any servers set via <varname>DNS=</varname> above or
  91         <filename>/etc/resolv.conf</filename>. This setting is hence only used if no other DNS server information is
  92         known. If this option is not given, a compiled-in list of DNS servers is used instead.</para></listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term><varname>Domains=</varname></term>
  97         <listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving
  98         single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified
  99         domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name
 100         with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search
 101         domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains
 102         are configured in it. This setting defaults to the empty list.</para>
 103
 104         <para>Specified domain names may optionally be prefixed with <literal>~</literal>. In this case they do not
 105         define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured
 106         with the system <varname>DNS=</varname> setting (see above), in case additional, suitable per-link DNS servers
 107         are known. If no per-link DNS servers are known using the <literal>~</literal> syntax has no effect. Use the
 108         construct <literal>~.</literal> (which is composed of <literal>~</literal> to indicate a routing domain and
 109         <literal>.</literal> to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the
 110         system DNS server defined with <varname>DNS=</varname> preferably for all domains.</para></listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term><varname>LLMNR=</varname></term>
 115         <listitem><para>Takes a boolean argument or
 116         <literal>resolve</literal>. Controls Link-Local Multicast Name
 117         Resolution support (<ulink
 118         url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on
 119         the local host. If true, enables full LLMNR responder and
 120         resolver support. If false, disables both. If set to
 121         <literal>resolve</literal>, only resolution support is enabled,
 122         but responding is disabled. Note that
 123         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 124         also maintains per-link LLMNR settings. LLMNR will be
 125         enabled on a link only if the per-link and the
 126         global setting is on.</para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><varname>MulticastDNS=</varname></term>
 131         <listitem><para>Takes a boolean argument or
 132         <literal>resolve</literal>. Controls Multicast DNS support (<ulink
 133         url="https://tools.ietf.org/html/rfc6762">RFC 6762</ulink>) on
 134         the local host. If true, enables full Multicast DNS responder and
 135         resolver support. If false, disables both. If set to
 136         <literal>resolve</literal>, only resolution support is enabled,
 137         but responding is disabled. Note that
 138         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 139         also maintains per-link Multicast DNS settings. Multicast DNS will be
 140         enabled on a link only if the per-link and the
 141         global setting is on.</para></listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><varname>DNSSEC=</varname></term>
 146         <listitem><para>Takes a boolean argument or
 147         <literal>allow-downgrade</literal>. If true all DNS lookups are
 148         DNSSEC-validated locally (excluding LLMNR and Multicast
 149         DNS). If the response to a lookup request is detected to be invalid
 150         a lookup failure is returned to applications. Note that
 151         this mode requires a DNS server that supports DNSSEC. If the
 152         DNS server does not properly support DNSSEC all validations
 153         will fail. If set to <literal>allow-downgrade</literal> DNSSEC
 154         validation is attempted, but if the server does not support
 155         DNSSEC properly, DNSSEC mode is automatically disabled. Note
 156         that this mode makes DNSSEC validation vulnerable to
 157         "downgrade" attacks, where an attacker might be able to
 158         trigger a downgrade to non-DNSSEC mode by synthesizing a DNS
 159         response that suggests DNSSEC was not supported. If set to
 160         false, DNS lookups are not DNSSEC validated.</para>
 161
 162         <para>Note that DNSSEC validation requires retrieval of
 163         additional DNS data, and thus results in a small DNS look-up
 164         time penalty.</para>
 165
 166         <para>DNSSEC requires knowledge of "trust anchors" to prove
 167         data integrity. The trust anchor for the Internet root domain
 168         is built into the resolver, additional trust anchors may be
 169         defined with
 170         <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 171         Trust anchors may change at regular intervals, and old trust
 172         anchors may be revoked. In such a case DNSSEC validation is
 173         not possible until new trust anchors are configured locally or
 174         the resolver software package is updated with the new root
 175         trust anchor. In effect, when the built-in trust anchor is
 176         revoked and <varname>DNSSEC=</varname> is true, all further
 177         lookups will fail, as it cannot be proved anymore whether
 178         lookups are correctly signed, or validly unsigned. If
 179         <varname>DNSSEC=</varname> is set to
 180         <literal>allow-downgrade</literal> the resolver will
 181         automatically turn off DNSSEC validation in such a case.</para>
 182
 183         <para>Client programs looking up DNS data will be informed
 184         whether lookups could be verified using DNSSEC, or whether the
 185         returned data could not be verified (either because the data
 186         was found unsigned in the DNS, or the DNS server did not
 187         support DNSSEC or no appropriate trust anchors were known). In
 188         the latter case it is assumed that client programs employ a
 189         secondary scheme to validate the returned DNS data, should
 190         this be required.</para>
 191
 192         <para>It is recommended to set <varname>DNSSEC=</varname> to
 193         true on systems where it is known that the DNS server supports
 194         DNSSEC correctly, and where software or trust anchor updates
 195         happen regularly. On other systems it is recommended to set
 196         <varname>DNSSEC=</varname> to
 197         <literal>allow-downgrade</literal>.</para>
 198
 199         <para>In addition to this global DNSSEC setting
 200         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 201         also maintains per-link DNSSEC settings. For system DNS
 202         servers (see above), only the global DNSSEC setting is in
 203         effect. For per-link DNS servers the per-link
 204         setting is in effect, unless it is unset in which case the
 205         global setting is used instead.</para>
 206
 207         <para>Site-private DNS zones generally conflict with DNSSEC
 208         operation, unless a negative (if the private zone is not
 209         signed) or positive (if the private zone is signed) trust
 210         anchor is configured for them. If
 211         <literal>allow-downgrade</literal> mode is selected, it is
 212         attempted to detect site-private DNS zones using top-level
 213         domains (TLDs) that are not known by the DNS root server. This
 214         logic does not work in all private zone setups.</para>
 215
 216         <para>Defaults to off.</para>
 217         </listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term><varname>Cache=</varname></term>
 222         <listitem><para>Takes a boolean argument. If "yes" (the default), resolving a domain name which already got
 223         queried earlier will return the previous result as long as it is still valid, and thus does not result in a new
 224         network request. Be aware that turning off caching comes at a performance penalty, which is particularly
 225         high when DNSSEC is used.</para>
 226
 227         <para>Note that caching is turned off implicitly if the configured DNS server is on a host-local IP address
 228         (such as 127.0.0.1 or ::1), in order to avoid duplicate local caching.</para></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><varname>DNSStubListener=</varname></term>
 233         <listitem><para>Takes a boolean argument or one of <literal>udp</literal> and <literal>tcp</literal>. If
 234         <literal>udp</literal> (the default), a DNS stub resolver will listen for UDP requests on address 127.0.0.53
 235         port 53. If <literal>tcp</literal>, the stub will listen for TCP requests on the same address and port. If
 236         <literal>yes</literal>, the stub listens for both UDP and TCP requests.  If <literal>no</literal>, the stub
 237         listener is disabled.</para>
 238
 239         <para>Note that the DNS stub listener is turned off implicitly when its listening address and port are already
 240         in use.</para></listitem>
 241       </varlistentry>
 242
 243     </variablelist>
 244   </refsect1>
 245
 246   <refsect1>
 247       <title>See Also</title>
 248       <para>
 249       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 250       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 251       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 252       <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 253       <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 254       </para>
 255   </refsect1>
 256
 257 </refentry>