From 1c4539afc08f2ce4af70d32e2dcd6a3fd414c0ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 14 Dec 2021 18:48:25 +0100 Subject: [PATCH 1/3] man: describe $SYSTEMD_NSS_RESOLVE_VALIDATE This variable has a pretty important effect, but we didn't mention it anywhere in the docs. It was added in aee9d18c8d909eb7aca2838e4bce5da018b6a112. --- man/nss-resolve.xml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml index b56ac5c129..7d427b1a1a 100644 --- a/man/nss-resolve.xml +++ b/man/nss-resolve.xml @@ -64,6 +64,20 @@ /run/systemd/resolve/io.systemd.Resolve AF_UNIX socket. + + Environment variables + + + + $SYSTEMD_NSS_RESOLVE_VALIDATE + + Takes a boolean argument. When false, cryptographic validation of resource records + via DNSSEC will be disabled. This may be useful for testing, or when system time is known to be + unreliable. + + + + Example @@ -95,7 +109,8 @@ netgroup: nis nss-systemd8, nss-myhostname8, nss-mymachines8, - nsswitch.conf5 + nsswitch.conf5, + systemd.syntax5 From c6f20515ab600098b5c2871bae2e9ecab3b41555 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 14 Dec 2021 19:39:36 +0100 Subject: [PATCH 2/3] man: describe flags for record resolving --- man/org.freedesktop.resolve1.xml | 84 +++++++++++++++++++++++--------- src/resolve/resolved-def.h | 2 +- 2 files changed, 63 insertions(+), 23 deletions(-) diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml index 78a52cc67d..b8fff5a502 100644 --- a/man/org.freedesktop.resolve1.xml +++ b/man/org.freedesktop.resolve1.xml @@ -440,16 +440,30 @@ node /org/freedesktop/resolve1 { and recommended. However, the following flags are defined to alter the look-up: -#define SD_RESOLVED_DNS (UINT64_C(1) << 0) -#define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) << 1) -#define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) << 2) -#define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) << 3) -#define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) << 4) -#define SD_RESOLVED_NO_CNAME (UINT64_C(1) << 5) -#define SD_RESOLVED_NO_TXT (UINT64_C(1) << 6) -#define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) << 7) -#define SD_RESOLVED_NO_SEARCH (UINT64_C(1) << 8) -#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9) +#define SD_RESOLVED_DNS (UINT64_C(1) << 0) +#define SD_RESOLVED_LLMNR_IPV4 (UINT64_C(1) << 1) +#define SD_RESOLVED_LLMNR_IPV6 (UINT64_C(1) << 2) +#define SD_RESOLVED_MDNS_IPV4 (UINT64_C(1) << 3) +#define SD_RESOLVED_MDNS_IPV6 (UINT64_C(1) << 4) +#define SD_RESOLVED_NO_CNAME (UINT64_C(1) << 5) +#define SD_RESOLVED_NO_TXT (UINT64_C(1) << 6) +#define SD_RESOLVED_NO_ADDRESS (UINT64_C(1) << 7) +#define SD_RESOLVED_NO_SEARCH (UINT64_C(1) << 8) +#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9) +#define SD_RESOLVED_NO_VALIDATE (UINT64_C(1) << 10) +#define SD_RESOLVED_NO_SYNTHESIZE (UINT64_C(1) << 11) +#define SD_RESOLVED_NO_CACHE (UINT64_C(1) << 12) +#define SD_RESOLVED_NO_ZONE (UINT64_C(1) << 13) +#define SD_RESOLVED_NO_TRUST_ANCHOR (UINT64_C(1) << 14) +#define SD_RESOLVED_NO_NETWORK (UINT64_C(1) << 15) +#define SD_RESOLVED_REQUIRE_PRIMARY (UINT64_C(1) << 16) +#define SD_RESOLVED_CLAMP_TTL (UINT64_C(1) << 17) +#define SD_RESOLVED_CONFIDENTIAL (UINT64_C(1) << 18) +#define SD_RESOLVED_SYNTHETIC (UINT64_C(1) << 19) +#define SD_RESOLVED_FROM_CACHE (UINT64_C(1) << 20) +#define SD_RESOLVED_FROM_ZONE (UINT64_C(1) << 21) +#define SD_RESOLVED_FROM_TRUST_ANCHOR (UINT64_C(1) << 22) +#define SD_RESOLVED_FROM_NETWORK (UINT64_C(1) << 23) On input, the first five flags control the protocols to use for the look-up. They refer to @@ -475,9 +489,9 @@ node /org/freedesktop/resolve1 { when the flag is off, CNAME/DNAME RRs are followed. The NO_TXT and NO_ADDRESS flags only influence operation of the - ResolveService() method. They are only defined for input, not output. If - NO_TXT set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is specified, - the hostnames discovered are not implicitly translated to their addresses. + ResolveService() method. They are only defined for input, not output. If NO_TXT + is set, the DNS-SD TXT RR look-up is not done in the same operation. If NO_ADDRESS is set, the + discovered hostnames are not implicitly translated to their addresses. The NO_SEARCH flag turns off the search domain logic. It is only defined for input in ResolveHostname(). When specified, single-label hostnames are not qualified @@ -486,15 +500,41 @@ node /org/freedesktop/resolve1 { multi-label hostnames are never subject to search list expansion. The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the - returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected data - for which a full trust chain may be established to a trusted domain anchor. It is also set for locally - synthesized data, such as localhost or data from - /etc/hosts. Moreover, it is set for all LLMNR or mDNS RRs which originate from the - local host. Applications that require authenticated RR data for operation should check this flag before - trusting the data. Note that systemd-resolved will never return invalidated data, hence this flag - simply allows to discern the cases where data is known to be trustable, or where there is proof that - the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server - does not support authenticating data). + returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected + data for which a full trust chain may be established to a trusted domain anchor. It is also set for + locally synthesized data, such as localhost or data from + /etc/hosts. Moreover, it is set for all LLMNR or mDNS RRs which originate from + the local host. Applications that require authenticated RR data for operation should check this flag + before trusting the data. Note that systemd-resolved will never return + invalidated data, hence this flag simply allows to discern the cases where data is known to be + trusted, or where there is proof that the data is "rightfully" unauthenticated (which includes cases + where the underlying protocol or server does not support authenticating data). + + NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be used. + + + The next four flags allow disabling certain sources during resolution. NO_SYNTHESIZE disables + synthetic records, e.g. the local host name, see section SYNTHETIC RECORDS in + systemd-resolved.service8 + for more information. NO_CACHE disables the use of the cache of previously resolved records. NO_ZONE + disables answers using locally registered public LLMNR/mDNS resource records. NO_TRUST_ANCHOR + disables answers using locally configured trust anchors. NO_NETWORK requires all answers to be + provided without using the network, i.e. either from local sources or the cache. + + With REQUIRE_PRIMARY the request must be answered from a "primary" answer, i.e. not from + resource records acquired as a side-effect of a previous transaction. + + With CLAMP_TTL, if reply is answered from cache, the TTLs will be adjusted by age of cache + entry. + + The next six bits flags are used in output and provide information about the source of the answer. + CONFIDENTIAL means the query was resolved via encrypted channels or never left this system. + FROM_SYNTHETIC means the query was (at least partially) synthesized. + FROM_CACHE means the query was answered (at least partially) using the cache. + FROM_ZONE means the query was answered (at least partially) using LLMNR/mDNS. + FROM_TRUST_ANCHOR means the query was answered (at least partially) using local trust anchors. + FROM_NETWORK means the query was answered (at least partially) using the network. + diff --git a/src/resolve/resolved-def.h b/src/resolve/resolved-def.h index 702d3f8b41..36092afa48 100644 --- a/src/resolve/resolved-def.h +++ b/src/resolve/resolved-def.h @@ -39,7 +39,7 @@ /* Input: Don't answer request from locally registered public LLMNR/mDNS RRs */ #define SD_RESOLVED_NO_ZONE (UINT64_C(1) << 13) -/* Input: Don't answer request from locally registered public LLMNR/mDNS RRs */ +/* Input: Don't answer request from locally configured trust anchors. */ #define SD_RESOLVED_NO_TRUST_ANCHOR (UINT64_C(1) << 14) /* Input: Don't go to network for this request */ From e803cf21393c9e49cb47903365f436a07a6fa3ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 18 Dec 2021 17:03:43 +0100 Subject: [PATCH 3/3] man: correctly document default for DNSSEC= and DNSoverTLS= https://bugzilla.redhat.com/show_bug.cgi?id=1926323 --- man/custom-entities.ent.in | 2 ++ man/resolved.conf.xml | 9 ++++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/man/custom-entities.ent.in b/man/custom-entities.ent.in index 815735910a..929ba8e83f 100644 --- a/man/custom-entities.ent.in +++ b/man/custom-entities.ent.in @@ -13,5 +13,7 @@ + + diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index f53af362e8..3c56b76748 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -1,6 +1,9 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +%entities; +]> - Defaults to allow-downgrade. + Defaults to &DEFAULT_DNSSEC_MODE;. @@ -239,7 +242,7 @@ DNSOverTLS= setting is in effect. For per-link DNS servers the per-link setting is in effect, unless it is unset in which case the global setting is used instead. - Defaults to off. + Defaults to &DEFAULT_DNS_OVER_TLS_MODE;.