a51c10485af349eb15faa4d1a63b9818bcf3e589Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen This file is part of systemd.
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen Copyright 2014 Tom Gundersen
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen systemd is free software; you can redistribute it and/or modify it
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen under the terms of the GNU Lesser General Public License as published by
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen the Free Software Foundation; either version 2.1 of the License, or
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen (at your option) any later version.
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen systemd is distributed in the hope that it will be useful, but
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen WITHOUT ANY WARRANTY; without even the implied warranty of
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen Lesser General Public License for more details.
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen You should have received a copy of the GNU Lesser General Public License
091a364c802e34a58f3260c9cb5db9b75c62215cTom Gundersen along with systemd; If not, see <http://www.gnu.org/licenses/>.
f2dacc96b25528ca1b0caca6364a69d656cf1569Josh Triplett<refentry id="resolved.conf" conditional='ENABLE_RESOLVED'
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>resolved.conf</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>resolved.conf</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>resolved.conf.d</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Network Name Resolution configuration files</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <para><filename>/etc/systemd/resolved.conf</filename></para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <para><filename>/etc/systemd/resolved.conf.d/*.conf</filename></para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><filename>/run/systemd/resolved.conf.d/*.conf</filename></para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <para><filename>/usr/lib/systemd/resolved.conf.d/*.conf</filename></para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>These configuration files control local DNS and LLMNR
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt name resolution.</para>
e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <xi:include href="standard-conf.xml" xpointer="main-conf" />
dbc7bede4a96d9a4d2fa75b6fb2a51076756b051Lennart Poettering <para>The following options are available in the <literal>[Resolve]</literal> section:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <variablelist class='network-directives'>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>DNS=</varname></term>
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. DNS requests
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> or
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering servers listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any servers
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering are configured in it. This setting defaults to the empty list.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>FallbackDNS=</varname></term>
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Any
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering per-link DNS servers obtained from
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering take precedence over this setting, as do any servers set via <varname>DNS=</varname> above or
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering <filename>/etc/resolv.conf</filename>. This setting is hence only used if no other DNS server information is
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering known. If this option is not given, a compiled-in list of DNS servers is used instead.</para></listitem>
a51c10485af349eb15faa4d1a63b9818bcf3e589Lennart Poettering <varlistentry>
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering <listitem><para>A space-separated list of domains. These domains are used as search suffixes when resolving
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering domains listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any domains
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering are configured in it. This setting defaults to the empty list.</para>
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering <para>Specified domain names may optionally be prefixed with <literal>~</literal>. In this case they do not
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering with the system <varname>DNS=</varname> setting (see above), in case additional, suitable per-link DNS servers
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering are known. If no per-link DNS servers are known using the <literal>~</literal> syntax has no effect. Use the
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering construct <literal>~.</literal> (which is composed of <literal>~</literal> to indicate a routing domain and
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering <literal>.</literal> to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering system DNS server defined with <varname>DNS=</varname> preferably for all domains.</para></listitem>
a51c10485af349eb15faa4d1a63b9818bcf3e589Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>LLMNR=</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Takes a boolean argument or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>resolve</literal>. Controls Link-Local Multicast Name
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Resolution support (<ulink
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt the local host. If true, enables full LLMNR responder and
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt resolver support. If false, disables both. If set to
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <literal>resolve</literal>, only resolution support is enabled,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek but responding is disabled. Note that
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering also maintains per-link LLMNR settings. LLMNR will be
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering enabled on a link only if the per-link and the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek global setting is on.</para></listitem>
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering <varlistentry>
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering <listitem><para>Takes a boolean argument or
1ed8c0fbb4cc51413f3a6025233f41c19f154bc1Lennart Poettering <literal>allow-downgrade</literal>. If true all DNS lookups are
b83d91c02947585df06207c604534d25d87b611fLennart Poettering DNSSEC-validated locally (excluding LLMNR and Multicast
c542f805ddc3ae28007c15827ef2e8a8247452bcZbigniew Jędrzejewski-Szmek DNS). If the response to a lookup request is detected to be invalid
c542f805ddc3ae28007c15827ef2e8a8247452bcZbigniew Jędrzejewski-Szmek a lookup failure is returned to applications. Note that
b83d91c02947585df06207c604534d25d87b611fLennart Poettering this mode requires a DNS server that supports DNSSEC. If the
b83d91c02947585df06207c604534d25d87b611fLennart Poettering DNS server does not properly support DNSSEC all validations
1ed8c0fbb4cc51413f3a6025233f41c19f154bc1Lennart Poettering will fail. If set to <literal>allow-downgrade</literal> DNSSEC
b83d91c02947585df06207c604534d25d87b611fLennart Poettering validation is attempted, but if the server does not support
b83d91c02947585df06207c604534d25d87b611fLennart Poettering DNSSEC properly, DNSSEC mode is automatically disabled. Note
b83d91c02947585df06207c604534d25d87b611fLennart Poettering that this mode makes DNSSEC validation vulnerable to
b83d91c02947585df06207c604534d25d87b611fLennart Poettering "downgrade" attacks, where an attacker might be able to
b83d91c02947585df06207c604534d25d87b611fLennart Poettering trigger a downgrade to non-DNSSEC mode by synthesizing a DNS
b83d91c02947585df06207c604534d25d87b611fLennart Poettering response that suggests DNSSEC was not supported. If set to
b83d91c02947585df06207c604534d25d87b611fLennart Poettering false, DNS lookups are not DNSSEC validated.</para>
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering <para>Note that DNSSEC validation requires retrieval of
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering additional DNS data, and thus results in a small DNS look-up
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering time penalty.</para>
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering <para>DNSSEC requires knowledge of "trust anchors" to prove
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering data integrity. The trust anchor for the Internet root domain
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering is built into the resolver, additional trust anchors may be
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
c542f805ddc3ae28007c15827ef2e8a8247452bcZbigniew Jędrzejewski-Szmek Trust anchors may change at regular intervals, and old trust
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering anchors may be revoked. In such a case DNSSEC validation is
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering not possible until new trust anchors are configured locally or
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering the resolver software package is updated with the new root
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering trust anchor. In effect, when the built-in trust anchor is
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering revoked and <varname>DNSSEC=</varname> is true, all further
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering lookups will fail, as it cannot be proved anymore whether
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering lookups are correctly signed, or validly unsigned. If
1ed8c0fbb4cc51413f3a6025233f41c19f154bc1Lennart Poettering <literal>allow-downgrade</literal> the resolver will
d57d3973a739fa7aa4c2e6c241588ba92f60e8d3Lennart Poettering automatically turn off DNSSEC validation in such a case.</para>
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering <para>Client programs looking up DNS data will be informed
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering whether lookups could be verified using DNSSEC, or whether the
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering returned data could not be verified (either because the data
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering was found unsigned in the DNS, or the DNS server did not
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering support DNSSEC or no appropriate trust anchors were known). In
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering the latter case it is assumed that client programs employ a
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering secondary scheme to validate the returned DNS data, should
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering this be required.</para>
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering <para>It is recommended to set <varname>DNSSEC=</varname> to
d57d3973a739fa7aa4c2e6c241588ba92f60e8d3Lennart Poettering true on systems where it is known that the DNS server supports
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering DNSSEC correctly, and where software or trust anchor updates
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering happen regularly. On other systems it is recommended to set
1ed8c0fbb4cc51413f3a6025233f41c19f154bc1Lennart Poettering <literal>allow-downgrade</literal>.</para>
ad6c04756115809d615dede330213d73edf732a8Lennart Poettering <para>In addition to this global DNSSEC setting
ad6c04756115809d615dede330213d73edf732a8Lennart Poettering <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering also maintains per-link DNSSEC settings. For system DNS
ad6c04756115809d615dede330213d73edf732a8Lennart Poettering servers (see above), only the global DNSSEC setting is in
adc800a6e0bf5483585e4210cf7125a7477ad85eLennart Poettering effect. For per-link DNS servers the per-link
ad6c04756115809d615dede330213d73edf732a8Lennart Poettering setting is in effect, unless it is unset in which case the
ad6c04756115809d615dede330213d73edf732a8Lennart Poettering global setting is used instead.</para>
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering <para>Site-private DNS zones generally conflict with DNSSEC
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering operation, unless a negative (if the private zone is not
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering signed) or positive (if the private zone is signed) trust
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering anchor is configured for them. If
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering <literal>allow-downgrade</literal> mode is selected, it is
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering attempted to detect site-private DNS zones using top-level
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering domains (TLDs) that are not known by the DNS root server. This
d33b6cf343f5a1e073c3060878d2cc5fed54d150Lennart Poettering logic does not work in all private zone setups.</para>
519d39deeeec7121649f28e7287b7790e50d2979Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
b5a8703fdb8e16f760bfb730df64f07173bb881dLennart Poettering <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
524f3e5c9d1eb2fba3d0b65d1790018163ba0b20Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>