<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
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>
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
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
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
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
<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>
</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>
[[<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>
[<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>
<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>
<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
<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>
<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
</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
</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
</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]
</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
</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
-- 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>
<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>
projects / thirdparty / systemd.git / commitdiff
