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" >
8 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
10 <refentry id=
"org.freedesktop.resolve1" conditional='ENABLE_RESOLVE'
11 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
13 <title>org.freedesktop.resolve1
</title>
14 <productname>systemd
</productname>
18 <refentrytitle>org.freedesktop.resolve1
</refentrytitle>
19 <manvolnum>5</manvolnum>
23 <refname>org.freedesktop.resolve1
</refname>
24 <refpurpose>The D-Bus interface of systemd-resolved
</refpurpose>
28 <title>Introduction
</title>
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>
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
45 <title>The Manager Object
</title>
47 <para>The service exposes the following interfaces on the Manager object on the bus:
</para>
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 {
53 ResolveHostname(in i ifindex,
57 out a(iiay) addresses,
60 ResolveAddress(in i ifindex,
66 ResolveRecord(in i ifindex,
73 ResolveService(in i ifindex,
79 out a(qqqsa(iiay)s) srv_data,
83 out s canonical_domain,
87 SetLinkDNS(in i ifindex,
89 SetLinkDomains(in i ifindex,
91 SetLinkDefaultRoute(in i ifindex,
93 SetLinkLLMNR(in i ifindex,
95 SetLinkMulticastDNS(in i ifindex,
97 SetLinkDNSOverTLS(in i ifindex,
99 SetLinkDNSSEC(in i ifindex,
101 SetLinkDNSSECNegativeTrustAnchors(in i ifindex,
103 RevertLink(in i ifindex);
104 RegisterService(in s name,
108 in q service_priority,
110 in aa{say} txt_datas,
112 UnregisterService(in o service_path);
115 ResetServerFeatures();
117 readonly s LLMNRHostname = '...';
118 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
119 readonly s LLMNR = '...';
120 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
121 readonly s MulticastDNS = '...';
122 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
123 readonly s DNSOverTLS = '...';
124 readonly a(iiay) DNS = [...];
125 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
126 readonly a(iiay) FallbackDNS = [...];
127 readonly (iiay) CurrentDNSServer = ...;
128 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
129 readonly a(isb) Domains = [...];
130 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
131 readonly (tt) TransactionStatistics = ...;
132 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
133 readonly (ttt) CacheStatistics = ...;
134 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
135 readonly s DNSSEC = '...';
136 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
137 readonly (tttt) DNSSECStatistics = ...;
138 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
139 readonly b DNSSECSupported = ...;
140 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
141 readonly as DNSSECNegativeTrustAnchors = ['...', ...];
142 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
143 readonly s DNSStubListener = '...';
145 interface org.freedesktop.DBus.Peer { ... };
146 interface org.freedesktop.DBus.Introspectable { ... };
147 interface org.freedesktop.DBus.Properties { ... };
151 <!--method SetLinkDefaultRoute is not documented!-->
153 <!--method SetLinkDNSOverTLS is not documented!-->
155 <!--method RegisterService is not documented!-->
157 <!--method UnregisterService is not documented!-->
159 <!--method FlushCaches is not documented!-->
161 <!--method ResetServerFeatures is not documented!-->
163 <!--property LLMNR is not documented!-->
165 <!--property MulticastDNS is not documented!-->
167 <!--property DNSOverTLS is not documented!-->
169 <!--property FallbackDNS is not documented!-->
171 <!--property CurrentDNSServer is not documented!-->
173 <!--property DNSSEC is not documented!-->
175 <!--property DNSSECNegativeTrustAnchors is not documented!-->
177 <!--property DNSStubListener is not documented!-->
179 <!--Autogenerated cross-references for systemd.directives, do not edit-->
181 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.resolve1.Manager"/>
183 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.resolve1.Manager"/>
185 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResolveHostname()"/>
187 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResolveAddress()"/>
189 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResolveRecord()"/>
191 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResolveService()"/>
193 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetLink()"/>
195 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkDNS()"/>
197 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkDomains()"/>
199 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkDefaultRoute()"/>
201 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkLLMNR()"/>
203 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkMulticastDNS()"/>
205 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkDNSOverTLS()"/>
207 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkDNSSEC()"/>
209 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLinkDNSSECNegativeTrustAnchors()"/>
211 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RevertLink()"/>
213 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RegisterService()"/>
215 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UnregisterService()"/>
217 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResetStatistics()"/>
219 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"FlushCaches()"/>
221 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResetServerFeatures()"/>
223 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"LLMNRHostname"/>
225 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"LLMNR"/>
227 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"MulticastDNS"/>
229 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSOverTLS"/>
231 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNS"/>
233 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"FallbackDNS"/>
235 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"CurrentDNSServer"/>
237 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Domains"/>
239 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"TransactionStatistics"/>
241 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"CacheStatistics"/>
243 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSSEC"/>
245 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSSECStatistics"/>
247 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSSECSupported"/>
249 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSSECNegativeTrustAnchors"/>
251 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSStubListener"/>
253 <!--End of Autogenerated section-->
256 <title>Methods
</title>
258 <para><function>ResolveHostname()
</function> takes a hostname and resolves it to one or more IP addresses.
259 As parameters it takes the Linux network interface index to execute the query on, or
0 if it may be
260 done on any suitable interface. The
<varname>name
</varname> parameter specifies the hostname to
261 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
262 limits the results to a specific address family. It may be
<constant>AF_INET
</constant>,
263 <constant>AF_INET6
</constant> or
<constant>AF_UNSPEC
</constant>. If
<constant>AF_UNSPEC
</constant> is specified (recommended), both kinds are retrieved, subject
264 to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is
265 retrieved; and similarly for IPv4). A
64-bit
<varname>flags
</varname> field may be used to alter the
266 behaviour of the resolver operation (see below). The method returns an array of address records. Each
267 address record consists of the interface index the address belongs to, an address family as well as a
268 byte array with the actual IP address data (which either has
4 or
16 elements, depending on the address
269 family). The returned address family will be one of
<constant>AF_INET
</constant> or
270 <constant>AF_INET6
</constant>. For IPv6, the returned address interface index should be used to
271 initialize the .sin6_scope_id field of a
<structname>struct sockaddr_in6
</structname> instance to permit
272 support for resolution to link-local IP addresses. The address array is followed by the canonical name
273 of the host, which may or may not be identical to the resolved hostname. Finally, a
64-bit
274 <varname>flags
</varname> field is returned that is defined similarly to the
<varname>flags
</varname>
275 field that was passed in, but contains information about the resolved data (see below). If the hostname
276 passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In
277 this case, no network communication is done.
</para>
279 <para><function>ResolveAddress()
</function> executes the reverse operation: it takes an IP address and
280 acquires one or more hostnames for it. As parameters it takes the interface index to execute the query
281 on, or
<constant>0</constant> if all suitable interfaces are OK. The
<varname>family
</varname>
282 parameter indicates the address family of the IP address to resolve. It may be either
283 <constant>AF_INET
</constant> or
<constant>AF_INET6
</constant>. The
<varname>address
</varname> parameter
284 takes the raw IP address data (as either a
4 or
16 byte array). The
<varname>flags
</varname> input
285 parameter may be used to alter the resolver operation (see below). The method returns an array of name
286 records, each consisting of an interface index and a hostname. The
<varname>flags
</varname> output
287 field contains additional information about the resolver operation (see below).
</para>
289 <para><function>ResolveRecord()
</function> takes a DNS resource record (RR) type, class and name, and
290 retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the
291 Linux network interface index to execute the query on, or
<constant>0</constant> if it may be done on
292 any suitable interface. The
<varname>name
</varname> parameter specifies the RR domain name to look up
293 (no IDNA conversion is applied), followed by the
16-bit class and type fields (which may be
294 ANY). Finally, a
<varname>flags
</varname> field may be passed in to alter behaviour of the look-up (see
295 below). On completion, an array of RR items is returned. Each array entry consists of the network interface
296 index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw
297 RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed
298 by the RR type, class, TTL and RDATA, in the binary format documented in
299 <ulink url=
"https://www.ietf.org/rfc/rfc1035.txt">RFC
1035</ulink>. For RRs that support name
300 compression in the payload (such as MX or PTR), the compression is expanded in the returned
303 <para>Note that currently, the class field has to be specified as IN or ANY. Specifying a different
304 class will return an error indicating that look-ups of this kind are unsupported. Similarly, some
305 special types are not supported either (AXFR, OPT, …). While
<filename>systemd-resolved
</filename> parses and validates resource
306 records of many types, it is crucial that clients using this API understand that the RR data originates
307 from the network and should be thoroughly validated before use.
</para>
309 <para><function>ResolveService()
</function> may be used to resolve a DNS SRV service record, as well as the
310 hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional
311 service metadata. The primary benefit of using this method over
<function>ResolveRecord()
</function>
312 specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced
313 in the SRV in a single operation. As parameters it takes a Linux network interface index, a service
314 name, a service type and a service domain. This method may be invoked in three different modes:
</para>
317 <listitem><para>To resolve a DNS-SD service, specify the service name (e.g.
<literal>Lennart's
318 Files
</literal>), the service type (e.g.
<literal>_webdav._tcp
</literal>) and the domain to search in
319 (e.g.
<literal>local
</literal>) as the three service parameters. The service name must be in UTF-
8
320 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD
321 specifications). However, if necessary, IDNA conversion is applied to the domain parameter.
</para>
324 <listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string
325 and set the service type and domain properly. (IDNA conversion is applied to the domain, if
326 necessary.)
</para></listitem>
328 <listitem><para>Alternatively, leave both the service name and type empty and specify the full
329 domain name of the SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA
330 coversion is applied in this mode.)
</para></listitem>
333 <para>The
<varname>family
</varname> parameter of the
<function>ResolveService()
</function> method encodes
334 the desired family of the addresses to resolve (use
<constant>AF_INET
</constant>,
335 <constant>AF_INET6
</constant>, or
<constant>AF_UNSPEC
</constant>). If this is enabled (Use the
336 <constant>NO_ADDRESS
</constant> flag to turn address resolution off, see below). The
337 <varname>flags
</varname> parameter takes a couple of flags that may be used to alter the resolver
340 <para>On completion,
<function>ResolveService()
</function> returns an array of SRV record structures. Each
341 items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV
342 record. Immediately following is an array of the addresses of this hostname, with each item consisting
343 of the interface index, the address family and the address data in a byte array. This address array is
344 followed by the canonicalized hostname. After this array of SRV record structures an array of byte
345 arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
346 are the canonical service name, type and domain. This may or may not be identical to the parameters
347 passed in. Finally, a
<varname>flags
</varname> field is returned that contains information about the
348 resolver operation performed.
</para>
350 <para>The
<function>ResetStatistics()
</function> method resets the various statistics counters that
351 <filename>systemd-resolved
</filename> maintains to zero. (For details, see the statistics properties below.)
</para>
353 <para>The
<function>GetLink()
</function> method takes a network interface index and returns the object
354 path to the
<interfacename>org.freedesktop.resolve1.Link
</interfacename> object corresponding to it.
357 <para>The
<function>SetLinkDNS()
</function> method sets the DNS servers to use on a specific
358 interface. This method (and the following ones) may be used by network management software to configure
359 per-interface DNS settings. It takes a network interface index as well as an array of DNS server IP
360 address records. Each array item consists of an address family (either
<constant>AF_INET
</constant> or
361 <constant>AF_INET6
</constant>), followed by a
4-byte or
16-byte array with the raw address data. This
362 method is a one-step shortcut for retrieving the Link object for a network interface using
363 <function>GetLink()
</function> (see above) and then invoking the
<function>SetDNS()
</function> method
367 <para>Network management software integrating with
<filename>systemd-resolved
</filename> should
368 call this method (and the five below) after the interface appeared in the kernel (and thus after a
369 network interface index has been assigned), but before the network interfaces is activated
370 (
<constant>IFF_UP
</constant> set) so that all settings take effect during the full time the network
371 interface is up. It is safe to alter settings while the interface is up, however. Use
372 <function>RevertLink()
</function> (described below) to reset all per-interface settings.
</para>
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>
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
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>
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>
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>
409 <para>The
<function>RevertLink()
</function> method may be used to revert all per-link settings done with
410 the six methods described above to the defaults again.
</para>
413 <title>The Flags Parameter
</title>
415 <para>The four methods above accept and return a
64-bit flags value. In most cases passing
0 is sufficient
416 and recommended. However, the following flags are defined to alter the look-up:
</para>
419 #define SD_RESOLVED_DNS (UINT64_C(
1)
<< 0)
420 #define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(
1)
<< 1)
421 #define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(
1)
<< 2)
422 #define SD_RESOLVED_MDNS_IPV4 (UINT64_C(
1)
<< 3)
423 #define SD_RESOLVED_MDNS_IPV6 (UINT64_C(
1)
<< 4)
424 #define SD_RESOLVED_NO_CNAME (UINT64_C(
1)
<< 5)
425 #define SD_RESOLVED_NO_TXT (UINT64_C(
1)
<< 6)
426 #define SD_RESOLVED_NO_ADDRESS (UINT64_C(
1)
<< 7)
427 #define SD_RESOLVED_NO_SEARCH (UINT64_C(
1)
<< 8)
428 #define SD_RESOLVED_AUTHENTICATED (UINT64_C(
1)
<< 9)
431 <para>On input, the first five flags control the protocols to use for the look-up. They refer to
432 classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
433 IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the
434 look-up will be done via all suitable protocols for the specific look-up. Note that these flags
435 operate as filter only, but cannot force a look-up to be done via a protocol. Specifically,
<filename>systemd-resolved
</filename>
436 will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address
437 domains), and single-label names to LLMNR (plus some reverse address lookup domains). It will route
438 neither of these to Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only on interfaces
439 suitable for multicast.
</para>
441 <para>On output, these five flags indicate which protocol was used to execute the operation, and hence
442 where the data was found.
</para>
444 <para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
445 earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
446 used to discover the first DNS result.
</para>
448 <para>The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the
449 look-up. This flag is only available at input, none of the functions will return it on output. If a
450 CNAME/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default,
451 when the flag is off, CNAME/DNAME RRs are followed.
</para>
453 <para>The NO_TXT and NO_ADDRESS flags only influence operation of the
454 <function>ResolveService()
</function> method. They are only defined for input, not output. If
455 NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified,
456 the hostnames discovered are not implicitly translated to their addresses.
</para>
458 <para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
459 <function>ResolveHostname()
</function>. When specified, single-label hostnames are not qualified
460 using defined search domains, if any are configured. Note that
<function>ResolveRecord()
</function>
461 will never qualify single-label domain names using search domains. Also note that
462 multi-label hostnames are never subject to search list expansion.
</para>
464 <para>The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the
465 returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data
466 for which a full trust chain may be established to a trusted domain anchor. It is also set for locally
467 synthesized data, such as
<literal>localhost
</literal> or data from
468 <filename>/etc/hosts
</filename>. Moreover, it is set for all LLMNR or mDNS RRs which originate from the
469 local host. Applications that require authenticated RR data for operation should check this flag before
470 trusting the data. Note that
<filename>systemd-resolved
</filename> will never return invalidated data, hence this flag
471 simply allows to discern the cases where data is known to be trustable, or where there is proof that
472 the data is
"rightfully" unauthenticated (which includes cases where the underlying protocol or server
473 does not support authenticating data).
</para>
479 <title>Properties
</title>
481 <para><varname>LLMNRHostname
</varname> contains the hostname currently exposed on the network via
482 LLMNR. It usually follows the system hostname as may be queried via
483 <citerefentry project=
"man-pages"><refentrytitle>gethostname
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
484 but may differ if a conflict is detected on the network.
</para>
486 <para><varname>DNS
</varname> contains an array of all DNS servers currently used by
487 <filename>systemd-resolved
</filename>. It contains similar information as the DNS server data written to
488 /run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface
489 index, an address family, and a byte array containing the DNS server address (either
4 bytes in length
490 for IPv4 or
16 bytes in lengths for IPv6). The array contains DNS servers configured system-wide,
491 including those possibly read from a foreign
<filename>/etc/resolv.conf
</filename> or the
492 <varname>DNS=
</varname> setting in
<filename>/etc/systemd/resolved.conf
</filename>, as well as
493 per-interface DNS server information either retrieved from
494 <citerefentry><refentrytitle>systemd-networkd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
495 or configured by external software via
<function>SetLinkDNS()
</function> (see above). The network
496 interface index will be
0 for the system-wide configured services and non-zero for the per-link
499 <para>Similarly, the
<varname>Domains
</varname> property contains an array of all search and
500 routing domains currently used by
<filename>systemd-resolved
</filename>. Each entry consists of a network interface index (again,
0
501 encodes system-wide entries), the actual domain name, and whether the entry is used only for routing
502 (true) or for both routing and searching (false).
</para>
504 <para>The
<varname>TransactionStatistics
</varname> property contains information about the number of
505 transactions
<filename>systemd-resolved
</filename> has processed. It contains a pair of unsigned
64-bit counters, the first
506 containing the number of currently ongoing transactions, the second the number of total transactions
507 <filename>systemd-resolved
</filename> is processing or has processed. The latter value may be reset using the
508 <function>ResetStatistics()
</function> method described above. Note that the number of transactions does
509 not directly map to the number of issued resolver bus method calls. While simple look-ups usually require a
510 single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC
513 <para>The
<varname>CacheStatistics
</varname> property contains information about the executed cache
514 operations so far. It exposes three
64-bit counters: the first being the total number of current cache
515 entries (both positive and negative), the second the number of cache hits, and the third the number of
516 cache misses. The latter counters may be reset using
<function>ResetStatistics()
</function> (see
519 <para>The
<varname>DNSSECStatistics
</varname> property contains information about the DNSSEC
520 validations executed so far. It contains four
64-bit counters: the number of secure, insecure, bogus,
521 and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and
522 each non-existance proof. The secure counter is increased for each operation that successfully verified
523 a signed reply, the insecure counter is increased for each operation that successfully verified that an
524 unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the
525 validation did not check out and the data is likely to have been tempered with. Finally the
526 indeterminate counter is increased for each operation which did not complete because the necessary keys
527 could not be acquired or the cryptographic algorithms were unknown.
</para>
529 <para>The
<varname>DNSSECSupported
</varname> boolean property reports whether DNSSEC is enabled and
530 the selected DNS servers support it. It combines information about system-wide and per-link DNS
531 settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for
532 which DNS is configured and for the system-wide settings if there are any. Note that
<filename>systemd-resolved
</filename> assumes
533 DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported
534 value may initially be true, until the first transactions are executed.
</para>
536 <para>The
<varname>LogLevel
</varname> property shows the (maximum) log level of the manager, with the
537 same values as the
<option>--log-level=
</option> option described in
538 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
543 <title>Link Object
</title>
545 <programlisting executable=
"systemd-resolved" node=
"/org/freedesktop/resolve1/link/_1" interface=
"org.freedesktop.resolve1.Link">
546 node /org/freedesktop/resolve1/link/_1 {
547 interface org.freedesktop.resolve1.Link {
549 SetDNS(in a(iay) addresses);
550 SetDomains(in a(sb) domains);
551 SetDefaultRoute(in b enable);
553 SetMulticastDNS(in s mode);
554 SetDNSOverTLS(in s mode);
555 SetDNSSEC(in s mode);
556 SetDNSSECNegativeTrustAnchors(in as names);
559 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
560 readonly t ScopesMask = ...;
561 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
562 readonly a(iay) DNS = [...];
563 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
564 readonly (iay) CurrentDNSServer = ...;
565 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
566 readonly a(sb) Domains = [...];
567 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
568 readonly b DefaultRoute = ...;
569 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
570 readonly s LLMNR = '...';
571 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
572 readonly s MulticastDNS = '...';
573 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
574 readonly s DNSOverTLS = '...';
575 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
576 readonly s DNSSEC = '...';
577 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
578 readonly as DNSSECNegativeTrustAnchors = ['...', ...];
579 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
580 readonly b DNSSECSupported = ...;
582 interface org.freedesktop.DBus.Peer { ... };
583 interface org.freedesktop.DBus.Introspectable { ... };
584 interface org.freedesktop.DBus.Properties { ... };
588 <!--method SetDomains is not documented!-->
590 <!--method SetDefaultRoute is not documented!-->
592 <!--method SetLLMNR is not documented!-->
594 <!--method SetMulticastDNS is not documented!-->
596 <!--method SetDNSOverTLS is not documented!-->
598 <!--method SetDNSSEC is not documented!-->
600 <!--method SetDNSSECNegativeTrustAnchors is not documented!-->
602 <!--method Revert is not documented!-->
604 <!--property CurrentDNSServer is not documented!-->
606 <!--property DefaultRoute is not documented!-->
608 <!--property LLMNR is not documented!-->
610 <!--property MulticastDNS is not documented!-->
612 <!--property DNSOverTLS is not documented!-->
614 <!--property DNSSEC is not documented!-->
616 <!--property DNSSECNegativeTrustAnchors is not documented!-->
618 <!--Autogenerated cross-references for systemd.directives, do not edit-->
620 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.resolve1.Link"/>
622 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.resolve1.Link"/>
624 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetDNS()"/>
626 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetDomains()"/>
628 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetDefaultRoute()"/>
630 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLLMNR()"/>
632 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetMulticastDNS()"/>
634 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetDNSOverTLS()"/>
636 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetDNSSEC()"/>
638 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetDNSSECNegativeTrustAnchors()"/>
640 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Revert()"/>
642 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"ScopesMask"/>
644 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNS"/>
646 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"CurrentDNSServer"/>
648 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Domains"/>
650 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DefaultRoute"/>
652 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"LLMNR"/>
654 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"MulticastDNS"/>
656 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSOverTLS"/>
658 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSSEC"/>
660 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSSECNegativeTrustAnchors"/>
662 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DNSSECSupported"/>
664 <!--End of Autogenerated section-->
666 <para>For each Linux network interface a
"Link" object is created which exposes per-link DNS
667 configuration and state. Use
<function>GetLink()
</function> on the Manager interface to retrieve the
668 object path for a link object given the network interface index (see above).
</para>
671 <title>Methods
</title>
673 <para>The various methods exposed by the Link interface are equivalent to their similarly named
674 counterparts on the Manager interface. e.g.
<function>SetDNS()
</function> on the Link object maps to
675 <function>SetLinkDNS()
</function> on the Manager object, the main difference being that the later
676 expects an interface index to be specified. Invoking the methods on the Manager interface has the
677 benefit of reducing roundtrips, as it is not necessary to first request the Link object path via
678 <function>GetLink()
</function> before invoking the methods. For further details on these methods see
679 the
<interfacename>Manager
</interfacename> documentation above.
</para>
683 <title>Properties
</title>
685 <para><varname>ScopesMask
</varname> defines which resolver scopes are currently active on this
686 interface. This
64-bit unsigned integer field is a bit mask consisting of a subset of the bits of the
687 flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in
688 IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific
689 interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in
690 the
"UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and
691 has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR
692 and MulticastDNS properties also exposed on the Link interface. The latter expose what is *configured*
693 to be used on the interface, the former expose what is actually used on the interface, taking into
694 account the abilities of the interface.
</para>
696 <para><varname>DNSSECSupported
</varname> exposes a boolean field that indicates whether DNSSEC is
697 currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface, it is
698 assumed available until it is detected that the configured server does not actually support it. Thus,
699 this property may initially report that DNSSEC is supported on an interface.
</para>
701 <para>The other properties reflect the state of the various configuration settings for the link which
702 may be set with the various methods calls such as SetDNS() or SetLLMNR().
</para>
707 <title>Common Errors
</title>
709 <para>Many bus methods
<filename>systemd-resolved
</filename> exposes (in particular the resolver methods such
710 as
<function>ResolveHostname()
</function> on the
<interfacename>Manager
</interfacename> interface) may return
711 some of the following errors:
</para>
714 <varlistentry><term><constant>org.freedesktop.resolve1.NoNameServers
</constant></term>
715 <listitem><para>No suitable DNS servers were found to resolve a request.
</para></listitem>
718 <varlistentry><term><constant>org.freedesktop.resolve1.InvalidReply
</constant></term>
719 <listitem><para>A response from the selected DNS server was not understood.
</para></listitem>
722 <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchRR
</constant></term>
723 <listitem><para>The requested name exists, but there is no resource record of the requested type for
724 it. (This is the DNS NODATA case).
</para></listitem></varlistentry>
726 <varlistentry><term><constant>org.freedesktop.resolve1.CNameLoop
</constant></term>
727 <listitem><para>The look-up failed because a CNAME or DNAME loop was detected.
</para></listitem>
730 <varlistentry><term><constant>org.freedesktop.resolve1.Aborted
</constant></term>
731 <listitem><para>The look-up was aborted because the selected protocol became unavailable while the
732 operation was ongoing.
</para></listitem>
735 <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService
</constant></term>
736 <listitem><para>A service look-up was successful, but the SRV record reported that the service is not
737 available.
</para></listitem></varlistentry>
739 <varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed
</constant></term>
740 <listitem><para>The acquired response did not pass DNSSEC validation.
</para></listitem>
743 <varlistentry><term><constant>org.freedesktop.resolve1.NoTrustAnchor
</constant></term>
744 <listitem><para>No chain of trust could be established for the response to a configured DNSSEC trust
745 anchor.
</para></listitem>
748 <varlistentry><term><constant>org.freedesktop.resolve1.ResourceRecordTypeUnsupported
</constant></term>
749 <listitem><para>The requested resource record type is not supported on the selected DNS servers. This
750 error is generated for example when an RRSIG record is requested from a DNS server that does not
751 support DNSSEC.
</para></listitem>
755 <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchLink
</constant></term>
756 <listitem><para>No network interface with the specified network interface index exists.
757 </para></listitem></varlistentry>
759 <varlistentry><term><constant>org.freedesktop.resolve1.LinkBusy
</constant></term>
760 <listitem><para>The requested configuration change could not be made because
761 <citerefentry><refentrytitle>systemd-networkd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
762 already took possession of the interface and supplied configuration data for it.
</para></listitem>
765 <varlistentry><term><constant>org.freedesktop.resolve1.NetworkDown
</constant></term>
766 <listitem><para>The requested look-up failed because the system is currently not connected to any
767 suitable network.
</para></listitem></varlistentry>
769 <varlistentry><term><constant>org.freedesktop.resolve1.DnsError.NXDOMAIN
</constant></term>
770 <term><constant>org.freedesktop.resolve1.DnsError.REFUSED
</constant></term>
772 <listitem><para>The look-up failed with a DNS return code reporting a failure. The error names used as
773 suffixes here are defined in by IANA in
774 <ulink url=
"https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6">DNS RCODEs
</ulink>.
781 <title>Examples
</title>
784 <title>Introspect
<interfacename>org.freedesktop.resolve1.Manager
</interfacename> on the bus
</title>
787 $ gdbus introspect --system \
788 --dest org.freedesktop.resolve1 \
789 --object-path /org/freedesktop/resolve1
794 <title>Introspect
<interfacename>org.freedesktop.resolve1.Link
</interfacename> on the bus
</title>
797 $ gdbus introspect --system \
798 --dest org.freedesktop.resolve1 \
799 --object-path /org/freedesktop/resolve1/link/_11
805 <title>Versioning
</title>
807 <para>These D-Bus interfaces follow
<ulink url=
"http://0pointer.de/blog/projects/versioning-dbus.html">
808 the usual interface versioning guidelines
</ulink>.
</para>