summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2016-06-21 13:19:21 +0200
committerLennart Poettering <lennart@poettering.net>2016-06-21 14:15:23 +0200
commitb541146bf8c34aaaa9efcf58325f18da9253c4ec (patch)
tree26392ff924cf3dab5a8051119acb456e8a4c3056
parentb30bf55d5c9942f15f27a641c2c34bbb646ec981 (diff)
man: beef up resolved man page
Let's explain the various APIs and various ways to handle /etc/resolv.conf.
-rw-r--r--man/systemd-resolved.service.xml95
1 files changed, 72 insertions, 23 deletions
diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 485f3e9aee..0df037ba69 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -58,27 +58,45 @@
<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. In addition it 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>.</para>
-
- <para>The glibc NSS module
- <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> is required to
- permit glibc's NSS resolver functions to resolve host names via <command>systemd-resolved</command>.</para>
-
- <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,
- and the per-link dynamic settings received over DHCP. See
- <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- and
- <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details. 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 above).</para>
+ 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="http://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><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><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><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 <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><command>systemd-resolved</command> synthesizes DNS RRs for the following cases:</para>
+ <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
@@ -137,15 +155,46 @@
per-interface domains are exclusively routed to the matching
interfaces.</para>
- <para>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>.</para>
-
<para>See the <ulink url="http://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><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) are
+ supported:</para>
+
+ <itemizedlist>
+ <listitem><para>A static file <filename>/usr/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>