Merge pull request #17415 from keszybz/logind-resolved-docs
A bunch of updates to logind and resolved man pages
This commit is contained in:
commit
44f88e7050
|
@ -156,12 +156,6 @@ node /org/freedesktop/resolve1 {
|
|||
};
|
||||
</programlisting>
|
||||
|
||||
<!--method SetLinkDNSEx is not documented!-->
|
||||
|
||||
<!--method SetLinkDefaultRoute is not documented!-->
|
||||
|
||||
<!--method SetLinkDNSOverTLS is not documented!-->
|
||||
|
||||
<!--method RegisterService is not documented!-->
|
||||
|
||||
<!--method UnregisterService is not documented!-->
|
||||
|
@ -170,28 +164,8 @@ node /org/freedesktop/resolve1 {
|
|||
|
||||
<!--method ResetServerFeatures is not documented!-->
|
||||
|
||||
<!--property LLMNR is not documented!-->
|
||||
|
||||
<!--property MulticastDNS is not documented!-->
|
||||
|
||||
<!--property DNSOverTLS is not documented!-->
|
||||
|
||||
<!--property DNSEx is not documented!-->
|
||||
|
||||
<!--property FallbackDNS is not documented!-->
|
||||
|
||||
<!--property FallbackDNSEx is not documented!-->
|
||||
|
||||
<!--property CurrentDNSServer is not documented!-->
|
||||
|
||||
<!--property CurrentDNSServerEx is not documented!-->
|
||||
|
||||
<!--property DNSSEC is not documented!-->
|
||||
|
||||
<!--property DNSSECNegativeTrustAnchors is not documented!-->
|
||||
|
||||
<!--property DNSStubListener is not documented!-->
|
||||
|
||||
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
||||
|
||||
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>
|
||||
|
@ -281,26 +255,28 @@ node /org/freedesktop/resolve1 {
|
|||
<refsect2>
|
||||
<title>Methods</title>
|
||||
|
||||
<para><function>ResolveHostname()</function> takes a hostname and resolves it to one or more IP addresses.
|
||||
As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be
|
||||
done on any suitable interface. The <varname>name</varname> parameter specifies the hostname to
|
||||
resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS. The <varname>family</varname> parameter
|
||||
limits the results to a specific address family. It may be <constant>AF_INET</constant>,
|
||||
<constant>AF_INET6</constant> or <constant>AF_UNSPEC</constant>. If <constant>AF_UNSPEC</constant> is specified (recommended), both kinds are retrieved, subject
|
||||
to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is
|
||||
retrieved; and similarly for IPv4). A 64-bit <varname>flags</varname> field may be used to alter the
|
||||
behaviour of the resolver operation (see below). The method returns an array of address records. Each
|
||||
address record consists of the interface index the address belongs to, an address family as well as a
|
||||
byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address
|
||||
family). The returned address family will be one of <constant>AF_INET</constant> or
|
||||
<constant>AF_INET6</constant>. For IPv6, the returned address interface index should be used to
|
||||
initialize the .sin6_scope_id field of a <structname>struct sockaddr_in6</structname> instance to permit
|
||||
support for resolution to link-local IP addresses. The address array is followed by the canonical name
|
||||
of the host, which may or may not be identical to the resolved hostname. Finally, a 64-bit
|
||||
<varname>flags</varname> field is returned that is defined similarly to the <varname>flags</varname>
|
||||
field that was passed in, but contains information about the resolved data (see below). If the hostname
|
||||
passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In
|
||||
this case, no network communication is done.</para>
|
||||
<para><function>ResolveHostname()</function> takes a hostname and resolves it to one or more IP
|
||||
addresses. As parameters it takes the Linux network interface index to execute the query on, or 0 if
|
||||
it may be done on any suitable interface. The <varname>name</varname> parameter specifies the hostname
|
||||
to resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via
|
||||
LLMNR or MulticastDNS. The <varname>family</varname> parameter limits the results to a specific address
|
||||
family. It may be <constant>AF_INET</constant>, <constant>AF_INET6</constant> or
|
||||
<constant>AF_UNSPEC</constant>. If <constant>AF_UNSPEC</constant> is specified (recommended), both
|
||||
kinds are retrieved, subject to local network configuration (i.e. if no local, routable IPv6 address is
|
||||
found, no IPv6 address is retrieved; and similarly for IPv4). A 64-bit <varname>flags</varname> field
|
||||
may be used to alter the behaviour of the resolver operation (see below). The method returns an array
|
||||
of address records. Each address record consists of the interface index the address belongs to, an
|
||||
address family as well as a byte array with the actual IP address data (which either has 4 or 16
|
||||
elements, depending on the address family). The returned address family will be one of
|
||||
<constant>AF_INET</constant> or <constant>AF_INET6</constant>. For IPv6, the returned address interface
|
||||
index should be used to initialize the .sin6_scope_id field of a
|
||||
<structname>struct sockaddr_in6</structname> instance to permit support for resolution to link-local IP
|
||||
addresses. The address array is followed by the canonical name of the host, which may or may not be
|
||||
identical to the resolved hostname. Finally, a 64-bit <varname>flags</varname> field is returned that
|
||||
is defined similarly to the <varname>flags</varname> field that was passed in, but contains information
|
||||
about the resolved data (see below). If the hostname passed in is an IPv4 or IPv6 address formatted as
|
||||
string, it is parsed, and the result is returned. In this case, no network communication is
|
||||
done.</para>
|
||||
|
||||
<para><function>ResolveAddress()</function> executes the reverse operation: it takes an IP address and
|
||||
acquires one or more hostnames for it. As parameters it takes the interface index to execute the query
|
||||
|
@ -387,15 +363,19 @@ node /org/freedesktop/resolve1 {
|
|||
<constant>AF_INET6</constant>), followed by a 4-byte or 16-byte array with the raw address data. This
|
||||
method is a one-step shortcut for retrieving the Link object for a network interface using
|
||||
<function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> method
|
||||
(see below) on it.
|
||||
(see below) on it.</para>
|
||||
|
||||
<para><function>SetLinkDNSEx()</function> is similar to <function>SetLinkDNS()</function>, but allows
|
||||
an IP port (instead of the default 53) and DNS name to be specified for each DNS server. The server
|
||||
name is used for Server Name Indication (SNI), which is useful when DNS-over-TLS is
|
||||
used. C.f. <varname>DNS=</varname> in
|
||||
<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>Network management software integrating with <filename>systemd-resolved</filename> should
|
||||
call this method (and the five below) after the interface appeared in the kernel (and thus after a
|
||||
network interface index has been assigned), but before the network interfaces is activated
|
||||
(<constant>IFF_UP</constant> set) so that all settings take effect during the full time the network
|
||||
interface is up. It is safe to alter settings while the interface is up, however. Use
|
||||
<function>RevertLink()</function> (described below) to reset all per-interface settings.</para>
|
||||
<para><function>SetLinkDefaultRoute()</function> specifies whether the link shall be used as the
|
||||
default route for name queries. See the description of name routing in
|
||||
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
for details.</para>
|
||||
|
||||
<para>The <function>SetLinkDomains()</function> method sets the search and routing domains to use on a
|
||||
specific network interface for DNS look-ups. It takes a network interface index and an array of domains,
|
||||
|
@ -432,8 +412,22 @@ node /org/freedesktop/resolve1 {
|
|||
Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a
|
||||
list of domains as arguments.</para>
|
||||
|
||||
<para>The <function>RevertLink()</function> method may be used to revert all per-link settings done with
|
||||
the six methods described above to the defaults again.</para>
|
||||
<para>The <function>SetLinkDNSOverTLS()</function> method enables or disables DNS-over-TLS.
|
||||
C.f. <varname>DNSOverTLS=</varname> in
|
||||
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
for details.</para>
|
||||
|
||||
<para>Network management software integrating with <filename>systemd-resolved</filename> should call
|
||||
<function>SetLinkDNS()</function> or <function>SetLinkDNSEx()</function>,
|
||||
<function>SetLinkDefaultRoute()</function>, <function>SetLinkDomains()</function> and others after the
|
||||
interface appeared in the kernel (and thus after a network interface index has been assigned), but
|
||||
before the network interfaces is activated (<constant>IFF_UP</constant> set) so that all settings take
|
||||
effect during the full time the network interface is up. It is safe to alter settings while the
|
||||
interface is up, however. Use <function>RevertLink()</function> (described below) to reset all
|
||||
per-interface settings.</para>
|
||||
|
||||
<para>The <function>RevertLink()</function> method may be used to revert all per-link settings
|
||||
described above to the defaults.</para>
|
||||
|
||||
<refsect3>
|
||||
<title>The Flags Parameter</title>
|
||||
|
@ -458,11 +452,11 @@ node /org/freedesktop/resolve1 {
|
|||
classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
|
||||
IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the
|
||||
look-up will be done via all suitable protocols for the specific look-up. Note that these flags
|
||||
operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, <filename>systemd-resolved</filename>
|
||||
will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address
|
||||
domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route
|
||||
neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces
|
||||
suitable for multicast.</para>
|
||||
operate as filter only, but cannot force a look-up to be done via a protocol. Specifically,
|
||||
<filename>systemd-resolved</filename> will only route look-ups within the .local TLD to MulticastDNS
|
||||
(plus some reverse look-up address domains), and single-label names to LLMNR (plus some reverse
|
||||
address lookup domains). It will route neither of these to Unicast DNS servers. Also, it will do
|
||||
LLMNR and Multicast DNS only on interfaces suitable for multicast.</para>
|
||||
|
||||
<para>On output, these five flags indicate which protocol was used to execute the operation, and hence
|
||||
where the data was found.</para>
|
||||
|
@ -498,34 +492,50 @@ node /org/freedesktop/resolve1 {
|
|||
the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server
|
||||
does not support authenticating data).</para>
|
||||
</refsect3>
|
||||
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Properties</title>
|
||||
|
||||
<para>The <varname>LLMNR</varname> and <varname>MulticastDNS</varname> properties report whether LLMNR
|
||||
and MulticastDNS are (globally) enabled. Each may be one of <literal>yes</literal>,
|
||||
<literal>no</literal>, and <literal>resolve</literal>. See <function>SetLinkLLMNR()</function>
|
||||
and <function>SetLinkMulticastDNS()</function> above.</para>
|
||||
|
||||
<para><varname>LLMNRHostname</varname> contains the hostname currently exposed on the network via
|
||||
LLMNR. It usually follows the system hostname as may be queried via
|
||||
<citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
but may differ if a conflict is detected on the network.</para>
|
||||
|
||||
<para><varname>DNS</varname> contains an array of all DNS servers currently used by
|
||||
<filename>systemd-resolved</filename>. It contains similar information as the DNS server data written to
|
||||
/run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface
|
||||
index, an address family, and a byte array containing the DNS server address (either 4 bytes in length
|
||||
for IPv4 or 16 bytes in lengths for IPv6). The array contains DNS servers configured system-wide,
|
||||
including those possibly read from a foreign <filename>/etc/resolv.conf</filename> or the
|
||||
<varname>DNS=</varname> setting in <filename>/etc/systemd/resolved.conf</filename>, as well as
|
||||
per-interface DNS server information either retrieved from
|
||||
<para><varname>DNS</varname> and <varname>DNSEx</varname> contain arrays of all DNS servers currently
|
||||
used by <filename>systemd-resolved</filename>. <varname>DNS</varname> contains information similar to
|
||||
the DNS server data in <filename>/run/systemd/resolve/resolv.conf</filename>. Each structure in the
|
||||
array consists of a numeric network interface index, an address family, and a byte array containing the
|
||||
DNS server address (either 4 bytes in length for IPv4 or 16 bytes in lengths for IPv6).
|
||||
<varname>DNSEx</varname> is similar, but additionally contains the IP port and server name (used for
|
||||
Server Name Indication, SNI). Both arrays contain DNS servers configured system-wide, including those
|
||||
possibly read from a foreign <filename>/etc/resolv.conf</filename> or the <varname>DNS=</varname>
|
||||
setting in <filename>/etc/systemd/resolved.conf</filename>, as well as per-interface DNS server
|
||||
information either retrieved from
|
||||
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||||
or configured by external software via <function>SetLinkDNS()</function> (see above). The network
|
||||
interface index will be 0 for the system-wide configured services and non-zero for the per-link
|
||||
servers.</para>
|
||||
or configured by external software via <function>SetLinkDNS()</function> or
|
||||
<function>SetLinkDNSEx()</function> (see above). The network interface index will be 0 for the
|
||||
system-wide configured services and non-zero for the per-link servers.</para>
|
||||
|
||||
<para>Similarly, the <varname>Domains</varname> property contains an array of all search and
|
||||
routing domains currently used by <filename>systemd-resolved</filename>. Each entry consists of a network interface index (again, 0
|
||||
encodes system-wide entries), the actual domain name, and whether the entry is used only for routing
|
||||
(true) or for both routing and searching (false).</para>
|
||||
<para><varname>FallbackDNS</varname> and <varname>FallbackDNSEx</varname> contain arrays of all DNS
|
||||
servers configured as fallback servers, if any, using the same format as <varname>DNS</varname> and
|
||||
<varname>DNSEx</varname> described above. See the description of <varname>FallbackDNS=</varname> in
|
||||
<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
||||
the description of when those servers are used.</para>
|
||||
|
||||
<para><varname>CurrentDNSServer</varname> and <varname>CurrentDNSServerEx</varname> specify the server
|
||||
that is currently used for query resolution, in the same format as a single entry in the
|
||||
<varname>DNS</varname> and <varname>DNSEx</varname> arrays described above.</para>
|
||||
|
||||
<para>Similarly, the <varname>Domains</varname> property contains an array of all search and routing
|
||||
domains currently used by <filename>systemd-resolved</filename>. Each entry consists of a network
|
||||
interface index (again, 0 encodes system-wide entries), the actual domain name, and whether the entry
|
||||
is used only for routing (true) or for both routing and searching (false).</para>
|
||||
|
||||
<para>The <varname>TransactionStatistics</varname> property contains information about the number of
|
||||
transactions <filename>systemd-resolved</filename> has processed. It contains a pair of unsigned 64-bit counters, the first
|
||||
|
@ -540,7 +550,14 @@ node /org/freedesktop/resolve1 {
|
|||
operations so far. It exposes three 64-bit counters: the first being the total number of current cache
|
||||
entries (both positive and negative), the second the number of cache hits, and the third the number of
|
||||
cache misses. The latter counters may be reset using <function>ResetStatistics()</function> (see
|
||||
above). </para>
|
||||
above).</para>
|
||||
|
||||
<para>The <varname>DNSSEC</varname> property specifies current status of DNSSEC validation. It is one
|
||||
of <literal>yes</literal> (validation is enforced), <literal>no</literal> (no validation is done),
|
||||
<literal>allow-downgrade</literal> (validation is done if the current DNS server supports it). See the
|
||||
description of <varname>DNSSEC=</varname> in
|
||||
<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>The <varname>DNSSECStatistics</varname> property contains information about the DNSSEC
|
||||
validations executed so far. It contains four 64-bit counters: the number of secure, insecure, bogus,
|
||||
|
@ -559,12 +576,20 @@ node /org/freedesktop/resolve1 {
|
|||
DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported
|
||||
value may initially be true, until the first transactions are executed.</para>
|
||||
|
||||
<para>The <varname>DNSOverTLS</varname> boolean property reports whether DNS-over-TLS is enabled.
|
||||
</para>
|
||||
|
||||
<para>The <varname>ResolvConfMode</varname> property exposes how <filename>/etc/resolv.conf</filename>
|
||||
is managed on the host. Currently, the values <literal>uplink</literal>, <literal>stub</literal>,
|
||||
<literal>static</literal> (these three correspond to the three different files
|
||||
<filename>systemd-resolved.service</filename> provides), <literal>foreign</literal> (the file is
|
||||
managed by admin or another service, <filename>systemd-resolved.service</filename> just consumes it),
|
||||
<literal>missing</literal> (<filename>/etc/resolv.conf</filename> is missing).</para>
|
||||
|
||||
<para>The <varname>DNSStubListener</varname> property reports whether the stub listener on port 53 is
|
||||
enabled. Possible values are <literal>yes</literal> (enabled), <literal>no</literal> (disabled),
|
||||
<literal>udp</literal> (only the UDP listener is enabled), and <literal>tcp</literal> (only the TCP
|
||||
listener is enabled).</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
|
@ -619,40 +644,6 @@ node /org/freedesktop/resolve1/link/_1 {
|
|||
};
|
||||
</programlisting>
|
||||
|
||||
<!--method SetDNSEx is not documented!-->
|
||||
|
||||
<!--method SetDomains is not documented!-->
|
||||
|
||||
<!--method SetDefaultRoute is not documented!-->
|
||||
|
||||
<!--method SetLLMNR is not documented!-->
|
||||
|
||||
<!--method SetMulticastDNS is not documented!-->
|
||||
|
||||
<!--method SetDNSOverTLS is not documented!-->
|
||||
|
||||
<!--method SetDNSSEC is not documented!-->
|
||||
|
||||
<!--method SetDNSSECNegativeTrustAnchors is not documented!-->
|
||||
|
||||
<!--method Revert is not documented!-->
|
||||
|
||||
<!--property DNSEx is not documented!-->
|
||||
|
||||
<!--property CurrentDNSServer is not documented!-->
|
||||
|
||||
<!--property CurrentDNSServerEx is not documented!-->
|
||||
|
||||
<!--property DefaultRoute is not documented!-->
|
||||
|
||||
<!--property LLMNR is not documented!-->
|
||||
|
||||
<!--property MulticastDNS is not documented!-->
|
||||
|
||||
<!--property DNSOverTLS is not documented!-->
|
||||
|
||||
<!--property DNSSEC is not documented!-->
|
||||
|
||||
<!--property DNSSECNegativeTrustAnchors is not documented!-->
|
||||
|
||||
<!--Autogenerated cross-references for systemd.directives, do not edit-->
|
||||
|
@ -721,8 +712,13 @@ node /org/freedesktop/resolve1/link/_1 {
|
|||
<function>SetLinkDNS()</function> on the Manager object, the main difference being that the later
|
||||
expects an interface index to be specified. Invoking the methods on the Manager interface has the
|
||||
benefit of reducing roundtrips, as it is not necessary to first request the Link object path via
|
||||
<function>GetLink()</function> before invoking the methods. For further details on these methods see
|
||||
the <interfacename>Manager</interfacename> documentation above.</para>
|
||||
<function>GetLink()</function> before invoking the methods. The same relationship holds for
|
||||
<function>SetDNSEx()</function>, <function>SetDomains()</function>,
|
||||
<function>SetDefaultRoute()</function>, <function>SetLLMNR()</function>,
|
||||
<function>SetMulticastDNS()</function>, <function>SetDNSOverTLS()</function>,
|
||||
<function>SetDNSSEC()</function>, <function>SetDNSSECNegativeTrustAnchors()</function>, and
|
||||
<function>Revert()</function>. For further details on these methods see the
|
||||
<interfacename>Manager</interfacename> documentation above.</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
|
@ -744,8 +740,12 @@ node /org/freedesktop/resolve1/link/_1 {
|
|||
assumed available until it is detected that the configured server does not actually support it. Thus,
|
||||
this property may initially report that DNSSEC is supported on an interface.</para>
|
||||
|
||||
<para><varname>DefaultRoute</varname> exposes a boolean field that indicates whether the interface will
|
||||
be used as default route for name queries. See <function>SetLinkDefaultRoute()</function> above.</para>
|
||||
|
||||
<para>The other properties reflect the state of the various configuration settings for the link which
|
||||
may be set with the various methods calls such as SetDNS() or SetLLMNR().</para>
|
||||
may be set with the various methods calls such as <function>SetDNS()</function> or
|
||||
<function>SetLLMNR()</function>.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
|
|
|
@ -87,17 +87,17 @@
|
|||
<refsect1>
|
||||
<title>Synthetic Records</title>
|
||||
|
||||
<para><command>systemd-resolved</command> synthesizes DNS resource records (RRs) for the following
|
||||
<para><command>systemd-resolved</command> synthetizes DNS resource records (RRs) for the following
|
||||
cases:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>The local, configured hostname is resolved to all locally configured IP addresses
|
||||
ordered by their scope, or — if none are configured — the IPv4 address 127.0.0.2 (which is on the local
|
||||
loopback) and the IPv6 address ::1 (which is the local host).</para></listitem>
|
||||
loopback interface) and the IPv6 address ::1 (which is the local host).</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.
|
||||
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
|
||||
|
@ -119,104 +119,162 @@
|
|||
according to the following rules:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Names for which synthetic records are generated (as listed in the previous section) are
|
||||
never routed to the network and a reply is sent immediately. In particular this means that lookups for
|
||||
<literal>localhost</literal> are never routed to the network.</para></listitem>
|
||||
<listitem><para>Names for which synthetic records are generated (the local hostname,
|
||||
<literal>localhost</literal> and <literal>localdomain</literal>, local gateway, as listed in the
|
||||
previous section) and addresses configured in <filename>/etc/hosts</filename> are never routed to the
|
||||
network and a reply is sent immediately.</para></listitem>
|
||||
|
||||
<listitem><para>Single-label names are routed to all local interfaces capable of IP multicasting, where
|
||||
LLMNR is not disabled, using the LLMNR protocol. Lookups for IPv4 addresses are only sent via LLMNR on
|
||||
IPv4, and lookups for IPv6 addresses are only sent via LLMNR on IPv6. Lookups for the locally
|
||||
configured hostname and the <literal>_gateway</literal> hostname are never routed to LLMNR.
|
||||
</para></listitem>
|
||||
<listitem><para>Single-label names are resolved using LLMNR on all local interfaces where LLMNR is
|
||||
enabled. Lookups for IPv4 addresses are only sent via LLMNR on IPv4, and lookups for IPv6 addresses are
|
||||
only sent via LLMNR on IPv6. Note that lookups for single-label synthetized names are not routed to
|
||||
LLMNR, MulticastDNS or unicast DNS.</para></listitem>
|
||||
|
||||
<listitem><para>Multi-label names with the domain suffix <literal>.local</literal> are routed to all
|
||||
local interfaces capable of IP multicasting, where MulticastDNS is not disabled, using the MulticastDNS
|
||||
protocol. As with LLMNR, IPv4 address lookups are sent via IPv4 and IPv6 address lookups are sent via
|
||||
IPv6.</para></listitem>
|
||||
<listitem><para>Queries for the address records (A and AAAA) of single-label non-synthetized names are
|
||||
resolved via unicast DNS using search domains. For any interface which defines search domains, such
|
||||
look-ups are routed to that interface, suffixed with each of the search domains defined on that
|
||||
interface in turn. When global search domains are defined, such look-ups are routed to all interfaces,
|
||||
suffixed by each of the global search domains in turn. Additionally, lookup of single-label names via
|
||||
unicast DNS may be enabled with the <varname>ResolveUnicastSingleLabel=yes</varname> setting. The
|
||||
details of which servers are queried and how the final reply is chosen are described below. Note that
|
||||
this means that address queries for single-label names are never sent out to remote DNS servers by
|
||||
default, and resoulution is only possible if search domains are defined.</para></listitem>
|
||||
|
||||
<listitem><para>Resolution of address records (A and AAAA) via unicast DNS (i.e. not LLMNR or
|
||||
MulticastDNS) for non-synthesized single-label names is allowed for non-top-level domains. This means
|
||||
that such records can be resolved when search domains are defined. For any interface which defines
|
||||
search domains, such look-ups are routed to that interface, suffixed with each of the search domains
|
||||
defined on that interface in turn. When global search domains are defined, such look-ups are routed to
|
||||
all interfaces, suffixed by each of the global search domains in turn. Additionally, lookup of
|
||||
single-label names via unicast DNS may be enabled with the
|
||||
<varname>ResolveUnicastSingleLabel=yes</varname> setting. The details of which servers are queried and
|
||||
how the final reply is chosen are described below. Note that this means that address queries for
|
||||
single-label names are never sent out to remote DNS servers by default, and if no search domains are
|
||||
defined, resolution will fail.</para></listitem>
|
||||
<listitem><para>Multi-label names with the domain suffix <literal>.local</literal> are resolved using
|
||||
MulticastDNS on all local interfaces where MulticastDNS is enabled. As with LLMNR, IPv4 address lookups
|
||||
are sent via IPv4 and IPv6 address lookups are sent via IPv6.</para></listitem>
|
||||
|
||||
<listitem><para>Other multi-label names are routed to all local interfaces that have a DNS server
|
||||
configured, plus the globally configured DNS servers if there are any. Note that by default, lookups for
|
||||
domains with the <literal>.local</literal> suffix are not routed to DNS servers, unless the domain is
|
||||
specified explicitly as routing or search domain for the DNS server and interface. This means that on
|
||||
networks where the <literal>.local</literal> domain is defined in a site-specific DNS server, explicit
|
||||
search or routing domains need to be configured to make lookups within this DNS domain work. Note that
|
||||
these days, it's generally recommended to avoid defining <literal>.local</literal> in a DNS server, as
|
||||
<ulink url="https://tools.ietf.org/html/rfc6762">RFC6762</ulink> reserves this domain for exclusive
|
||||
<listitem><para>Queries for multi-label names are routed via unicast DNS on local interfaces that have
|
||||
a DNS server configured, plus the globally configured DNS servers if there are any. Which interfaces
|
||||
are used is determined by the routing logic based on search and route-only domains, described below.
|
||||
Note that by default, lookups for domains with the <literal>.local</literal> suffix are not routed to
|
||||
DNS servers, unless the domain is specified explicitly as routing or search domain for the DNS server
|
||||
and interface. This means that on networks where the <literal>.local</literal> domain is defined in a
|
||||
site-specific DNS server, explicit search or routing domains need to be configured to make lookups work
|
||||
within this DNS domain. Note that these days, it's generally recommended to avoid defining
|
||||
<literal>.local</literal> in a DNS server, as <ulink
|
||||
url="https://tools.ietf.org/html/rfc6762">RFC6762</ulink> reserves this domain for exclusive
|
||||
MulticastDNS use.</para></listitem>
|
||||
|
||||
<listitem><para>Address lookups are routed similarly to multi-label names, with the exception that
|
||||
addresses from the link-local address range are never routed to unicast DNS and are only resolved using
|
||||
LLMNR and MulticastDNS (when enabled).</para></listitem>
|
||||
<listitem><para>Address lookups (reverse lookups) are routed similarly to multi-label names, with the
|
||||
exception that addresses from the link-local address range are never routed to unicast DNS and are only
|
||||
resolved using LLMNR and MulticastDNS (when enabled).</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>If lookups are routed to multiple interfaces, the first successful response is returned (thus
|
||||
effectively merging the lookup zones on all matching interfaces). If the lookup failed on all interfaces,
|
||||
the last failing response is returned.</para>
|
||||
|
||||
<para>Routing of lookups may be influenced by configuring per-interface domain names and other
|
||||
settings. See
|
||||
<para>Routing of lookups is determined by the per-interface routing domains (search and route-only) and
|
||||
global search domains. See
|
||||
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
|
||||
<citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
|
||||
details. The following query routing logic applies for unicast DNS traffic:</para>
|
||||
<citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for a
|
||||
description how those settings are set dynamically and the discussion of <varname>Domains=</varname> in
|
||||
<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
|
||||
description of globally configured DNS settings.</para>
|
||||
|
||||
<para>The following query routing logic applies for unicast DNS traffic:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>If a name to look up matches (that is: is equal to or has as suffix) any of the
|
||||
configured search or route-only domains of any link (see
|
||||
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
|
||||
or the globally configured DNS settings (see the discussion of <varname>Domains=</varname> in
|
||||
<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
|
||||
"best matching" search/route-only domain is determined: the matching one with the most labels. The
|
||||
query is then sent to all DNS servers of any links or the globally configured DNS servers associated
|
||||
with this "best matching" search/route-only domain. (Note that more than one link might have this same
|
||||
"best matching" search/route-only domain configured, in which case the query is sent to all of them in
|
||||
parallel).</para>
|
||||
configured routing domains (search or route-only) of any link, or the globally configured DNS settings,
|
||||
"best matching" routing domain is determined: the matching one with the most labels. The query is then
|
||||
sent to all DNS servers of any links or the globally configured DNS servers associated with this "best
|
||||
matching" routing domain. (Note that more than one link might have this same "best matching" routing
|
||||
domain configured, in which case the query is sent to all of them in parallel).</para>
|
||||
|
||||
<para>In case of single-label names, when search domains are defined, the same logic applies, except
|
||||
that the name is first suffixed by the search domain.</para></listitem>
|
||||
that the name is first suffixed by each of the search domains in turn. Note that this search logic
|
||||
doesn't apply to any names with at least one dot. Also see the discussion about compatiblity with
|
||||
the traditional glibc resolver below.</para></listitem>
|
||||
|
||||
<listitem><para>If a query does not match any configured search/route-only domain (neither per-link nor
|
||||
global), it is sent to all DNS servers that are configured on links with the "DNS default route" option
|
||||
set, as well as the globally configured DNS server.</para></listitem>
|
||||
<listitem><para>If a query does not match any configured routing domain (either per-link or global), it
|
||||
is sent to all DNS servers that are configured on links with the <varname>DefaultRoute=</varname>
|
||||
option set, as well as the globally configured DNS server.</para></listitem>
|
||||
|
||||
<listitem><para>If there is no link configured as "DNS default route" and no global DNS server
|
||||
configured, the compiled-in fallback DNS server is used.</para></listitem>
|
||||
<listitem><para>If there is no link configured as <varname>DefaultRoute=</varname> and no global DNS
|
||||
server configured, one of the compiled-in fallback DNS servers is used.</para></listitem>
|
||||
|
||||
<listitem><para>Otherwise the query is failed as no suitable DNS servers could be determined.
|
||||
<listitem><para>Otherwise the unicast DNS query fails, as no suitable DNS servers can be determined.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>The "DNS default route" option is a boolean setting configurable with <command>resolvectl</command>
|
||||
or in <filename>.network</filename> files. If not set, it is implicitly determined based on the
|
||||
configured DNS domains for a link: if there's any route-only domain (not matching <literal>~.</literal>)
|
||||
it defaults to false, otherwise to true.</para>
|
||||
<para>The <varname>DefaultRoute=</varname> option is a boolean setting configurable with
|
||||
<command>resolvectl</command> or in <filename>.network</filename> files. If not set, it is implicitly
|
||||
determined based on the configured DNS domains for a link: if there's a route-only domain other than
|
||||
<literal>~.</literal>, it defaults to false, otherwise to true.</para>
|
||||
|
||||
<para>Effectively this means: in order to support single-label non-synthetized names, define appropriate
|
||||
search domains. In order to preferably route all DNS queries not explicitly matched by search/route-only
|
||||
domain configuration to a specific link, configure a <literal>~.</literal> route-only domain on it. This
|
||||
will ensure that other links will not be considered for these queries (unless they too carry such a
|
||||
route-only domain). In order to route all such DNS queries to a specific link only if no other link
|
||||
is preferable, set the "DNS default route" option for the link to true and do not configure a
|
||||
search domains. In order to preferably route all DNS queries not explicitly matched by routing domain
|
||||
configuration to a specific link, configure a <literal>~.</literal> route-only domain on it. This will
|
||||
ensure that other links will not be considered for these queries (unless they too carry such a routing
|
||||
domain). In order to route all such DNS queries to a specific link only if no other link is preferred,
|
||||
set the <varname>DefaultRoute=</varname> option for the link to true and do not configure a
|
||||
<literal>~.</literal> route-only domain on it. Finally, in order to ensure that a specific link never
|
||||
receives any DNS traffic not matching any of its configured search/route-only domains, set the "DNS
|
||||
default route" option for it to false.</para>
|
||||
receives any DNS traffic not matching any of its configured routing domains, set the
|
||||
<varname>DefaultRoute=</varname> option for it to false.</para>
|
||||
|
||||
<para>See
|
||||
<citerefentry><refentrytitle>org.freedesktop.resolve1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for information about the D-Bus APIs <filename>systemd-resolved</filename> provides.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Compatibility with the traditional glibc stub resolver</title>
|
||||
|
||||
<para>This section provides a short summary of differences in the stub resolver implemented by
|
||||
<citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry> together
|
||||
with <command>systemd-resolved</command> and the tranditional stub resolver implemented in
|
||||
<citerefentry><refentrytitle>nss-dns</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Some names are always resolved internally (see Synthetic Records above). Traditionally
|
||||
they would be resolved by <filename>nss-files</filename>, and only if provided in
|
||||
<filename>/etc/hosts</filename>.</para></listitem>
|
||||
|
||||
<listitem><para>Single-label names are not resolved for A and AAAA records using unicast DNS (unless
|
||||
overriden with <varname>ResolveUnicastSingleLabel=</varname>, see
|
||||
<citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
|
||||
This is similar to the <option>no-tld-query</option> option being set in
|
||||
<citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>Search domains are not used for <emphasis>suffixing</emphasis> of multi-label names.
|
||||
(Search domains are nevertheless used for lookup <emphasis>routing</emphasis>, for names that were
|
||||
originally specified as single-label or multi-label.) Any name with at least one dot is always
|
||||
interpreted as a FQDN. <filename>nss-dns</filename> would resolve names both as relative (using search
|
||||
domains) and absolute FQDN names. Some names would be resolved as relative first, and after that query
|
||||
has failed, as absolute, while other names would be resolved in opposite order. The
|
||||
<varname>ndots</varname> option in <filename>/etc/resolv.conf</filename> was used to control how many
|
||||
dots the name needs to have to be resolved as relative first. This stub resolver does not implement
|
||||
this at all: multi-label names are only resolved as FQDNs. (There are currently more than 1500
|
||||
top-level domain names defined, and new ones are added regularly, often using "attractive" names that
|
||||
are also likely to be used locally. Not looking up multi-label names in this fashion avoids fragility
|
||||
in both directions: a valid global name could be obscured by a local name, and resolution of a relative
|
||||
local name could suddenly break when a new top-level domain is created, or when a new subdomain of a
|
||||
top-level domain in registered. Resolving any given name as either relative or absolute avoids this
|
||||
ambiguity.)</para></listitem>
|
||||
|
||||
<listitem><para>This resolver has a notion of the special <literal>.local</literal> domain used for
|
||||
MulticastDNS, and will not route queries with that suffix to unicast DNS servers unless explicitly
|
||||
configured, see above. Also, reverse lookups for link-local addresses are not sent to unicast DNS
|
||||
servers.</para></listitem>
|
||||
|
||||
<listitem><para>This resolver reads and caches <filename>/etc/hosts</filename> internally. (In other
|
||||
words, <filename>nss-resolve</filename> replaces <filename>nss-files</filename> in addition to
|
||||
<filename>nss-dns</filename>). Entries in <filename>/etc/hosts</filename> have highest priority.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>This resolver also implements LLMNR and MulticastDNS in addition to the classic unicast
|
||||
DNS protocol, and will resolve single-label names using LLMNR (when enabled) and names ending in
|
||||
<literal>.local</literal> using MulticastDNS (when enabled).</para></listitem>
|
||||
|
||||
<listitem><para>Environment variables <varname>$LOCALDOMAIN</varname> and
|
||||
<varname>$RES_OPTIONS</varname> described in
|
||||
<citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> are not
|
||||
supported currently.</para></listitem>
|
||||
</itemizedlist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title><filename>/etc/resolv.conf</filename></title>
|
||||
|
||||
|
@ -303,7 +361,6 @@
|
|||
synchronous way.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
|
|
@ -273,7 +273,7 @@ static int write_uplink_resolv_conf_contents(FILE *f, OrderedSet *dns, OrderedSe
|
|||
}
|
||||
|
||||
if (ordered_set_isempty(domains))
|
||||
fputs("search .", f); /* Make sure that if the local hostname is chosen as fqdn this does not
|
||||
fputs("search .\n", f); /* Make sure that if the local hostname is chosen as fqdn this does not
|
||||
* imply a search domain */
|
||||
else
|
||||
write_resolv_conf_search(domains, f);
|
||||
|
@ -302,7 +302,7 @@ static int write_stub_resolv_conf_contents(FILE *f, OrderedSet *dns, OrderedSet
|
|||
"options edns0 trust-ad\n", f);
|
||||
|
||||
if (ordered_set_isempty(domains))
|
||||
fputs("search .", f); /* Make sure that if the local hostname is chosen as fqdn this does not
|
||||
fputs("search .\n", f); /* Make sure that if the local hostname is chosen as fqdn this does not
|
||||
* imply a search domain */
|
||||
else
|
||||
write_resolv_conf_search(domains, f);
|
||||
|
|
|
@ -25,5 +25,6 @@
|
|||
#LLMNR=@DEFAULT_LLMNR_MODE@
|
||||
#Cache=yes
|
||||
#DNSStubListener=yes
|
||||
#DNSStubListenerExtra=
|
||||
#ReadEtcHosts=yes
|
||||
#ResolveUnicastSingleLabel=no
|
||||
|
|
Loading…
Reference in a new issue