man/org.freedesktop.resolve1: briefly document a bunch of methods and properties
Fixes #13799.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
9e1804b24c
commit
2ce493672c
|
|
@ -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>
|
||||
|
||||
<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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue