man/org.freedesktop.resolve1.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   5 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   6 %entities;
   7 ]>
   8 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   9
  10 <refentry id="org.freedesktop.resolve1" conditional='ENABLE_RESOLVE'
  11     xmlns:xi="http://www.w3.org/2001/XInclude">
  12   <refentryinfo>
  13     <title>org.freedesktop.resolve1</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>org.freedesktop.resolve1</refentrytitle>
  19     <manvolnum>5</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>org.freedesktop.resolve1</refname>
  24     <refpurpose>The D-Bus interface of systemd-resolved</refpurpose>
  25   </refnamediv>
  26
  27   <refsect1>
  28     <title>Introduction</title>
  29
  30     <para>
  31     <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  32     is a system service that provides hostname resolution and caching using DNS, LLMNR, and mDNS. It also
  33     does DNSSEC validation. This page describes the resolve semantics and the D-Bus interface.</para>
  34
  35     <para>This page contains an API reference only. If you are looking for a longer explanation how to use
  36     this API, please consult
  37     <ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers">
  38     Writing Network Configuration Managers</ulink> and
  39     <ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients">Writing Resolver
  40     Clients</ulink>.
  41     </para>
  42   </refsect1>
  43
  44   <refsect1>
  45     <title>The Manager Object</title>
  46
  47     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
  48
  49     <programlisting>
  50 $ gdbus introspect --system \
  51         --dest org.freedesktop.resolve1 \
  52         --object-path /org/freedesktop/resolve1
  53
  54 node /org/freedesktop/resolve1 {
  55   interface org.freedesktop.resolve1.Manager {
  56     methods:
  57       ResolveHostname(in  i ifindex,
  58                       in  s name,
  59                       in  i family,
  60                       in  t flags,
  61                       out a(iiay) addresses,
  62                       out s canonical,
  63                       out t flags);
  64       ResolveAddress(in  i ifindex,
  65                      in  i family,
  66                      in  ay address,
  67                      in  t flags,
  68                      out a(is) names,
  69                      out t flags);
  70       ResolveRecord(in  i ifindex,
  71                     in  s name,
  72                     in  q class,
  73                     in  q type,
  74                     in  t flags,
  75                     out a(iqqay) records,
  76                     out t flags);
  77       ResolveService(in  i ifindex,
  78                      in  s name,
  79                      in  s type,
  80                      in  s domain,
  81                      in  i family,
  82                      in  t flags,
  83                      out a(qqqsa(iiay)s) srv_data,
  84                      out aay txt_data,
  85                      out s canonical_name,
  86                      out s canonical_type,
  87                      out s canonical_domain,
  88                      out t flags);
  89       GetLink(in  i ifindex,
  90               out o path);
  91       SetLinkDNS(in  i ifindex,
  92                  in  a(iay) addresses);
  93       SetLinkDomains(in  i ifindex,
  94                      in  a(sb) domains);
  95       SetLinkDefaultRoute(in  i ifindex,
  96                           in  b enable);
  97       SetLinkLLMNR(in  i ifindex,
  98                    in  s mode);
  99       SetLinkMulticastDNS(in  i ifindex,
 100                           in  s mode);
 101       SetLinkDNSOverTLS(in  i ifindex,
 102                         in  s mode);
 103       SetLinkDNSSEC(in  i ifindex,
 104                     in  s mode);
 105       SetLinkDNSSECNegativeTrustAnchors(in  i ifindex,
 106                                         in  as names);
 107       RevertLink(in  i ifindex);
 108       RegisterService(in  s name,
 109                       in  s name_template,
 110                       in  s type,
 111                       in  q service_port,
 112                       in  q service_priority,
 113                       in  q serwise_weight,
 114                       in  aa{say} txt_datas,
 115                       out o service_path);
 116       UnregisterService(in  o service_path);
 117       ResetStatistics();
 118       FlushCaches();
 119       ResetServerFeatures();
 120     properties:
 121       readonly s LLMNRHostname = '...';
 122       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 123       readonly s LLMNR = '...';
 124       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 125       readonly s MulticastDNS = '...';
 126       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 127       readonly s DNSOverTLS = '...';
 128       readonly a(iiay) DNS = [...];
 129       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 130       readonly a(iiay) FallbackDNS = [...];
 131       readonly (iiay) CurrentDNSServer = ...;
 132       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 133       readonly a(isb) Domains = [...];
 134       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 135       readonly (tt) TransactionStatistics = ...;
 136       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 137       readonly (ttt) CacheStatistics = ...;
 138       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 139       readonly s DNSSEC = '...';
 140       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 141       readonly (tttt) DNSSECStatistics = ...;
 142       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 143       readonly b DNSSECSupported = ...;
 144       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 145       readonly as DNSSECNegativeTrustAnchors = ['...', ...];
 146       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 147       readonly s DNSStubListener = '...';
 148   };
 149   interface org.freedesktop.DBus.Peer { ... };
 150   interface org.freedesktop.DBus.Introspectable { ... };
 151   interface org.freedesktop.DBus.Properties { ... };
 152 };
 153     </programlisting>
 154
 155     <!--method SetLinkDefaultRoute is not documented!-->
 156
 157     <!--method SetLinkDNSOverTLS is not documented!-->
 158
 159     <!--method RegisterService is not documented!-->
 160
 161     <!--method UnregisterService is not documented!-->
 162
 163     <!--method FlushCaches is not documented!-->
 164
 165     <!--method ResetServerFeatures is not documented!-->
 166
 167     <!--property LLMNR is not documented!-->
 168
 169     <!--property MulticastDNS is not documented!-->
 170
 171     <!--property DNSOverTLS is not documented!-->
 172
 173     <!--property FallbackDNS is not documented!-->
 174
 175     <!--property CurrentDNSServer is not documented!-->
 176
 177     <!--property DNSSEC is not documented!-->
 178
 179     <!--property DNSSECNegativeTrustAnchors is not documented!-->
 180
 181     <!--property DNSStubListener is not documented!-->
 182
 183     <refsect2>
 184       <title>Methods</title>
 185
 186       <para><function>ResolveHostname()</function> takes a hostname and resolves it to one or more IP addresses.
 187       As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be
 188       done on any suitable interface. The <varname>name</varname> parameter specifies the hostname to
 189       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
 190       limits the results to a specific address family. It may be <constant>AF_INET</constant>,
 191       <constant>AF_INET6</constant> or <constant>AF_UNSPEC</constant>. If <constant>AF_UNSPEC</constant> is specified (recommended), both kinds are retrieved, subject
 192       to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is
 193       retrieved; and similarly for IPv4). A 64-bit <varname>flags</varname> field may be used to alter the
 194       behaviour of the resolver operation (see below). The method returns an array of address records. Each
 195       address record consists of the interface index the address belongs to, an address family as well as a
 196       byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address
 197       family). The returned address family will be one of <constant>AF_INET</constant> or
 198       <constant>AF_INET6</constant>. For IPv6, the returned address interface index should be used to
 199       initialize the .sin6_scope_id field of a <structname>struct sockaddr_in6</structname> instance to permit
 200       support for resolution to link-local IP addresses. The address array is followed by the canonical name
 201       of the host, which may or may not be identical to the resolved hostname. Finally, a 64-bit
 202       <varname>flags</varname> field is returned that is defined similarly to the <varname>flags</varname>
 203       field that was passed in, but contains information about the resolved data (see below). If the hostname
 204       passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In
 205       this case, no network communication is done.</para>
 206
 207       <para><function>ResolveAddress()</function> executes the reverse operation: it takes an IP address and
 208       acquires one or more hostnames for it. As parameters it takes the interface index to execute the query
 209       on, or <constant>0</constant> if all suitable interfaces are OK. The <varname>family</varname>
 210       parameter indicates the address family of the IP address to resolve. It may be either
 211       <constant>AF_INET</constant> or <constant>AF_INET6</constant>. The <varname>address</varname> parameter
 212       takes the raw IP address data (as either a 4 or 16 byte array). The <varname>flags</varname> input
 213       parameter may be used to alter the resolver operation (see below). The method returns an array of name
 214       records, each consisting of an interface index and a hostname.  The <varname>flags</varname> output
 215       field contains additional information about the resolver operation (see below).</para>
 216
 217       <para><function>ResolveRecord()</function> takes a DNS resource record (RR) type, class and name, and
 218       retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the
 219       Linux network interface index to execute the query on, or <constant>0</constant> if it may be done on
 220       any suitable interface. The <varname>name</varname> parameter specifies the RR domain name to look up
 221       (no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be
 222       ANY). Finally, a <varname>flags</varname> field may be passed in to alter behaviour of the look-up (see
 223       below). On completion, an array of RR items is returned. Each array entry consists of the network interface
 224       index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw
 225       RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed
 226       by the RR type, class, TTL and RDATA, in the binary format documented in
 227       <ulink url="https://www.ietf.org/rfc/rfc1035.txt">RFC 1035</ulink>. For RRs that support name
 228       compression in the payload (such as MX or PTR), the compression is expanded in the returned
 229       data.</para>
 230
 231       <para>Note that currently, the class field has to be specified as IN or ANY. Specifying a different
 232       class will return an error indicating that look-ups of this kind are unsupported. Similarly, some
 233       special types are not supported either (AXFR, OPT, …). While <filename>systemd-resolved</filename> parses and validates resource
 234       records of many types, it is crucial that clients using this API understand that the RR data originates
 235       from the network and should be thoroughly validated before use.</para>
 236
 237       <para><function>ResolveService()</function> may be used to resolve a DNS SRV service record, as well as the
 238       hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional
 239       service metadata. The primary benefit of using this method over <function>ResolveRecord()</function>
 240       specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced
 241       in the SRV in a single operation. As parameters it takes a Linux network interface index, a service
 242       name, a service type and a service domain. This method may be invoked in three different modes:</para>
 243
 244       <orderedlist>
 245         <listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
 246         Files</literal>), the service type (e.g. <literal>_webdav._tcp</literal>) and the domain to search in
 247         (e.g. <literal>local</literal>) as the three service parameters. The service name must be in UTF-8
 248         format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD
 249         specifications). However, if necessary, IDNA conversion is applied to the domain parameter.</para>
 250         </listitem>
 251
 252         <listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string
 253         and set the service type and domain properly. (IDNA conversion is applied to the domain, if
 254         necessary.)</para></listitem>
 255
 256         <listitem><para>Alternatively, leave both the service name and type empty and specify the full
 257         domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA
 258         coversion is applied in this mode.)</para></listitem>
 259       </orderedlist>
 260
 261       <para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
 262       the desired family of the addresses to resolve (use <constant>AF_INET</constant>,
 263       <constant>AF_INET6</constant>, or <constant>AF_UNSPEC</constant>). If this is enabled (Use the
 264       <constant>NO_ADDRESS</constant> flag to turn address resolution off, see below). The
 265       <varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
 266       operation.</para>
 267
 268       <para>On completion, <function>ResolveService()</function> returns an array of SRV record structures. Each
 269       items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV
 270       record. Immediately following is an array of the addresses of this hostname, with each item consisting
 271       of the interface index, the address family and the address data in a byte array. This address array is
 272       followed by the canonicalized hostname. After this array of SRV record structures an array of byte
 273       arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
 274       are the canonical service name, type and domain. This may or may not be identical to the parameters
 275       passed in. Finally, a <varname>flags</varname> field is returned that contains information about the
 276       resolver operation performed.</para>
 277
 278       <para>The <function>ResetStatistics()</function> method resets the various statistics counters that
 279       <filename>systemd-resolved</filename> maintains to zero. (For details, see the statistics properties below.)</para>
 280
 281       <para>The <function>GetLink()</function> method takes a network interface index and returns the object
 282       path to the <interfacename>org.freedesktop.resolve1.Link</interfacename> object corresponding to it.
 283       </para>
 284
 285       <para>The <function>SetLinkDNS()</function> method sets the DNS servers to use on a specific
 286       interface. This method (and the following ones) may be used by network management software to configure
 287       per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP
 288       address records. Each array item consists of an address family (either <constant>AF_INET</constant> or
 289       <constant>AF_INET6</constant>), followed by a 4-byte or 16-byte array with the raw address data. This
 290       method is a one-step shortcut for retrieving the Link object for a network interface using
 291       <function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> method
 292       (see below) on it.
 293       </para>
 294
 295       <para>Network management software integrating with <filename>systemd-resolved</filename> should
 296       call this method (and the five below) after the interface appeared in the kernel (and thus after a
 297       network interface index has been assigned), but before the network interfaces is activated
 298       (<constant>IFF_UP</constant> set) so that all settings take effect during the full time the network
 299       interface is up. It is safe to alter settings while the interface is up, however. Use
 300       <function>RevertLink()</function> (described below) to reset all per-interface settings.</para>
 301
 302       <para>The <function>SetLinkDomains()</function> method sets the search and routing domains to use on a
 303       specific network interface for DNS look-ups. It takes a network interface index and an array of domains,
 304       each with a boolean parameter indicating whether the specified domain shall be used as a search domain
 305       (false), or just as a routing domain (true). Search domains are used for qualifying single-label names into
 306       FQDN when looking up hostnames, as well as for making routing decisions on which interface to send
 307       queries ending in the domain to. Routing domains are only used for routing decisions and not used for single-label
 308       name qualification. Pass the search domains in the order they should be used.</para>
 309
 310       <para>The <function>SetLinkLLMNR()</function> method enables or disables LLMNR support on a specific
 311       network interface. It takes a network interface index as well as a string that may either be empty or one of
 312       <literal>yes</literal>, <literal>no</literal> or <literal>resolve</literal>. If empty, the systemd-wide
 313       default LLMNR setting is used. If <literal>yes</literal>, LLMNR is used for resolution of single-label
 314       names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If
 315       <literal>no</literal>, LLMNR is turned off fully on this interface. If <literal>resolve</literal>, LLMNR
 316       is only enabled for resolving names, but the local host name is not registered for other peers to
 317       use.</para>
 318
 319       <para>Similarly, the <function>SetLinkMulticastDNS()</function> method enables or disables MulticastDNS
 320       support on a specific interface. It takes the same parameters as <function>SetLinkLLMNR()</function>
 321       described above.</para>
 322
 323       <para>The <function>SetLinkDNSSEC()</function> method enables or disables DNSSEC validation on a
 324       specific network interface. It takes a network interface index as well as a string that may either be
 325       empty or one of <literal>yes</literal>, <literal>no</literal>, or <literal>allow-downgrade</literal>. When
 326       empty, the system-wide default DNSSEC setting is used. If <literal>yes</literal>, full DNSSEC validation
 327       is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this
 328       mode is used. If <literal>no</literal>, DNSSEC validation is fully disabled. If
 329       <literal>allow-downgrade</literal>, DNSSEC validation is enabled, but is turned off automatically if the
 330       selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC
 331       only applies to traditional DNS, not to LLMNR or MulticastDNS.</para>
 332
 333       <para>The <function>SetLinkDNSSECNegativeTrustAnchors()</function> method may be used to configure DNSSEC
 334       Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a
 335       list of domains as arguments.</para>
 336
 337       <para>The <function>RevertLink()</function> method may be used to revert all per-link settings done with
 338       the six methods described above to the defaults again.</para>
 339
 340       <refsect3>
 341         <title>The Flags Parameter</title>
 342
 343         <para>The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
 344         and recommended. However, the following flags are defined to alter the look-up:</para>
 345
 346         <programlisting>
 347 #define SD_RESOLVED_DNS           (UINT64_C(1) &lt;&lt; 0)
 348 #define SD_RESOLVED_LLMNR_IPV4    (UINT64_C(1) &lt;&lt; 1)
 349 #define SD_RESOLVED_LLMNR_IPV6    (UINT64_C(1) &lt;&lt; 2)
 350 #define SD_RESOLVED_MDNS_IPV4     (UINT64_C(1) &lt;&lt; 3)
 351 #define SD_RESOLVED_MDNS_IPV6     (UINT64_C(1) &lt;&lt; 4)
 352 #define SD_RESOLVED_NO_CNAME      (UINT64_C(1) &lt;&lt; 5)
 353 #define SD_RESOLVED_NO_TXT        (UINT64_C(1) &lt;&lt; 6)
 354 #define SD_RESOLVED_NO_ADDRESS    (UINT64_C(1) &lt;&lt; 7)
 355 #define SD_RESOLVED_NO_SEARCH     (UINT64_C(1) &lt;&lt; 8)
 356 #define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) &lt;&lt; 9)
 357         </programlisting>
 358
 359         <para>On input, the first five flags control the protocols to use for the look-up. They refer to
 360         classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
 361         IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the
 362         look-up will be done via all suitable protocols for the specific look-up. Note that these flags
 363         operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, <filename>systemd-resolved</filename>
 364         will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address
 365         domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route
 366         neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces
 367         suitable for multicast.</para>
 368
 369         <para>On output, these five flags indicate which protocol was used to execute the operation, and hence
 370         where the data was found.</para>
 371
 372         <para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
 373         earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
 374         used to discover the first DNS result.</para>
 375
 376         <para>The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the
 377         look-up. This flag is only available at input, none of the functions will return it on output. If a
 378         CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default,
 379         when the flag is off, CNAME/DNAME RRs are followed.</para>
 380
 381         <para>The NO_TXT and NO_ADDRESS flags only influence operation of the
 382         <function>ResolveService()</function> method. They are only defined for input, not output. If
 383         NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified,
 384         the hostnames discovered are not implicitly translated to their addresses.</para>
 385
 386         <para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
 387         <function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
 388         using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
 389         will never qualify single-label domain names using search domains. Also note that
 390         multi-label hostnames are never subject to search list expansion.</para>
 391
 392         <para>The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the
 393         returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data
 394         for which a full trust chain may be established to a trusted domain anchor. It is also set for locally
 395         synthesized data, such as <literal>localhost</literal> or data from
 396         <filename>/etc/hosts</filename>. Moreover, it is set for all LLMNR or mDNS RRs which originate from the
 397         local host. Applications that require authenticated RR data for operation should check this flag before
 398         trusting the data. Note that <filename>systemd-resolved</filename> will never return invalidated data, hence this flag
 399         simply allows to discern the cases where data is known to be trustable, or where there is proof that
 400         the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server
 401         does not support authenticating data).</para>
 402       </refsect3>
 403
 404   </refsect2>
 405
 406     <refsect2>
 407       <title>Properties</title>
 408
 409       <varname>LLMNRHostname</varname> contains the hostname currently exposed on the network via LLMNR. It
 410       usually follows the system hostname as may be queried via
 411       <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 412       but may differ if a conflict is detected on the network.
 413
 414       <para><varname>DNS</varname> contains an array of all DNS servers currently used by
 415       <filename>systemd-resolved</filename>. It contains similar information as the DNS server data written to
 416       /run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface
 417       index, an address family, and a byte array containing the DNS server address (either 4 bytes in length
 418       for IPv4 or 16 bytes in lengths for IPv6). The array contains DNS servers configured system-wide,
 419       including those possibly read from a foreign <filename>/etc/resolv.conf</filename> or the
 420       <varname>DNS=</varname> setting in <filename>/etc/systemd/resolved.conf</filename>, as well as
 421       per-interface DNS server information either retrieved from
 422       <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 423       or configured by external software via <function>SetLinkDNS()</function> (see above). The network
 424       interface index will be 0 for the system-wide configured services and non-zero for the per-link
 425       servers.</para>
 426
 427       <para>Similarly, the <varname>Domains</varname> property contains an array of all search and
 428       routing domains currently used by <filename>systemd-resolved</filename>. Each entry consists of a network interface index (again, 0
 429       encodes system-wide entries), the actual domain name, and whether the entry is used only for routing
 430       (true) or for both routing and searching (false).</para>
 431
 432       <para>The <varname>TransactionStatistics</varname> property contains information about the number of
 433       transactions <filename>systemd-resolved</filename> has processed. It contains a pair of unsigned 64-bit counters, the first
 434       containing the number of currently ongoing transactions, the second the number of total transactions
 435       <filename>systemd-resolved</filename> is processing or has processed. The latter value may be reset using the
 436       <function>ResetStatistics()</function> method described above. Note that the number of transactions does
 437       not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a
 438       single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC
 439       are in use.</para>
 440
 441       <para>The <varname>CacheStatistics</varname> property contains information about the executed cache
 442       operations so far. It exposes three 64-bit counters: the first being the total number of current cache
 443       entries (both positive and negative), the second the number of cache hits, and the third the number of
 444       cache misses. The latter counters may be reset using <function>ResetStatistics()</function> (see
 445       above). </para>
 446
 447       <para>The <varname>DNSSECStatistics</varname> property contains information about the DNSSEC
 448       validations executed so far. It contains four 64-bit counters: the number of secure, insecure, bogus,
 449       and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and
 450       each non-existance proof. The secure counter is increased for each operation that successfully verified
 451       a signed reply, the insecure counter is increased for each operation that successfully verified that an
 452       unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the
 453       validation did not check out and the data is likely to have been tempered with. Finally the
 454       indeterminate counter is increased for each operation which did not complete because the necessary keys
 455       could not be acquired or the cryptographic algorithms were unknown.</para>
 456
 457       <para>The <varname>DNSSECSupported</varname> boolean property reports whether DNSSEC is enabled and
 458       the selected DNS servers support it. It combines information about system-wide and per-link DNS
 459       settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for
 460       which DNS is configured and for the system-wide settings if there are any. Note that <filename>systemd-resolved</filename> assumes
 461       DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported
 462       value may initially be true, until the first transactions are executed.</para>
 463     </refsect2>
 464   </refsect1>
 465
 466   <refsect1>
 467     <title>Link Object</title>
 468
 469     <programlisting>
 470 $ gdbus introspect --system \
 471         --dest org.freedesktop.resolve1 \
 472         --object-path /org/freedesktop/resolve1/link/_34
 473
 474 node /org/freedesktop/resolve1/link/_34 {
 475   interface org.freedesktop.resolve1.Link {
 476     methods:
 477       SetDNS(in  a(iay) addresses);
 478       SetDomains(in  a(sb) domains);
 479       SetDefaultRoute(in  b enable);
 480       SetLLMNR(in  s mode);
 481       SetMulticastDNS(in  s mode);
 482       SetDNSOverTLS(in  s mode);
 483       SetDNSSEC(in  s mode);
 484       SetDNSSECNegativeTrustAnchors(in  as names);
 485       Revert();
 486     properties:
 487       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 488       readonly t ScopesMask = ...;
 489       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 490       readonly a(iay) DNS = [...];
 491       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 492       readonly (iay) CurrentDNSServer = ...;
 493       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 494       readonly a(sb) Domains = [...];
 495       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 496       readonly b DefaultRoute = ...;
 497       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 498       readonly s LLMNR = '...';
 499       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 500       readonly s MulticastDNS = '...';
 501       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 502       readonly s DNSOverTLS = '...';
 503       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 504       readonly s DNSSEC = '...';
 505       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 506       readonly as DNSSECNegativeTrustAnchors = ['...', ...];
 507       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 508       readonly b DNSSECSupported = ...;
 509   };
 510   interface org.freedesktop.DBus.Peer { ... };
 511   interface org.freedesktop.DBus.Introspectable { ... };
 512   interface org.freedesktop.DBus.Properties { ... };
 513 };
 514     </programlisting>
 515
 516     <!--method SetDomains is not documented!-->
 517
 518     <!--method SetDefaultRoute is not documented!-->
 519
 520     <!--method SetLLMNR is not documented!-->
 521
 522     <!--method SetMulticastDNS is not documented!-->
 523
 524     <!--method SetDNSOverTLS is not documented!-->
 525
 526     <!--method SetDNSSEC is not documented!-->
 527
 528     <!--method SetDNSSECNegativeTrustAnchors is not documented!-->
 529
 530     <!--method Revert is not documented!-->
 531
 532     <!--property CurrentDNSServer is not documented!-->
 533
 534     <!--property DefaultRoute is not documented!-->
 535
 536     <!--property LLMNR is not documented!-->
 537
 538     <!--property MulticastDNS is not documented!-->
 539
 540     <!--property DNSOverTLS is not documented!-->
 541
 542     <!--property DNSSEC is not documented!-->
 543
 544     <!--property DNSSECNegativeTrustAnchors is not documented!-->
 545
 546     <para>For each Linux network interface a "Link" object is created which exposes per-link DNS
 547     configuration and state. Use <function>GetLink()</function> on the Manager interface to retrieve the
 548     object path for a link object given the network interface index (see above).</para>
 549
 550     <refsect2>
 551       <title>Methods</title>
 552
 553       <para>The various methods exposed by the Link interface are equivalent to their similarly named
 554       counterparts on the Manager interface. e.g. <function>SetDNS()</function> on the Link object maps to
 555       <function>SetLinkDNS()</function> on the Manager object, the main difference being that the later
 556       expects an interface index to be specified. Invoking the methods on the Manager interface has the
 557       benefit of reducing roundtrips, as it is not necessary to first request the Link object path via
 558       <function>GetLink()</function> before invoking the methods. For further details on these methods see
 559       the <interfacename>Manager</interfacename> documentation above.</para>
 560     </refsect2>
 561
 562     <refsect2>
 563       <title>Properties</title>
 564
 565       <para><varname>ScopesMask</varname> defines which resolver scopes are currently active on this
 566       interface. This 64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the
 567       flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in
 568       IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific
 569       interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in
 570       the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and
 571       has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR
 572       and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured*
 573       to be used on the interface, the former expose what is actually used on the interface, taking into
 574       account the abilities of the interface.</para>
 575
 576       <para><varname>DNSSECSupported</varname> exposes a boolean field that indicates whether DNSSEC is
 577       currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is
 578       assumed available until it is detected that the configured server does not actually support it. Thus,
 579       this property may initially report that DNSSEC is supported on an interface.</para>
 580
 581       <para>The other properties reflect the state of the various configuration settings for the link which
 582       may be set with the various methods calls such as SetDNS() or SetLLMNR().</para>
 583     </refsect2>
 584   </refsect1>
 585
 586   <refsect1>
 587     <title>Common Errors</title>
 588
 589     <para>Many bus methods <filename>systemd-resolved</filename> exposes (in particular the resolver methods such
 590     as <function>ResolveHostname()</function> on the <interfacename>Manager</interfacename> interface) may return
 591     some of the following errors:</para>
 592
 593     <variablelist>
 594       <varlistentry><term><constant>org.freedesktop.resolve1.NoNameServers</constant></term>
 595       <listitem><para>No suitable DNS servers were found to resolve a request.</para></listitem>
 596       </varlistentry>
 597
 598       <varlistentry><term><constant>org.freedesktop.resolve1.InvalidReply</constant></term>
 599       <listitem><para>A response from the selected DNS server was not understood.</para></listitem>
 600       </varlistentry>
 601
 602       <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchRR</constant></term>
 603       <listitem><para>The requested name exists, but there is no resource record of the requested type for
 604       it. (This is the DNS NODATA case).</para></listitem></varlistentry>
 605
 606       <varlistentry><term><constant>org.freedesktop.resolve1.CNameLoop</constant></term>
 607       <listitem><para>The look-up failed because a CNAME or DNAME loop was detected.</para></listitem>
 608       </varlistentry>
 609
 610       <varlistentry><term><constant>org.freedesktop.resolve1.Aborted</constant></term>
 611       <listitem><para>The look-up was aborted because the selected protocol became unavailable while the
 612       operation was ongoing.</para></listitem>
 613       </varlistentry>
 614
 615       <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService</constant></term>
 616       <listitem><para>A service look-up was successful, but the SRV record reported that the service is not
 617       available.</para></listitem></varlistentry>
 618
 619       <varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed</constant></term>
 620       <listitem><para>The acquired response did not pass DNSSEC validation.</para></listitem>
 621       </varlistentry>
 622
 623       <varlistentry><term><constant>org.freedesktop.resolve1.NoTrustAnchor</constant></term>
 624       <listitem><para>No chain of trust could be established for the response to a configured DNSSEC trust
 625       anchor.</para></listitem>
 626       </varlistentry>
 627
 628       <varlistentry><term><constant>org.freedesktop.resolve1.ResourceRecordTypeUnsupported</constant></term>
 629       <listitem><para>The requested resource record type is not supported on the selected DNS servers. This
 630       error is generated for example when an RRSIG record is requested from a DNS server that does not
 631       support DNSSEC.</para></listitem>
 632
 633       </varlistentry>
 634
 635       <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchLink</constant></term>
 636       <listitem><para>No network interface with the specified network interface index exists.
 637       </para></listitem></varlistentry>
 638
 639       <varlistentry><term><constant>org.freedesktop.resolve1.LinkBusy</constant></term>
 640       <listitem><para>The requested configuration change could not be made because
 641       <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 642       already took possession of the interface and supplied configuration data for it.</para></listitem>
 643       </varlistentry>
 644
 645       <varlistentry><term><constant>org.freedesktop.resolve1.NetworkDown</constant></term>
 646       <listitem><para>The requested look-up failed because the system is currently not connected to any
 647       suitable network.</para></listitem></varlistentry>
 648
 649       <varlistentry><term><constant>org.freedesktop.resolve1.DnsError.NXDOMAIN</constant></term>
 650       <term><constant>org.freedesktop.resolve1.DnsError.REFUSED</constant></term>
 651       <term>...</term>
 652       <listitem><para>The look-up failed with a DNS return code reporting a failure. The error names used as
 653       suffixes here are defined in by IANA in
 654       <ulink url="https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6">DNS RCODEs</ulink>.
 655       </para></listitem>
 656       </varlistentry>
 657     </variablelist>
 658   </refsect1>
 659
 660   <refsect1>
 661     <title>Versioning</title>
 662
 663     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
 664     the usual interface versioning guidelines</ulink>.</para>
 665   </refsect1>
 666 </refentry>