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