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.5/docbookx.dtd" [
   5 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   6 %entities;
   7 ]>
   8 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   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 executable="systemd-resolved" node="/org/freedesktop/resolve1" interface="org.freedesktop.resolve1.Manager">
  50 node /org/freedesktop/resolve1 {
  51   interface org.freedesktop.resolve1.Manager {
  52     methods:
  53       ResolveHostname(in  i ifindex,
  54                       in  s name,
  55                       in  i family,
  56                       in  t flags,
  57                       out a(iiay) addresses,
  58                       out s canonical,
  59                       out t flags);
  60       ResolveAddress(in  i ifindex,
  61                      in  i family,
  62                      in  ay address,
  63                      in  t flags,
  64                      out a(is) names,
  65                      out t flags);
  66       ResolveRecord(in  i ifindex,
  67                     in  s name,
  68                     in  q class,
  69                     in  q type,
  70                     in  t flags,
  71                     out a(iqqay) records,
  72                     out t flags);
  73       ResolveService(in  i ifindex,
  74                      in  s name,
  75                      in  s type,
  76                      in  s domain,
  77                      in  i family,
  78                      in  t flags,
  79                      out a(qqqsa(iiay)s) srv_data,
  80                      out aay txt_data,
  81                      out s canonical_name,
  82                      out s canonical_type,
  83                      out s canonical_domain,
  84                      out t flags);
  85       GetLink(in  i ifindex,
  86               out o path);
  87       SetLinkDNS(in  i ifindex,
  88                  in  a(iay) addresses);
  89       SetLinkDNSEx(in  i ifindex,
  90                    in  a(iayqs) addresses);
  91       SetLinkDomains(in  i ifindex,
  92                      in  a(sb) domains);
  93       SetLinkDefaultRoute(in  i ifindex,
  94                           in  b enable);
  95       SetLinkLLMNR(in  i ifindex,
  96                    in  s mode);
  97       SetLinkMulticastDNS(in  i ifindex,
  98                           in  s mode);
  99       SetLinkDNSOverTLS(in  i ifindex,
 100                         in  s mode);
 101       SetLinkDNSSEC(in  i ifindex,
 102                     in  s mode);
 103       SetLinkDNSSECNegativeTrustAnchors(in  i ifindex,
 104                                         in  as names);
 105       RevertLink(in  i ifindex);
 106       RegisterService(in  s id,
 107                       in  s name_template,
 108                       in  s type,
 109                       in  q service_port,
 110                       in  q service_priority,
 111                       in  q service_weight,
 112                       in  aa{say} txt_datas,
 113                       out o service_path);
 114       UnregisterService(in  o service_path);
 115       ResetStatistics();
 116       FlushCaches();
 117       ResetServerFeatures();
 118     properties:
 119       readonly s LLMNRHostname = '...';
 120       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 121       readonly s LLMNR = '...';
 122       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 123       readonly s MulticastDNS = '...';
 124       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 125       readonly s DNSOverTLS = '...';
 126       readonly a(iiay) DNS = [...];
 127       readonly a(iiayqs) DNSEx = [...];
 128       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 129       readonly a(iiay) FallbackDNS = [...];
 130       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 131       readonly a(iiayqs) FallbackDNSEx = [...];
 132       readonly (iiay) CurrentDNSServer = ...;
 133       readonly (iiayqs) CurrentDNSServerEx = ...;
 134       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 135       readonly a(isb) Domains = [...];
 136       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 137       readonly (tt) TransactionStatistics = ...;
 138       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 139       readonly (ttt) CacheStatistics = ...;
 140       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 141       readonly s DNSSEC = '...';
 142       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 143       readonly (tttt) DNSSECStatistics = ...;
 144       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 145       readonly b DNSSECSupported = ...;
 146       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 147       readonly as DNSSECNegativeTrustAnchors = ['...', ...];
 148       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 149       readonly s DNSStubListener = '...';
 150       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 151       readonly s ResolvConfMode = '...';
 152   };
 153   interface org.freedesktop.DBus.Peer { ... };
 154   interface org.freedesktop.DBus.Introspectable { ... };
 155   interface org.freedesktop.DBus.Properties { ... };
 156 };
 157 </programlisting>
 158
 159     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 160
 161     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>
 162
 163     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>
 164
 165     <variablelist class="dbus-method" generated="True" extra-ref="ResolveHostname()"/>
 166
 167     <variablelist class="dbus-method" generated="True" extra-ref="ResolveAddress()"/>
 168
 169     <variablelist class="dbus-method" generated="True" extra-ref="ResolveRecord()"/>
 170
 171     <variablelist class="dbus-method" generated="True" extra-ref="ResolveService()"/>
 172
 173     <variablelist class="dbus-method" generated="True" extra-ref="GetLink()"/>
 174
 175     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNS()"/>
 176
 177     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSEx()"/>
 178
 179     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDomains()"/>
 180
 181     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDefaultRoute()"/>
 182
 183     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkLLMNR()"/>
 184
 185     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkMulticastDNS()"/>
 186
 187     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSOverTLS()"/>
 188
 189     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSEC()"/>
 190
 191     <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSECNegativeTrustAnchors()"/>
 192
 193     <variablelist class="dbus-method" generated="True" extra-ref="RevertLink()"/>
 194
 195     <variablelist class="dbus-method" generated="True" extra-ref="RegisterService()"/>
 196
 197     <variablelist class="dbus-method" generated="True" extra-ref="UnregisterService()"/>
 198
 199     <variablelist class="dbus-method" generated="True" extra-ref="ResetStatistics()"/>
 200
 201     <variablelist class="dbus-method" generated="True" extra-ref="FlushCaches()"/>
 202
 203     <variablelist class="dbus-method" generated="True" extra-ref="ResetServerFeatures()"/>
 204
 205     <variablelist class="dbus-property" generated="True" extra-ref="LLMNRHostname"/>
 206
 207     <variablelist class="dbus-property" generated="True" extra-ref="LLMNR"/>
 208
 209     <variablelist class="dbus-property" generated="True" extra-ref="MulticastDNS"/>
 210
 211     <variablelist class="dbus-property" generated="True" extra-ref="DNSOverTLS"/>
 212
 213     <variablelist class="dbus-property" generated="True" extra-ref="DNS"/>
 214
 215     <variablelist class="dbus-property" generated="True" extra-ref="DNSEx"/>
 216
 217     <variablelist class="dbus-property" generated="True" extra-ref="FallbackDNS"/>
 218
 219     <variablelist class="dbus-property" generated="True" extra-ref="FallbackDNSEx"/>
 220
 221     <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServer"/>
 222
 223     <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServerEx"/>
 224
 225     <variablelist class="dbus-property" generated="True" extra-ref="Domains"/>
 226
 227     <variablelist class="dbus-property" generated="True" extra-ref="TransactionStatistics"/>
 228
 229     <variablelist class="dbus-property" generated="True" extra-ref="CacheStatistics"/>
 230
 231     <variablelist class="dbus-property" generated="True" extra-ref="DNSSEC"/>
 232
 233     <variablelist class="dbus-property" generated="True" extra-ref="DNSSECStatistics"/>
 234
 235     <variablelist class="dbus-property" generated="True" extra-ref="DNSSECSupported"/>
 236
 237     <variablelist class="dbus-property" generated="True" extra-ref="DNSSECNegativeTrustAnchors"/>
 238
 239     <variablelist class="dbus-property" generated="True" extra-ref="DNSStubListener"/>
 240
 241     <variablelist class="dbus-property" generated="True" extra-ref="ResolvConfMode"/>
 242
 243     <!--End of Autogenerated section-->
 244
 245     <refsect2>
 246       <title>Methods</title>
 247
 248       <para><function>ResolveHostname()</function> takes a hostname and resolves it to one or more IP
 249       addresses.  As parameters it takes the Linux network interface index to execute the query on, or 0 if
 250       it may be done on any suitable interface. The <varname>name</varname> parameter specifies the hostname
 251       to resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via
 252       LLMNR or MulticastDNS. The <varname>family</varname> parameter limits the results to a specific address
 253       family. It may be <constant>AF_INET</constant>, <constant>AF_INET6</constant> or
 254       <constant>AF_UNSPEC</constant>. If <constant>AF_UNSPEC</constant> is specified (recommended), both
 255       kinds are retrieved, subject to local network configuration (i.e. if no local, routable IPv6 address is
 256       found, no IPv6 address is retrieved; and similarly for IPv4). A 64-bit <varname>flags</varname> field
 257       may be used to alter the behaviour of the resolver operation (see below). The method returns an array
 258       of address records. Each address record consists of the interface index the address belongs to, an
 259       address family as well as a byte array with the actual IP address data (which either has 4 or 16
 260       elements, depending on the address family). The returned address family will be one of
 261       <constant>AF_INET</constant> or <constant>AF_INET6</constant>. For IPv6, the returned address interface
 262       index should be used to initialize the .sin6_scope_id field of a
 263       <structname>struct sockaddr_in6</structname> instance to permit support for resolution to link-local IP
 264       addresses. The address array is followed by the canonical name of the host, which may or may not be
 265       identical to the resolved hostname. Finally, a 64-bit <varname>flags</varname> field is returned that
 266       is defined similarly to the <varname>flags</varname> field that was passed in, but contains information
 267       about the resolved data (see below). If the hostname passed in is an IPv4 or IPv6 address formatted as
 268       string, it is parsed, and the result is returned. In this case, no network communication is
 269       done.</para>
 270
 271       <para><function>ResolveAddress()</function> executes the reverse operation: it takes an IP address and
 272       acquires one or more hostnames for it. As parameters it takes the interface index to execute the query
 273       on, or <constant>0</constant> if all suitable interfaces are OK. The <varname>family</varname>
 274       parameter indicates the address family of the IP address to resolve. It may be either
 275       <constant>AF_INET</constant> or <constant>AF_INET6</constant>. The <varname>address</varname> parameter
 276       takes the raw IP address data (as either a 4 or 16 byte array). The <varname>flags</varname> input
 277       parameter may be used to alter the resolver operation (see below). The method returns an array of name
 278       records, each consisting of an interface index and a hostname.  The <varname>flags</varname> output
 279       field contains additional information about the resolver operation (see below).</para>
 280
 281       <para><function>ResolveRecord()</function> takes a DNS resource record (RR) type, class and name, and
 282       retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the
 283       Linux network interface index to execute the query on, or <constant>0</constant> if it may be done on
 284       any suitable interface. The <varname>name</varname> parameter specifies the RR domain name to look up
 285       (no IDNA conversion is applied), followed by the 16-bit class and type fields (which may be
 286       ANY). Finally, a <varname>flags</varname> field may be passed in to alter behaviour of the look-up (see
 287       below). On completion, an array of RR items is returned. Each array entry consists of the network interface
 288       index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw
 289       RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed
 290       by the RR type, class, TTL and RDATA, in the binary format documented in
 291       <ulink url="https://www.ietf.org/rfc/rfc1035.txt">RFC 1035</ulink>. For RRs that support name
 292       compression in the payload (such as MX or PTR), the compression is expanded in the returned
 293       data.</para>
 294
 295       <para>Note that currently, the class field has to be specified as IN or ANY. Specifying a different
 296       class will return an error indicating that look-ups of this kind are unsupported. Similarly, some
 297       special types are not supported either (AXFR, OPT, …). While <filename>systemd-resolved</filename> parses and validates resource
 298       records of many types, it is crucial that clients using this API understand that the RR data originates
 299       from the network and should be thoroughly validated before use.</para>
 300
 301       <para><function>ResolveService()</function> may be used to resolve a DNS
 302       <constant class="dns">SRV</constant> service record, as well as the hostnames referenced in it, and
 303       possibly an accompanying DNS-SD <constant class="dns">TXT</constant> record containing additional
 304       service metadata.  The primary benefit of using this method over <function>ResolveRecord()</function>
 305       specifying the <constant class="dns">SRV</constant> type is that it will resolve the
 306       <constant class="dns">SRV</constant> and <constant class="dns">TXT</constant> RRs as well as the
 307       hostnames referenced in the SRV in a single operation. As parameters it takes a Linux network interface
 308       index, a service name, a service type and a service domain. This method may be invoked in three
 309       different modes:</para>
 310
 311       <orderedlist>
 312         <listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
 313         Files</literal>), the service type (e.g. <literal>_webdav._tcp</literal>) and the domain to search in
 314         (e.g. <literal>local</literal>) as the three service parameters. The service name must be in UTF-8
 315         format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD
 316         specifications). However, if necessary, IDNA conversion is applied to the domain parameter.</para>
 317         </listitem>
 318
 319         <listitem><para>To resolve a plain <constant class="dns">SRV</constant> record, set the service name
 320         parameter to the empty string and set the service type and domain properly. (IDNA conversion is
 321         applied to the domain, if necessary.)</para></listitem>
 322
 323         <listitem><para>Alternatively, leave both the service name and type empty and specify the full domain
 324         name of the <constant class="dns">SRV</constant> record (i.e. prefixed with the service type) in the
 325         domain parameter. (No IDNA conversion is applied in this mode.)</para></listitem>
 326       </orderedlist>
 327
 328       <para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
 329       the desired family of the addresses to resolve (use <constant>AF_INET</constant>,
 330       <constant>AF_INET6</constant>, or <constant>AF_UNSPEC</constant>). If this is enabled (Use the
 331       <constant>NO_ADDRESS</constant> flag to turn address resolution off, see below). The
 332       <varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
 333       operation.</para>
 334
 335       <para>On completion, <function>ResolveService()</function> returns an array of
 336       <constant class="dns">SRV</constant> record structures. Each items consisting of the priority, weight and port
 337       fields as well as the hostname to contact, as encoded in the <constant class="dns">SRV</constant>
 338       record. Immediately following is an array of the addresses of this hostname, with each item consisting
 339       of the interface index, the address family and the address data in a byte array. This address array is
 340       followed by the canonicalized hostname. After this array of <constant class="dns">SRV</constant> record
 341       structures an array of byte arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are
 342       enabled. The next parameters are the canonical service name, type and domain. This may or may not be
 343       identical to the parameters passed in. Finally, a <varname>flags</varname> field is returned that
 344       contains information about the resolver operation performed.</para>
 345
 346       <para>The <function>ResetStatistics()</function> method resets the various statistics counters that
 347       <filename>systemd-resolved</filename> maintains to zero. (For details, see the statistics properties below.)</para>
 348
 349       <para>The <function>GetLink()</function> method takes a network interface index and returns the object
 350       path to the <interfacename>org.freedesktop.resolve1.Link</interfacename> object corresponding to it.
 351       </para>
 352
 353       <para>The <function>SetLinkDNS()</function> method sets the DNS servers to use on a specific
 354       interface. This method (and the following ones) may be used by network management software to configure
 355       per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP
 356       address records. Each array item consists of an address family (either <constant>AF_INET</constant> or
 357       <constant>AF_INET6</constant>), followed by a 4-byte or 16-byte array with the raw address data. This
 358       method is a one-step shortcut for retrieving the Link object for a network interface using
 359       <function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> method
 360       (see below) on it.</para>
 361
 362       <para><function>SetLinkDNSEx()</function> is similar to <function>SetLinkDNS()</function>, but allows
 363       an IP port (instead of the default 53) and DNS name to be specified for each DNS server. The server
 364       name is used for Server Name Indication (SNI), which is useful when DNS-over-TLS is
 365       used. C.f. <varname>DNS=</varname> in
 366       <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 367       </para>
 368
 369       <para><function>SetLinkDefaultRoute()</function> specifies whether the link shall be used as the
 370       default route for name queries. See the description of name routing in
 371       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 372       for details.</para>
 373
 374       <para>The <function>SetLinkDomains()</function> method sets the search and routing domains to use on a
 375       specific network interface for DNS look-ups. It takes a network interface index and an array of domains,
 376       each with a boolean parameter indicating whether the specified domain shall be used as a search domain
 377       (false), or just as a routing domain (true). Search domains are used for qualifying single-label names into
 378       FQDN when looking up hostnames, as well as for making routing decisions on which interface to send
 379       queries ending in the domain to. Routing domains are only used for routing decisions and not used for single-label
 380       name qualification. Pass the search domains in the order they should be used.</para>
 381
 382       <para>The <function>SetLinkLLMNR()</function> method enables or disables LLMNR support on a specific
 383       network interface. It takes a network interface index as well as a string that may either be empty or one of
 384       <literal>yes</literal>, <literal>no</literal> or <literal>resolve</literal>. If empty, the systemd-wide
 385       default LLMNR setting is used. If <literal>yes</literal>, LLMNR is used for resolution of single-label
 386       names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If
 387       <literal>no</literal>, LLMNR is turned off fully on this interface. If <literal>resolve</literal>, LLMNR
 388       is only enabled for resolving names, but the local hostname is not registered for other peers to
 389       use.</para>
 390
 391       <para>Similarly, the <function>SetLinkMulticastDNS()</function> method enables or disables MulticastDNS
 392       support on a specific interface. It takes the same parameters as <function>SetLinkLLMNR()</function>
 393       described above.</para>
 394
 395       <para>The <function>SetLinkDNSSEC()</function> method enables or disables DNSSEC validation on a
 396       specific network interface. It takes a network interface index as well as a string that may either be
 397       empty or one of <literal>yes</literal>, <literal>no</literal>, or <literal>allow-downgrade</literal>. When
 398       empty, the system-wide default DNSSEC setting is used. If <literal>yes</literal>, full DNSSEC validation
 399       is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this
 400       mode is used. If <literal>no</literal>, DNSSEC validation is fully disabled. If
 401       <literal>allow-downgrade</literal>, DNSSEC validation is enabled, but is turned off automatically if the
 402       selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC
 403       only applies to traditional DNS, not to LLMNR or MulticastDNS.</para>
 404
 405       <para>The <function>SetLinkDNSSECNegativeTrustAnchors()</function> method may be used to configure DNSSEC
 406       Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a
 407       list of domains as arguments.</para>
 408
 409       <para>The <function>SetLinkDNSOverTLS()</function> method enables or disables DNS-over-TLS.
 410       C.f. <varname>DNSOverTLS=</varname> in
 411       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 412       for details.</para>
 413
 414       <para>Network management software integrating with <filename>systemd-resolved</filename> should call
 415       <function>SetLinkDNS()</function> or <function>SetLinkDNSEx()</function>,
 416       <function>SetLinkDefaultRoute()</function>, <function>SetLinkDomains()</function> and others after the
 417       interface appeared in the kernel (and thus after a network interface index has been assigned), but
 418       before the network interfaces is activated (<constant>IFF_UP</constant> set) so that all settings take
 419       effect during the full time the network interface is up. It is safe to alter settings while the
 420       interface is up, however. Use <function>RevertLink()</function> (described below) to reset all
 421       per-interface settings.</para>
 422
 423       <para>The <function>RevertLink()</function> method may be used to revert all per-link settings
 424       described above to the defaults.</para>
 425
 426       <para>The <function>FlushCaches()</function> flushes all resource record caches maintained by the
 427       resolver, and ensures that any subsequent lookups re-request their responses from their sources.</para>
 428
 429       <para>The <function>ResetServerFeatures()</function> flushes any feature information learned about
 430       remote DNS servers. This ensures that subsequent lookups will be initially attempted at the highest DNS
 431       protocol feature level again, possibly requiring a (potentially slow) downgrade cycle to recognize the
 432       supported feature level again.</para>
 433
 434       <para>The <function>RegisterService()</function> method may be used to register a DNS-SD service on the
 435       host. This functionality is closely related to the functionality provided by
 436       <citerefentry><refentrytitle>systemd.dnssd</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 437       files. It takes a server identifier string as first parameter (this is just a local identifier, and
 438       should be chosen so that it neither collides with the basename of <filename>*.dnssd</filename> files
 439       nor with names chosen by other IPC clients). It also takes a name template string for the DNS-SD
 440       service name visible on the network. This string is subject to specifier expansation, as documented for
 441       the <varname>Name=</varname> setting in <filename>*.dnssd</filename> files. It also takes a service
 442       type string containing the DNS-SD service type, as well as an IP port, a priority/weight pair for the
 443       DNS-SD SRV record. Finally, it takes an array of TXT record data. It returns an object path which may be
 444       used as handle to the registered service.</para>
 445
 446       <para>The <function>UnregisterService()</function> method undoes the effect of
 447       <function>RegisterService()</function> and deletes a DNS-SD service previously created via IPC
 448       again.</para>
 449
 450       <refsect3>
 451         <title>The Flags Parameter</title>
 452
 453         <para>The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
 454         and recommended. However, the following flags are defined to alter the look-up:</para>
 455
 456         <programlisting>/* Input+Output: Protocol/scope */
 457 #define SD_RESOLVED_DNS                (UINT64_C(1) &lt;&lt;  0)
 458 #define SD_RESOLVED_LLMNR_IPV4         (UINT64_C(1) &lt;&lt;  1)
 459 #define SD_RESOLVED_LLMNR_IPV6         (UINT64_C(1) &lt;&lt;  2)
 460 #define SD_RESOLVED_MDNS_IPV4          (UINT64_C(1) &lt;&lt;  3)
 461 #define SD_RESOLVED_MDNS_IPV6          (UINT64_C(1) &lt;&lt;  4)
 462
 463 /* Input: Restrictions */
 464 #define SD_RESOLVED_NO_CNAME           (UINT64_C(1) &lt;&lt;  5)
 465 #define SD_RESOLVED_NO_TXT             (UINT64_C(1) &lt;&lt;  6)
 466 #define SD_RESOLVED_NO_ADDRESS         (UINT64_C(1) &lt;&lt;  7)
 467 #define SD_RESOLVED_NO_SEARCH          (UINT64_C(1) &lt;&lt;  8)
 468 #define SD_RESOLVED_NO_VALIDATE        (UINT64_C(1) &lt;&lt; 10)
 469 #define SD_RESOLVED_NO_SYNTHESIZE      (UINT64_C(1) &lt;&lt; 11)
 470 #define SD_RESOLVED_NO_CACHE           (UINT64_C(1) &lt;&lt; 12)
 471 #define SD_RESOLVED_NO_ZONE            (UINT64_C(1) &lt;&lt; 13)
 472 #define SD_RESOLVED_NO_TRUST_ANCHOR    (UINT64_C(1) &lt;&lt; 14)
 473 #define SD_RESOLVED_NO_NETWORK         (UINT64_C(1) &lt;&lt; 15)
 474 #define SD_RESOLVED_NO_STALE           (UINT64_C(1) &lt;&lt; 24)
 475 #define SD_RESOLVED_RELAX_SINGLE_LABEL (UINT64_C(1) &lt;&lt; 25)
 476
 477 /* Output: Security */
 478 #define SD_RESOLVED_AUTHENTICATED      (UINT64_C(1) &lt;&lt;  9)
 479 #define SD_RESOLVED_CONFIDENTIAL       (UINT64_C(1) &lt;&lt; 18)
 480
 481 /* Output: Origin */
 482 #define SD_RESOLVED_SYNTHETIC          (UINT64_C(1) &lt;&lt; 19)
 483 #define SD_RESOLVED_FROM_CACHE         (UINT64_C(1) &lt;&lt; 20)
 484 #define SD_RESOLVED_FROM_ZONE          (UINT64_C(1) &lt;&lt; 21)
 485 #define SD_RESOLVED_FROM_TRUST_ANCHOR  (UINT64_C(1) &lt;&lt; 22)
 486 #define SD_RESOLVED_FROM_NETWORK       (UINT64_C(1) &lt;&lt; 23)
 487 </programlisting>
 488
 489         <para>On input, the first five flags control the protocols to use for the look-up. They refer to
 490         classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
 491         IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the
 492         look-up will be done via all suitable protocols for the specific look-up. Note that these flags
 493         operate as filter only, but cannot force a look-up to be done via a protocol. Specifically,
 494         <filename>systemd-resolved</filename> will only route look-ups within the .local TLD to MulticastDNS
 495         (plus some reverse look-up address domains), and single-label names to LLMNR (plus some reverse
 496         address lookup domains). It will route neither of these to Unicast DNS servers. Also, it will do
 497         LLMNR and Multicast DNS only on interfaces suitable for multicast.</para>
 498
 499         <para>On output, these five flags indicate which protocol was used to execute the operation, and
 500         hence where the data was found.</para>
 501
 502         <para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
 503         earlier. In this case, it is often a good idea to limit the follow-up look-up to the protocol that was
 504         used to discover the first DNS result.</para>
 505
 506         <para>The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the
 507         look-up. This flag is only available at input, none of the functions will return it on output. If a
 508         CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default,
 509         when the flag is off, CNAME/DNAME RRs are followed.</para>
 510
 511         <para>The NO_TXT and NO_ADDRESS flags only influence operation of the
 512         <function>ResolveService()</function> method. They are only defined for input, not output. If NO_TXT
 513         is set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is set, the
 514         discovered hostnames are not implicitly translated to their addresses.</para>
 515
 516         <para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
 517         <function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
 518         using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
 519         will never qualify single-label domain names using search domains. Also note that multi-label
 520         hostnames are never subject to search list expansion.</para>
 521
 522         <para>NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be
 523         used.</para>
 524
 525         <para>The next six flags allow disabling certain sources during resolution. NO_SYNTHESIZE disables
 526         synthetic records, e.g. the local host name, see section SYNTHETIC RECORDS in
 527         <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 528         for more information. NO_CACHE disables the use of the cache of previously resolved records. NO_ZONE
 529         disables answers using locally registered public LLMNR/mDNS resource records. NO_TRUST_ANCHOR
 530         disables answers using locally configured trust anchors. NO_NETWORK requires all answers to be
 531         provided without using the network, i.e. either from local sources or the cache. NO_STALE flag
 532         can be set to disable answering request with stale records.</para>
 533
 534         <para>The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the
 535         returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected
 536         data for which a full trust chain may be established to a trusted domain anchor. It is also set for
 537         locally synthesized data, such as <literal>localhost</literal> or data from
 538         <filename>/etc/hosts</filename>. Moreover, it is set for all LLMNR or mDNS RRs which originate from
 539         the local host. Applications that require authenticated RR data for operation should check this flag
 540         before trusting the data. Note that <filename>systemd-resolved</filename> will never return
 541         invalidated data, hence this flag simply allows one to discern the cases where data is known to be
 542         trusted, or where there is proof that the data is "rightfully" unauthenticated (which includes cases
 543         where the underlying protocol or server does not support authenticating data).</para>
 544
 545         <para>CONFIDENTIAL means the query was resolved via encrypted channels or never left this
 546         system.</para>
 547
 548         <para>The next five bits flags are used in output and provide information about the origin of the
 549         answer. FROM_SYNTHETIC means the query was (at least partially) synthesized locally. FROM_CACHE means
 550         the query was answered (at least partially) using the cache. FROM_ZONE means the query was answered
 551         (at least partially) based on public, locally registered records. FROM_TRUST_ANCHOR means the query
 552         was answered (at least partially) using local trust anchors. FROM_NETWORK means the query was
 553         answered (at least partially) using the network.</para>
 554       </refsect3>
 555     </refsect2>
 556
 557     <refsect2>
 558       <title>Properties</title>
 559
 560       <para>The <varname>LLMNR</varname> and <varname>MulticastDNS</varname> properties report whether LLMNR
 561       and MulticastDNS are (globally) enabled. Each may be one of <literal>yes</literal>,
 562       <literal>no</literal>, and <literal>resolve</literal>. See <function>SetLinkLLMNR()</function>
 563       and <function>SetLinkMulticastDNS()</function> above.</para>
 564
 565       <para><varname>LLMNRHostname</varname> contains the hostname currently exposed on the network via
 566       LLMNR. It usually follows the system hostname as may be queried via
 567       <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 568       but may differ if a conflict is detected on the network.</para>
 569
 570       <para><varname>DNS</varname> and <varname>DNSEx</varname> contain arrays of all DNS servers currently
 571       used by <filename>systemd-resolved</filename>. <varname>DNS</varname> contains information similar to
 572       the DNS server data in <filename>/run/systemd/resolve/resolv.conf</filename>. Each structure in the
 573       array consists of a numeric network interface index, an address family, and a byte array containing the
 574       DNS server address (either 4 bytes in length for IPv4 or 16 bytes in lengths for IPv6).
 575       <varname>DNSEx</varname> is similar, but additionally contains the IP port and server name (used for
 576       Server Name Indication, SNI). Both arrays contain DNS servers configured system-wide, including those
 577       possibly read from a foreign <filename>/etc/resolv.conf</filename> or the <varname>DNS=</varname>
 578       setting in <filename>/etc/systemd/resolved.conf</filename>, as well as per-interface DNS server
 579       information either retrieved from
 580       <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 581       or configured by external software via <function>SetLinkDNS()</function> or
 582       <function>SetLinkDNSEx()</function> (see above). The network interface index will be 0 for the
 583       system-wide configured services and non-zero for the per-link servers.</para>
 584
 585       <para><varname>FallbackDNS</varname> and <varname>FallbackDNSEx</varname> contain arrays of all DNS
 586       servers configured as fallback servers, if any, using the same format as <varname>DNS</varname> and
 587       <varname>DNSEx</varname> described above. See the description of <varname>FallbackDNS=</varname> in
 588       <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 589       the description of when those servers are used.</para>
 590
 591       <para><varname>CurrentDNSServer</varname> and <varname>CurrentDNSServerEx</varname> specify the server
 592       that is currently used for query resolution, in the same format as a single entry in the
 593       <varname>DNS</varname> and <varname>DNSEx</varname> arrays described above.</para>
 594
 595       <para>Similarly, the <varname>Domains</varname> property contains an array of all search and routing
 596       domains currently used by <filename>systemd-resolved</filename>. Each entry consists of a network
 597       interface index (again, 0 encodes system-wide entries), the actual domain name, and whether the entry
 598       is used only for routing (true) or for both routing and searching (false).</para>
 599
 600       <para>The <varname>TransactionStatistics</varname> property contains information about the number of
 601       transactions <filename>systemd-resolved</filename> has processed. It contains a pair of unsigned 64-bit counters, the first
 602       containing the number of currently ongoing transactions, the second the number of total transactions
 603       <filename>systemd-resolved</filename> is processing or has processed. The latter value may be reset using the
 604       <function>ResetStatistics()</function> method described above. Note that the number of transactions does
 605       not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a
 606       single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC
 607       are in use.</para>
 608
 609       <para>The <varname>CacheStatistics</varname> property contains information about the executed cache
 610       operations so far. It exposes three 64-bit counters: the first being the total number of current cache
 611       entries (both positive and negative), the second the number of cache hits, and the third the number of
 612       cache misses. The latter counters may be reset using <function>ResetStatistics()</function> (see
 613       above).</para>
 614
 615       <para>The <varname>DNSSEC</varname> property specifies current status of DNSSEC validation. It is one
 616       of <literal>yes</literal> (validation is enforced), <literal>no</literal> (no validation is done),
 617       <literal>allow-downgrade</literal> (validation is done if the current DNS server supports it). See the
 618       description of <varname>DNSSEC=</varname> in
 619       <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 620       </para>
 621
 622       <para>The <varname>DNSSECStatistics</varname> property contains information about the DNSSEC
 623       validations executed so far. It contains four 64-bit counters: the number of secure, insecure, bogus,
 624       and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and
 625       each non-existence proof. The secure counter is increased for each operation that successfully verified
 626       a signed reply, the insecure counter is increased for each operation that successfully verified that an
 627       unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the
 628       validation did not check out and the data is likely to have been tempered with. Finally, the
 629       indeterminate counter is increased for each operation which did not complete because the necessary keys
 630       could not be acquired or the cryptographic algorithms were unknown.</para>
 631
 632       <para>The <varname>DNSSECSupported</varname> boolean property reports whether DNSSEC is enabled and
 633       the selected DNS servers support it. It combines information about system-wide and per-link DNS
 634       settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for
 635       which DNS is configured and for the system-wide settings if there are any. Note that <filename>systemd-resolved</filename> assumes
 636       DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported
 637       value may initially be true, until the first transactions are executed.</para>
 638
 639       <para>The <varname>DNSOverTLS</varname> boolean property reports whether DNS-over-TLS is enabled.
 640       </para>
 641
 642       <para>The <varname>ResolvConfMode</varname> property exposes how <filename>/etc/resolv.conf</filename>
 643       is managed on the host. Currently, the values <literal>uplink</literal>, <literal>stub</literal>,
 644       <literal>static</literal> (these three correspond to the three different files
 645       <filename>systemd-resolved.service</filename> provides), <literal>foreign</literal> (the file is
 646       managed by admin or another service, <filename>systemd-resolved.service</filename> just consumes it),
 647       <literal>missing</literal> (<filename>/etc/resolv.conf</filename> is missing).</para>
 648
 649       <para>The <varname>DNSStubListener</varname> property reports whether the stub listener on port 53 is
 650       enabled. Possible values are <literal>yes</literal> (enabled), <literal>no</literal> (disabled),
 651       <literal>udp</literal> (only the UDP listener is enabled), and <literal>tcp</literal> (only the TCP
 652       listener is enabled).</para>
 653
 654       <para>The <varname>DNSSECNegativeTrustAnchors</varname> property contains a list of recognized DNSSEC
 655       negative trust anchors and contains a list of domains.</para>
 656     </refsect2>
 657   </refsect1>
 658
 659   <refsect1>
 660     <title>Link Object</title>
 661
 662     <programlisting executable="systemd-resolved" node="/org/freedesktop/resolve1/link/_1" interface="org.freedesktop.resolve1.Link">
 663 node /org/freedesktop/resolve1/link/_1 {
 664   interface org.freedesktop.resolve1.Link {
 665     methods:
 666       SetDNS(in  a(iay) addresses);
 667       SetDNSEx(in  a(iayqs) addresses);
 668       SetDomains(in  a(sb) domains);
 669       SetDefaultRoute(in  b enable);
 670       SetLLMNR(in  s mode);
 671       SetMulticastDNS(in  s mode);
 672       SetDNSOverTLS(in  s mode);
 673       SetDNSSEC(in  s mode);
 674       SetDNSSECNegativeTrustAnchors(in  as names);
 675       Revert();
 676     properties:
 677       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 678       readonly t ScopesMask = ...;
 679       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 680       readonly a(iay) DNS = [...];
 681       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 682       readonly a(iayqs) DNSEx = [...];
 683       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 684       readonly (iay) CurrentDNSServer = ...;
 685       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 686       readonly (iayqs) CurrentDNSServerEx = ...;
 687       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 688       readonly a(sb) Domains = [...];
 689       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 690       readonly b DefaultRoute = ...;
 691       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 692       readonly s LLMNR = '...';
 693       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 694       readonly s MulticastDNS = '...';
 695       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 696       readonly s DNSOverTLS = '...';
 697       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 698       readonly s DNSSEC = '...';
 699       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 700       readonly as DNSSECNegativeTrustAnchors = ['...', ...];
 701       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 702       readonly b DNSSECSupported = ...;
 703   };
 704   interface org.freedesktop.DBus.Peer { ... };
 705   interface org.freedesktop.DBus.Introspectable { ... };
 706   interface org.freedesktop.DBus.Properties { ... };
 707 };
 708 </programlisting>
 709
 710     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 711
 712     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Link"/>
 713
 714     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Link"/>
 715
 716     <variablelist class="dbus-method" generated="True" extra-ref="SetDNS()"/>
 717
 718     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSEx()"/>
 719
 720     <variablelist class="dbus-method" generated="True" extra-ref="SetDomains()"/>
 721
 722     <variablelist class="dbus-method" generated="True" extra-ref="SetDefaultRoute()"/>
 723
 724     <variablelist class="dbus-method" generated="True" extra-ref="SetLLMNR()"/>
 725
 726     <variablelist class="dbus-method" generated="True" extra-ref="SetMulticastDNS()"/>
 727
 728     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSOverTLS()"/>
 729
 730     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSSEC()"/>
 731
 732     <variablelist class="dbus-method" generated="True" extra-ref="SetDNSSECNegativeTrustAnchors()"/>
 733
 734     <variablelist class="dbus-method" generated="True" extra-ref="Revert()"/>
 735
 736     <variablelist class="dbus-property" generated="True" extra-ref="ScopesMask"/>
 737
 738     <variablelist class="dbus-property" generated="True" extra-ref="DNS"/>
 739
 740     <variablelist class="dbus-property" generated="True" extra-ref="DNSEx"/>
 741
 742     <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServer"/>
 743
 744     <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServerEx"/>
 745
 746     <variablelist class="dbus-property" generated="True" extra-ref="Domains"/>
 747
 748     <variablelist class="dbus-property" generated="True" extra-ref="DefaultRoute"/>
 749
 750     <variablelist class="dbus-property" generated="True" extra-ref="LLMNR"/>
 751
 752     <variablelist class="dbus-property" generated="True" extra-ref="MulticastDNS"/>
 753
 754     <variablelist class="dbus-property" generated="True" extra-ref="DNSOverTLS"/>
 755
 756     <variablelist class="dbus-property" generated="True" extra-ref="DNSSEC"/>
 757
 758     <variablelist class="dbus-property" generated="True" extra-ref="DNSSECNegativeTrustAnchors"/>
 759
 760     <variablelist class="dbus-property" generated="True" extra-ref="DNSSECSupported"/>
 761
 762     <!--End of Autogenerated section-->
 763
 764     <para>For each Linux network interface a "Link" object is created which exposes per-link DNS
 765     configuration and state. Use <function>GetLink()</function> on the Manager interface to retrieve the
 766     object path for a link object given the network interface index (see above).</para>
 767
 768     <refsect2>
 769       <title>Methods</title>
 770
 771       <para>The various methods exposed by the Link interface are equivalent to their similarly named
 772       counterparts on the Manager interface. e.g. <function>SetDNS()</function> on the Link object maps to
 773       <function>SetLinkDNS()</function> on the Manager object, the main difference being that the later
 774       expects an interface index to be specified. Invoking the methods on the Manager interface has the
 775       benefit of reducing roundtrips, as it is not necessary to first request the Link object path via
 776       <function>GetLink()</function> before invoking the methods. The same relationship holds for
 777       <function>SetDNSEx()</function>, <function>SetDomains()</function>,
 778       <function>SetDefaultRoute()</function>, <function>SetLLMNR()</function>,
 779       <function>SetMulticastDNS()</function>, <function>SetDNSOverTLS()</function>,
 780       <function>SetDNSSEC()</function>, <function>SetDNSSECNegativeTrustAnchors()</function>, and
 781       <function>Revert()</function>. For further details on these methods see the
 782       <interfacename>Manager</interfacename> documentation above.</para>
 783     </refsect2>
 784
 785     <refsect2>
 786       <title>Properties</title>
 787
 788       <para><varname>ScopesMask</varname> defines which resolver scopes are currently active on this
 789       interface. This 64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the
 790       flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in
 791       IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific
 792       interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in
 793       the "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and
 794       has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR
 795       and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured*
 796       to be used on the interface, the former expose what is actually used on the interface, taking into
 797       account the abilities of the interface.</para>
 798
 799       <para><varname>DNSSECSupported</varname> exposes a boolean field that indicates whether DNSSEC is
 800       currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is
 801       assumed available until it is detected that the configured server does not actually support it. Thus,
 802       this property may initially report that DNSSEC is supported on an interface.</para>
 803
 804       <para><varname>DefaultRoute</varname> exposes a boolean field that indicates whether the interface will
 805       be used as default route for name queries. See <function>SetLinkDefaultRoute()</function> above.</para>
 806
 807       <para>The other properties reflect the state of the various configuration settings for the link which
 808       may be set with the various methods calls such as <function>SetDNS()</function> or
 809       <function>SetLLMNR()</function>.</para>
 810     </refsect2>
 811   </refsect1>
 812
 813   <refsect1>
 814     <title>Common Errors</title>
 815
 816     <para>Many bus methods <filename>systemd-resolved</filename> exposes (in particular the resolver methods such
 817     as <function>ResolveHostname()</function> on the <interfacename>Manager</interfacename> interface) may return
 818     some of the following errors:</para>
 819
 820     <variablelist>
 821       <varlistentry><term><constant>org.freedesktop.resolve1.NoNameServers</constant></term>
 822       <listitem><para>No suitable DNS servers were found to resolve a request.</para>
 823
 824       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 825       </varlistentry>
 826
 827       <varlistentry><term><constant>org.freedesktop.resolve1.InvalidReply</constant></term>
 828       <listitem><para>A response from the selected DNS server was not understood.</para>
 829
 830       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 831       </varlistentry>
 832
 833       <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchRR</constant></term>
 834       <listitem><para>The requested name exists, but there is no resource record of the requested type for
 835       it. (This is the DNS NODATA case).</para>
 836
 837       <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>
 838
 839       <varlistentry><term><constant>org.freedesktop.resolve1.CNameLoop</constant></term>
 840       <listitem><para>The look-up failed because a CNAME or DNAME loop was detected.</para>
 841
 842       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 843       </varlistentry>
 844
 845       <varlistentry><term><constant>org.freedesktop.resolve1.Aborted</constant></term>
 846       <listitem><para>The look-up was aborted because the selected protocol became unavailable while the
 847       operation was ongoing.</para>
 848
 849       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 850       </varlistentry>
 851
 852       <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService</constant></term>
 853       <listitem><para>A service look-up was successful, but the <constant class="dns">SRV</constant> record
 854       reported that the service is not available.</para>
 855
 856       <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>
 857
 858       <varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed</constant></term>
 859       <listitem><para>The acquired response did not pass DNSSEC validation.</para>
 860
 861       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 862       </varlistentry>
 863
 864       <varlistentry><term><constant>org.freedesktop.resolve1.NoTrustAnchor</constant></term>
 865       <listitem><para>No chain of trust could be established for the response to a configured DNSSEC trust
 866       anchor.</para>
 867
 868       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 869       </varlistentry>
 870
 871       <varlistentry><term><constant>org.freedesktop.resolve1.ResourceRecordTypeUnsupported</constant></term>
 872       <listitem><para>The requested resource record type is not supported on the selected DNS servers. This
 873       error is generated for example when an RRSIG record is requested from a DNS server that does not
 874       support DNSSEC.</para>
 875
 876       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 877
 878       </varlistentry>
 879
 880       <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchLink</constant></term>
 881       <listitem><para>No network interface with the specified network interface index exists.
 882       </para>
 883
 884       <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>
 885
 886       <varlistentry><term><constant>org.freedesktop.resolve1.LinkBusy</constant></term>
 887       <listitem><para>The requested configuration change could not be made because
 888       <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 889       already took possession of the interface and supplied configuration data for it.</para>
 890
 891       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 892       </varlistentry>
 893
 894       <varlistentry><term><constant>org.freedesktop.resolve1.NetworkDown</constant></term>
 895       <listitem><para>The requested look-up failed because the system is currently not connected to any
 896       suitable network.</para>
 897
 898       <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>
 899
 900       <varlistentry><term><constant>org.freedesktop.resolve1.DnsError.NXDOMAIN</constant></term>
 901       <term><constant>org.freedesktop.resolve1.DnsError.REFUSED</constant></term>
 902       <term>...</term>
 903       <listitem><para>The look-up failed with a DNS return code reporting a failure. The error names used as
 904       suffixes here are defined in by IANA in
 905       <ulink url="https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6">DNS RCODEs</ulink>.
 906       </para>
 907
 908       <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 909       </varlistentry>
 910     </variablelist>
 911   </refsect1>
 912
 913   <refsect1>
 914     <title>Examples</title>
 915
 916     <example>
 917       <title>Introspect <interfacename>org.freedesktop.resolve1.Manager</interfacename> on the bus</title>
 918
 919       <programlisting>
 920 $ gdbus introspect --system \
 921   --dest org.freedesktop.resolve1 \
 922   --object-path /org/freedesktop/resolve1
 923 </programlisting>
 924     </example>
 925
 926     <example>
 927       <title>Introspect <interfacename>org.freedesktop.resolve1.Link</interfacename> on the bus</title>
 928
 929       <programlisting>
 930 $ gdbus introspect --system \
 931   --dest org.freedesktop.resolve1 \
 932   --object-path /org/freedesktop/resolve1/link/_11
 933 </programlisting>
 934     </example>
 935   </refsect1>
 936
 937   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
 938
 939   <refsect1>
 940     <title>See Also</title>
 941     <para><simplelist type="inline">
 942       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 943       <member><citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 944       <member><citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 945     </simplelist></para>
 946   </refsect1>
 947 </refentry>