Skip to content

Commit d46be5a

Browse files
blucabluca
authored
Merge pull request systemd#20047 from keszybz/doc-fix
Update dnssec-trust-anchors comment syntax description and put rrs in index
2 parents 12c0bb3 + d080734 commit d46be5a

File tree

6 files changed

+112
-94
lines changed

6 files changed

+112
-94
lines changed

‎man/directives-template.xml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,11 +132,17 @@
132132
<refsect1>
133133
<title>Constants</title>
134134

135-
<para>Various constant used and/or defined by systemd.</para>
135+
<para>Various constants used and/or defined by systemd.</para>
136136

137137
<variablelist id='constants' />
138138
</refsect1>
139139

140+
<refsect1>
141+
<title>DNS resource record types</title>
142+
143+
<variablelist id='dns' />
144+
</refsect1>
145+
140146
<refsect1>
141147
<title>Miscellaneous options and directives</title>
142148

‎man/dnssec-trust-anchors.d.xml‎

Lines changed: 29 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -43,12 +43,10 @@
4343
<refsect1>
4444
<title>Positive Trust Anchors</title>
4545

46-
<para>Positive trust anchor configuration files contain DNSKEY and
47-
DS resource record definitions to use as base for DNSSEC integrity
48-
proofs. See <ulink
49-
url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035,
50-
Section 4.4</ulink> for more information about DNSSEC trust
51-
anchors.</para>
46+
<para>Positive trust anchor configuration files contain <constant class='dns'>DNSKEY</constant> and
47+
<constant class='dns'>DS</constant> resource record definitions to use as base for DNSSEC integrity
48+
proofs. See <ulink url="https://tools.ietf.org/html/rfc4035#section-4.4">RFC 4035, Section 4.4</ulink>
49+
for more information about DNSSEC trust anchors.</para>
5250

5351
<para>Positive trust anchors are read from files with the suffix
5452
<filename>.positive</filename> located in
@@ -64,13 +62,12 @@
6462
<filename>/run/dnssec-trust-anchors.d/</filename> that is either
6563
empty or a symlink to <filename>/dev/null</filename> ("masked").</para>
6664

67-
<para>Positive trust anchor files are simple text files resembling
68-
DNS zone files, as documented in <ulink
69-
url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section
70-
5</ulink>. One DS or DNSKEY resource record may be listed per
71-
line. Empty lines and lines starting with a semicolon
72-
(<literal>;</literal>) are ignored and considered comments. A DS
73-
resource record is specified like in the following example:</para>
65+
<para>Positive trust anchor files are simple text files resembling DNS zone files, as documented in
66+
<ulink url="https://tools.ietf.org/html/rfc1035#section-5">RFC 1035, Section 5</ulink>. One <constant
67+
class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> resource record may be listed per
68+
line. Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored, which
69+
may be used for commenting. A <consant class='dns'>DS</consant> resource record is specified like in the
70+
following example:</para>
7471

7572
<programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>
7673

@@ -85,24 +82,20 @@
8582
Section 5</ulink> for details about the precise syntax and meaning
8683
of these fields.</para>
8784

88-
<para>Alternatively, DNSKEY resource records may be used to define
89-
trust anchors, like in the following example:</para>
85+
<para>Alternatively, <constant class='dns'>DNSKEY</constant> resource records may be used to define trust
86+
anchors, like in the following example:</para>
9087

9188
<programlisting>. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=</programlisting>
9289

93-
<para>The first word specifies the domain again, the second word
94-
must be <literal>IN</literal>, followed by
95-
<literal>DNSKEY</literal>. The subsequent words encode the DNSKEY
96-
flags, protocol and algorithm fields, followed by the key data
97-
encoded in Base64. See <ulink
98-
url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034,
99-
Section 2</ulink> for details about the precise syntax and meaning
100-
of these fields.</para>
90+
<para>The first word specifies the domain again, the second word must be <literal>IN</literal>, followed
91+
by <literal>DNSKEY</literal>. The subsequent words encode the <constant class='dns'>DNSKEY</constant>
92+
flags, protocol and algorithm fields, followed by the key data encoded in Base64. See <ulink
93+
url="https://tools.ietf.org/html/rfc4034#section-2">RFC 4034, Section 2</ulink> for details about the
94+
precise syntax and meaning of these fields.</para>
10195

102-
<para>If multiple DS or DNSKEY records are defined for the same
103-
domain (possibly even in different trust anchor files), all keys
104-
are used and are considered equivalent as base for DNSSEC
105-
proofs.</para>
96+
<para>If multiple <constant class='dns'>DS</constant> or <constant class='dns'>DNSKEY</constant> records
97+
are defined for the same domain (possibly even in different trust anchor files), all keys are used and
98+
are considered equivalent as base for DNSSEC proofs.</para>
10699

107100
<para>Note that <filename>systemd-resolved</filename> will
108101
automatically use a built-in trust anchor key for the Internet
@@ -112,17 +105,15 @@
112105
as soon as at least one trust anchor key for the root domain is
113106
defined in trust anchor files.</para>
114107

