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>DNSSEC=</varname></term>
 129         <listitem><para>Takes a boolean argument or
 130         <literal>allow-downgrade</literal>. If true all DNS lookups are
 131         DNSSEC-validated locally (excluding LLMNR and Multicast
 132         DNS). If a response for a lookup request is detected invalid
 133         this is returned as lookup failure to applications. Note that
 134         this mode requires a DNS server that supports DNSSEC. If the
 135         DNS server does not properly support DNSSEC all validations
 136         will fail. If set to <literal>allow-downgrade</literal> DNSSEC
 137         validation is attempted, but if the server does not support
 138         DNSSEC properly, DNSSEC mode is automatically disabled. Note
 139         that this mode makes DNSSEC validation vulnerable to
 140         "downgrade" attacks, where an attacker might be able to
 141         trigger a downgrade to non-DNSSEC mode by synthesizing a DNS
 142         response that suggests DNSSEC was not supported. If set to
 143         false, DNS lookups are not DNSSEC validated.</para>
 144
 145         <para>Note that DNSSEC validation requires retrieval of
 146         additional DNS data, and thus results in a small DNS look-up
 147         time penalty.</para>
 148
 149         <para>DNSSEC requires knowledge of "trust anchors" to prove
 150         data integrity. The trust anchor for the Internet root domain
 151         is built into the resolver, additional trust anchors may be
 152         defined with
 153         <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 154         Trust anchors may change in regular intervals, and old trust
 155         anchors may be revoked. In such a case DNSSEC validation is
 156         not possible until new trust anchors are configured locally or
 157         the resolver software package is updated with the new root
 158         trust anchor. In effect, when the built-in trust anchor is
 159         revoked and <varname>DNSSEC=</varname> is true, all further
 160         lookups will fail, as it cannot be proved anymore whether
 161         lookups are correctly signed, or validly unsigned. If
 162         <varname>DNSSEC=</varname> is set to
 163         <literal>allow-downgrade</literal> the resolver will
 164         automatically turn off DNSSEC validation in such a case.</para>
 165
 166         <para>Client programs looking up DNS data will be informed
 167         whether lookups could be verified using DNSSEC, or whether the
 168         returned data could not be verified (either because the data
 169         was found unsigned in the DNS, or the DNS server did not
 170         support DNSSEC or no appropriate trust anchors were known). In
 171         the latter case it is assumed that client programs employ a
 172         secondary scheme to validate the returned DNS data, should
 173         this be required.</para>
 174
 175         <para>It is recommended to set <varname>DNSSEC=</varname> to
 176         true on systems where it is known that the DNS server supports
 177         DNSSEC correctly, and where software or trust anchor updates
 178         happen regularly. On other systems it is recommended to set
 179         <varname>DNSSEC=</varname> to
 180         <literal>allow-downgrade</literal>.</para>
 181
 182         <para>In addition to this global DNSSEC setting
 183         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 184         also maintains per-interface DNSSEC settings. For system DNS
 185         servers (see above), only the global DNSSEC setting is in
 186         effect. For per-interface DNS servers the per-interface
 187         setting is in effect, unless it is unset in which case the
 188         global setting is used instead.</para>
 189
 190         <para>Site-private DNS zones generally conflict with DNSSEC
 191         operation, unless a negative (if the private zone is not
 192         signed) or positive (if the private zone is signed) trust
 193         anchor is configured for them. If
 194         <literal>allow-downgrade</literal> mode is selected, it is
 195         attempted to detect site-private DNS zones using top-level
 196         domains (TLDs) that are not known by the DNS root server. This
 197         logic does not work in all private zone setups.</para>
 198
 199         <para>Defaults to off.</para>
 200         </listitem>
 201       </varlistentry>
 202
 203     </variablelist>
 204   </refsect1>
 205
 206   <refsect1>
 207       <title>See Also</title>
 208       <para>
 209       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 210       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 212       <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 213       <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 214       </para>
 215   </refsect1>
 216
 217 </refentry>