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     <variablelist class='network-directives'>
  72
  73       <varlistentry>
  74         <term><varname>DNS=</varname></term>
  75         <listitem><para>A space-separated list of IPv4 and IPv6
  76         addresses to be used as system DNS servers. DNS requests are
  77         sent to one of the listed DNS servers in parallel to any
  78         per-interface DNS servers acquired from
  79         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  80         For compatibility reasons, if this setting is not specified,
  81         the DNS servers listed in
  82         <filename>/etc/resolv.conf</filename> are used instead, if
  83         that file exists and any servers are configured in it. This
  84         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
  90         addresses to be used as the fallback DNS servers. Any
  91         per-interface DNS servers obtained from
  92         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  93         take precedence over this setting, as do any servers set via
  94         <varname>DNS=</varname> above or
  95         <filename>/etc/resolv.conf</filename>. This setting is hence
  96         only used if no other DNS server information is known. If this
  97         option is not given, a compiled-in list of DNS servers is used
  98         instead.</para></listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><varname>Domains=</varname></term>
 103         <listitem><para>A space-separated list of search domains.  For
 104         compatibility reasons, if this setting is not specified, the
 105         search domains listed in <filename>/etc/resolv.conf</filename>
 106         are used instead, if that file exists and any domains are
 107         configured in it. This setting defaults to the empty
 108         list.</para></listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term><varname>LLMNR=</varname></term>
 113         <listitem><para>Takes a boolean argument or
 114         <literal>resolve</literal>. Controls Link-Local Multicast Name
 115         Resolution support (<ulink
 116         url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on
 117         the local host. If true, enables full LLMNR responder and
 118         resolver support. If false, disables both. If set to
 119         <literal>resolve</literal>, only resolution support is enabled,
 120         but responding is disabled. Note that
 121         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 122         also maintains per-interface LLMNR settings. LLMNR will be
 123         enabled on an interface only if the per-interface and the
 124         global setting is on.</para></listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term><varname>MulticastDNS=</varname></term>
 129         <listitem><para>Takes a boolean argument or
 130         <literal>resolve</literal>. Controls Multicast DNS support
 131         (<ulink url="https://tools.ietf.org/html/rfc6762">RFC
 132         6762</ulink>) on the local host. If true, enables full
 133         Multicast DNS responder and resolver support. If false,
 134         disables both. If set to <literal>resolve</literal>, only
 135         resolution support is enabled, but responding is
 136         disabled. Note that
 137         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 138         also maintains per-interface Multicast DNS settings. Multicast
 139         DNS will be enabled on an interface only if the per-interface
 140         and the global setting is on.</para></listitem>
 141       </varlistentry>
 142
 143       <varlistentry>
 144         <term><varname>DNSSEC=</varname></term>
 145         <listitem><para>Takes a boolean argument or
 146         <literal>allow-downgrade</literal>. If true all DNS lookups are
 147         DNSSEC-validated locally (excluding LLMNR and Multicast
 148         DNS). If a response for a lookup request is detected invalid
 149         this is returned as lookup failure to applications. Note that
 150         this mode requires a DNS server that supports DNSSEC. If the
 151         DNS server does not properly support DNSSEC all validations
 152         will fail. If set to <literal>allow-downgrade</literal> DNSSEC
 153         validation is attempted, but if the server does not support
 154         DNSSEC properly, DNSSEC mode is automatically disabled. Note
 155         that this mode makes DNSSEC validation vulnerable to
 156         "downgrade" attacks, where an attacker might be able to
 157         trigger a downgrade to non-DNSSEC mode by synthesizing a DNS
 158         response that suggests DNSSEC was not supported. If set to
 159         false, DNS lookups are not DNSSEC validated.</para>
 160
 161         <para>Note that DNSSEC validation requires retrieval of
 162         additional DNS data, and thus results in a small DNS look-up
 163         time penalty.</para>
 164
 165         <para>DNSSEC requires knowledge of "trust anchors" to prove
 166         data integrity. The trust anchor for the Internet root domain
 167         is built into the resolver, additional trust anchors may be
 168         defined with
 169         <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 170         Trust anchors may change in regular intervals, and old trust
 171         anchors may be revoked. In such a case DNSSEC validation is
 172         not possible until new trust anchors are configured locally or
 173         the resolver software package is updated with the new root
 174         trust anchor. In effect, when the built-in trust anchor is
 175         revoked and <varname>DNSSEC=</varname> is true, all further
 176         lookups will fail, as it cannot be proved anymore whether
 177         lookups are correctly signed, or validly unsigned. If
 178         <varname>DNSSEC=</varname> is set to
 179         <literal>allow-downgrade</literal> the resolver will
 180         automatically turn off DNSSEC validation in such a case.</para>
 181
 182         <para>Client programs looking up DNS data will be informed
 183         whether lookups could be verified using DNSSEC, or whether the
 184         returned data could not be verified (either because the data
 185         was found unsigned in the DNS, or the DNS server did not
 186         support DNSSEC or no appropriate trust anchors were known). In
 187         the latter case it is assumed that client programs employ a
 188         secondary scheme to validate the returned DNS data, should
 189         this be required.</para>
 190
 191         <para>It is recommended to set <varname>DNSSEC=</varname> to
 192         true on systems where it is known that the DNS server supports
 193         DNSSEC correctly, and where software or trust anchor updates
 194         happen regularly. On other systems it is recommended to set
 195         <varname>DNSSEC=</varname> to
 196         <literal>allow-downgrade</literal>.</para>
 197
 198         <para>In addition to this global DNSSEC setting
 199         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 200         also maintains per-interface DNSSEC settings. For system DNS
 201         servers (see above), only the global DNSSEC setting is in
 202         effect. For per-interface DNS servers the per-interface
 203         setting is in effect, unless it is unset in which case the
 204         global setting is used instead.</para>
 205
 206         <para>Defaults to off.</para>
 207         </listitem>
 208       </varlistentry>
 209
 210     </variablelist>
 211   </refsect1>
 212
 213   <refsect1>
 214       <title>See Also</title>
 215       <para>
 216       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 217       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 218       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 219       <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 220       <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 221       </para>
 222   </refsect1>
 223
 224 </refentry>