man: import org.freedesktop.resolve1(3) from the wiki
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
5cc34d6d1a
commit
ffd10e5a24
|
|
@ -0,0 +1,567 @@
|
|||
<?xml version="1.0"?>
|
||||
<!--*-nxml-*-->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
||||
%entities;
|
||||
]>
|
||||
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
||||
|
||||
<refentry id="org.freedesktop.resolve1" conditional='ENABLE_RESOLVE'
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<refentryinfo>
|
||||
<title>org.freedesktop.resolve1</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>org.freedesktop.resolve1</refentrytitle>
|
||||
<manvolnum>5</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>org.freedesktop.resolve1</refname>
|
||||
<refpurpose>The D-Bus interface of systemd-resolved</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
is a system service that provides host name resolution and caching using DNS, LLMNR, and mDNS. It also
|
||||
does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface.</para>
|
||||
|
||||
<para>This page contains an API reference only. If you are looking for a longer explanation how to use
|
||||
this API, please consult
|
||||
<ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers">
|
||||
Writing Network Configuration Managers</ulink>
|
||||
and
|
||||
<ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients">Writing Resolver
|
||||
Clients</ulink>.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>The Manager Object</title>
|
||||
|
||||
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
|
||||
|
||||
<programlisting>
|
||||
$ gdbus introspect --system \
|
||||
--dest org.freedesktop.resolve1 \
|
||||
--object-path /org/freedesktop/resolve1
|
||||
|
||||
node /org/freedesktop/resolve1 {
|
||||
interface org.freedesktop.resolve1.Manager {
|
||||
methods:
|
||||
ResolveHostname(in i ifindex,
|
||||
in s name,
|
||||
in i family,
|
||||
in t flags,
|
||||
out a(iiay) addresses,
|
||||
out s canonical,
|
||||
out t flags);
|
||||
ResolveAddress(in i ifindex,
|
||||
in i family,
|
||||
in ay address,
|
||||
in t flags,
|
||||
out a(is) names,
|
||||
out t flags);
|
||||
ResolveRecord(in i ifindex,
|
||||
in s name,
|
||||
in q class,
|
||||
in q type,
|
||||
in t flags,
|
||||
out a(iqqay) records,
|
||||
out t flags);
|
||||
ResolveService(in i ifindex,
|
||||
in s name,
|
||||
in s type,
|
||||
in s domain,
|
||||
in i family,
|
||||
in t flags,
|
||||
out a(qqqsa(iiay)s) srv_data,
|
||||
out aay txt_data,
|
||||
out s canonical_name,
|
||||
out s canonical_type,
|
||||
out s canonical_domain,
|
||||
out t flags);
|
||||
ResetStatistics();
|
||||
GetLink(in i ifindex,
|
||||
out o path);
|
||||
SetLinkDNS(in i ifindex,
|
||||
in a(iay) addresses);
|
||||
SetLinkDomains(in i ifindex,
|
||||
in a(sb) domains);
|
||||
SetLinkLLMNR(in i ifindex,
|
||||
in s mode);
|
||||
SetLinkMulticastDNS(in i ifindex,
|
||||
in s mode);
|
||||
SetLinkDNSSEC(in i ifindex,
|
||||
in s mode);
|
||||
SetLinkDNSSECNegativeTrustAnchors(in i ifindex,
|
||||
in as names);
|
||||
RevertLink(in i ifindex);
|
||||
properties:
|
||||
readonly s LLMNRHostname = 'delta';
|
||||
readonly a(iiay) DNS = [(0, 2, [0xac, 0x1f, 0x00, 0x01])];
|
||||
readonly a(isb) Domains = [(0, 'fritz.box', false)];
|
||||
readonly (tt) TransactionStatistics = (0, 846);
|
||||
readonly (ttt) CacheStatistics = (55, 406, 439);
|
||||
readonly (tttt) DNSSECStatistics = (0, 0, 0, 0);
|
||||
readonly b DNSSECSupported = false;
|
||||
};
|
||||
interface org.freedesktop.DBus.Peer {
|
||||
};
|
||||
interface org.freedesktop.DBus.Introspectable {
|
||||
};
|
||||
interface org.freedesktop.DBus.Properties {
|
||||
};
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
<refsect2>
|
||||
<title>Methods</title>
|
||||
|
||||
<para><function>ResolveHostname()</function> takes a hostname and acquires one or more IP addresses for
|
||||
it. 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 IDNA conversion is applied to this name when necessary, and when it is resolved via
|
||||
Unicast DNS, but not for resolution via LLMNR or MulticastDNS. The <varname>family</varname> parameter
|
||||
specifies the address family of the IP address to retrieve. It may be <constant>AF_INET</constant>,
|
||||
<constant>AF_INET6</constant> or <constant>AF_UNSPEC</constant>, to request addresses of a specific
|
||||
family. 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
|
||||
behaviour of the resolver operation (see below). The method returns an array of address records. Each
|
||||
address record consists of an 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>, 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 name looked up. 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 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
|
||||
on, or <constant>0</constant> if all suitable interfaces are OK. The <varname>family</varname>
|
||||
parameter indicates the address family of the IP address to resolve, it may be either
|
||||
<constant>AF_INET</constant> or <constant>AF_INET6</constant>. The <varname>address</varname> parameter
|
||||
takes the raw IP address data (as either 4 or 16 byte array). The <varname>flags</varname> input
|
||||
parameter may be used to alter the resolver operation (see below). The call returns an array of name
|
||||
records, consisting of an interface index plus the name each. The <varname>flags</varname> output
|
||||
field contains additional information about the resolver operation (see below).</para>
|
||||
|
||||
<para><function>ResolveRecord()</function> takes a DNS resource record (RR) type, class and name, and
|
||||
retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the
|
||||
Linux network interface index to execute the query on, or <constant>0</constant> if it may be done on
|
||||
any suitable interface. The <varname>name</varname> parameter specifies the RR domain name to look up
|
||||
(no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be
|
||||
ANY). Finally, a <varname>flags</varname> field may be passed in to alter behaviour of the look-up (see
|
||||
below). On return an array of RR items is returned. Each array entry consists of the network interface
|
||||
index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw
|
||||
RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed
|
||||
by the RR type, class, TTL and RDATA, in the binary format documented in
|
||||
<ulink url="https://www.ietf.org/rfc/rfc1035.txt">RFC 1035</ulink>. For RRs that support name
|
||||
compression in the payload (such as MX or PTR), the compression is expanded in the returned
|
||||
data.</para>
|
||||
|
||||
<para>Note that the class field has to be specified as IN or ANY currently, and specifying a different
|
||||
class will return an error indicating that look-ups of this kind are unsupported. Similarly, some
|
||||
special types are not supported either (AXFR, OPT, …). While <filename>systmed-resolved</filename> parses and validates resource
|
||||
record of many types, it is crucial that clients using this API understand that the RR data originates
|
||||
from the network and should be thoroughly validated before use.</para>
|
||||
|
||||
<para><function>ResolveService()</function> may be used to resolve a DNS SRV service record, as the
|
||||
hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional
|
||||
service metadata. The primary benefit of using this call over <function>ResolveRecord()</function>
|
||||
specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced
|
||||
in the SRV in a single operation. As parameters it takes a Linux network interface index, a service
|
||||
name, a service type and a service domain. The call may be invoked in three different modes:</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
|
||||
Files</literal>), the service type (e.g. <literal>_webdav._tcp</literal>) and the domain to search in
|
||||
(e.g. <literal>local</literal>) in the three service parameters. The service name must be in UTF-8
|
||||
format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD
|
||||
specifications). However, if necessary IDNA conversion is applied to the domain parameter.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string,
|
||||
and set the service type and domain properly. (IDNA conversion is applied to the domain, if
|
||||
necessary.)</para></listitem>
|
||||
|
||||
<listitem><para>Alternatively, leave both the service name and type empty, and specify the full
|
||||
domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA
|
||||
coversion is applied in this mode.)</para></listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>The <varname>family</varname> parameter of the <function>ResolveService()</function> call encodes
|
||||
the desired family of the addresses to resolve (use <constant>AF_INET</constant>,
|
||||
<constant>AF_INET6</constant>, <constant>AF_UNSPEC</constant>), if this is enabled (Use the
|
||||
<constant>NO_ADDRESS</constant> flag to turn address resolution off, see below). The
|
||||
<varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
|
||||
operation.</para>
|
||||
|
||||
<para>On return, <function>ResolveService()</function> returns an array of SRV record structures. Each
|
||||
item consists of the priority, weight and port fields and the hostname to contact, as encoded in the SRV
|
||||
record. Immediately following is an array with the addresses of this hostname, with each item consisting
|
||||
of the interface index, the address family and the address data in a byte array. This address array is
|
||||
followed with the canonicalized hostname. After this array of SRV record structures an array of byte
|
||||
arrays follows, that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
|
||||
are the canonical service name, type and domain. This may or may not be identical to the parameters
|
||||
passed in. Finally, a <varname>flags</varname> field is returned that contains information about the
|
||||
resolver operation performed.</para>
|
||||
|
||||
<para>The <function>ResetStatistics()</function> method resets to zero the various statistics counters
|
||||
<filename>systmed-resolved</filename> maintains. (For details, see the statistics properties below.)</para>
|
||||
|
||||
<para>The <function>GetLink()</function> method takes a network interface index and returns the object
|
||||
path to the <interfacename>org.freedesktop.resolve1.Link</interfacename> object corresponding to it.
|
||||
</para>
|
||||
|
||||
<para>The <function>SetLinkDNS()</function> method sets the DNS servers to use on a specific
|
||||
interface. This call (and the following ones) may be used by network management software to configure
|
||||
per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP
|
||||
address records. Each array item consists of an address family (either <constant>AF_INET</constant> or
|
||||
<constant>AF_INET6</constant>), followed by a 4-byte or 16-byte array with the raw address data. This
|
||||
call is a one-call shortcut for retrieving the Link object for a network interface using
|
||||
<function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> call
|
||||
(see below) on it.
|
||||
</para>
|
||||
|
||||
<para>Network management software integrating with <filename>systmed-resolved</filename> is recommended
|
||||
to invoke 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 (set
|
||||
<constant>IFF_UP</constant> on) 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 the
|
||||
<function>RevertLink()</function> (described below) to reset all per-interface settings.</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 take a network interface index plus an array of domains,
|
||||
each with a boolean parameter indicating whether the specified domain shall be used as search domain
|
||||
(false), or just as routing domain (true). Search domains are used for qualifying single-label names into
|
||||
FQDN when looking up hostnames, as well as for making routing decisions on which interface to send
|
||||
queries ending in the domain to. Routing domains are not used for single-label name qualification, and
|
||||
are only used for routing decisions. Pass the search domains in the order they shall be used.</para>
|
||||
|
||||
<para>The <function>SetLinkLLMNR()</function> method enables or disables LLMNR support on a specific
|
||||
network interface. It takes a network interface index as well as a string that either may be empty,
|
||||
<literal>yes</literal>, <literal>no</literal> or <literal>resolve</literal>. If empty, the systemd-wide
|
||||
default LLMNR setting is used. If <literal>yes</literal> LLMNR is used for resolution of single-label
|
||||
names, and the local hostname is registered on all local LANs for LLMNR resolution by peers. If
|
||||
<literal>no</literal> LLMNR is turned off fully on this interface. If <literal>resolve</literal> LLMNR
|
||||
is only enabled for resolving names, but the local host name is not registered for other peers to
|
||||
use.</para>
|
||||
|
||||
<para>Similarly, the <function>SetLinkMulticastDNS()</function> method enables or disables MulticastDNS
|
||||
support on a specific interface. It takes the same parameters as <function>SetLinkLLMNR()</function>
|
||||
described above.</para>
|
||||
|
||||
<para>The <function>SetLinkDNSSEC()</function> method enables or disables DNSSEC validation on a
|
||||
specific network interface. It takes a network interface index as well as a string that either may be
|
||||
empty, <literal>yes</literal>, <literal>no</literal> or <literal>allow-downgrade</literal>. If empty,
|
||||
the system-wide default DNSSEC setting is used. If <literal>yes</literal> full DNSSEC validation is
|
||||
done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this
|
||||
mode is used. If <literal>no</literal> DNSSEC validation is fully disabled. If
|
||||
<literal>allow-downgrade</literal> DNSSEC validation is enabled, but is turned off automatically if the
|
||||
selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC
|
||||
only applies to traditional DNS, not to LLMNR or MulticastDNS.</para>
|
||||
|
||||
<para>The <function>SetLinkDNSSECNegativeTrustAnchors()</function> method may be used to configure DNSSEC
|
||||
Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a
|
||||
list of domains as parameters.</para>
|
||||
|
||||
<para>The <function>RevertLink()</function> method may be used to revert all per-link settings done with
|
||||
the six calls described above to the defaults again.</para>
|
||||
|
||||
<refsect3>
|
||||
<title>The Flags Parameter</title>
|
||||
|
||||
<para>The four calls above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
|
||||
and recommended. However, the following flags are defined to alter the look-up:</para>
|
||||
|
||||
<programlisting>
|
||||
#define SD_RESOLVED_DNS (UINT64_C(1) << 0)
|
||||
#define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) << 1)
|
||||
#define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) << 2)
|
||||
#define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) << 3)
|
||||
#define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) << 4)
|
||||
#define SD_RESOLVED_NO_CNAME (UINT64_C(1) << 5)
|
||||
#define SD_RESOLVED_NO_TXT (UINT64_C(1) << 6)
|
||||
#define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) << 7)
|
||||
#define SD_RESOLVED_NO_SEARCH (UINT64_C(1) << 8)
|
||||
#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9)
|
||||
</programlisting>
|
||||
|
||||
<para>On input, the first five flags control the protocols to use for the look-up. They refer to
|
||||
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>systmed-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 multicasting.</para>
|
||||
|
||||
<para>On output these five flags indicate which protocol was used to execute the operation, and hence
|
||||
where the data was found.</para>
|
||||
|
||||
<para>The primary use case for these five flags are follow-up look-ups based on DNS data retrieved
|
||||
earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
|
||||
used to discover the first DNS data look-up.</para>
|
||||
|
||||
<para>The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the
|
||||
look-up. This flag is only available at input, none of the functions will return it on output. If a
|
||||
CNAME/DNAME RR is discovered while resolving a hostname an error is returned instead. By default,
|
||||
when the flag is off, CNAME/DNAME RRs are followed.</para>
|
||||
|
||||
<para>The NO_TXT and NO_ADDRESS flags influence operation of the
|
||||
<function>ResolveService()</function> call only. They are only defined for input, not output. If
|
||||
NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified
|
||||
the hostnames discovered are not implicitly translated to their addresses.</para>
|
||||
|
||||
<para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
|
||||
<function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
|
||||
using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
|
||||
will not qualify single-label domain names using search domains in any case. Also note that
|
||||
multi-label hostnames are never subject to search list expansion.</para>
|
||||
|
||||
<para>The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the
|
||||
returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data
|
||||
for which a full trust chain may be established to a trusted domain anchor. It is also set for locally
|
||||
synthesized data, such as <literal>localhost</literal> or data from
|
||||
<filename>/etc/hosts</filename>. Moreover, it is set for all LLMNR or mDNS RRs which originate from the
|
||||
local host. Applications that require authenticated RR data for operation should check this flag before
|
||||
trusting the data. Not that <filename>systmed-resolved</filename> will not return invalidated data in any case, hence this flag
|
||||
simply allows to discern the cases where data is known to be trustable, or where there is proof that
|
||||
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>
|
||||
|
||||
<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><varname>DNS</varname> contains an array containing all DNS servers currently used by
|
||||
<filename>systmed-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
|
||||
<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>
|
||||
|
||||
<para>Similarly, the <varname>Domains</varname> property contains an array containing all search and
|
||||
routing domains currently used by <filename>systmed-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>systmed-resolved</filename> has been processing. It contains a pair of unsigned 64-bit counters, the first
|
||||
containing the number of currently ongoing transactions, the second the number of total transactions
|
||||
<filename>systmed-resolved</filename> is processing or has processed. The latter value may be reset using the
|
||||
<function>ResetStatistics()</function> call described above. Note that the number of transaction does
|
||||
not directly map to the number of resolver bus calls issued. While simple look-ups usually require a
|
||||
single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC
|
||||
are in use.</para>
|
||||
|
||||
<para>The <varname>CacheStatistics</varname> property contains information about the executed cache
|
||||
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 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>
|
||||
|
||||
<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,
|
||||
and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and
|
||||
each non-existance proof. The secure counter is increased for each operation that successfully verified
|
||||
a signed reply, the insecure counter is increased for each operation that successfully verified that an
|
||||
unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the
|
||||
validation did not check out, and the data is likely to have been tempered with. Finally the
|
||||
indeterminate counter is increased for each operation which did not complete because the necessary keys
|
||||
could not be acquired or the cryptographic algorithms were unknown.</para>
|
||||
|
||||
<para>The <varname>DNSSECSupported</varname> boolean property reports whether DNSSEC is enabled and
|
||||
the selected DNS servers support it. It combines information about system-wide and per-link DNS
|
||||
settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for
|
||||
which DNS is configured and for the system-wide settings if there are any. Note that <filename>systmed-resolved</filename> assumes
|
||||
DNSSEC is supported by DNS servers until it verified that this is not the case. Thus, the reported
|
||||
value may initially be true, until the first transactions are executed.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Link Object</title>
|
||||
|
||||
<programlisting>
|
||||
$ gdbus introspect --system \
|
||||
--dest org.freedesktop.resolve1 \
|
||||
--object-path /org/freedesktop/resolve1/link/_34
|
||||
|
||||
node /org/freedesktop/resolve1/link/_34 {
|
||||
interface org.freedesktop.resolve1.Link {
|
||||
methods:
|
||||
SetDNS(in a(iay) arg_0);
|
||||
SetDomains(in a(sb) arg_0);
|
||||
SetLLMNR(in s arg_0);
|
||||
SetMulticastDNS(in s arg_0);
|
||||
SetDNSSEC(in s arg_0);
|
||||
SetDNSSECNegativeTrustAnchors(in as arg_0);
|
||||
Revert();
|
||||
signals:
|
||||
properties:
|
||||
readonly t ScopesMask = 6;
|
||||
readonly a(iay) DNS = [];
|
||||
readonly a(sb) Domains = [];
|
||||
readonly s LLMNR = 'yes';
|
||||
readonly s MulticastDNS = 'no';
|
||||
readonly s DNSSEC = '';
|
||||
readonly as DNSSECNegativeTrustAnchors = [];
|
||||
readonly b DNSSECSupported = true;
|
||||
};
|
||||
interface org.freedesktop.DBus.Peer {
|
||||
};
|
||||
interface org.freedesktop.DBus.Introspectable {
|
||||
};
|
||||
interface org.freedesktop.DBus.Properties {
|
||||
};
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
<para>For each Linux network interface a "Link" object is created, which exposes per-link DNS
|
||||
configuration and state. Use <function>GetLink()</function> on the Manager interface to retrieve the
|
||||
object path for a link object given the network interface index (see above).</para>
|
||||
|
||||
<refsect2>
|
||||
<title>Methods</title>
|
||||
|
||||
<para>The various methods exposed by the Link interface are equivalent to their similarly named
|
||||
counterparts on the Manager interface. e.g. <function>SetDNS()</function> on the Link object maps to
|
||||
<function>SetLinkDNS()</function> on the Manager object, the main difference being that the later
|
||||
expects an interface index to be speicified. Invoking the calls 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 calls see the
|
||||
Manager documentation above. </para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Properties</title>
|
||||
|
||||
<para><varname>ScopesMask</varname> defines which resolver scopes are currently active on this
|
||||
interface. This 64-bit unsigned integer field is a bit mask, consisting of a subset of the bits as the
|
||||
flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in
|
||||
IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific
|
||||
interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in
|
||||
"UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and
|
||||
has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR
|
||||
and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured*
|
||||
to be used on the interface, the former expose what is actually used on the interface, taking into
|
||||
account the abilities of the interface.</para>
|
||||
|
||||
<para><varname>DNSSECSupported</varname> exposes a boolean field that indicates whether DNSSEC is
|
||||
currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface it is
|
||||
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>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>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Common Errors</title>
|
||||
|
||||
<para>Many bus calls <filename>systmed-resolved</filename> exposes (in particular the resolver calls such
|
||||
as <function>ResolveHostname()</function> on the <interfacename>Manager</interfacename> interface) return
|
||||
some of the following errors:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.NoNameServers</constant></term>
|
||||
<listitem><para>No suitable DNS servers have been found to resolve a request.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.InvalidReply</constant></term>
|
||||
<listitem><para>A response from the selected DNS server could not be understood.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.NoSuchRR</constant></term>
|
||||
<listitem><para>The requested name exists, but there is no resource record of the requested type for
|
||||
it. (This is the DNS NODATA case).</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.CNameLoop</constant></term>
|
||||
<listitem><para>The look-up failed because a CNAME or DNAME loop was detected.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.Aborted</constant></term>
|
||||
<listitem><para>The look-up was aborted, because the selected protocol became unavailable while the
|
||||
operation was ongoing.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService</constant></term>
|
||||
<listitem><para>A service look-up was successful, but the SRV record reported that the service is not
|
||||
available.</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed</constant></term>
|
||||
<listitem><para>The acquired response did not pass DNSSEC validation.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.NoTrustAnchor</constant></term>
|
||||
<listitem><para>No chain of trust could be established for the response, to a configured DNSSEC trust
|
||||
anchor.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.ResourceRecordTypeUnsupported</constant></term>
|
||||
<listitem><para>The requested resource record type is not supported on the selected DNS servers. This
|
||||
error is generated for example when an RRSIG record is requested from a DNS server that does not
|
||||
support DNSSEC.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.NoSuchLink</constant></term>
|
||||
<listitem><para>No network interface with the specified network interface index exists.
|
||||
</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.LinkBusy</constant></term>
|
||||
<listitem><para>The requested configuration change can not be made, because
|
||||
<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||||
already took possession of the interface and supplied configuration data for it.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.NetworkDown</constant></term>
|
||||
<listitem><para>The requested look-up failed because the system is currently not connected to any
|
||||
suitable network.</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>org.freedesktop.resolve1.DnsError.NXDOMAIN</constant></term>
|
||||
<term><constant>org.freedesktop.resolve1.DnsError.REFUSED</constant></term>
|
||||
<term>...</term>
|
||||
<listitem><para>The look-up failed with a DNS return code reporting a failure. The error names used as
|
||||
suffixes here are defined in by IANA in
|
||||
<ulink url="https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6">DNS RCODEs</ulink>.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Versioning</title>
|
||||
|
||||
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
|
||||
the usual interface versioning guidelines</ulink>.</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
|
@ -49,6 +49,7 @@ manpages = [
|
|||
['org.freedesktop.locale1', '5', [], 'ENABLE_LOCALED'],
|
||||
['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'],
|
||||
['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'],
|
||||
['org.freedesktop.resolve1', '5', [], 'ENABLE_RESOLVE'],
|
||||
['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'],
|
||||
['os-release', '5', [], ''],
|
||||
['pam_systemd', '8', [], 'HAVE_PAM'],
|
||||
|
|
|
|||
|
|
@ -34,11 +34,12 @@
|
|||
resolver and 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="https://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 native, fully-featured API <command>systemd-resolved</command> exposes on the bus,
|
||||
see
|
||||
<citerefentry><refentrytitle>org.freedesktop.resolve1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
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 project='man-pages'><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry> API as defined
|
||||
|
|
|
|||
Loading…
Reference in New Issue