man: beef up resolved man page
Let's explain the various APIs and various ways to handle /etc/resolv.conf.
This commit is contained in:
Lennart Poettering
parent
b30bf55d5c
commit
b541146bf8
|
|
@ -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>
|
||||
responder. Local applications may submit network name resolution requests via three interfaces:</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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<para><command>systemd-resolved</command> synthesizes DNS RRs for the following cases:</para>
|
||||
<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>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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue