diff options
| -rw-r--r-- | man/dnssec-trust-anchors.d.xml | 63 | ||||
| -rw-r--r-- | man/org.freedesktop.resolve1.xml | 46 | ||||
| -rw-r--r-- | man/resolvectl.xml | 76 | ||||
| -rw-r--r-- | man/systemd.dnssd.xml | 6 |
4 files changed, 102 insertions, 89 deletions
diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml index d2f2f9b0ea..b0e95ce841 100644 --- a/man/dnssec-trust-anchors.d.xml +++ b/man/dnssec-trust-anchors.d.xml @@ -43,12 +43,10 @@ <refsect1> <title>Positive Trust Anchors</title> - <para>Positive trust anchor configuration files contain DNSKEY and - DS resource record definitions to use as base for DNSSEC integrity - proofs. See <ulink - url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, - Section 4.4</ulink> for more information about DNSSEC trust - anchors.</para> + <para>Positive trust anchor configuration files contain <constant class='dns'>DNSKEY</constant> and + <constant class='dns'>DS</constant> resource record definitions to use as base for DNSSEC integrity + proofs. See <ulink url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, Section 4.4</ulink> + for more information about DNSSEC trust anchors.</para> <para>Positive trust anchors are read from files with the suffix <filename>.positive</filename> located in @@ -65,10 +63,11 @@ empty or a symlink to <filename>/dev/null</filename> ("masked").</para> <para>Positive trust anchor files are simple text files resembling DNS zone files, as documented in - <ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One DS or DNSKEY - resource record may be listed per line. Empty lines and lines starting with <literal>#</literal> or - <literal>;</literal> are ignored, which may be used for commenting. A DS resource record is specified - like in the following example:</para> + <ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One <constant + class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> resource record may be listed per + line. Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored, which + may be used for commenting. A <consant class='dns'>DS</consant> resource record is specified like in the + following example:</para> <programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting> @@ -83,24 +82,20 @@ Section 5</ulink> for details about the precise syntax and meaning of these fields.</para> - <para>Alternatively, DNSKEY resource records may be used to define - trust anchors, like in the following example:</para> + <para>Alternatively, <constant class='dns'>DNSKEY</constant> resource records may be used to define trust + anchors, like in the following example:</para> <programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting> - <para>The first word specifies the domain again, the second word - must be <literal>IN</literal>, followed by - <literal>DNSKEY</literal>. The subsequent words encode the DNSKEY - flags, protocol and algorithm fields, followed by the key data - encoded in Base64. See <ulink - url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, - Section 2</ulink> for details about the precise syntax and meaning - of these fields.</para> + <para>The first word specifies the domain again, the second word must be <literal>IN</literal>, followed + by <literal>DNSKEY</literal>. The subsequent words encode the <constant class='dns'>DNSKEY</constant> + flags, protocol and algorithm fields, followed by the key data encoded in Base64. See <ulink + url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, Section 2</ulink> for details about the + precise syntax and meaning of these fields.</para> - <para>If multiple DS or DNSKEY records are defined for the same - domain (possibly even in different trust anchor files), all keys - are used and are considered equivalent as base for DNSSEC - proofs.</para> + <para>If multiple <constant class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> records + are defined for the same domain (possibly even in different trust anchor files), all keys are used and + are considered equivalent as base for DNSSEC proofs.</para> <para>Note that <filename>systemd-resolved</filename> will automatically use a built-in trust anchor key for the Internet @@ -110,17 +105,15 @@ as soon as at least one trust anchor key for the root domain is defined in trust anchor files.</para> - <para>It is generally recommended to encode trust anchors in DS - resource records, rather than DNSKEY resource records.</para> - - <para>If a trust anchor specified via a DS record is found revoked - it is automatically removed from the trust anchor database for the - runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC - 5011</ulink> for details about revoked trust anchors. Note that - <filename>systemd-resolved</filename> will not update its trust - anchor database from DNS servers automatically. Instead, it is - recommended to update the resolver software or update the new - trust anchor via adding in new trust anchor files.</para> + <para>It is generally recommended to encode trust anchors in <constant class='dns'>DS</constant> resource + records, rather than <constant class='dns'>DNSKEY</constant> resource records.</para> + + <para>If a trust anchor specified via a <constant class='dns'>DS</constant> record is found revoked it is + automatically removed from the trust anchor database for the runtime. See <ulink + url="https://tools.ietf.org/html/rfc5011">RFC 5011</ulink> for details about revoked trust anchors. Note + that <filename>systemd-resolved</filename> will not update its trust anchor database from DNS servers + automatically. Instead, it is recommended to update the resolver software or update the new trust anchor + via adding in new trust anchor files.</para> <para>The current DNSSEC trust anchor for the Internet's root domain is available at the <ulink diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml index 860a14877d..78a52cc67d 100644 --- a/man/org.freedesktop.resolve1.xml +++ b/man/org.freedesktop.resolve1.xml @@ -308,12 +308,15 @@ node /org/freedesktop/resolve1 { 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 SRV service record, as well as the - hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional - service metadata. The primary benefit of using this method over <function>ResolveRecord()</function> - specifying the SRV type is that it will resolve the SRV and TXT 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> + <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 @@ -323,13 +326,13 @@ node /org/freedesktop/resolve1 { specifications). However, if necessary, IDNA conversion is applied to the domain parameter.</para> </listitem> - <listitem><para>To resolve a plain SRV 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>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 SRV record (i.e. prefixed with the service type) in the domain parameter. (No IDNA - conversion is applied in this mode.)</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 @@ -339,15 +342,16 @@ node /org/freedesktop/resolve1 { <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 SRV record structures. Each - items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV + <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 SRV 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> + 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> @@ -779,8 +783,8 @@ node /org/freedesktop/resolve1/link/_1 { </varlistentry> <varlistentry><term><constant>org.freedesktop.resolve1.NoSuchService</constant></term> - <listitem><para>A service look-up was successful, but the SRV record reported that the service is not - available.</para></listitem></varlistentry> + <listitem><para>A service look-up was successful, but the <constant class="dns">SRV</constant> record + reported that the service is not available.</para></listitem></varlistentry> <varlistentry><term><constant>org.freedesktop.resolve1.DnssecFailed</constant></term> <listitem><para>The acquired response did not pass DNSSEC validation.</para></listitem> diff --git a/man/resolvectl.xml b/man/resolvectl.xml index bd1a636d60..b9c4d1d768 100644 --- a/man/resolvectl.xml +++ b/man/resolvectl.xml @@ -75,21 +75,26 @@ [[<replaceable>NAME</replaceable>] <replaceable>TYPE</replaceable>] <replaceable>DOMAIN</replaceable></term> - <listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> and - <ulink url="https://tools.ietf.org/html/rfc2782">SRV</ulink> services, depending on the specified list of parameters. - If three parameters are passed the first is assumed to be the DNS-SD service name, the second the SRV service type, - and the third the domain to search in. In this case a full DNS-SD style SRV and TXT lookup is executed. If only two - parameters are specified, the first is assumed to be the SRV service type, and the second the domain to look in. In - this case no TXT RR is requested. Finally, if only one parameter is specified, it is assumed to be a domain name, - that is already prefixed with an SRV type, and an SRV lookup is done (no TXT).</para></listitem> + <listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> and <ulink + url="https://tools.ietf.org/html/rfc2782">SRV</ulink> services, depending on the specified list of + parameters. If three parameters are passed the first is assumed to be the DNS-SD service name, the + second the <constant class='dns'>SRV</constant> service type, and the third the domain to search in. + In this case a full DNS-SD style <constant class='dns'>SRV</constant> and <constant + class='dns'>TXT</constant> lookup is executed. If only two parameters are specified, the first is + assumed to be the <constant class='dns'>SRV</constant> service type, and the second the domain to look + in. In this case no <constant class='dns'>TXT</constant> resource record is requested. Finally, if + only one parameter is specified, it is assumed to be a domain name, that is already prefixed with an + <constant class='dns'>SRV</constant> type, and an <constant class='dns'>SRV</constant> lookup is done + (no <constant class='dns'>TXT</constant>).</para></listitem> </varlistentry> <varlistentry> <term><command>openpgp</command> <replaceable>EMAIL@DOMAIN</replaceable>…</term> - <listitem><para>Query PGP keys stored as <ulink url="https://tools.ietf.org/html/rfc7929">OPENPGPKEY</ulink> - resource records. Specified e-mail addresses are converted to the corresponding DNS domain name, and any - OPENPGPKEY keys are printed.</para></listitem> + <listitem><para>Query PGP keys stored as <constant class='dns'>OPENPGPKEY</constant> resource records, + ssee <ulink url="https://tools.ietf.org/html/rfc7929">RFC 7929</ulink>. Specified e-mail addresses + are converted to the corresponding DNS domain name, and any <constant class='dns'>OPENPGPKEY</constant> + keys are printed.</para></listitem> </varlistentry> <varlistentry> @@ -97,11 +102,13 @@ [<replaceable>FAMILY</replaceable>] <replaceable>DOMAIN</replaceable>[:<replaceable>PORT</replaceable>]…</term> - <listitem><para>Query TLS public keys stored as <ulink url="https://tools.ietf.org/html/rfc6698">TLSA</ulink> - resource records. A query will be performed for each of the specified names prefixed with the port and family + <listitem><para>Query TLS public keys stored as <constant class='dns'>TLSA</constant> resource + records, see <ulink url="https://tools.ietf.org/html/rfc6698">RFC 6698</ulink>. A query will be + performed for each of the specified names prefixed with the port and family (<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>). - The port number may be specified after a colon (<literal>:</literal>), otherwise <constant>443</constant> will be used - by default. The family may be specified as the first argument, otherwise <constant>tcp</constant> will be used.</para></listitem> + The port number may be specified after a colon (<literal>:</literal>), otherwise + <constant>443</constant> will be used by default. The family may be specified as the first argument, + otherwise <constant>tcp</constant> will be used.</para></listitem> </varlistentry> <varlistentry> @@ -128,8 +135,8 @@ <varlistentry> <term><command>flush-caches</command></term> - <listitem><para>Flushes all DNS resource record caches the service maintains locally. This is mostly equivalent - to sending the <constant>SIGUSR2</constant> to the <command>systemd-resolved</command> + <listitem><para>Flushes all DNS resource record caches the service maintains locally. This is mostly + equivalent to sending the <constant>SIGUSR2</constant> to the <command>systemd-resolved</command> service.</para></listitem> </varlistentry> @@ -246,10 +253,11 @@ <term><option>--class=</option><replaceable>CLASS</replaceable></term> <listitem><para>When used in conjunction with the <command>query</command> command, specifies the DNS - resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to look up. If these options - are used a DNS resource record set matching the specified class and type is requested. The class - defaults to IN if only a type is specified. The special value <literal>help</literal> may be used to - list known values.</para> + resource record type (e.g. <constant class='dns'>A</constant>, <constant class='dns'>AAAA</constant>, + <constant class='dns'>MX</constant>, …) and class (e.g. <constant>IN</constant>, + <constant>ANY</constant>, …) to look up. If these options are used a DNS resource record set matching + the specified class and type is requested. The class defaults to <constant>IN</constant> if only a + type is specified. The special value <literal>help</literal> may be used to list known values.</para> <para>Without these options <command>resolvectl query</command> provides high-level domain name to address and address to domain name resolution. With these options it provides low-level DNS resource @@ -264,20 +272,23 @@ <term><option>--service-address=</option><replaceable>BOOL</replaceable></term> <listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with - <option>--service</option> the hostnames contained in the SRV resource records are resolved as well.</para></listitem> + <option>--service</option> the hostnames contained in the <constant class='dns'>SRV</constant> + resource records are resolved as well.</para></listitem> </varlistentry> <varlistentry> <term><option>--service-txt=</option><replaceable>BOOL</replaceable></term> - <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with - <option>--service</option> the TXT service metadata record is resolved as well.</para></listitem> + <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup + with <option>--service</option> the <constant class='dns'>TXT</constant> service metadata record is + resolved as well.</para></listitem> </varlistentry> <varlistentry> <term><option>--cname=</option><replaceable>BOOL</replaceable></term> - <listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are + <listitem><para>Takes a boolean parameter. If true (the default), DNS <constant + class='dns'>CNAME</constant> or <constant class='dns'>DNAME</constant> redirections are followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is returned.</para></listitem> </varlistentry> @@ -465,7 +476,7 @@ <title>Examples</title> <example> - <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title> + <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain (<constant class='dns'>A</constant> and <constant class='dns'>AAAA</constant> resource records)</title> <programlisting>$ resolvectl query www.0pointer.net www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 @@ -477,7 +488,8 @@ www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 </example> <example> - <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title> + <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address + (<constant class='dns'>PTR</constant> resource record)</title> <programlisting>$ resolvectl query 85.214.157.71 85.214.157.71: gardel.0pointer.net @@ -488,7 +500,8 @@ www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 </example> <example> - <title>Retrieve the MX record of the <literal>yahoo.com</literal> domain</title> + <title>Retrieve the <constant class='dns'>MX</constant> record of the <literal>yahoo.com</literal> + domain</title> <programlisting>$ resolvectl --legend=no -t MX query yahoo.com yahoo.com. IN MX 1 mta7.am0.yahoodns.net @@ -498,7 +511,7 @@ yahoo.com. IN MX 1 mta5.am0.yahoodns.net </example> <example> - <title>Resolve an SRV service</title> + <title>Resolve an <constant class='dns'>SRV</constant> service</title> <programlisting>$ resolvectl service _xmpp-server._tcp gmail.com _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0] @@ -510,7 +523,7 @@ _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, we </example> <example> - <title>Retrieve a PGP key</title> + <title>Retrieve a PGP key (<constant class='dns'>OPENPGP</constant> resource record)</title> <programlisting>$ resolvectl openpgp zbyszek@fedoraproject.org d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY @@ -521,8 +534,7 @@ d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproje </example> <example> - <title>Retrieve a TLS key (<literal>tcp</literal> and - <literal>:443</literal> could be skipped)</title> + <title>Retrieve a TLS key (<constant class='dns'>TLSA</constant> resource record)</title> <programlisting>$ resolvectl tlsa tcp fedoraproject.org:443 _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0 @@ -530,6 +542,8 @@ _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0 -- Selector: Full Certificate -- Matching type: SHA-256 </programlisting> + + <para><literal>tcp</literal> and <literal>:443</literal> are optional and could be skipped.</para> </example> </refsect1> diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml index be2e873efb..c7d781b568 100644 --- a/man/systemd.dnssd.xml +++ b/man/systemd.dnssd.xml @@ -123,13 +123,15 @@ <varlistentry> <term><varname>Priority=</varname></term> <listitem> - <para>A priority number set in SRV resource records corresponding to the network service.</para> + <para>A priority number set in <constant class='dns'>SRV</constant> resource records corresponding + to the network service.</para> </listitem> </varlistentry> <varlistentry> <term><varname>Weight=</varname></term> <listitem> - <para>A weight number set in SRV resource records corresponding to the network service.</para> + <para>A weight number set in <constant class='dns'>SRV</constant> resource records corresponding + to the network service.</para> </listitem> </varlistentry> <varlistentry> |