summaryrefslogtreecommitdiffstats
path: root/man/org.freedesktop.resolve1.xml
blob: f6b70d6e4f4d75a36a72b3da28191347bc22b3e5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
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
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
<?xml version="1.0"?>
<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="org.freedesktop.resolve1" conditional='ENABLE_RESOLVE'
    xmlns:xi="http://www.w3.org/2001/XInclude">
  <refentryinfo>
    <title>org.freedesktop.resolve1</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>org.freedesktop.resolve1</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>org.freedesktop.resolve1</refname>
    <refpurpose>The D-Bus interface of systemd-resolved</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Introduction</title>

    <para>
    <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    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.</para>

    <para>This page contains an API reference only. If you are looking for a longer explanation how to use
    this API, please consult
    <ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-network-configuration-managers">
    Writing Network Configuration Managers</ulink> and
    <ulink url="https://wiki.freedesktop.org/www/Software/systemd/writing-resolver-clients">Writing Resolver
    Clients</ulink>.
    </para>
  </refsect1>

  <refsect1>
    <title>The Manager Object</title>

    <para>The service exposes the following interfaces on the Manager object on the bus:</para>

    <programlisting executable="systemd-resolved" node="/org/freedesktop/resolve1" interface="org.freedesktop.resolve1.Manager">
