shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-03-23 10:50:16 +03:00
Code

man: add markup to dns resource record labels

Browse Source
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2021-06-27 16:20:38 +02:00
parent 0b497bc46f
commit 9a024bf18d
4 changed files with 101 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
man/dnssec-trust-anchors.d.xml
View File

@ -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>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 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>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

46
man/org.freedesktop.resolve1.xml
View File

@ -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>

76
man/resolvectl.xml
View File

@ -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>

6
man/systemd.dnssd.xml
View File

@ -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>