man: document what SIGUSR1 and SIGUSR2 do to resolved

[thirdparty/systemd.git] / man / systemd-resolved.service.xml

diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 8e1ca1c092ad01e043f015737d11d835bce5ae5d..485f3e9aee41479dec58264b1d3db9e937a93f19 100644 (file)
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -56,15 +56,15 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>systemd-resolved</command> is a system service that
-    manages network name resolution. It implements a caching DNS stub
-    resolver and an LLMNR resolver and responder. It also generates
-    <filename>/run/systemd/resolve/resolv.conf</filename> for
-    compatibility which may be symlinked from
-    <filename>/etc/resolv.conf</filename>. The glibc NSS module
-    <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    is necessary to allow libc's NSS resolver functions to resolve
-    host names via <command>systemd-resolved</command>.</para>
+    <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
@@ -87,15 +87,19 @@
       is on the local loopback) and the IPv6 address ::1 (which is the
       local host).</para></listitem>
 
-      <listitem><para>The hostname <literal>localhost</literal> is
-      resolved to the IP addresses 127.0.0.1 and
-      ::1.</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.</para></listitem>
     </itemizedlist>
 
     <para>Lookup requests are routed to the available DNS servers
@@ -104,7 +108,7 @@
     <itemizedlist>
       <listitem><para>Lookups for the special hostname
       <literal>localhost</literal> are never routed to the
-      network.</para></listitem>
+      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
@@ -133,10 +137,34 @@
     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, but only through a symlink from
-    <filename>/etc/resolv.conf</filename>.</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>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>
@@ -146,7 +174,9 @@
       <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>resolv.conf</refentrytitle><manvolnum>5</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>