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