1ORG.FREEDESKTOP.RESOLVE1(5)org.freedesktop.resolve1ORG.FREEDESKTOP.RESOLVE1(5)
2
3
4

NAME

6       org.freedesktop.resolve1 - The D-Bus interface of systemd-resolved
7

INTRODUCTION

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
14       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

THE MANAGER OBJECT

19       The service exposes the following interfaces on the Manager object on
20       the bus:
21
22           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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171   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
199       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
211       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
227       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
235       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
245        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
253        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
257        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
262       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
268       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
282       The ResetStatistics() method resets the various statistics counters
283       that systemd-resolved maintains to zero. (For details, see the
284       statistics properties below.)
285
286       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
290       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
300       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
305       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
309       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
320       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
330       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
334       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
346       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
350       The SetLinkDNSOverTLS() method enables or disables DNS-over-TLS. C.f.
351       DNSOverTLS= in systemd-resolved.service(8) for details.
352
353       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
362       The RevertLink() method may be used to revert all per-link settings
363       described above to the defaults.
364
365       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
370               #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
395
396           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
410           On output, these five flags indicate which protocol was used to
411           execute the operation, and hence where the data was found.
412
413           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
418           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
425           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
431           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
439           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
455           NO_VALIDATE can be set to disable validation via DNSSEC even if it
456           would normally be used.
457
458           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
469           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
473           With CLAMP_TTL, if reply is answered from cache, the TTLs will be
474           adjusted by age of cache entry.
475
476           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
487   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
492       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
497       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
513       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
518       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
522       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
528       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
539       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
546       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
551       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-existance 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
565       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
574       The DNSOverTLS boolean property reports whether DNS-over-TLS is
575       enabled.
576
577       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
584       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
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662       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
667   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
680   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
696       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
703       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
707       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

COMMON ERRORS

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
716       org.freedesktop.resolve1.NoNameServers
717           No suitable DNS servers were found to resolve a request.
718
719       org.freedesktop.resolve1.InvalidReply
720           A response from the selected DNS server was not understood.
721
722       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
726       org.freedesktop.resolve1.CNameLoop
727           The look-up failed because a CNAME or DNAME loop was detected.
728
729       org.freedesktop.resolve1.Aborted
730           The look-up was aborted because the selected protocol became
731           unavailable while the operation was ongoing.
732
733       org.freedesktop.resolve1.NoSuchService
734           A service look-up was successful, but the SRV record reported that
735           the service is not available.
736
737       org.freedesktop.resolve1.DnssecFailed
738           The acquired response did not pass DNSSEC validation.
739
740       org.freedesktop.resolve1.NoTrustAnchor
741           No chain of trust could be established for the response to a
742           configured DNSSEC trust anchor.
743
744       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
749       org.freedesktop.resolve1.NoSuchLink
750           No network interface with the specified network interface index
751           exists.
752
753       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
758       org.freedesktop.resolve1.NetworkDown
759           The requested look-up failed because the system is currently not
760           connected to any suitable network.
761
762       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

EXAMPLES

769       Example 1. Introspect org.freedesktop.resolve1.Manager on the bus
770
771           $ gdbus introspect --system \
772             --dest org.freedesktop.resolve1 \
773             --object-path /org/freedesktop/resolve1
774
775
776       Example 2. Introspect org.freedesktop.resolve1.Link on the bus
777
778           $ gdbus introspect --system \
779             --dest org.freedesktop.resolve1 \
780             --object-path /org/freedesktop/resolve1/link/_11
781
782

VERSIONING

784       These D-Bus interfaces follow the usual interface versioning
785       guidelines[5].
786

NOTES

788        1. Writing Network Configuration Managers
789           https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers
790
791        2. Writing Resolver Clients
792           https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients
793
794        3. RFC 1035
795           https://www.ietf.org/rfc/rfc1035.txt
796
797        4. DNS RCODEs
798           https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6
799
800        5. the usual interface versioning guidelines
801           http://0pointer.de/blog/projects/versioning-dbus.html
802
803
804
805systemd 251                                        ORG.FREEDESKTOP.RESOLVE1(5)
Impressum