mirror of
https://github.com/Dasharo/systemd.git
synced 2026-03-06 15:02:31 -08:00
man: drop documentation of internal lookup flags
This removes documentation of SD_RESOLVED_REQUIRE_PRIMARY and SD_RESOLVED_CLAMP_TTL, which are internal flags, and not usable from outside of resolved. They are refused by D-Bus APIs, for a reason. Various other fixes/clean-ups of the relevant docs (including reordering of the flags docs by "grouping" rather than bit values). Fixes: #26619
This commit is contained in:
Lennart Poettering
committed by
Luca Boccassi
Luca Boccassi
parent
bd65ee34ae
commit
50ff4753ec
@@ -439,32 +439,36 @@ node /org/freedesktop/resolve1 {
|
||||
<para>The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
|
||||
and recommended. However, the following flags are defined to alter the look-up:</para>
|
||||
|
||||
<programlisting>
|
||||
<programlisting>/* Input+Output: Protocol/scope */
|
||||
#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)
|
||||
|
||||
/* Input: Restrictions */
|
||||
#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)
|
||||
|
||||
/* Output: Security */
|
||||
#define SD_RESOLVED_AUTHENTICATED (UINT64_C(1) << 9)
|
||||
#define SD_RESOLVED_CONFIDENTIAL (UINT64_C(1) << 18)
|
||||
|
||||
/* Output: Origin */
|
||||
#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)
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
|
||||
<para>On input, the first five flags control the protocols to use for the look-up. They refer to
|
||||
classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
|
||||
@@ -476,8 +480,8 @@ node /org/freedesktop/resolve1 {
|
||||
address lookup domains). It will route neither of these to Unicast DNS servers. Also, it will do
|
||||
LLMNR and Multicast DNS only on interfaces suitable for multicast.</para>
|
||||
|
||||
<para>On output, these five flags indicate which protocol was used to execute the operation, and hence
|
||||
where the data was found.</para>
|
||||
<para>On output, these five flags indicate which protocol was used to execute the operation, and
|
||||
hence where the data was found.</para>
|
||||
|
||||
<para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
|
||||
earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
|
||||
@@ -496,8 +500,19 @@ node /org/freedesktop/resolve1 {
|
||||
<para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
|
||||
<function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
|
||||
using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
|
||||
will never qualify single-label domain names using search domains. Also note that
|
||||
multi-label hostnames are never subject to search list expansion.</para>
|
||||
will never qualify single-label domain names using search domains. Also note that multi-label
|
||||
hostnames are never subject to search list expansion.</para>
|
||||
|
||||
<para>NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be
|
||||
used.</para>
|
||||
|
||||
<para>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
|
||||
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
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.</para>
|
||||
|
||||
<para>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
|
||||
@@ -510,31 +525,15 @@ node /org/freedesktop/resolve1 {
|
||||
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).</para>
|
||||
|
||||
<para>NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be used.
|
||||
</para>
|
||||
<para>CONFIDENTIAL means the query was resolved via encrypted channels or never left this
|
||||
system.</para>
|
||||
|
||||
<para>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
|
||||
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>With CLAMP_TTL, if reply is answered from cache, the TTLs will be adjusted by age of cache
|
||||
entry.</para>
|
||||
|
||||
<para>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.
|
||||
</para>
|
||||
<para>The next five bits flags are used in output and provide information about the origin of the
|
||||
answer. FROM_SYNTHETIC means the query was (at least partially) synthesized locally. FROM_CACHE means
|
||||
the query was answered (at least partially) using the cache. FROM_ZONE means the query was answered
|
||||
(at least partially) based on public, locally registered records. 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.</para>
|
||||
</refsect3>
|
||||
</refsect2>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user