node /org/freedesktop/resolve1 {
  interface org.freedesktop.resolve1.Manager {
    methods:
      ResolveHostname(in  i ifindex,
                      in  s name,
                      in  i family,
                      in  t flags,
                      out a(iiay) addresses,
                      out s canonical,
                      out t flags);
      ResolveAddress(in  i ifindex,
                     in  i family,
                     in  ay address,
                     in  t flags,
                     out a(is) names,
                     out t flags);
      ResolveRecord(in  i ifindex,
                    in  s name,
                    in  q class,
                    in  q type,
                    in  t flags,
                    out a(iqqay) records,
                    out t flags);
      ResolveService(in  i ifindex,
                     in  s name,
                     in  s type,
                     in  s domain,
                     in  i family,
                     in  t flags,
                     out a(qqqsa(iiay)s) srv_data,
                     out aay txt_data,
                     out s canonical_name,
                     out s canonical_type,
                     out s canonical_domain,
                     out t flags);
      GetLink(in  i ifindex,
              out o path);
      SetLinkDNS(in  i ifindex,
                 in  a(iay) addresses);
      SetLinkDNSEx(in  i ifindex,
                   in  a(iayqs) addresses);
      SetLinkDomains(in  i ifindex,
                     in  a(sb) domains);
      SetLinkDefaultRoute(in  i ifindex,
                          in  b enable);
      SetLinkLLMNR(in  i ifindex,
                   in  s mode);
      SetLinkMulticastDNS(in  i ifindex,
                          in  s mode);
      SetLinkDNSOverTLS(in  i ifindex,
                        in  s mode);
      SetLinkDNSSEC(in  i ifindex,
                    in  s mode);
      SetLinkDNSSECNegativeTrustAnchors(in  i ifindex,
                                        in  as names);
      RevertLink(in  i ifindex);
      RegisterService(in  s id,
                      in  s name_template,
                      in  s type,
                      in  q service_port,
                      in  q service_priority,
                      in  q service_weight,
                      in  aa{say} txt_datas,
                      out o service_path);
      UnregisterService(in  o service_path);
      ResetStatistics();
      FlushCaches();
      ResetServerFeatures();
    properties:
      readonly s LLMNRHostname = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s LLMNR = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s MulticastDNS = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s DNSOverTLS = '...';
      readonly a(iiay) DNS = [...];
      readonly a(iiayqs) DNSEx = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly a(iiay) FallbackDNS = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly a(iiayqs) FallbackDNSEx = [...];
      readonly (iiay) CurrentDNSServer = ...;
      readonly (iiayqs) CurrentDNSServerEx = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly a(isb) Domains = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly (tt) TransactionStatistics = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly (ttt) CacheStatistics = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s DNSSEC = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly (tttt) DNSSECStatistics = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly b DNSSECSupported = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly as DNSSECNegativeTrustAnchors = ['...', ...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s DNSStubListener = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s ResolvConfMode = '...';
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};
    </programlisting>

    <!--Autogenerated cross-references for systemd.directives, do not edit-->

    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>

    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>

    <variablelist class="dbus-method" generated="True" extra-ref="ResolveHostname()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="ResolveAddress()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="ResolveRecord()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="ResolveService()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="GetLink()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNS()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSEx()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDomains()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDefaultRoute()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkLLMNR()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkMulticastDNS()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSOverTLS()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSEC()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLinkDNSSECNegativeTrustAnchors()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="RevertLink()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="RegisterService()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="UnregisterService()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="ResetStatistics()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="FlushCaches()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="ResetServerFeatures()"/>

    <variablelist class="dbus-property" generated="True" extra-ref="LLMNRHostname"/>

    <variablelist class="dbus-property" generated="True" extra-ref="LLMNR"/>

    <variablelist class="dbus-property" generated="True" extra-ref="MulticastDNS"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSOverTLS"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNS"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSEx"/>

    <variablelist class="dbus-property" generated="True" extra-ref="FallbackDNS"/>

    <variablelist class="dbus-property" generated="True" extra-ref="FallbackDNSEx"/>

    <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServer"/>

    <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServerEx"/>

    <variablelist class="dbus-property" generated="True" extra-ref="Domains"/>

    <variablelist class="dbus-property" generated="True" extra-ref="TransactionStatistics"/>

    <variablelist class="dbus-property" generated="True" extra-ref="CacheStatistics"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSSEC"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSSECStatistics"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSSECSupported"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSSECNegativeTrustAnchors"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSStubListener"/>

    <variablelist class="dbus-property" generated="True" extra-ref="ResolvConfMode"/>

    <!--End of Autogenerated section-->

    <refsect2>
      <title>Methods</title>

      <para><function>ResolveHostname()</function> 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 <varname>name</varname> 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 <varname>family</varname> parameter limits the results to a specific address
      family. It may be <constant>AF_INET</constant>, <constant>AF_INET6</constant> or
      <constant>AF_UNSPEC</constant>. If <constant>AF_UNSPEC</constant> 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 <varname>flags</varname> 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
      <constant>AF_INET</constant> or <constant>AF_INET6</constant>. For IPv6, the returned address interface
      index should be used to initialize the .sin6_scope_id field of a
      <structname>struct sockaddr_in6</structname> 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 <varname>flags</varname> field is returned that
      is defined similarly to the <varname>flags</varname> 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.</para>

      <para><function>ResolveAddress()</function> 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 <constant>0</constant> if all suitable interfaces are OK. The <varname>family</varname>
      parameter indicates the address family of the IP address to resolve. It may be either
      <constant>AF_INET</constant> or <constant>AF_INET6</constant>. The <varname>address</varname> parameter
      takes the raw IP address data (as either a 4 or 16 byte array). The <varname>flags</varname> 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 <varname>flags</varname> output
      field contains additional information about the resolver operation (see below).</para>

      <para><function>ResolveRecord()</function> 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 <constant>0</constant> if it may be done on
      any suitable interface. The <varname>name</varname> 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 <varname>flags</varname> 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 type and class field of the RR found, and a byte array of the raw
      RR discovered. The raw RR data starts with the RR's domain name, in the original casing, followed
      by the RR type, class, TTL and RDATA, in the binary format documented in
      <ulink url="https://www.ietf.org/rfc/rfc1035.txt">RFC 1035</ulink>. For RRs that support name
      compression in the payload (such as MX or PTR), the compression is expanded in the returned
      data.</para>

      <para>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 <filename>systemd-resolved</filename> 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.</para>

      <para><function>ResolveService()</function> may be used to resolve a DNS
      <constant class="dns">SRV</constant> service record, as well as the hostnames referenced in it, and
      possibly an accompanying DNS-SD <constant class="dns">TXT</constant> record containing additional
      service metadata.  The primary benefit of using this method over <function>ResolveRecord()</function>
      specifying the <constant class="dns">SRV</constant> type is that it will resolve the
      <constant class="dns">SRV</constant> and <constant class="dns">TXT</constant> 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:</para>

      <orderedlist>
        <listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
        Files</literal>), the service type (e.g. <literal>_webdav._tcp</literal>) and the domain to search in
        (e.g. <literal>local</literal>) 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.</para>
        </listitem>

        <listitem><para>To resolve a plain <constant class="dns">SRV</constant> 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.)</para></listitem>

        <listitem><para>Alternatively, leave both the service name and type empty and specify the full domain
        name of the <constant class="dns">SRV</constant> record (i.e. prefixed with the service type) in the
        domain parameter. (No IDNA conversion is applied in this mode.)</para></listitem>
      </orderedlist>

      <para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
      the desired family of the addresses to resolve (use <constant>AF_INET</constant>,
      <constant>AF_INET6</constant>, or <constant>AF_UNSPEC</constant>). If this is enabled (Use the
      <constant>NO_ADDRESS</constant> flag to turn address resolution off, see below). The
      <varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
      operation.</para>

      <para>On completion, <function>ResolveService()</function> returns an array of
      <constant class="dns">SRV</constant> record structures. Each items consisting of the priority, weight and port
      fields as well as the hostname to contact, as encoded in the <constant class="dns">SRV</constant>
      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 <constant class="dns">SRV</constant> 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 <varname>flags</varname> field is returned that
      contains information about the resolver operation performed.</para>

      <para>The <function>ResetStatistics()</function> method resets the various statistics counters that
      <filename>systemd-resolved</filename> maintains to zero. (For details, see the statistics properties below.)</para>

      <para>The <function>GetLink()</function> method takes a network interface index and returns the object
      path to the <interfacename>org.freedesktop.resolve1.Link</interfacename> object corresponding to it.
      </para>

      <para>The <function>SetLinkDNS()</function> 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 <constant>AF_INET</constant> or
      <constant>AF_INET6</constant>), 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
      <function>GetLink()</function> (see above) and then invoking the <function>SetDNS()</function> method
      (see below) on it.</para>

      <para><function>SetLinkDNSEx()</function> is similar to <function>SetLinkDNS()</function>, 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. <varname>DNS=</varname> in
      <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
      </para>

      <para><function>SetLinkDefaultRoute()</function> specifies whether the link shall be used as the
      default route for name queries. See the description of name routing in
      <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      for details.</para>

      <para>The <function>SetLinkDomains()</function> 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.</para>

      <para>The <function>SetLinkLLMNR()</function> 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
      <literal>yes</literal>, <literal>no</literal> or <literal>resolve</literal>. If empty, the systemd-wide
      default LLMNR setting is used. If <literal>yes</literal>, 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
      <literal>no</literal>, LLMNR is turned off fully on this interface. If <literal>resolve</literal>, LLMNR
      is only enabled for resolving names, but the local hostname is not registered for other peers to
      use.</para>

      <para>Similarly, the <function>SetLinkMulticastDNS()</function> method enables or disables MulticastDNS
      support on a specific interface. It takes the same parameters as <function>SetLinkLLMNR()</function>
      described above.</para>

      <para>The <function>SetLinkDNSSEC()</function> 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 <literal>yes</literal>, <literal>no</literal>, or <literal>allow-downgrade</literal>. When
      empty, the system-wide default DNSSEC setting is used. If <literal>yes</literal>, 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 <literal>no</literal>, DNSSEC validation is fully disabled. If
      <literal>allow-downgrade</literal>, 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.</para>

      <para>The <function>SetLinkDNSSECNegativeTrustAnchors()</function> 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.</para>

      <para>The <function>SetLinkDNSOverTLS()</function> method enables or disables DNS-over-TLS.
      C.f. <varname>DNSOverTLS=</varname> in
      <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      for details.</para>

      <para>Network management software integrating with <filename>systemd-resolved</filename> should call
      <function>SetLinkDNS()</function> or <function>SetLinkDNSEx()</function>,
      <function>SetLinkDefaultRoute()</function>, <function>SetLinkDomains()</function> 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 (<constant>IFF_UP</constant> 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 <function>RevertLink()</function> (described below) to reset all
      per-interface settings.</para>

      <para>The <function>RevertLink()</function> method may be used to revert all per-link settings
      described above to the defaults.</para>

      <para>The <function>FlushCaches()</function> flushes all resource record caches maintained by the
      resolver, and ensures that any subsequent lookups re-request their responses from their sources.</para>

      <para>The <function>ResetServerFeatures()</function> 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.</para>

      <para>The <function>RegisterService()</function> method may be used to register a DNS-SD service on the
      host. This functionality is closely related to the functionality provided by
      <citerefentry><refentrytitle>systemd.dnssd</refentrytitle><manvolnum>5</manvolnum></citerefentry>
      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 <filename>*.dnssd</filename> 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 <varname>Name=</varname> setting in <filename>*.dnssd</filename> 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.</para>

      <para>The <function>UnregisterService()</function> method undoes the effect of
      <function>RegisterService()</function> and deletes a DNS-SD service previously created via IPC
      again.</para>

      <refsect3>
        <title>The Flags Parameter</title>

        <para>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:</para>

        <programlisting>/* Input+Output: Protocol/scope */
#define SD_RESOLVED_DNS                (UINT64_C(1) &lt;&lt;  0)
#define SD_RESOLVED_LLMNR_IPV4         (UINT64_C(1) &lt;&lt;  1)
#define SD_RESOLVED_LLMNR_IPV6         (UINT64_C(1) &lt;&lt;  2)
#define SD_RESOLVED_MDNS_IPV4          (UINT64_C(1) &lt;&lt;  3)
#define SD_RESOLVED_MDNS_IPV6          (UINT64_C(1) &lt;&lt;  4)

/* Input: Restrictions */
#define SD_RESOLVED_NO_CNAME           (UINT64_C(1) &lt;&lt;  5)
#define SD_RESOLVED_NO_TXT             (UINT64_C(1) &lt;&lt;  6)
#define SD_RESOLVED_NO_ADDRESS         (UINT64_C(1) &lt;&lt;  7)
#define SD_RESOLVED_NO_SEARCH          (UINT64_C(1) &lt;&lt;  8)
#define SD_RESOLVED_NO_VALIDATE        (UINT64_C(1) &lt;&lt; 10)
#define SD_RESOLVED_NO_SYNTHESIZE      (UINT64_C(1) &lt;&lt; 11)
#define SD_RESOLVED_NO_CACHE           (UINT64_C(1) &lt;&lt; 12)
#define SD_RESOLVED_NO_ZONE            (UINT64_C(1) &lt;&lt; 13)
#define SD_RESOLVED_NO_TRUST_ANCHOR    (UINT64_C(1) &lt;&lt; 14)
#define SD_RESOLVED_NO_NETWORK         (UINT64_C(1) &lt;&lt; 15)
#define SD_RESOLVED_NO_STALE           (UINT64_C(1) &lt;&lt; 24)
#define SD_RESOLVED_RELAX_SINGLE_LABEL (UINT64_C(1) &lt;&lt; 25)

/* Output: Security */
#define SD_RESOLVED_AUTHENTICATED      (UINT64_C(1) &lt;&lt;  9)
#define SD_RESOLVED_CONFIDENTIAL       (UINT64_C(1) &lt;&lt; 18)

/* Output: Origin */
#define SD_RESOLVED_SYNTHETIC          (UINT64_C(1) &lt;&lt; 19)
#define SD_RESOLVED_FROM_CACHE         (UINT64_C(1) &lt;&lt; 20)
#define SD_RESOLVED_FROM_ZONE          (UINT64_C(1) &lt;&lt; 21)
#define SD_RESOLVED_FROM_TRUST_ANCHOR  (UINT64_C(1) &lt;&lt; 22)
#define SD_RESOLVED_FROM_NETWORK       (UINT64_C(1) &lt;&lt; 23)
</programlisting>

        <para>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,
        <filename>systemd-resolved</filename> 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.</para>

        <para>On output, these five flags indicate which protocol was used to execute the operation, and
        hence where the data was found.</para>

        <para>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.</para>

        <para>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.</para>

        <para>The NO_TXT and NO_ADDRESS flags only influence operation of the
        <function>ResolveService()</function> 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.</para>

        <para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
        <function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
        using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
        will never qualify single-label domain names using search domains. Also note that multi-label
        hostnames are never subject to search list expansion.</para>

        <para>NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be
        used.</para>

        <para>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
        <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        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.</para>

        <para>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 <literal>localhost</literal> or data from
        <filename>/etc/hosts</filename>. 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 <filename>systemd-resolved</filename> 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).</para>

        <para>CONFIDENTIAL means the query was resolved via encrypted channels or never left this
        system.</para>

        <para>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.</para>
      </refsect3>
    </refsect2>

    <refsect2>
      <title>Properties</title>

      <para>The <varname>LLMNR</varname> and <varname>MulticastDNS</varname> properties report whether LLMNR
      and MulticastDNS are (globally) enabled. Each may be one of <literal>yes</literal>,
      <literal>no</literal>, and <literal>resolve</literal>. See <function>SetLinkLLMNR()</function>
      and <function>SetLinkMulticastDNS()</function> above.</para>

      <para><varname>LLMNRHostname</varname> contains the hostname currently exposed on the network via
      LLMNR. It usually follows the system hostname as may be queried via
      <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      but may differ if a conflict is detected on the network.</para>

      <para><varname>DNS</varname> and <varname>DNSEx</varname> contain arrays of all DNS servers currently
      used by <filename>systemd-resolved</filename>. <varname>DNS</varname> contains information similar to
      the DNS server data in <filename>/run/systemd/resolve/resolv.conf</filename>. 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).
      <varname>DNSEx</varname> 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 <filename>/etc/resolv.conf</filename> or the <varname>DNS=</varname>
      setting in <filename>/etc/systemd/resolved.conf</filename>, as well as per-interface DNS server
      information either retrieved from
      <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      or configured by external software via <function>SetLinkDNS()</function> or
      <function>SetLinkDNSEx()</function> (see above). The network interface index will be 0 for the
      system-wide configured services and non-zero for the per-link servers.</para>

      <para><varname>FallbackDNS</varname> and <varname>FallbackDNSEx</varname> contain arrays of all DNS
      servers configured as fallback servers, if any, using the same format as <varname>DNS</varname> and
      <varname>DNSEx</varname> described above. See the description of <varname>FallbackDNS=</varname> in
      <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
      the description of when those servers are used.</para>

      <para><varname>CurrentDNSServer</varname> and <varname>CurrentDNSServerEx</varname> specify the server
      that is currently used for query resolution, in the same format as a single entry in the
      <varname>DNS</varname> and <varname>DNSEx</varname> arrays described above.</para>

      <para>Similarly, the <varname>Domains</varname> property contains an array of all search and routing
      domains currently used by <filename>systemd-resolved</filename>. 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).</para>

      <para>The <varname>TransactionStatistics</varname> property contains information about the number of
      transactions <filename>systemd-resolved</filename> 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
      <filename>systemd-resolved</filename> is processing or has processed. The latter value may be reset using the
      <function>ResetStatistics()</function> 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.</para>

      <para>The <varname>CacheStatistics</varname> 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 <function>ResetStatistics()</function> (see
      above).</para>

      <para>The <varname>DNSSEC</varname> property specifies current status of DNSSEC validation. It is one
      of <literal>yes</literal> (validation is enforced), <literal>no</literal> (no validation is done),
      <literal>allow-downgrade</literal> (validation is done if the current DNS server supports it). See the
      description of <varname>DNSSEC=</varname> in
      <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
      </para>

      <para>The <varname>DNSSECStatistics</varname> 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.</para>

      <para>The <varname>DNSSECSupported</varname> 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 <filename>systemd-resolved</filename> 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.</para>

      <para>The <varname>DNSOverTLS</varname> boolean property reports whether DNS-over-TLS is enabled.
      </para>

      <para>The <varname>ResolvConfMode</varname> property exposes how <filename>/etc/resolv.conf</filename>
      is managed on the host. Currently, the values <literal>uplink</literal>, <literal>stub</literal>,
      <literal>static</literal> (these three correspond to the three different files
      <filename>systemd-resolved.service</filename> provides), <literal>foreign</literal> (the file is
      managed by admin or another service, <filename>systemd-resolved.service</filename> just consumes it),
      <literal>missing</literal> (<filename>/etc/resolv.conf</filename> is missing).</para>

      <para>The <varname>DNSStubListener</varname> property reports whether the stub listener on port 53 is
      enabled. Possible values are <literal>yes</literal> (enabled), <literal>no</literal> (disabled),
      <literal>udp</literal> (only the UDP listener is enabled), and <literal>tcp</literal> (only the TCP
      listener is enabled).</para>

      <para>The <varname>DNSSECNegativeTrustAnchors</varname> property contains a list of recognized DNSSEC
      negative trust anchors and contains a list of domains.</para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Link Object</title>

    <programlisting executable="systemd-resolved" node="/org/freedesktop/resolve1/link/_1" interface="org.freedesktop.resolve1.Link">
