diff options
| -rw-r--r-- | man/systemd-resolved.service.xml | 95 |
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> |