1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ 4<!ENTITY % entities SYSTEM "custom-entities.ent" > 5%entities; 6]> 7<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 8 9<refentry id="resolved.conf" conditional='ENABLE_RESOLVE' 10 xmlns:xi="http://www.w3.org/2001/XInclude"> 11 <refentryinfo> 12 <title>resolved.conf</title> 13 <productname>systemd</productname> 14 </refentryinfo> 15 16 <refmeta> 17 <refentrytitle>resolved.conf</refentrytitle> 18 <manvolnum>5</manvolnum> 19 </refmeta> 20 21 <refnamediv> 22 <refname>resolved.conf</refname> 23 <refname>resolved.conf.d</refname> 24 <refpurpose>Network Name Resolution configuration files</refpurpose> 25 </refnamediv> 26 27 <refsynopsisdiv> 28 <para><filename>/etc/systemd/resolved.conf</filename></para> 29 <para><filename>/etc/systemd/resolved.conf.d/*.conf</filename></para> 30 <para><filename>/run/systemd/resolved.conf.d/*.conf</filename></para> 31 <para><filename>/usr/lib/systemd/resolved.conf.d/*.conf</filename></para> 32 </refsynopsisdiv> 33 34 <refsect1> 35 <title>Description</title> 36 37 <para>These configuration files control local DNS and LLMNR 38 name resolution.</para> 39 40 </refsect1> 41 42 <xi:include href="standard-conf.xml" xpointer="main-conf" /> 43 44 <refsect1> 45 <title>Options</title> 46 47 <para>The following options are available in the [Resolve] section:</para> 48 49 <variablelist class='network-directives'> 50 51 <varlistentry> 52 <term><varname>DNS=</varname></term> 53 <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. Each address can 54 optionally take a port number separated with <literal>:</literal>, a network interface name or index separated with 55 <literal>%</literal>, and a Server Name Indication (SNI) separated with <literal>#</literal>. When IPv6 address is 56 specified with a port number, then the address must be in the square brackets. That is, the acceptable full formats 57 are <literal>111.222.333.444:9953%ifname#example.com</literal> for IPv4 and 58 <literal>[1111:2222::3333]:9953%ifname#example.com</literal> for IPv6. DNS requests are sent to one of the listed 59 DNS servers in parallel to suitable per-link DNS servers acquired from 60 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> or 61 set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS 62 servers listed in <filename>/etc/resolv.conf</filename> are used instead, if that file exists and any servers 63 are configured in it. This setting defaults to the empty list.</para></listitem> 64 </varlistentry> 65 66 <varlistentry> 67 <term><varname>FallbackDNS=</varname></term> 68 <listitem><para>A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Please see 69 <varname>DNS=</varname> for acceptable format of addresses. Any per-link DNS servers obtained from 70 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 71 take precedence over this setting, as do any servers set via <varname>DNS=</varname> above or 72 <filename>/etc/resolv.conf</filename>. This setting is hence only used if no other DNS server information is 73 known. If this option is not given, a compiled-in list of DNS servers is used instead.</para></listitem> 74 </varlistentry> 75 76 <varlistentry> 77 <term><varname>Domains=</varname></term> 78 <listitem><para>A space-separated list of domains optionally prefixed with <literal>~</literal>, 79 used for two distinct purposes described below. Defaults to the empty list.</para> 80 81 <para>Any domains <emphasis>not</emphasis> prefixed with <literal>~</literal> are used as search 82 suffixes when resolving single-label hostnames (domain names which contain no dot), in order to 83 qualify them into fully-qualified domain names (FQDNs). These "search domains" are strictly processed 84 in the order they are specified in, until the name with the suffix appended is found. For 85 compatibility reasons, if this setting is not specified, the search domains listed in 86 <filename>/etc/resolv.conf</filename> with the <varname>search</varname> keyword are used instead, if 87 that file exists and any domains are configured in it.</para> 88 89 <para>The domains prefixed with <literal>~</literal> are called "routing domains". All domains listed 90 here (both search domains and routing domains after removing the <literal>~</literal> prefix) define 91 a search path that preferably directs DNS queries to this interface. This search path has an effect 92 only when suitable per-link DNS servers are known. Such servers may be defined through the 93 <varname>DNS=</varname> setting (see above) and dynamically at run time, for example from DHCP 94 leases. If no per-link DNS servers are known, routing domains have no effect.</para> 95 96 <para>Use the construct <literal>~.</literal> (which is composed from <literal>~</literal> to 97 indicate a routing domain and <literal>.</literal> to indicate the DNS root domain that is the 98 implied suffix of all DNS domains) to use the DNS servers defined for this link preferably for all 99 domains.</para></listitem> 100 </varlistentry> 101 102 <varlistentry> 103 <term><varname>LLMNR=</varname></term> 104 <listitem><para>Takes a boolean argument or 105 <literal>resolve</literal>. Controls Link-Local Multicast Name 106 Resolution support (<ulink 107 url="https://tools.ietf.org/html/rfc4795">RFC 4795</ulink>) on 108 the local host. If true, enables full LLMNR responder and 109 resolver support. If false, disables both. If set to 110 <literal>resolve</literal>, only resolution support is enabled, 111 but responding is disabled. Note that 112 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 113 also maintains per-link LLMNR settings. LLMNR will be 114 enabled on a link only if the per-link and the 115 global setting is on.</para></listitem> 116 </varlistentry> 117 118 <varlistentry> 119 <term><varname>MulticastDNS=</varname></term> 120 <listitem><para>Takes a boolean argument or 121 <literal>resolve</literal>. Controls Multicast DNS support (<ulink 122 url="https://tools.ietf.org/html/rfc6762">RFC 6762</ulink>) on 123 the local host. If true, enables full Multicast DNS responder and 124 resolver support. If false, disables both. If set to 125 <literal>resolve</literal>, only resolution support is enabled, 126 but responding is disabled. Note that 127 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 128 also maintains per-link Multicast DNS settings. Multicast DNS will be 129 enabled on a link only if the per-link and the 130 global setting is on.</para></listitem> 131 </varlistentry> 132 133 <varlistentry> 134 <term><varname>DNSSEC=</varname></term> 135 <listitem><para>Takes a boolean argument or 136 <literal>allow-downgrade</literal>. If true all DNS lookups are 137 DNSSEC-validated locally (excluding LLMNR and Multicast 138 DNS). If the response to a lookup request is detected to be invalid 139 a lookup failure is returned to applications. Note that 140 this mode requires a DNS server that supports DNSSEC. If the 141 DNS server does not properly support DNSSEC all validations 142 will fail. If set to <literal>allow-downgrade</literal> DNSSEC 143 validation is attempted, but if the server does not support 144 DNSSEC properly, DNSSEC mode is automatically disabled. Note 145 that this mode makes DNSSEC validation vulnerable to 146 "downgrade" attacks, where an attacker might be able to 147 trigger a downgrade to non-DNSSEC mode by synthesizing a DNS 148 response that suggests DNSSEC was not supported. If set to 149 false, DNS lookups are not DNSSEC validated.</para> 150 151 <para>Note that DNSSEC validation requires retrieval of 152 additional DNS data, and thus results in a small DNS look-up 153 time penalty.</para> 154 155 <para>DNSSEC requires knowledge of "trust anchors" to prove 156 data integrity. The trust anchor for the Internet root domain 157 is built into the resolver, additional trust anchors may be 158 defined with 159 <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. 160 Trust anchors may change at regular intervals, and old trust 161 anchors may be revoked. In such a case DNSSEC validation is 162 not possible until new trust anchors are configured locally or 163 the resolver software package is updated with the new root 164 trust anchor. In effect, when the built-in trust anchor is 165 revoked and <varname>DNSSEC=</varname> is true, all further 166 lookups will fail, as it cannot be proved anymore whether 167 lookups are correctly signed, or validly unsigned. If 168 <varname>DNSSEC=</varname> is set to 169 <literal>allow-downgrade</literal> the resolver will 170 automatically turn off DNSSEC validation in such a case.</para> 171 172 <para>Client programs looking up DNS data will be informed 173 whether lookups could be verified using DNSSEC, or whether the 174 returned data could not be verified (either because the data 175 was found unsigned in the DNS, or the DNS server did not 176 support DNSSEC or no appropriate trust anchors were known). In 177 the latter case it is assumed that client programs employ a 178 secondary scheme to validate the returned DNS data, should 179 this be required.</para> 180 181 <para>It is recommended to set <varname>DNSSEC=</varname> to 182 true on systems where it is known that the DNS server supports 183 DNSSEC correctly, and where software or trust anchor updates 184 happen regularly. On other systems it is recommended to set 185 <varname>DNSSEC=</varname> to 186 <literal>allow-downgrade</literal>.</para> 187 188 <para>In addition to this global DNSSEC setting 189 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 190 also maintains per-link DNSSEC settings. For system DNS 191 servers (see above), only the global DNSSEC setting is in 192 effect. For per-link DNS servers the per-link 193 setting is in effect, unless it is unset in which case the 194 global setting is used instead.</para> 195 196 <para>Site-private DNS zones generally conflict with DNSSEC 197 operation, unless a negative (if the private zone is not 198 signed) or positive (if the private zone is signed) trust 199 anchor is configured for them. If 200 <literal>allow-downgrade</literal> mode is selected, it is 201 attempted to detect site-private DNS zones using top-level 202 domains (TLDs) that are not known by the DNS root server. This 203 logic does not work in all private zone setups.</para> 204 205 <para>Defaults to <literal>&DEFAULT_DNSSEC_MODE;</literal>.</para> 206 </listitem> 207 </varlistentry> 208 209 <varlistentry> 210 <term><varname>DNSOverTLS=</varname></term> 211 <listitem> 212 <para>Takes a boolean argument or <literal>opportunistic</literal>. If 213 true all connections to the server will be encrypted. Note that this 214 mode requires a DNS server that supports DNS-over-TLS and has a valid 215 certificate. If the hostname was specified in <varname>DNS=</varname> 216 by using the format <literal>address#server_name</literal> it 217 is used to validate its certificate and also to enable Server Name 218 Indication (SNI) when opening a TLS connection. Otherwise 219 the certificate is checked against the server's IP. 220 If the DNS server does not support DNS-over-TLS all DNS requests will fail.</para> 221 222 <para>When set to <literal>opportunistic</literal> 223 DNS request are attempted to send encrypted with DNS-over-TLS. 224 If the DNS server does not support TLS, DNS-over-TLS is disabled. 225 Note that this mode makes DNS-over-TLS vulnerable to "downgrade" 226 attacks, where an attacker might be able to trigger a downgrade 227 to non-encrypted mode by synthesizing a response that suggests 228 DNS-over-TLS was not supported. If set to false, DNS lookups 229 are send over UDP.</para> 230 231 <para>Note that DNS-over-TLS requires additional data to be 232 send for setting up an encrypted connection, and thus results 233 in a small DNS look-up time penalty.</para> 234 235 <para>Note that in <literal>opportunistic</literal> mode the 236 resolver is not capable of authenticating the server, so it is 237 vulnerable to "man-in-the-middle" attacks.</para> 238 239 <para>In addition to this global <varname>DNSOverTLS=</varname> setting 240 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 241 also maintains per-link <varname>DNSOverTLS=</varname> settings. For system DNS servers (see above), only the global 242 <varname>DNSOverTLS=</varname> setting is in effect. For per-link DNS servers the per-link setting is in effect, unless 243 it is unset in which case the global setting is used instead.</para> 244 245 <para>Defaults to <literal>&DEFAULT_DNS_OVER_TLS_MODE;</literal>.</para> 246 </listitem> 247 </varlistentry> 248 249 <varlistentry> 250 <term><varname>Cache=</varname></term> 251 <listitem><para>Takes a boolean or <literal>no-negative</literal> as argument. If 252 <literal>yes</literal> (the default), resolving a domain name which already got queried earlier will 253 return the previous result as long as it is still valid, and thus does not result in a new network 254 request. Be aware that turning off caching comes at a performance penalty, which is particularly high 255 when DNSSEC is used. If <literal>no-negative</literal>, only positive answers are cached.</para> 256 257 <para>Note that caching is turned off by default for host-local DNS servers. 258 See <varname>CacheFromLocalhost=</varname> for details.</para></listitem> 259 </varlistentry> 260 261 <varlistentry> 262 <term><varname>CacheFromLocalhost=</varname></term> 263 <listitem><para>Takes a boolean as argument. If <literal>no</literal> (the default), and response cames from 264 host-local IP address (such as 127.0.0.1 or ::1), the result wouldn't be cached in order to avoid 265 potential duplicate local caching.</para> 266 </listitem> 267 </varlistentry> 268 269 <varlistentry> 270 <term><varname>DNSStubListener=</varname></term> 271 <listitem><para>Takes a boolean argument or one of <literal>udp</literal> and 272 <literal>tcp</literal>. If <literal>udp</literal>, a DNS stub resolver will listen for UDP requests 273 on addresses 127.0.0.53 and 127.0.0.54, port 53. If <literal>tcp</literal>, the stub will listen for 274 TCP requests on the same addresses and port. If <literal>yes</literal> (the default), the stub listens 275 for both UDP and TCP requests. If <literal>no</literal>, the stub listener is disabled.</para> 276 277 <xi:include href="systemd-resolved.service.xml" xpointer="proxy-stub" /> 278 279 <para>Note that the DNS stub listener is turned off implicitly when its listening address and port are already 280 in use.</para></listitem> 281 </varlistentry> 282 283 <varlistentry> 284 <term><varname>DNSStubListenerExtra=</varname></term> 285 <listitem><para>Takes an IPv4 or IPv6 address to listen on. The address may be optionally 286 prefixed with a protocol name (<literal>udp</literal> or <literal>tcp</literal>) separated with 287 <literal>:</literal>. If the protocol is not specified, the service will listen on both UDP and 288 TCP. It may be also optionally suffixed by a numeric port number with separator 289 <literal>:</literal>. When an IPv6 address is specified with a port number, then the address 290 must be in the square brackets. If the port is not specified, then the service uses port 53. 291 Note that this is independent of the primary DNS stub configured with 292 <varname>DNSStubListener=</varname>, and only configures <emphasis>additional</emphasis> 293 sockets to listen on. This option can be specified multiple times. If an empty string is 294 assigned, then the all previous assignments are cleared. Defaults to unset.</para> 295 296 <para>Examples: 297 <programlisting>DNSStubListenerExtra=192.168.10.10 298DNSStubListenerExtra=2001:db8:0:f102::10 299DNSStubListenerExtra=192.168.10.11:9953 300DNSStubListenerExtra=[2001:db8:0:f102::11]:9953 301DNSStubListenerExtra=tcp:192.168.10.12 302DNSStubListenerExtra=udp:2001:db8:0:f102::12 303DNSStubListenerExtra=tcp:192.168.10.13:9953 304DNSStubListenerExtra=udp:[2001:db8:0:f102::13]:9953</programlisting> 305 </para></listitem> 306 </varlistentry> 307 308 <varlistentry> 309 <term><varname>ReadEtcHosts=</varname></term> 310 <listitem><para>Takes a boolean argument. If <literal>yes</literal> (the default), 311 <command>systemd-resolved</command> will read <filename>/etc/hosts</filename>, and try to resolve 312 hosts or address by using the entries in the file before sending query to DNS servers. 313 </para></listitem> 314 </varlistentry> 315 316 <varlistentry> 317 <term><varname>ResolveUnicastSingleLabel=</varname></term> 318 <listitem><para>Takes a boolean argument. When false (the default), 319 <command>systemd-resolved</command> will not resolve A and AAAA queries for single-label names over 320 classic DNS. Note that such names may still be resolved if search domains are specified (see 321 <varname>Domains=</varname> above), or using other mechanisms, in particular via LLMNR or from 322 <filename>/etc/hosts</filename>. When true, queries for single-label names will be forwarded to 323 global DNS servers even if no search domains are defined. 324 </para> 325 326 <para>This option is provided for compatibility with configurations where <emphasis>public DNS 327 servers are not used</emphasis>. Forwarding single-label names to servers not under your control is 328 not standard-conformant, see <ulink 329 url="https://www.iab.org/documents/correspondence-reports-documents/2013-2/iab-statement-dotless-domains-considered-harmful/">IAB 330 Statement</ulink>, and may create a privacy and security risk.</para></listitem> 331 </varlistentry> 332 </variablelist> 333 </refsect1> 334 335 <refsect1> 336 <title>See Also</title> 337 <para> 338 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 339 <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 340 <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 341 <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 342 <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> 343 </para> 344 </refsect1> 345 346</refentry> 347