node /org/freedesktop/resolve1/link/_1 {
  interface org.freedesktop.resolve1.Link {
    methods:
      SetDNS(in  a(iay) addresses);
      SetDNSEx(in  a(iayqs) addresses);
      SetDomains(in  a(sb) domains);
      SetDefaultRoute(in  b enable);
      SetLLMNR(in  s mode);
      SetMulticastDNS(in  s mode);
      SetDNSOverTLS(in  s mode);
      SetDNSSEC(in  s mode);
      SetDNSSECNegativeTrustAnchors(in  as names);
      Revert();
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t ScopesMask = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly a(iay) DNS = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly a(iayqs) DNSEx = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly (iay) CurrentDNSServer = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly (iayqs) CurrentDNSServerEx = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly a(sb) Domains = [...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly b DefaultRoute = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s LLMNR = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s MulticastDNS = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s DNSOverTLS = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s DNSSEC = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly as DNSSECNegativeTrustAnchors = ['...', ...];
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly b DNSSECSupported = ...;
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};
    </programlisting>

    <!--Autogenerated cross-references for systemd.directives, do not edit-->

    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Link"/>

    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Link"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetDNS()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetDNSEx()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetDomains()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetDefaultRoute()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetLLMNR()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetMulticastDNS()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetDNSOverTLS()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetDNSSEC()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="SetDNSSECNegativeTrustAnchors()"/>

    <variablelist class="dbus-method" generated="True" extra-ref="Revert()"/>

    <variablelist class="dbus-property" generated="True" extra-ref="ScopesMask"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNS"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSEx"/>

    <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServer"/>

    <variablelist class="dbus-property" generated="True" extra-ref="CurrentDNSServerEx"/>

    <variablelist class="dbus-property" generated="True" extra-ref="Domains"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DefaultRoute"/>

    <variablelist class="dbus-property" generated="True" extra-ref="LLMNR"/>

    <variablelist class="dbus-property" generated="True" extra-ref="MulticastDNS"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSOverTLS"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSSEC"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSSECNegativeTrustAnchors"/>

    <variablelist class="dbus-property" generated="True" extra-ref="DNSSECSupported"/>

    <!--End of Autogenerated section-->

    <para>For each Linux network interface a "Link" object is created which exposes per-link DNS
    configuration and state. Use <function>GetLink()</function> on the Manager interface to retrieve the
    object path for a link object given the network interface index (see above).</para>

    <refsect2>
      <title>Methods</title>

      <para>The various methods exposed by the Link interface are equivalent to their similarly named
      counterparts on the Manager interface. e.g. <function>SetDNS()</function> on the Link object maps to
      <function>SetLinkDNS()</function> 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
      <function>GetLink()</function> before invoking the methods. The same relationship holds for
      <function>SetDNSEx()</function>, <function>SetDomains()</function>,
      <function>SetDefaultRoute()</function>, <function>SetLLMNR()</function>,
      <function>SetMulticastDNS()</function>, <function>SetDNSOverTLS()</function>,
      <function>SetDNSSEC()</function>, <function>SetDNSSECNegativeTrustAnchors()</function>, and
      <function>Revert()</function>. For further details on these methods see the
      <interfacename>Manager</interfacename> documentation above.</para>
    </refsect2>

    <refsect2>
      <title>Properties</title>

      <para><varname>ScopesMask</varname> 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.</para>

      <para><varname>DNSSECSupported</varname> 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.</para>

      <para><varname>DefaultRoute</varname> exposes a boolean field that indicates whether the interface will
      be used as default route for name queries. See <function>SetLinkDefaultRoute()</function> above.</para>

      <para>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 <function>SetDNS()</function> or
      <function>SetLLMNR()</function>.</para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Common Errors</title>

    <para>Many bus methods <filename>systemd-resolved</filename> exposes (in particular the resolver methods such
    as <function>ResolveHostname()</function> on the <interfacename>Manager</interfacename> interface) may return
    some of the following errors:</para>

    <variablelist>
      <varlistentry><term><constant>org.freedesktop.resolve1.NoNameServers</constant></term>
      <listitem><para>No suitable DNS servers were found to resolve a request.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.InvalidReply</constant></term>
      <listitem><para>A response from the selected DNS server was not understood.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchRR</constant></term>
      <listitem><para>The requested name exists, but there is no resource record of the requested type for
      it. (This is the DNS NODATA case).</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.CNameLoop</constant></term>
      <listitem><para>The look-up failed because a CNAME or DNAME loop was detected.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.Aborted</constant></term>
      <listitem><para>The look-up was aborted because the selected protocol became unavailable while the
      operation was ongoing.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService</constant></term>
      <listitem><para>A service look-up was successful, but the <constant class="dns">SRV</constant> record
      reported that the service is not available.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed</constant></term>
      <listitem><para>The acquired response did not pass DNSSEC validation.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.NoTrustAnchor</constant></term>
      <listitem><para>No chain of trust could be established for the response to a configured DNSSEC trust
      anchor.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.ResourceRecordTypeUnsupported</constant></term>
      <listitem><para>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.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>

      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchLink</constant></term>
      <listitem><para>No network interface with the specified network interface index exists.
      </para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.LinkBusy</constant></term>
      <listitem><para>The requested configuration change could not be made because
      <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      already took possession of the interface and supplied configuration data for it.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.NetworkDown</constant></term>
      <listitem><para>The requested look-up failed because the system is currently not connected to any
      suitable network.</para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem></varlistentry>

      <varlistentry><term><constant>org.freedesktop.resolve1.DnsError.NXDOMAIN</constant></term>
      <term><constant>org.freedesktop.resolve1.DnsError.REFUSED</constant></term>
      <term>...</term>
      <listitem><para>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
      <ulink url="https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6">DNS RCODEs</ulink>.
      </para>

      <xi:include href="version-info.xml" xpointer="v246"/></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <example>
      <title>Introspect <interfacename>org.freedesktop.resolve1.Manager</interfacename> on the bus</title>

      <programlisting>
$ gdbus introspect --system \
  --dest org.freedesktop.resolve1 \
  --object-path /org/freedesktop/resolve1
      </programlisting>
    </example>

    <example>
      <title>Introspect <interfacename>org.freedesktop.resolve1.Link</interfacename> on the bus</title>

      <programlisting>
$ gdbus introspect --system \
  --dest org.freedesktop.resolve1 \
  --object-path /org/freedesktop/resolve1/link/_11
      </programlisting>
    </example>
  </refsect1>

  <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
</refentry>