man: beef up resolved man page

Let's explain the various APIs and various ways to handle /etc/resolv.conf.

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,14 +155,45 @@
     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>