1ORG.FREEDESKTOP.RESOLVE1(5)org.freedesktop.resolve1ORG.FREEDESKTOP.RESOLVE1(5)
2
6 org.freedesktop.resolve1 - The D-Bus interface of systemd-resolved
7
9 systemd-resolved.service(8) is a system service that provides hostname
10 resolution and caching using DNS, LLMNR, and mDNS. It also does DNSSEC
11 validation. This page describes the resolve semantics and the D-Bus
12 interface.
13 This page contains an API reference only. If you are looking for a
15 longer explanation how to use this API, please consult Writing Network
16 Configuration Managers[1] and Writing Resolver Clients[2].
17
19 The service exposes the following interfaces on the Manager object on
20 the bus:
21 node /org/freedesktop/resolve1 {
23 interface org.freedesktop.resolve1.Manager {
24 methods:
25 ResolveHostname(in i ifindex,
26 in s name,
27 in i family,
28 in t flags,
29 out a(iiay) addresses,
30 out s canonical,
31 out t flags);
32 ResolveAddress(in i ifindex,
33 in i family,
34 in ay address,
35 in t flags,
36 out a(is) names,
37 out t flags);
38 ResolveRecord(in i ifindex,
39 in s name,
40 in q class,
41 in q type,
42 in t flags,
43 out a(iqqay) records,
44 out t flags);
45 ResolveService(in i ifindex,
46 in s name,
47 in s type,
48 in s domain,
49 in i family,
50 in t flags,
51 out a(qqqsa(iiay)s) srv_data,
52 out aay txt_data,
53 out s canonical_name,
54 out s canonical_type,
55 out s canonical_domain,
56 out t flags);
57 GetLink(in i ifindex,
58 out o path);
59 SetLinkDNS(in i ifindex,
60 in a(iay) addresses);
61 SetLinkDNSEx(in i ifindex,
62 in a(iayqs) addresses);
63 SetLinkDomains(in i ifindex,
64 in a(sb) domains);
65 SetLinkDefaultRoute(in i ifindex,
66 in b enable);
67 SetLinkLLMNR(in i ifindex,
68 in s mode);
69 SetLinkMulticastDNS(in i ifindex,
70 in s mode);
71 SetLinkDNSOverTLS(in i ifindex,
72 in s mode);
73 SetLinkDNSSEC(in i ifindex,
74 in s mode);
75 SetLinkDNSSECNegativeTrustAnchors(in i ifindex,
76 in as names);
77 RevertLink(in i ifindex);
78 RegisterService(in s name,
79 in s name_template,
80 in s type,
81 in q service_port,
82 in q service_priority,
83 in q service_weight,
84 in aa{say} txt_datas,
85 out o service_path);
86 UnregisterService(in o service_path);
87 ResetStatistics();
88 FlushCaches();
89 ResetServerFeatures();
90 properties:
91 readonly s LLMNRHostname = '...';
92 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
93 readonly s LLMNR = '...';
94 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
95 readonly s MulticastDNS = '...';
96 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
97 readonly s DNSOverTLS = '...';
98 readonly a(iiay) DNS = [...];
99 readonly a(iiayqs) DNSEx = [...];
100 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
101 readonly a(iiay) FallbackDNS = [...];
102 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
103 readonly a(iiayqs) FallbackDNSEx = [...];
104 readonly (iiay) CurrentDNSServer = ...;
105 readonly (iiayqs) CurrentDNSServerEx = ...;
106 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
107 readonly a(isb) Domains = [...];
108 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
109 readonly (tt) TransactionStatistics = ...;
110 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
111 readonly (ttt) CacheStatistics = ...;
112 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
113 readonly s DNSSEC = '...';
114 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
115 readonly (tttt) DNSSECStatistics = ...;
116 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
117 readonly b DNSSECSupported = ...;
118 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
119 readonly as DNSSECNegativeTrustAnchors = ['...', ...];
120 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
121 readonly s DNSStubListener = '...';
122 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
123 readonly s ResolvConfMode = '...';
124 };
125 interface org.freedesktop.DBus.Peer { ... };
126 interface org.freedesktop.DBus.Introspectable { ... };
127 interface org.freedesktop.DBus.Properties { ... };
128 };
129 Methods
172 ResolveHostname() takes a hostname and resolves it to one or more IP
173 addresses. As parameters it takes the Linux network interface index to
174 execute the query on, or 0 if it may be done on any suitable interface.
175 The name parameter specifies the hostname to resolve. Note that if
176 required, IDNA conversion is applied to this name unless it is resolved
177 via LLMNR or MulticastDNS. The family parameter limits the results to a
178 specific address family. It may be AF_INET, AF_INET6 or AF_UNSPEC. If
179 AF_UNSPEC is specified (recommended), both kinds are retrieved, subject
180 to local network configuration (i.e. if no local, routable IPv6 address
181 is found, no IPv6 address is retrieved; and similarly for IPv4). A
182 64-bit flags field may be used to alter the behaviour of the resolver
183 operation (see below). The method returns an array of address records.
184 Each address record consists of the interface index the address belongs
185 to, an address family as well as a byte array with the actual IP
186 address data (which either has 4 or 16 elements, depending on the
187 address family). The returned address family will be one of AF_INET or
188 AF_INET6. For IPv6, the returned address interface index should be used
189 to initialize the .sin6_scope_id field of a struct sockaddr_in6
190 instance to permit support for resolution to link-local IP addresses.
191 The address array is followed by the canonical name of the host, which
192 may or may not be identical to the resolved hostname. Finally, a 64-bit
193 flags field is returned that is defined similarly to the flags field
194 that was passed in, but contains information about the resolved data
195 (see below). If the hostname passed in is an IPv4 or IPv6 address
196 formatted as string, it is parsed, and the result is returned. In this
197 case, no network communication is done.
198 ResolveAddress() executes the reverse operation: it takes an IP address
200 and acquires one or more hostnames for it. As parameters it takes the
201 interface index to execute the query on, or 0 if all suitable
202 interfaces are OK. The family parameter indicates the address family of
203 the IP address to resolve. It may be either AF_INET or AF_INET6. The
204 address parameter takes the raw IP address data (as either a 4 or 16
205 byte array). The flags input parameter may be used to alter the
206 resolver operation (see below). The method returns an array of name
207 records, each consisting of an interface index and a hostname. The
208 flags output field contains additional information about the resolver
209 operation (see below).
210 ResolveRecord() takes a DNS resource record (RR) type, class and name,
212 and retrieves the full resource record set (RRset), including the
213 RDATA, for it. As parameter it takes the Linux network interface index
214 to execute the query on, or 0 if it may be done on any suitable
215 interface. The name parameter specifies the RR domain name to look up
216 (no IDNA conversion is applied), followed by the 16-bit class and type
217 fields (which may be ANY). Finally, a flags field may be passed in to
218 alter behaviour of the look-up (see below). On completion, an array of
219 RR items is returned. Each array entry consists of the network
220 interface index the RR was discovered on, the type and class field of
221 the RR found, and a byte array of the raw RR discovered. The raw RR
222 data starts with the RR's domain name, in the original casing, followed
223 by the RR type, class, TTL and RDATA, in the binary format documented
224 in RFC 1035[3]. For RRs that support name compression in the payload
225 (such as MX or PTR), the compression is expanded in the returned data.
226 Note that currently, the class field has to be specified as IN or ANY.
228 Specifying a different class will return an error indicating that
229 look-ups of this kind are unsupported. Similarly, some special types
230 are not supported either (AXFR, OPT, ...). While systemd-resolved
231 parses and validates resource records of many types, it is crucial that
232 clients using this API understand that the RR data originates from the
233 network and should be thoroughly validated before use.
234 ResolveService() may be used to resolve a DNS SRV service record, as
236 well as the hostnames referenced in it, and possibly an accompanying
237 DNS-SD TXT record containing additional service metadata. The primary
238 benefit of using this method over ResolveRecord() specifying the SRV
239 type is that it will resolve the SRV and TXT RRs as well as the
240 hostnames referenced in the SRV in a single operation. As parameters it
241 takes a Linux network interface index, a service name, a service type
242 and a service domain. This method may be invoked in three different
243 modes:
244 1. To resolve a DNS-SD service, specify the service name (e.g.
246 "Lennart's Files"), the service type (e.g. "_webdav._tcp") and the
247 domain to search in (e.g. "local") as the three service
248 parameters. The service name must be in UTF-8 format, and no IDNA
249 conversion is applied to it in this mode (as mandated by the DNS-SD
250 specifications). However, if necessary, IDNA conversion is applied
251 to the domain parameter.
252 2. To resolve a plain SRV record, set the service name parameter to
254 the empty string and set the service type and domain properly.
255 (IDNA conversion is applied to the domain, if necessary.)
256 3. Alternatively, leave both the service name and type empty and
258 specify the full domain name of the SRV record (i.e. prefixed with
259 the service type) in the domain parameter. (No IDNA conversion is
260 applied in this mode.)
261 The family parameter of the ResolveService() method encodes the desired
263 family of the addresses to resolve (use AF_INET, AF_INET6, or
264 AF_UNSPEC). If this is enabled (Use the NO_ADDRESS flag to turn address
265 resolution off, see below). The flags parameter takes a couple of flags
266 that may be used to alter the resolver operation.
267 On completion, ResolveService() returns an array of SRV record
269 structures. Each items consisting of the priority, weight and port
270 fields as well as the hostname to contact, as encoded in the SRV
271 record. Immediately following is an array of the addresses of this
272 hostname, with each item consisting of the interface index, the address
273 family and the address data in a byte array. This address array is
274 followed by the canonicalized hostname. After this array of SRV record
275 structures an array of byte arrays follows that encodes the TXT RR
276 strings, in case DNS-SD look-ups are enabled. The next parameters are
277 the canonical service name, type and domain. This may or may not be
278 identical to the parameters passed in. Finally, a flags field is
279 returned that contains information about the resolver operation
280 performed.
281 The ResetStatistics() method resets the various statistics counters
283 that systemd-resolved maintains to zero. (For details, see the
284 statistics properties below.)
285 The GetLink() method takes a network interface index and returns the
287 object path to the org.freedesktop.resolve1.Link object corresponding
288 to it.
289 The SetLinkDNS() method sets the DNS servers to use on a specific
291 interface. This method (and the following ones) may be used by network
292 management software to configure per-interface DNS settings. It takes a
293 network interface index as well as an array of DNS server IP address
294 records. Each array item consists of an address family (either AF_INET
295 or AF_INET6), followed by a 4-byte or 16-byte array with the raw
296 address data. This method is a one-step shortcut for retrieving the
297 Link object for a network interface using GetLink() (see above) and
298 then invoking the SetDNS() method (see below) on it.
299 SetLinkDNSEx() is similar to SetLinkDNS(), but allows an IP port
301 (instead of the default 53) and DNS name to be specified for each DNS
302 server. The server name is used for Server Name Indication (SNI), which
303 is useful when DNS-over-TLS is used. C.f. DNS= in resolved.conf(5).
304 SetLinkDefaultRoute() specifies whether the link shall be used as the
306 default route for name queries. See the description of name routing in
307 systemd-resolved.service(8) for details.
308 The SetLinkDomains() method sets the search and routing domains to use
310 on a specific network interface for DNS look-ups. It takes a network
311 interface index and an array of domains, each with a boolean parameter
312 indicating whether the specified domain shall be used as a search
313 domain (false), or just as a routing domain (true). Search domains are
314 used for qualifying single-label names into FQDN when looking up
315 hostnames, as well as for making routing decisions on which interface
316 to send queries ending in the domain to. Routing domains are only used
317 for routing decisions and not used for single-label name qualification.
318 Pass the search domains in the order they should be used.
319 The SetLinkLLMNR() method enables or disables LLMNR support on a
321 specific network interface. It takes a network interface index as well
322 as a string that may either be empty or one of "yes", "no" or
323 "resolve". If empty, the systemd-wide default LLMNR setting is used. If
324 "yes", LLMNR is used for resolution of single-label names and the local
325 hostname is registered on all local LANs for LLMNR resolution by peers.
326 If "no", LLMNR is turned off fully on this interface. If "resolve",
327 LLMNR is only enabled for resolving names, but the local hostname is
328 not registered for other peers to use.
329 Similarly, the SetLinkMulticastDNS() method enables or disables
331 MulticastDNS support on a specific interface. It takes the same
332 parameters as SetLinkLLMNR() described above.
333 The SetLinkDNSSEC() method enables or disables DNSSEC validation on a
335 specific network interface. It takes a network interface index as well
336 as a string that may either be empty or one of "yes", "no", or
337 "allow-downgrade". When empty, the system-wide default DNSSEC setting
338 is used. If "yes", full DNSSEC validation is done for all look-ups. If
339 the selected DNS server does not support DNSSEC, look-ups will fail if
340 this mode is used. If "no", DNSSEC validation is fully disabled. If
341 "allow-downgrade", DNSSEC validation is enabled, but is turned off
342 automatically if the selected server does not support it (thus opening
343 up behaviour to downgrade attacks). Note that DNSSEC only applies to
344 traditional DNS, not to LLMNR or MulticastDNS.
345 The SetLinkDNSSECNegativeTrustAnchors() method may be used to configure
347 DNSSEC Negative Trust Anchors (NTAs) for a specific network interface.
348 It takes a network interface index and a list of domains as arguments.
349 The SetLinkDNSOverTLS() method enables or disables DNS-over-TLS. C.f.
351 DNSOverTLS= in systemd-resolved.service(8) for details.
352 Network management software integrating with systemd-resolved should
354 call SetLinkDNS() or SetLinkDNSEx(), SetLinkDefaultRoute(),
355 SetLinkDomains() and others after the interface appeared in the kernel
356 (and thus after a network interface index has been assigned), but
357 before the network interfaces is activated (IFF_UP set) so that all
358 settings take effect during the full time the network interface is up.
359 It is safe to alter settings while the interface is up, however. Use
360 RevertLink() (described below) to reset all per-interface settings.
361 The RevertLink() method may be used to revert all per-link settings
363 described above to the defaults.
364 The Flags Parameter
366 The four methods above accept and return a 64-bit flags value. In
367 most cases passing 0 is sufficient and recommended. However, the
368 following flags are defined to alter the look-up:
369 #define SD_RESOLVED_DNS (UINT64_C(1) << 0)
371 #define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) << 1)
372 #define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) << 2)
373 #define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) << 3)
374 #define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) << 4)
375 #define SD_RESOLVED_NO_CNAME (UINT64_C(1) << 5)
376 #define SD_RESOLVED_NO_TXT (UINT64_C(1) << 6)
377 #define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) << 7)
378 #define SD_RESOLVED_NO_SEARCH (UINT64_C(1) << 8)
379 #define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9)
380 #define SD_RESOLVED_NO_VALIDATE (UINT64_C(1) << 10)
381 #define SD_RESOLVED_NO_SYNTHESIZE (UINT64_C(1) << 11)
382 #define SD_RESOLVED_NO_CACHE (UINT64_C(1) << 12)
383 #define SD_RESOLVED_NO_ZONE (UINT64_C(1) << 13)
384 #define SD_RESOLVED_NO_TRUST_ANCHOR (UINT64_C(1) << 14)
385 #define SD_RESOLVED_NO_NETWORK (UINT64_C(1) << 15)
386 #define SD_RESOLVED_REQUIRE_PRIMARY (UINT64_C(1) << 16)
387 #define SD_RESOLVED_CLAMP_TTL (UINT64_C(1) << 17)
388 #define SD_RESOLVED_CONFIDENTIAL (UINT64_C(1) << 18)
389 #define SD_RESOLVED_SYNTHETIC (UINT64_C(1) << 19)
390 #define SD_RESOLVED_FROM_CACHE (UINT64_C(1) << 20)
391 #define SD_RESOLVED_FROM_ZONE (UINT64_C(1) << 21)
392 #define SD_RESOLVED_FROM_TRUST_ANCHOR (UINT64_C(1) << 22)
393 #define SD_RESOLVED_FROM_NETWORK (UINT64_C(1) << 23)
394 On input, the first five flags control the protocols to use for the
397 look-up. They refer to classic unicast DNS, LLMNR via IPv4/UDP and
398 IPv6/UDP respectively, as well as MulticastDNS via IPv4/UDP and
399 IPv6/UDP. If all of these five bits are off on input (which is
400 strongly recommended) the look-up will be done via all suitable
401 protocols for the specific look-up. Note that these flags operate
402 as filter only, but cannot force a look-up to be done via a
403 protocol. Specifically, systemd-resolved will only route look-ups
404 within the .local TLD to MulticastDNS (plus some reverse look-up
405 address domains), and single-label names to LLMNR (plus some
406 reverse address lookup domains). It will route neither of these to
407 Unicast DNS servers. Also, it will do LLMNR and Multicast DNS only
408 on interfaces suitable for multicast.
409 On output, these five flags indicate which protocol was used to
411 execute the operation, and hence where the data was found.
412 The primary use cases for these five flags are follow-up look-ups
414 based on DNS data retrieved earlier. In this case it is often a
415 good idea to limit the follow-up look-up to the protocol that was
416 used to discover the first DNS result.
417 The NO_CNAME flag controls whether CNAME/DNAME resource records
419 shall be followed during the look-up. This flag is only available
420 at input, none of the functions will return it on output. If a
421 CNAME/DNAME RR is discovered while resolving a hostname, an error
422 is returned instead. By default, when the flag is off, CNAME/DNAME
423 RRs are followed.
424 The NO_TXT and NO_ADDRESS flags only influence operation of the
426 ResolveService() method. They are only defined for input, not
427 output. If NO_TXT is set, the DNS-SD TXT RR look-up is not done in
428 the same operation. If NO_ADDRESS is set, the discovered hostnames
429 are not implicitly translated to their addresses.
430 The NO_SEARCH flag turns off the search domain logic. It is only
432 defined for input in ResolveHostname(). When specified,
433 single-label hostnames are not qualified using defined search
434 domains, if any are configured. Note that ResolveRecord() will
435 never qualify single-label domain names using search domains. Also
436 note that multi-label hostnames are never subject to search list
437 expansion.
438 The AUTHENTICATED bit is defined only in the output flags of the
440 four functions. If set, the returned data has been fully
441 authenticated. Specifically, this bit is set for all
442 DNSSEC-protected data for which a full trust chain may be
443 established to a trusted domain anchor. It is also set for locally
444 synthesized data, such as "localhost" or data from /etc/hosts.
445 Moreover, it is set for all LLMNR or mDNS RRs which originate from
446 the local host. Applications that require authenticated RR data for
447 operation should check this flag before trusting the data. Note
448 that systemd-resolved will never return invalidated data, hence
449 this flag simply allows one to discern the cases where data is
450 known to be trusted, or where there is proof that the data is
451 "rightfully" unauthenticated (which includes cases where the
452 underlying protocol or server does not support authenticating
453 data).
454 NO_VALIDATE can be set to disable validation via DNSSEC even if it
456 would normally be used.
457 The next four flags allow disabling certain sources during
459 resolution. NO_SYNTHESIZE disables synthetic records, e.g. the
460 local host name, see section SYNTHETIC RECORDS in systemd-
461 resolved.service(8) for more information. NO_CACHE disables the use
462 of the cache of previously resolved records. NO_ZONE disables
463 answers using locally registered public LLMNR/mDNS resource
464 records. NO_TRUST_ANCHOR disables answers using locally configured
465 trust anchors. NO_NETWORK requires all answers to be provided
466 without using the network, i.e. either from local sources or the
467 cache.
468 With REQUIRE_PRIMARY the request must be answered from a "primary"
470 answer, i.e. not from resource records acquired as a side-effect of
471 a previous transaction.
472 With CLAMP_TTL, if reply is answered from cache, the TTLs will be
474 adjusted by age of cache entry.
475 The next six bits flags are used in output and provide information
477 about the source of the answer. CONFIDENTIAL means the query was
478 resolved via encrypted channels or never left this system.
479 FROM_SYNTHETIC means the query was (at least partially)
480 synthesized. FROM_CACHE means the query was answered (at least
481 partially) using the cache. FROM_ZONE means the query was answered
482 (at least partially) using LLMNR/mDNS. FROM_TRUST_ANCHOR means the
483 query was answered (at least partially) using local trust anchors.
484 FROM_NETWORK means the query was answered (at least partially)
485 using the network.
486 Properties
488 The LLMNR and MulticastDNS properties report whether LLMNR and
489 MulticastDNS are (globally) enabled. Each may be one of "yes", "no",
490 and "resolve". See SetLinkLLMNR() and SetLinkMulticastDNS() above.
491 LLMNRHostname contains the hostname currently exposed on the network
493 via LLMNR. It usually follows the system hostname as may be queried via
494 gethostname(3), but may differ if a conflict is detected on the
495 network.
496 DNS and DNSEx contain arrays of all DNS servers currently used by
498 systemd-resolved. DNS contains information similar to the DNS server
499 data in /run/systemd/resolve/resolv.conf. Each structure in the array
500 consists of a numeric network interface index, an address family, and a
501 byte array containing the DNS server address (either 4 bytes in length
502 for IPv4 or 16 bytes in lengths for IPv6). DNSEx is similar, but
503 additionally contains the IP port and server name (used for Server Name
504 Indication, SNI). Both arrays contain DNS servers configured
505 system-wide, including those possibly read from a foreign
506 /etc/resolv.conf or the DNS= setting in /etc/systemd/resolved.conf, as
507 well as per-interface DNS server information either retrieved from
508 systemd-networkd(8), or configured by external software via
509 SetLinkDNS() or SetLinkDNSEx() (see above). The network interface index
510 will be 0 for the system-wide configured services and non-zero for the
511 per-link servers.
512 FallbackDNS and FallbackDNSEx contain arrays of all DNS servers
514 configured as fallback servers, if any, using the same format as DNS
515 and DNSEx described above. See the description of FallbackDNS= in
516 resolved.conf(5) for the description of when those servers are used.
517 CurrentDNSServer and CurrentDNSServerEx specify the server that is
519 currently used for query resolution, in the same format as a single
520 entry in the DNS and DNSEx arrays described above.
521 Similarly, the Domains property contains an array of all search and
523 routing domains currently used by systemd-resolved. Each entry consists
524 of a network interface index (again, 0 encodes system-wide entries),
525 the actual domain name, and whether the entry is used only for routing
526 (true) or for both routing and searching (false).
527 The TransactionStatistics property contains information about the
529 number of transactions systemd-resolved has processed. It contains a
530 pair of unsigned 64-bit counters, the first containing the number of
531 currently ongoing transactions, the second the number of total
532 transactions systemd-resolved is processing or has processed. The
533 latter value may be reset using the ResetStatistics() method described
534 above. Note that the number of transactions does not directly map to
535 the number of issued resolver bus method calls. While simple look-ups
536 usually require a single transaction only, more complex look-ups might
537 result in more, for example when CNAMEs or DNSSEC are in use.
538 The CacheStatistics property contains information about the executed
540 cache operations so far. It exposes three 64-bit counters: the first
541 being the total number of current cache entries (both positive and
542 negative), the second the number of cache hits, and the third the
543 number of cache misses. The latter counters may be reset using
544 ResetStatistics() (see above).
545 The DNSSEC property specifies current status of DNSSEC validation. It
547 is one of "yes" (validation is enforced), "no" (no validation is done),
548 "allow-downgrade" (validation is done if the current DNS server
549 supports it). See the description of DNSSEC= in resolved.conf(5).
550 The DNSSECStatistics property contains information about the DNSSEC
552 validations executed so far. It contains four 64-bit counters: the
553 number of secure, insecure, bogus, and indeterminate DNSSEC validations
554 so far. The counters are increased for each validated RRset, and each
555 non-existence proof. The secure counter is increased for each operation
556 that successfully verified a signed reply, the insecure counter is
557 increased for each operation that successfully verified that an
558 unsigned reply is rightfully unsigned. The bogus counter is increased
559 for each operation where the validation did not check out and the data
560 is likely to have been tempered with. Finally the indeterminate counter
561 is increased for each operation which did not complete because the
562 necessary keys could not be acquired or the cryptographic algorithms
563 were unknown.
564 The DNSSECSupported boolean property reports whether DNSSEC is enabled
566 and the selected DNS servers support it. It combines information about
567 system-wide and per-link DNS settings (see below), and only reports
568 true if DNSSEC is enabled and supported on every interface for which
569 DNS is configured and for the system-wide settings if there are any.
570 Note that systemd-resolved assumes DNSSEC is supported by DNS servers
571 until it verifies that this is not the case. Thus, the reported value
572 may initially be true, until the first transactions are executed.
573 The DNSOverTLS boolean property reports whether DNS-over-TLS is
575 enabled.
576 The ResolvConfMode property exposes how /etc/resolv.conf is managed on
578 the host. Currently, the values "uplink", "stub", "static" (these three
579 correspond to the three different files systemd-resolved.service
580 provides), "foreign" (the file is managed by admin or another service,
581 systemd-resolved.service just consumes it), "missing" (/etc/resolv.conf
582 is missing).
583 The DNSStubListener property reports whether the stub listener on port
585 53 is enabled. Possible values are "yes" (enabled), "no" (disabled),
586 "udp" (only the UDP listener is enabled), and "tcp" (only the TCP
587 listener is enabled).
588
590 node /org/freedesktop/resolve1/link/_1 {
591 interface org.freedesktop.resolve1.Link {
592 methods:
593 SetDNS(in a(iay) addresses);
594 SetDNSEx(in a(iayqs) addresses);
595 SetDomains(in a(sb) domains);
596 SetDefaultRoute(in b enable);
597 SetLLMNR(in s mode);
598 SetMulticastDNS(in s mode);
599 SetDNSOverTLS(in s mode);
600 SetDNSSEC(in s mode);
601 SetDNSSECNegativeTrustAnchors(in as names);
602 Revert();
603 properties:
604 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
605 readonly t ScopesMask = ...;
606 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
607 readonly a(iay) DNS = [...];
608 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
609 readonly a(iayqs) DNSEx = [...];
610 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
611 readonly (iay) CurrentDNSServer = ...;
612 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
613 readonly (iayqs) CurrentDNSServerEx = ...;
614 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
615 readonly a(sb) Domains = [...];
616 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
617 readonly b DefaultRoute = ...;
618 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
619 readonly s LLMNR = '...';
620 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
621 readonly s MulticastDNS = '...';
622 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
623 readonly s DNSOverTLS = '...';
624 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
625 readonly s DNSSEC = '...';
626 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
627 readonly as DNSSECNegativeTrustAnchors = ['...', ...];
628 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
629 readonly b DNSSECSupported = ...;
630 };
631 interface org.freedesktop.DBus.Peer { ... };
632 interface org.freedesktop.DBus.Introspectable { ... };
633 interface org.freedesktop.DBus.Properties { ... };
634 };
635 For each Linux network interface a "Link" object is created which
663 exposes per-link DNS configuration and state. Use GetLink() on the
664 Manager interface to retrieve the object path for a link object given
665 the network interface index (see above).
666 Methods
668 The various methods exposed by the Link interface are equivalent to
669 their similarly named counterparts on the Manager interface. e.g.
670 SetDNS() on the Link object maps to SetLinkDNS() on the Manager object,
671 the main difference being that the later expects an interface index to
672 be specified. Invoking the methods on the Manager interface has the
673 benefit of reducing roundtrips, as it is not necessary to first request
674 the Link object path via GetLink() before invoking the methods. The
675 same relationship holds for SetDNSEx(), SetDomains(),
676 SetDefaultRoute(), SetLLMNR(), SetMulticastDNS(), SetDNSOverTLS(),
677 SetDNSSEC(), SetDNSSECNegativeTrustAnchors(), and Revert(). For further
678 details on these methods see the Manager documentation above.
679 Properties
681 ScopesMask defines which resolver scopes are currently active on this
682 interface. This 64-bit unsigned integer field is a bit mask consisting
683 of a subset of the bits of the flags parameter describe above.
684 Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in
685 IPv4 and IPv6 flavours) set. Each individual bit is set when the
686 protocol applies to a specific interface and is enabled for it. It is
687 unset otherwise. Specifically, a multicast-capable interface in the
688 "UP" state with an IP address is suitable for LLMNR or MulticastDNS,
689 and any interface that is UP and has an IP address is suitable for DNS.
690 Note the relationship of the bits exposed here with the LLMNR and
691 MulticastDNS properties also exposed on the Link interface. The latter
692 expose what is *configured* to be used on the interface, the former
693 expose what is actually used on the interface, taking into account the
694 abilities of the interface.
695 DNSSECSupported exposes a boolean field that indicates whether DNSSEC
697 is currently configured and in use on the interface. Note that if
698 DNSSEC is enabled on an interface, it is assumed available until it is
699 detected that the configured server does not actually support it. Thus,
700 this property may initially report that DNSSEC is supported on an
701 interface.
702 DefaultRoute exposes a boolean field that indicates whether the
704 interface will be used as default route for name queries. See
705 SetLinkDefaultRoute() above.
706 The other properties reflect the state of the various configuration
708 settings for the link which may be set with the various methods calls
709 such as SetDNS() or SetLLMNR().
710
712 Many bus methods systemd-resolved exposes (in particular the resolver
713 methods such as ResolveHostname() on the Manager interface) may return
714 some of the following errors:
715 org.freedesktop.resolve1.NoNameServers
717 No suitable DNS servers were found to resolve a request.
718 org.freedesktop.resolve1.InvalidReply
720 A response from the selected DNS server was not understood.
721 org.freedesktop.resolve1.NoSuchRR
723 The requested name exists, but there is no resource record of the
724 requested type for it. (This is the DNS NODATA case).
725 org.freedesktop.resolve1.CNameLoop
727 The look-up failed because a CNAME or DNAME loop was detected.
728 org.freedesktop.resolve1.Aborted
730 The look-up was aborted because the selected protocol became
731 unavailable while the operation was ongoing.
732 org.freedesktop.resolve1.NoSuchService
734 A service look-up was successful, but the SRV record reported that
735 the service is not available.
736 org.freedesktop.resolve1.DnssecFailed
738 The acquired response did not pass DNSSEC validation.
739 org.freedesktop.resolve1.NoTrustAnchor
741 No chain of trust could be established for the response to a
742 configured DNSSEC trust anchor.
743 org.freedesktop.resolve1.ResourceRecordTypeUnsupported
745 The requested resource record type is not supported on the selected
746 DNS servers. This error is generated for example when an RRSIG
747 record is requested from a DNS server that does not support DNSSEC.
748 org.freedesktop.resolve1.NoSuchLink
750 No network interface with the specified network interface index
751 exists.
752 org.freedesktop.resolve1.LinkBusy
754 The requested configuration change could not be made because
755 systemd-networkd(8), already took possession of the interface and
756 supplied configuration data for it.
757 org.freedesktop.resolve1.NetworkDown
759 The requested look-up failed because the system is currently not
760 connected to any suitable network.
761 org.freedesktop.resolve1.DnsError.NXDOMAIN,
763 org.freedesktop.resolve1.DnsError.REFUSED, ...
764 The look-up failed with a DNS return code reporting a failure. The
765 error names used as suffixes here are defined in by IANA in
766 DNS RCODEs[4].
767
769 Example 1. Introspect org.freedesktop.resolve1.Manager on the bus
770 $ gdbus introspect --system \
772 --dest org.freedesktop.resolve1 \
773 --object-path /org/freedesktop/resolve1
774 Example 2. Introspect org.freedesktop.resolve1.Link on the bus
777 $ gdbus introspect --system \
779 --dest org.freedesktop.resolve1 \
780 --object-path /org/freedesktop/resolve1/link/_11
781
784 These D-Bus interfaces follow the usual interface versioning
785 guidelines[5].
786
788 1. Writing Network Configuration Managers
789 https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers
790 2. Writing Resolver Clients
792 https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients
793 3. RFC 1035
795 https://www.ietf.org/rfc/rfc1035.txt
796 4. DNS RCODEs
798 https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
799 5. the usual interface versioning guidelines
801 https://0pointer.de/blog/projects/versioning-dbus.html
802systemd 253 ORG.FREEDESKTOP.RESOLVE1(5)