man/org.freedesktop.resolve1: briefly document a bunch of methods and properties

Fixes #13799.

1 files changed, 115 insertions, 115 deletions

diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml
index 6a6d9de6b9..b06155662a 100644
--- a/man/org.freedesktop.resolve1.xml
+++ b/man/org.freedesktop.resolve1.xml
@@ -156,12 +156,6 @@ node /org/freedesktop/resolve1 {
 };
     </programlisting>
 
-    <!--method SetLinkDNSEx is not documented!-->
-
-    <!--method SetLinkDefaultRoute is not documented!-->
-
-    <!--method SetLinkDNSOverTLS is not documented!-->
-
     <!--method RegisterService is not documented!-->
 
     <!--method UnregisterService is not documented!-->
@@ -170,28 +164,8 @@ node /org/freedesktop/resolve1 {
 
     <!--method ResetServerFeatures is not documented!-->
 
-    <!--property LLMNR is not documented!-->
-
-    <!--property MulticastDNS is not documented!-->
-
-    <!--property DNSOverTLS is not documented!-->
-
-    <!--property DNSEx is not documented!-->
-
-    <!--property FallbackDNS is not documented!-->
-
-    <!--property FallbackDNSEx is not documented!-->
-
-    <!--property CurrentDNSServer is not documented!-->
-
-    <!--property CurrentDNSServerEx is not documented!-->
-
-    <!--property DNSSEC is not documented!-->
-
     <!--property DNSSECNegativeTrustAnchors is not documented!-->
 
-    <!--property DNSStubListener is not documented!-->
-
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.resolve1.Manager"/>
@@ -281,26 +255,28 @@ node /org/freedesktop/resolve1 {
     <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>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
@@ -387,15 +363,19 @@ node /org/freedesktop/resolve1 {
       <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.
+      (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>Network management software integrating with <filename>systemd-resolved</filename> should
-      call this method (and the five below) 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><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,
@@ -432,8 +412,22 @@ node /org/freedesktop/resolve1 {
       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>RevertLink()</function> method may be used to revert all per-link settings done with
-      the six methods described above to the defaults again.</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>
 
       <refsect3>
         <title>The Flags Parameter</title>
@@ -458,11 +452,11 @@ node /org/freedesktop/resolve1 {
         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>
+        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>
@@ -498,34 +492,50 @@ node /org/freedesktop/resolve1 {
         the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server
         does not support authenticating data).</para>
       </refsect3>
-
-  </refsect2>
+    </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> contains an array of all DNS servers currently used by
-      <filename>systemd-resolved</filename>. It contains similar information as the DNS server data written to
-      /run/systemd/resolve/resolv.conf. Each structure in the array consists of a numeric network interface
-      index, an address family, and a byte array containing the DNS server address (either 4 bytes in length
-      for IPv4 or 16 bytes in lengths for IPv6). The array contains 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
+      <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> (see above). The network
-      interface index will be 0 for the system-wide configured services and non-zero for the per-link
-      servers.</para>
+      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>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><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
@@ -540,7 +550,14 @@ node /org/freedesktop/resolve1 {
       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>
+      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,
@@ -559,12 +576,20 @@ node /org/freedesktop/resolve1 {
       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>
     </refsect2>
   </refsect1>
 
@@ -619,40 +644,6 @@ node /org/freedesktop/resolve1/link/_1 {
 };
     </programlisting>
 
-    <!--method SetDNSEx is not documented!-->
-
-    <!--method SetDomains is not documented!-->
-
-    <!--method SetDefaultRoute is not documented!-->
-
-    <!--method SetLLMNR is not documented!-->
-
-    <!--method SetMulticastDNS is not documented!-->
-
-    <!--method SetDNSOverTLS is not documented!-->
-
-    <!--method SetDNSSEC is not documented!-->
-
-    <!--method SetDNSSECNegativeTrustAnchors is not documented!-->
-
-    <!--method Revert is not documented!-->
-
-    <!--property DNSEx is not documented!-->
-
-    <!--property CurrentDNSServer is not documented!-->
-
-    <!--property CurrentDNSServerEx is not documented!-->
-
-    <!--property DefaultRoute is not documented!-->
-
-    <!--property LLMNR is not documented!-->
-
-    <!--property MulticastDNS is not documented!-->
-
-    <!--property DNSOverTLS is not documented!-->
-
-    <!--property DNSSEC is not documented!-->
-
     <!--property DNSSECNegativeTrustAnchors is not documented!-->
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
@@ -721,8 +712,13 @@ node /org/freedesktop/resolve1/link/_1 {
       <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. For further details on these methods see
-      the <interfacename>Manager</interfacename> documentation above.</para>
+      <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>
@@ -744,8 +740,12 @@ node /org/freedesktop/resolve1/link/_1 {
       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 SetDNS() or SetLLMNR().</para>
+      may be set with the various methods calls such as <function>SetDNS()</function> or
+      <function>SetLLMNR()</function>.</para>
     </refsect2>
   </refsect1>