diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml index d2f2f9b0ea4..b0e95ce841c 100644 --- a/man/dnssec-trust-anchors.d.xml +++ b/man/dnssec-trust-anchors.d.xml @@ -43,12 +43,10 @@ Positive Trust Anchors - Positive trust anchor configuration files contain DNSKEY and - DS resource record definitions to use as base for DNSSEC integrity - proofs. See RFC 4035, - Section 4.4 for more information about DNSSEC trust - anchors. + Positive trust anchor configuration files contain DNSKEY and + DS resource record definitions to use as base for DNSSEC integrity + proofs. See RFC 4035, Section 4.4 + for more information about DNSSEC trust anchors. Positive trust anchors are read from files with the suffix .positive located in @@ -65,10 +63,11 @@ empty or a symlink to /dev/null ("masked"). Positive trust anchor files are simple text files resembling DNS zone files, as documented in - RFC 1035, Section 5. One DS or DNSKEY - resource record may be listed per line. Empty lines and lines starting with # or - ; are ignored, which may be used for commenting. A DS resource record is specified - like in the following example: + RFC 1035, Section 5. One DS or DNSKEY resource record may be listed per + line. Empty lines and lines starting with # or ; are ignored, which + may be used for commenting. A DS resource record is specified like in the + following example: . IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5 @@ -83,24 +82,20 @@ Section 5 for details about the precise syntax and meaning of these fields. - Alternatively, DNSKEY resource records may be used to define - trust anchors, like in the following example: + Alternatively, DNSKEY resource records may be used to define trust + anchors, like in the following example: . IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0= - The first word specifies the domain again, the second word - must be IN, followed by - DNSKEY. The subsequent words encode the DNSKEY - flags, protocol and algorithm fields, followed by the key data - encoded in Base64. See RFC 4034, - Section 2 for details about the precise syntax and meaning - of these fields. + The first word specifies the domain again, the second word must be IN, followed + by DNSKEY. The subsequent words encode the DNSKEY + flags, protocol and algorithm fields, followed by the key data encoded in Base64. See RFC 4034, Section 2 for details about the + precise syntax and meaning of these fields. - 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. + 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. Note that systemd-resolved 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. - It is generally recommended to encode trust anchors in DS - resource records, rather than DNSKEY resource records. + It is generally recommended to encode trust anchors in DS resource + records, rather than DNSKEY resource records. - 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 RFC - 5011 for details about revoked trust anchors. Note that - systemd-resolved 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. + 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 RFC 5011 for details about revoked trust anchors. Note + that systemd-resolved 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. The current DNSSEC trust anchor for the Internet's root domain is available at the - ResolveService() 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 ResolveRecord() - 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: + ResolveService() 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 ResolveRecord() + 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: To resolve a DNS-SD service, specify the service name (e.g. Lennart's @@ -323,13 +326,13 @@ node /org/freedesktop/resolve1 { specifications). However, if necessary, IDNA conversion is applied to the domain parameter. - 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.) + 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.) - 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.) + 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.) The family parameter of the ResolveService() method encodes @@ -339,15 +342,16 @@ node /org/freedesktop/resolve1 { flags parameter takes a couple of flags that may be used to alter the resolver operation. - On completion, ResolveService() 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 + On completion, ResolveService() 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 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 flags field is returned that contains information about the - resolver operation performed. + 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 flags field is returned that + contains information about the resolver operation performed. The ResetStatistics() method resets the various statistics counters that systemd-resolved maintains to zero. (For details, see the statistics properties below.) @@ -779,8 +783,8 @@ node /org/freedesktop/resolve1/link/_1 { org.freedesktop.resolve1.NoSuchService - A service look-up was successful, but the SRV record reported that the service is not - available. + A service look-up was successful, but the SRV record + reported that the service is not available. org.freedesktop.resolve1.DnssecFailed The acquired response did not pass DNSSEC validation. diff --git a/man/resolvectl.xml b/man/resolvectl.xml index bd1a636d605..b9c4d1d768f 100644 --- a/man/resolvectl.xml +++ b/man/resolvectl.xml @@ -75,21 +75,26 @@ [[NAME] TYPE] DOMAIN - Resolve DNS-SD and - SRV 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). + Resolve DNS-SD and SRV 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 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 + SRV type, and an SRV lookup is done + (no TXT). openpgp EMAIL@DOMAIN… - Query PGP keys stored as OPENPGPKEY - resource records. Specified e-mail addresses are converted to the corresponding DNS domain name, and any - OPENPGPKEY keys are printed. + Query PGP keys stored as OPENPGPKEY resource records, + ssee RFC 7929. Specified e-mail addresses + are converted to the corresponding DNS domain name, and any OPENPGPKEY + keys are printed. @@ -97,11 +102,13 @@ [FAMILY] DOMAIN[:PORT]… - Query TLS public keys stored as TLSA - resource records. A query will be performed for each of the specified names prefixed with the port and family + Query TLS public keys stored as TLSA resource + records, see RFC 6698. A query will be + performed for each of the specified names prefixed with the port and family (_port._family.domain). - The port number may be specified after a colon (:), otherwise 443 will be used - by default. The family may be specified as the first argument, otherwise tcp will be used. + The port number may be specified after a colon (:), otherwise + 443 will be used by default. The family may be specified as the first argument, + otherwise tcp will be used. @@ -128,8 +135,8 @@ flush-caches - Flushes all DNS resource record caches the service maintains locally. This is mostly equivalent - to sending the SIGUSR2 to the systemd-resolved + Flushes all DNS resource record caches the service maintains locally. This is mostly + equivalent to sending the SIGUSR2 to the systemd-resolved service. @@ -246,10 +253,11 @@ CLASS When used in conjunction with the query 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 help may be used to - list known values. + 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 help may be used to list known values. Without these options resolvectl query 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 @@ BOOL Takes a boolean parameter. If true (the default), when doing a service lookup with - the hostnames contained in the SRV resource records are resolved as well. + the hostnames contained in the SRV + resource records are resolved as well. BOOL - Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with - the TXT service metadata record is resolved as well. + Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup + with the TXT service metadata record is + resolved as well. BOOL - Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are + 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. @@ -465,7 +476,7 @@ Examples - Retrieve the addresses of the <literal>www.0pointer.net</literal> domain + Retrieve the addresses of the <literal>www.0pointer.net</literal> domain (<constant class='dns'>A</constant> and <constant class='dns'>AAAA</constant> resource records) $ 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 - Retrieve the domain of the <literal>85.214.157.71</literal> IP address + Retrieve the domain of the <literal>85.214.157.71</literal> IP address + (<constant class='dns'>PTR</constant> resource record) $ 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 - Retrieve the MX record of the <literal>yahoo.com</literal> domain + Retrieve the <constant class='dns'>MX</constant> record of the <literal>yahoo.com</literal> + domain $ 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 - Resolve an SRV service + Resolve an <constant class='dns'>SRV</constant> service $ 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 - Retrieve a PGP key + Retrieve a PGP key (<constant class='dns'>OPENPGP</constant> resource record) $ resolvectl openpgp zbyszek@fedoraproject.org d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY @@ -521,8 +534,7 @@ d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproje - Retrieve a TLS key (<literal>tcp</literal> and - <literal>:443</literal> could be skipped) + Retrieve a TLS key (<constant class='dns'>TLSA</constant> resource record) $ 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 + + tcp and :443 are optional and could be skipped. diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml index be2e873efb3..c7d781b5688 100644 --- a/man/systemd.dnssd.xml +++ b/man/systemd.dnssd.xml @@ -123,13 +123,15 @@ Priority= - A priority number set in SRV resource records corresponding to the network service. + A priority number set in SRV resource records corresponding + to the network service. Weight= - A weight number set in SRV resource records corresponding to the network service. + A weight number set in SRV resource records corresponding + to the network service.