man/systemd-resolved.service.xml - systemd-stable - Rivoreo Source Code Repositories

 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

 <!--
   This file is part of systemd.

   Copyright 2014 Tom Gundersen

   systemd is free software; you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as published by
   the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.

   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->

 <refentry id="systemd-resolved.service" conditional='ENABLE_RESOLVED'>

   <refentryinfo>
     <title>systemd-resolved.service</title>
     <productname>systemd</productname>

     <authorgroup>
       <author>
         <contrib>Developer</contrib>
         <firstname>Tom</firstname>
         <surname>Gundersen</surname>
         <email>teg@jklm.no</email>
       </author>
     </authorgroup>
   </refentryinfo>

   <refmeta>
     <refentrytitle>systemd-resolved.service</refentrytitle>
     <manvolnum>8</manvolnum>
   </refmeta>

   <refnamediv>
     <refname>systemd-resolved.service</refname>
     <refname>systemd-resolved</refname>
     <refpurpose>Network Name Resolution manager</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
     <para><filename>systemd-resolved.service</filename></para>
     <para><filename>/lib/systemd/systemd-resolved</filename></para>
   </refsynopsisdiv>

   <refsect1>
     <title>Description</title>

     <para><command>systemd-resolved</command> is a system service that provides network name resolution to local
     applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and
     responder. Local applications may submit network name resolution requests via three interfaces:</para>

     <itemizedlist>
       <listitem><para>The native, fully-featured API <command>systemd-resolved</command> exposes on the bus. See the
       <ulink url="https://www.freedesktop.org/wiki/Software/systemd/resolved">API Documentation</ulink> for
       details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for
       example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting
       link-local networking).</para></listitem>

       <listitem><para>The glibc
       <citerefentry project='man-pages'><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry> API as defined
       by <ulink url="https://tools.ietf.org/html/rfc3493">RFC3493</ulink> and its related resolver functions,
       including <citerefentry project='man-pages'><refentrytitle>gethostbyname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
       API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC
       validation status information however, and is synchronous only. This API is backed by the glibc Name Service
       Switch (<citerefentry project='man-pages'><refentrytitle>nss</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Usage of the
       glibc NSS module <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>
       is required in order to allow glibc's NSS resolver functions to resolve host names via
       <command>systemd-resolved</command>.</para></listitem>

       <listitem><para>Additionally, <command>systemd-resolved</command> provides a local DNS stub listener on IP
       address 127.0.0.53 on the local loopback interface. Programs issuing DNS requests directly, bypassing any local
       API may be directed to this stub, in order to connect them to <command>systemd-resolved</command>. Note however
       that it is strongly recommended that local programs use the glibc NSS or bus APIs instead (as described above),
       as various network resolution concepts (such as link-local addressing, or LLMNR Unicode domains) cannot be mapped
       to the unicast DNS protocol.</para></listitem>
     </itemizedlist>

     <para>The DNS servers contacted are determined from the global settings in
     <filename>/etc/systemd/resolved.conf</filename>, the per-link static settings in
     <filename>/etc/systemd/network/*.network</filename> files, the per-link dynamic settings received over DHCP and any
     DNS server information made available by other system services. See
     <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details
     about systemd's own configuration files for DNS servers. To improve compatibility,
     <filename>/etc/resolv.conf</filename> is read in order to discover configured system DNS servers, but only if it is
     not a symlink to <filename>/run/systemd/resolve/resolv.conf</filename> (see below).</para>

     <para><command>systemd-resolved</command> synthesizes DNS resource records (RRs) for the following cases:</para>

     <itemizedlist>
       <listitem><para>The local, configured hostname is resolved to
       all locally configured IP addresses ordered by their scope, or
       — if none are configured — the IPv4 address 127.0.0.2 (which
       is on the local loopback) and the IPv6 address ::1 (which is the
       local host).</para></listitem>

       <listitem><para>The hostnames <literal>localhost</literal> and
       <literal>localhost.localdomain</literal> (as well as any hostname
       ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>)
       are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>

       <listitem><para>The hostname <literal>gateway</literal> is
       resolved to all current default routing gateway addresses,
       ordered by their metric. This assigns a stable hostname to the
       current gateway, useful for referencing it independently of the
       current network configuration state.</para></listitem>

       <listitem><para>The mappings defined in <filename>/etc/hosts</filename> are resolved
       to their configured addresses and back, but they will not affect lookups for
       non-address types (like MX).</para></listitem>
     </itemizedlist>

     <para>Lookup requests are routed to the available DNS servers
     and LLMNR interfaces according to the following rules:</para>

     <itemizedlist>
       <listitem><para>Lookups for the special hostname
       <literal>localhost</literal> are never routed to the
       network. (A few other, special domains are handled the same way.)</para></listitem>

       <listitem><para>Single-label names are routed to all local
       interfaces capable of IP multicasting, using the LLMNR
       protocol. Lookups for IPv4 addresses are only sent via LLMNR on
       IPv4, and lookups for IPv6 addresses are only sent via LLMNR on
       IPv6. Lookups for the locally configured host name and the
       <literal>gateway</literal> host name are never routed to
       LLMNR.</para></listitem>

       <listitem><para>Multi-label names are routed to all local
       interfaces that have a DNS sever configured, plus the globally
       configured DNS server if there is one. Address lookups from the
       link-local address range are never routed to
       DNS.</para></listitem>
     </itemizedlist>

     <para>If lookups are routed to multiple interfaces, the first
     successful response is returned (thus effectively merging the
     lookup zones on all matching interfaces). If the lookup failed on
     all interfaces, the last failing response is returned.</para>

     <para>Routing of lookups may be influenced by configuring
     per-interface domain names. See
     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for details. Lookups for a hostname ending in one of the
     per-interface domains are exclusively routed to the matching
     interfaces.</para>

     <para>See the <ulink url="https://www.freedesktop.org/wiki/Software/systemd/resolved"> resolved D-Bus API
     Documentation</ulink> for information about the APIs <filename>systemd-resolved</filename> provides.</para>

   </refsect1>

   <refsect1>
     <title><filename>/etc/resolv.conf</filename></title>

     <para>Three modes of handling <filename>/etc/resolv.conf</filename> (see
     <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) are
     supported:</para>

     <itemizedlist>
       <listitem><para>A static file <filename>/lib/systemd/resolv.conf</filename> is provided that lists
       the 127.0.0.53 DNS stub (see above) as only DNS server. This file may be symlinked from
       <filename>/etc/resolv.conf</filename> in order to connect all local clients that bypass local DNS APIs to
       <command>systemd-resolved</command>. This mode of operation is recommended.</para></listitem>

       <listitem><para><command>systemd-resolved</command> maintains the
       <filename>/run/systemd/resolve/resolv.conf</filename> file for compatibility with traditional Linux
       programs. This file may be symlinked from <filename>/etc/resolv.conf</filename> and is always kept up-to-date,
       containing information about all known DNS servers. Note the file format's limitations: it does not know a
       concept of per-interface DNS servers and hence only contains system-wide DNS server definitions. Note that
       <filename>/run/systemd/resolve/resolv.conf</filename> should not be used directly by applications, but only
       through a symlink from <filename>/etc/resolv.conf</filename>. If this mode of operation is used local clients
       that bypass any local DNS API will also bypass <command>systemd-resolved</command> and will talk directly to the
       known DNS servers.</para> </listitem>

       <listitem><para>Alternatively, <filename>/etc/resolv.conf</filename> may be managed by other packages, in which
       case <command>systemd-resolved</command> will read it for DNS configuration data. In this mode of operation
       <command>systemd-resolved</command> is consumer rather than provider of this configuration
       file. </para></listitem>
     </itemizedlist>

     <para>Note that the selected mode of operation for this file is detected fully automatically, depending on whether
     <filename>/etc/resolv.conf</filename> is a symlink to <filename>/run/systemd/resolve/resolv.conf</filename> or
     lists 127.0.0.53 as DNS server.</para>
   </refsect1>

   <refsect1>
     <title>Signals</title>

     <variablelist>
       <varlistentry>
         <term><constant>SIGUSR1</constant></term>

         <listitem><para>Upon reception of the SIGUSR1 process signal <command>systemd-resolved</command> will dump the
         contents of all DNS resource record caches it maintains into the system logs.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><constant>SIGUSR2</constant></term>

         <listitem><para>Upon reception of the SIGUSR2 process signal <command>systemd-resolved</command> will flush all
         caches it maintains. Note that it should normally not be necessary to request this explicitly – except for
         debugging purposes – as <command>systemd-resolved</command> flushes the caches automatically anyway any time
         the host's network configuration changes.</para></listitem>
       </varlistentry>
     </variablelist>
   </refsect1>

   <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-resolve</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>hosts</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>
   </refsect1>

 </refentry>
	<?xml version='1.0'?> <!--- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil --->
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

	<!--
	This file is part of systemd.

	Copyright 2014 Tom Gundersen

	systemd is free software; you can redistribute it and/or modify it
	under the terms of the GNU Lesser General Public License as published by
	the Free Software Foundation; either version 2.1 of the License, or
	(at your option) any later version.

	systemd is distributed in the hope that it will be useful, but
	WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	Lesser General Public License for more details.

	You should have received a copy of the GNU Lesser General Public License
	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	-->

	<refentry id="systemd-resolved.service" conditional='ENABLE_RESOLVED'>

	<refentryinfo>
	<title>systemd-resolved.service</title>
	<productname>systemd</productname>

	<authorgroup>
	<author>
	<contrib>Developer</contrib>
	<firstname>Tom</firstname>
	<surname>Gundersen</surname>
	<email>teg@jklm.no</email>
	</author>
	</authorgroup>
	</refentryinfo>

	<refmeta>
	<refentrytitle>systemd-resolved.service</refentrytitle>
	<manvolnum>8</manvolnum>
	</refmeta>

	<refnamediv>
	<refname>systemd-resolved.service</refname>
	<refname>systemd-resolved</refname>
	<refpurpose>Network Name Resolution manager</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
	<para><filename>systemd-resolved.service</filename></para>
	<para><filename>/lib/systemd/systemd-resolved</filename></para>
	</refsynopsisdiv>

	<refsect1>
	<title>Description</title>

	<para><command>systemd-resolved</command> is a system service that provides network name resolution to local
	applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and
	responder. Local applications may submit network name resolution requests via three interfaces:</para>

	<itemizedlist>
	<listitem><para>The native, fully-featured API <command>systemd-resolved</command> exposes on the bus. See the
	<ulink url="https://www.freedesktop.org/wiki/Software/systemd/resolved">API Documentation</ulink> for
	details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for
	example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting
	link-local networking).</para></listitem>

	<listitem><para>The glibc
	<citerefentry project='man-pages'><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry> API as defined
	by <ulink url="https://tools.ietf.org/html/rfc3493">RFC3493</ulink> and its related resolver functions,
	including <citerefentry project='man-pages'><refentrytitle>gethostbyname</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
	API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC
	validation status information however, and is synchronous only. This API is backed by the glibc Name Service
	Switch (<citerefentry project='man-pages'><refentrytitle>nss</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Usage of the
	glibc NSS module <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	is required in order to allow glibc's NSS resolver functions to resolve host names via
	<command>systemd-resolved</command>.</para></listitem>

	<listitem><para>Additionally, <command>systemd-resolved</command> provides a local DNS stub listener on IP
	address 127.0.0.53 on the local loopback interface. Programs issuing DNS requests directly, bypassing any local
	API may be directed to this stub, in order to connect them to <command>systemd-resolved</command>. Note however
	that it is strongly recommended that local programs use the glibc NSS or bus APIs instead (as described above),
	as various network resolution concepts (such as link-local addressing, or LLMNR Unicode domains) cannot be mapped
	to the unicast DNS protocol.</para></listitem>
	</itemizedlist>

	<para>The DNS servers contacted are determined from the global settings in
	<filename>/etc/systemd/resolved.conf</filename>, the per-link static settings in
	<filename>/etc/systemd/network/*.network</filename> files, the per-link dynamic settings received over DHCP and any
	DNS server information made available by other system services. See
	<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
	<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details
	about systemd's own configuration files for DNS servers. To improve compatibility,
	<filename>/etc/resolv.conf</filename> is read in order to discover configured system DNS servers, but only if it is
	not a symlink to <filename>/run/systemd/resolve/resolv.conf</filename> (see below).</para>

	<para><command>systemd-resolved</command> synthesizes DNS resource records (RRs) for the following cases:</para>

	<itemizedlist>
	<listitem><para>The local, configured hostname is resolved to
	all locally configured IP addresses ordered by their scope, or
	— if none are configured — the IPv4 address 127.0.0.2 (which
	is on the local loopback) and the IPv6 address ::1 (which is the
	local host).</para></listitem>

	<listitem><para>The hostnames <literal>localhost</literal> and
	<literal>localhost.localdomain</literal> (as well as any hostname
	ending in <literal>.localhost</literal> or <literal>.localhost.localdomain</literal>)
	are resolved to the IP addresses 127.0.0.1 and ::1.</para></listitem>

	<listitem><para>The hostname <literal>gateway</literal> is
	resolved to all current default routing gateway addresses,
	ordered by their metric. This assigns a stable hostname to the
	current gateway, useful for referencing it independently of the
	current network configuration state.</para></listitem>

	<listitem><para>The mappings defined in <filename>/etc/hosts</filename> are resolved
	to their configured addresses and back, but they will not affect lookups for
	non-address types (like MX).</para></listitem>
	</itemizedlist>

	<para>Lookup requests are routed to the available DNS servers
	and LLMNR interfaces according to the following rules:</para>

	<itemizedlist>
	<listitem><para>Lookups for the special hostname
	<literal>localhost</literal> are never routed to the
	network. (A few other, special domains are handled the same way.)</para></listitem>

	<listitem><para>Single-label names are routed to all local
	interfaces capable of IP multicasting, using the LLMNR
	protocol. Lookups for IPv4 addresses are only sent via LLMNR on
	IPv4, and lookups for IPv6 addresses are only sent via LLMNR on
	IPv6. Lookups for the locally configured host name and the
	<literal>gateway</literal> host name are never routed to
	LLMNR.</para></listitem>

	<listitem><para>Multi-label names are routed to all local
	interfaces that have a DNS sever configured, plus the globally
	configured DNS server if there is one. Address lookups from the
	link-local address range are never routed to
	DNS.</para></listitem>
	</itemizedlist>

	<para>If lookups are routed to multiple interfaces, the first
	successful response is returned (thus effectively merging the
	lookup zones on all matching interfaces). If the lookup failed on
	all interfaces, the last failing response is returned.</para>

	<para>Routing of lookups may be influenced by configuring
	per-interface domain names. See
	<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	for details. Lookups for a hostname ending in one of the
	per-interface domains are exclusively routed to the matching
	interfaces.</para>

	<para>See the <ulink url="https://www.freedesktop.org/wiki/Software/systemd/resolved"> resolved D-Bus API
	Documentation</ulink> for information about the APIs <filename>systemd-resolved</filename> provides.</para>

	</refsect1>

	<refsect1>
	<title><filename>/etc/resolv.conf</filename></title>

	<para>Three modes of handling <filename>/etc/resolv.conf</filename> (see
	<citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) are
	supported:</para>

	<itemizedlist>
	<listitem><para>A static file <filename>/lib/systemd/resolv.conf</filename> is provided that lists
	the 127.0.0.53 DNS stub (see above) as only DNS server. This file may be symlinked from
	<filename>/etc/resolv.conf</filename> in order to connect all local clients that bypass local DNS APIs to
	<command>systemd-resolved</command>. This mode of operation is recommended.</para></listitem>

	<listitem><para><command>systemd-resolved</command> maintains the
	<filename>/run/systemd/resolve/resolv.conf</filename> file for compatibility with traditional Linux
	programs. This file may be symlinked from <filename>/etc/resolv.conf</filename> and is always kept up-to-date,
	containing information about all known DNS servers. Note the file format's limitations: it does not know a
	concept of per-interface DNS servers and hence only contains system-wide DNS server definitions. Note that
	<filename>/run/systemd/resolve/resolv.conf</filename> should not be used directly by applications, but only
	through a symlink from <filename>/etc/resolv.conf</filename>. If this mode of operation is used local clients
	that bypass any local DNS API will also bypass <command>systemd-resolved</command> and will talk directly to the
	known DNS servers.</para> </listitem>

	<listitem><para>Alternatively, <filename>/etc/resolv.conf</filename> may be managed by other packages, in which
	case <command>systemd-resolved</command> will read it for DNS configuration data. In this mode of operation
	<command>systemd-resolved</command> is consumer rather than provider of this configuration
	file. </para></listitem>
	</itemizedlist>

	<para>Note that the selected mode of operation for this file is detected fully automatically, depending on whether
	<filename>/etc/resolv.conf</filename> is a symlink to <filename>/run/systemd/resolve/resolv.conf</filename> or
	lists 127.0.0.53 as DNS server.</para>
	</refsect1>

	<refsect1>
	<title>Signals</title>

	<variablelist>
	<varlistentry>
	<term><constant>SIGUSR1</constant></term>

	<listitem><para>Upon reception of the SIGUSR1 process signal <command>systemd-resolved</command> will dump the
	contents of all DNS resource record caches it maintains into the system logs.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><constant>SIGUSR2</constant></term>

	<listitem><para>Upon reception of the SIGUSR2 process signal <command>systemd-resolved</command> will flush all
	caches it maintains. Note that it should normally not be necessary to request this explicitly – except for
	debugging purposes – as <command>systemd-resolved</command> flushes the caches automatically anyway any time
	the host's network configuration changes.</para></listitem>
	</varlistentry>
	</variablelist>
	</refsect1>

	<refsect1>
	<title>See Also</title>
	<para>
	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd-resolve</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	<citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry project='man-pages'><refentrytitle>hosts</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	</para>
	</refsect1>

	</refentry>