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