Debian Codegraph @

upstream/debian-unstable/man5/org.freedesktop.resolve1.5

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