115-
<para>It is generally recommended to encode trust anchors in DS
116-
resource records, rather than DNSKEY resource records.</para>
117-
118-
<para>If a trust anchor specified via a DS record is found revoked
119-
it is automatically removed from the trust anchor database for the
120-
runtime. See <ulink url="https://tools.ietf.org/html/rfc5011">RFC
121-
5011</ulink> for details about revoked trust anchors. Note that
122-
<filename>systemd-resolved</filename> will not update its trust
123-
anchor database from DNS servers automatically. Instead, it is
124-
recommended to update the resolver software or update the new
125-
trust anchor via adding in new trust anchor files.</para>
108+
<para>It is generally recommended to encode trust anchors in <constant class='dns'>DS</constant> resource
109+
records, rather than <constant class='dns'>DNSKEY</constant> resource records.</para>
110+
111+
<para>If a trust anchor specified via a <constant class='dns'>DS</constant> record is found revoked it is
112+
automatically removed from the trust anchor database for the runtime. See <ulink
113+
url="https://tools.ietf.org/html/rfc5011">RFC 5011</ulink> for details about revoked trust anchors. Note
114+
that <filename>systemd-resolved</filename> will not update its trust anchor database from DNS servers
115+
automatically. Instead, it is recommended to update the resolver software or update the new trust anchor
116+
via adding in new trust anchor files.</para>
126117

127118
<para>The current DNSSEC trust anchor for the Internet's root
128119
domain is available at the <ulink

‎man/org.freedesktop.resolve1.xml‎

Lines changed: 25 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -308,12 +308,15 @@ node /org/freedesktop/resolve1 {
308308
records of many types, it is crucial that clients using this API understand that the RR data originates
309309
from the network and should be thoroughly validated before use.</para>
310310

311-
<para><function>ResolveService()</function> may be used to resolve a DNS SRV service record, as well as the
312-
hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional
313-
service metadata. The primary benefit of using this method over <function>ResolveRecord()</function>
314-
specifying the SRV type is that it will resolve the SRV and TXT RRs as well as the hostnames referenced
315-
in the SRV in a single operation. As parameters it takes a Linux network interface index, a service
316-
name, a service type and a service domain. This method may be invoked in three different modes:</para>
311+
<para><function>ResolveService()</function> may be used to resolve a DNS
312+
<constant class="dns">SRV</constant> service record, as well as the hostnames referenced in it, and
313+
possibly an accompanying DNS-SD <constant class="dns">TXT</constant> record containing additional
314+
service metadata. The primary benefit of using this method over <function>ResolveRecord()</function>
315+
specifying the <constant class="dns">SRV</constant> type is that it will resolve the
316+
<constant class="dns">SRV</constant> and <constant class="dns">TXT</constant> RRs as well as the
317+
hostnames referenced in the SRV in a single operation. As parameters it takes a Linux network interface
318+
index, a service name, a service type and a service domain. This method may be invoked in three
319+
different modes:</para>
317320

318321
<orderedlist>
319322
<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 {
323326
specifications). However, if necessary, IDNA conversion is applied to the domain parameter.</para>
324327
</listitem>
325328

326-
<listitem><para>To resolve a plain SRV record, set the service name parameter to the empty string
327-
and set the service type and domain properly. (IDNA conversion is applied to the domain, if
328-
necessary.)</para></listitem>
329+
<listitem><para>To resolve a plain <constant class="dns">SRV</constant> record, set the service name
330+
parameter to the empty string and set the service type and domain properly. (IDNA conversion is
331+
applied to the domain, if necessary.)</para></listitem>
329332

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

335338
<para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
@@ -339,15 +342,16 @@ node /org/freedesktop/resolve1 {
339342
<varname>flags</varname> parameter takes a couple of flags that may be used to alter the resolver
340343
operation.</para>
341344

342-
<para>On completion, <function>ResolveService()</function> returns an array of SRV record structures. Each
343-
items consisting of the priority, weight and port fields as well as the hostname to contact, as encoded in the SRV
345+
<para>On completion, <function>ResolveService()</function> returns an array of
346+
<constant class="dns">SRV</constant> record structures. Each items consisting of the priority, weight and port
347+
fields as well as the hostname to contact, as encoded in the <constant class="dns">SRV</constant>
344348
record. Immediately following is an array of the addresses of this hostname, with each item consisting
345349
of the interface index, the address family and the address data in a byte array. This address array is
346-
followed by the canonicalized hostname. After this array of SRV record structures an array of byte
347-
arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are enabled. The next parameters
348-
are the canonical service name, type and domain. This may or may not be identical to the parameters
349-
passed in. Finally, a <varname>flags</varname> field is returned that contains information about the
350-
resolver operation performed.</para>
350+
followed by the canonicalized hostname. After this array of <constant class="dns">SRV</constant> record
351+
structures an array of byte arrays follows that encodes the TXT RR strings, in case DNS-SD look-ups are
352+
enabled. The next parameters are the canonical service name, type and domain. This may or may not be
353+
identical to the parameters passed in. Finally, a <varname>flags</varname> field is returned that
354+
contains information about the resolver operation performed.</para>
351355

352356
<para>The <function>ResetStatistics()</function> method resets the various statistics counters that
353357
<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 {
779783
</varlistentry>
780784

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

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

0 commit comments

Comments
 (0)