1
0
mirror of https://github.com/systemd/systemd synced 2026-03-20 03:54:45 +01:00

Compare commits

..

No commits in common. "d46be5a6ac93bc68b60b8b108ea4c0431fb88927" and "9952f11a84b333a36e9f1f4a62b951ab84c897f5" have entirely different histories.

8 changed files with 100 additions and 122 deletions

View File

@ -132,17 +132,11 @@
<refsect1>
<title>Constants</title>
<para>Various constants used and/or defined by systemd.</para>
<para>Various constant used and/or defined by systemd.</para>
<variablelist id='constants' />
</refsect1>
<refsect1>
<title>DNS resource record types</title>
<variablelist id='dns' />
</refsect1>
<refsect1>
<title>Miscellaneous options and directives</title>

View File

@ -43,10 +43,12 @@
<refsect1>
<title>Positive Trust Anchors</title>
<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 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 anchors are read from files with the suffix
<filename>.positive</filename> located in
@ -62,12 +64,13 @@
<filename>/run/dnssec-trust-anchors.d/</filename> that is either
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 <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>
<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 a semicolon
(<literal>;</literal>) are ignored and considered comments. A DS
resource record is specified like in the following example:</para>
<programlisting>. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5</programlisting>
@ -82,20 +85,24 @@
Section 5</ulink> for details about the precise syntax and meaning
of these fields.</para>
<para>Alternatively, <constant class='dns'>DNSKEY</constant> resource records may be used to define trust
anchors, like in the following example:</para>
<para>Alternatively, DNSKEY 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 <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>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>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>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>Note that <filename>systemd-resolved</filename> will
automatically use a built-in trust anchor key for the Internet
@ -105,15 +112,17 @@
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 <constant class='dns'>DS</constant> resource
records, rather than <constant class='dns'>DNSKEY</constant> resource records.</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 <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>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>The current DNSSEC trust anchor for the Internet's root
domain is available at the <ulink

View File

@ -308,15 +308,12 @@ 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
<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
<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 <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>
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>
<orderedlist>
<listitem><para>To resolve a DNS-SD service, specify the service name (e.g. <literal>Lennart's
@ -326,13 +323,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 <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>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>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>
<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>
</orderedlist>
<para>The <varname>family</varname> parameter of the <function>ResolveService()</function> method encodes
@ -342,16 +339,15 @@ 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
<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>
<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
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>
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>
<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>
@ -783,8 +779,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 <constant class="dns">SRV</constant> record
reported that the service is not available.</para></listitem></varlistentry>
<listitem><para>A service look-up was successful, but the SRV 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>

View File

@ -75,26 +75,21 @@
[[<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 <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>
<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>
</varlistentry>
<varlistentry>
<term><command>openpgp</command> <replaceable>EMAIL@DOMAIN</replaceable></term>
<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>
<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>
</varlistentry>
<varlistentry>
@ -102,13 +97,11 @@
[<replaceable>FAMILY</replaceable>]
<replaceable>DOMAIN</replaceable>[:<replaceable>PORT</replaceable>]…</term>
<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
<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
(<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>
@ -135,8 +128,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>
@ -253,11 +246,10 @@
<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. <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>
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>
<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
@ -272,23 +264,20 @@
<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 <constant class='dns'>SRV</constant>
resource records are resolved as well.</para></listitem>
<option>--service</option> the hostnames contained in the SRV 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 <constant class='dns'>TXT</constant> 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 TXT 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 <constant
class='dns'>CNAME</constant> or <constant class='dns'>DNAME</constant> redirections are
<listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are
followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is
returned.</para></listitem>
</varlistentry>
@ -476,7 +465,7 @@
<title>Examples</title>
<example>
<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>
<title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title>
<programlisting>$ resolvectl query www.0pointer.net
www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
@ -488,8 +477,7 @@ 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
(<constant class='dns'>PTR</constant> resource record)</title>
<title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title>
<programlisting>$ resolvectl query 85.214.157.71
85.214.157.71: gardel.0pointer.net
@ -500,8 +488,7 @@ www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
</example>
<example>
<title>Retrieve the <constant class='dns'>MX</constant> record of the <literal>yahoo.com</literal>
domain</title>
<title>Retrieve the MX 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
@ -511,7 +498,7 @@ yahoo.com. IN MX 1 mta5.am0.yahoodns.net
</example>
<example>
<title>Resolve an <constant class='dns'>SRV</constant> service</title>
<title>Resolve an SRV 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]
@ -523,7 +510,7 @@ _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, we
</example>
<example>
<title>Retrieve a PGP key (<constant class='dns'>OPENPGP</constant> resource record)</title>
<title>Retrieve a PGP key</title>
<programlisting>$ resolvectl openpgp zbyszek@fedoraproject.org
d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY
@ -534,7 +521,8 @@ d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproje
</example>
<example>
<title>Retrieve a TLS key (<constant class='dns'>TLSA</constant> resource record)</title>
<title>Retrieve a TLS key (<literal>tcp</literal> and
<literal>:443</literal> could be skipped)</title>
<programlisting>$ resolvectl tlsa tcp fedoraproject.org:443
_443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
@ -542,8 +530,6 @@ _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>

View File

@ -334,7 +334,7 @@ DNSStubListenerExtra=udp:[2001:db8:0:f102::13]:9953</programlisting>
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>dnssec-trust-anchors.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>
</para>
</refsect1>

View File

@ -123,15 +123,13 @@
<varlistentry>
<term><varname>Priority=</varname></term>
<listitem>
<para>A priority number set in <constant class='dns'>SRV</constant> resource records corresponding
to the network service.</para>
<para>A priority number set in SRV resource records corresponding to the network service.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>Weight=</varname></term>
<listitem>
<para>A weight number set in <constant class='dns'>SRV</constant> resource records corresponding
to the network service.</para>
<para>A weight number set in SRV resource records corresponding to the network service.</para>
</listitem>
</varlistentry>
<varlistentry>

View File

@ -1613,11 +1613,9 @@ DnsResourceRecord *dns_resource_record_copy(DnsResourceRecord *rr) {
copy->nsec.next_domain_name = strdup(rr->nsec.next_domain_name);
if (!copy->nsec.next_domain_name)
return NULL;
if (rr->nsec.types) {
copy->nsec.types = bitmap_copy(rr->nsec.types);
if (!copy->nsec.types)
return NULL;
}
break;
case DNS_TYPE_DS:
@ -1642,11 +1640,9 @@ DnsResourceRecord *dns_resource_record_copy(DnsResourceRecord *rr) {
if (!copy->nsec3.next_hashed_name)
return NULL;
copy->nsec3.next_hashed_name_size = rr->nsec3.next_hashed_name_size;
if (rr->nsec3.types) {
copy->nsec3.types = bitmap_copy(rr->nsec3.types);
if (!copy->nsec3.types)
return NULL;
}
break;
case DNS_TYPE_TLSA:

View File

@ -77,14 +77,13 @@ def _extract_directives(directive_groups, formatting, page):
storfile[text].append((pagename, section))
formatting[text] = name
storfile = directive_groups['constants']
for name in t.iterfind('.//constant'):
if name.attrib.get('index') == 'false':
continue
name.tail = ''
if name.text.startswith('('): # a cast, strip it
name.text = name.text.partition(' ')[2]
klass = name.attrib.get('class') or 'constants'
storfile = directive_groups[klass]
storfile[name.text].append((pagename, section))
formatting[name.text] = name