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>DNSSEC=</varname></term>
 131         <listitem><para>Takes a boolean argument or
 132         <literal>allow-downgrade</literal>. If true all DNS lookups are
 133         DNSSEC-validated locally (excluding LLMNR and Multicast
 134         DNS). If the response to a lookup request is detected to be invalid
 135         a lookup failure is returned to applications. Note that
 136         this mode requires a DNS server that supports DNSSEC. If the
 137         DNS server does not properly support DNSSEC all validations
 138         will fail. If set to <literal>allow-downgrade</literal> DNSSEC
 139         validation is attempted, but if the server does not support
 140         DNSSEC properly, DNSSEC mode is automatically disabled. Note
 141         that this mode makes DNSSEC validation vulnerable to
 142         "downgrade" attacks, where an attacker might be able to
 143         trigger a downgrade to non-DNSSEC mode by synthesizing a DNS
 144         response that suggests DNSSEC was not supported. If set to
 145         false, DNS lookups are not DNSSEC validated.</para>
 146
 147         <para>Note that DNSSEC validation requires retrieval of
 148         additional DNS data, and thus results in a small DNS look-up
 149         time penalty.</para>
 150
 151         <para>DNSSEC requires knowledge of "trust anchors" to prove
 152         data integrity. The trust anchor for the Internet root domain
 153         is built into the resolver, additional trust anchors may be
 154         defined with
 155         <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 156         Trust anchors may change at regular intervals, and old trust
 157         anchors may be revoked. In such a case DNSSEC validation is
 158         not possible until new trust anchors are configured locally or
 159         the resolver software package is updated with the new root
 160         trust anchor. In effect, when the built-in trust anchor is
 161         revoked and <varname>DNSSEC=</varname> is true, all further
 162         lookups will fail, as it cannot be proved anymore whether
 163         lookups are correctly signed, or validly unsigned. If
 164         <varname>DNSSEC=</varname> is set to
 165         <literal>allow-downgrade</literal> the resolver will
 166         automatically turn off DNSSEC validation in such a case.</para>
 167
 168         <para>Client programs looking up DNS data will be informed
 169         whether lookups could be verified using DNSSEC, or whether the
 170         returned data could not be verified (either because the data
 171         was found unsigned in the DNS, or the DNS server did not
 172         support DNSSEC or no appropriate trust anchors were known). In
 173         the latter case it is assumed that client programs employ a
 174         secondary scheme to validate the returned DNS data, should
 175         this be required.</para>
 176
 177         <para>It is recommended to set <varname>DNSSEC=</varname> to
 178         true on systems where it is known that the DNS server supports
 179         DNSSEC correctly, and where software or trust anchor updates
 180         happen regularly. On other systems it is recommended to set
 181         <varname>DNSSEC=</varname> to
 182         <literal>allow-downgrade</literal>.</para>
 183
 184         <para>In addition to this global DNSSEC setting
 185         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 186         also maintains per-link DNSSEC settings. For system DNS
 187         servers (see above), only the global DNSSEC setting is in
 188         effect. For per-link DNS servers the per-link
 189         setting is in effect, unless it is unset in which case the
 190         global setting is used instead.</para>
 191
 192         <para>Site-private DNS zones generally conflict with DNSSEC
 193         operation, unless a negative (if the private zone is not
 194         signed) or positive (if the private zone is signed) trust
 195         anchor is configured for them. If
 196         <literal>allow-downgrade</literal> mode is selected, it is
 197         attempted to detect site-private DNS zones using top-level
 198         domains (TLDs) that are not known by the DNS root server. This
 199         logic does not work in all private zone setups.</para>
 200
 201         <para>Defaults to off.</para>
 202         </listitem>
 203       </varlistentry>
 204
 205       <varlistentry>
 206         <term><varname>Cache=</varname></term>
 207         <listitem><para>Takes a boolean argument. If "yes" (the default), resolving a domain name which already got
 208         queried earlier will return the previous result as long as it is still valid, and thus does not result in a new
 209         network request. Be aware that turning off caching comes at a performance penalty, which is particularly
 210         high when DNSSEC is used.</para>
 211
 212         <para>Note that caching is turned off implicitly if the configured DNS server is on a host-local IP address
 213         (such as 127.0.0.1 or ::1), in order to avoid duplicate local caching.</para></listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><varname>DNSStubListener=</varname></term>
 218         <listitem><para>Takes a boolean argument or one of <literal>udp</literal> and <literal>tcp</literal>. If
 219         <literal>udp</literal> (the default), a DNS stub resolver will listen for UDP requests on address 127.0.0.53
 220         port 53. If <literal>tcp</literal>, the stub will listen for TCP requests on the same address and port. If
 221         <literal>yes</literal>, the stub listens for both UDP and TCP requests.  If <literal>no</literal>, the stub
 222         listener is disabled.</para>
 223
 224         <para>Note that the DNS stub listener is turned off implicitly when its listening address and port are already
 225         in use.</para></listitem>
 226       </varlistentry>
 227
 228     </variablelist>
 229   </refsect1>
 230
 231   <refsect1>
 232       <title>See Also</title>
 233       <para>
 234       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 236       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 237       <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 238       <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 239       </para>
 240   </refsect1>
 241
 242 </refentry>