<\/a> <\/h2>\nThe service exposes the following interfaces on the Manager object on the bus:<\/font><\/p>\nnode \/org\/freedesktop\/resolve1 {
interface org.freedesktop.resolve1.Manager {
methods:
ResolveHostname(in i ifindex,
in s name,
in i family,
in t flags,
out a(iiay) addresses,
out s canonical,
out t flags);
ResolveAddress(in i ifindex,
in i family,
in ay address,
in t flags,
out a(is) names,
out t flags);
ResolveRecord(in i ifindex,
in s name,
in q class,
in q type,
in t flags,
out a(iqqay) records,
out t flags);
ResolveService(in i ifindex,
in s name,
in s type,
in s domain,
in i family,
in t flags,
out a(qqqsa(iiay)s) srv_data,
out aay txt_data,
out s canonical_name,
out s canonical_type,
out s canonical_domain,
out t flags);
GetLink(in i ifindex,
out o path);
SetLinkDNS(in i ifindex,
in a(iay) addresses);
SetLinkDNSEx(in i ifindex,
in a(iayqs) addresses);
SetLinkDomains(in i ifindex,
in a(sb) domains);
SetLinkDefaultRoute(in i ifindex,
in b enable);
SetLinkLLMNR(in i ifindex,
in s mode);
SetLinkMulticastDNS(in i ifindex,
in s mode);
SetLinkDNSOverTLS(in i ifindex,
in s mode);
SetLinkDNSSEC(in i ifindex,
in s mode);
SetLinkDNSSECNegativeTrustAnchors(in i ifindex,
in as names);
RevertLink(in i ifindex);
RegisterService(in s name,
in s name_template,
in s type,
in q service_port,
in q service_priority,
in q service_weight,
in aa{say} txt_datas,
out o service_path);
UnregisterService(in o service_path);
ResetStatistics();
FlushCaches();
ResetServerFeatures();
properties:
readonly s LLMNRHostname = ‘…’;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly s LLMNR = ‘…’;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly s MulticastDNS = ‘…’;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly s DNSOverTLS = ‘…’;
readonly a(iiay) DNS = […];
readonly a(iiayqs) DNSEx = […];
@org.freedesktop.DBus.Property.EmitsChangedSignal(“const”)
readonly a(iiay) FallbackDNS = […];
@org.freedesktop.DBus.Property.EmitsChangedSignal(“const”)
readonly a(iiayqs) FallbackDNSEx = […];
readonly (iiay) CurrentDNSServer = …;
readonly (iiayqs) CurrentDNSServerEx = …;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly a(isb) Domains = […];
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly (tt) TransactionStatistics = …;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly (ttt) CacheStatistics = …;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly s DNSSEC = ‘…’;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly (tttt) DNSSECStatistics = …;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly b DNSSECSupported = …;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly as DNSSECNegativeTrustAnchors = [‘…’, …];
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly s DNSStubListener = ‘…’;
@org.freedesktop.DBus.Property.EmitsChangedSignal(“false”)
readonly s ResolvConfMode = ‘…’;
};
interface org.freedesktop.DBus.Peer { … };
interface org.freedesktop.DBus.Introspectable { … };
interface org.freedesktop.DBus.Properties { … };
};<\/font><\/p>\nMethods
ResolveHostname()<\/b> takes a hostname and resolves it to one or more IP addresses. As parameters it takes the Linux network interface index to execute the query on, or 0 if it may be done on any suitable interface. The name<\/i> parameter specifies the hostname to resolve. Note that if required, IDNA conversion is applied to this name unless it is resolved via LLMNR or MulticastDNS. The family<\/i> parameter limits the results to a specific address family. It may be AF_INET<\/b>, AF_INET6<\/b> or AF_UNSPEC<\/b>. If AF_UNSPEC<\/b> is specified (recommended), both kinds are retrieved, subject to local network configuration (i.e. if no local, routable IPv6 address is found, no IPv6 address is retrieved; and similarly for IPv4). A 64\u2212bit flags<\/i> field may be used to alter the behaviour of the resolver operation (see below). The method returns an array of address records. Each address record consists of the interface index the address belongs to, an address family as well as a byte array with the actual IP address data (which either has 4 or 16 elements, depending on the address family). The returned address family will be one of AF_INET<\/b> or AF_INET6<\/b>. For IPv6, the returned address interface index should be used to initialize the .sin6_scope_id field of a struct\u00a0sockaddr_in6 instance to permit support for resolution to link\u2212local IP addresses. The address array is followed by the canonical name of the host, which may or may not be identical to the resolved hostname. Finally, a 64\u2212bit flags<\/i> field is returned that is defined similarly to the flags<\/i> field that was passed in, but contains information about the resolved data (see below). If the hostname passed in is an IPv4 or IPv6 address formatted as string, it is parsed, and the result is returned. In this case, no network communication is done.<\/font><\/p>\nResolveAddress()<\/b> executes the reverse operation: it takes an IP address and acquires one or more hostnames for it. As parameters it takes the interface index to execute the query on, or 0<\/b> if all suitable interfaces are OK. The family<\/i> parameter indicates the address family of the IP address to resolve. It may be either AF_INET<\/b> or AF_INET6<\/b>. The address<\/i> parameter takes the raw IP address data (as either a 4 or 16 byte array). The flags<\/i> input parameter may be used to alter the resolver operation (see below). The method returns an array of name records, each consisting of an interface index and a hostname. The flags<\/i> output field contains additional information about the resolver operation (see below).<\/font><\/p>\nResolveRecord()<\/b> takes a DNS resource record (RR) type, class and name, and retrieves the full resource record set (RRset), including the RDATA, for it. As parameter it takes the Linux network interface index to execute the query on, or 0<\/b> if it may be done on any suitable interface. The name<\/i> parameter specifies the RR domain name to look up (no IDNA conversion is applied), followed by the 16\u2212bit class and type fields (which may be ANY). Finally, a flags<\/i> field may be passed in to alter behaviour of the look\u2212up (see below). On completion, an array of RR items is returned. Each array entry consists of the network interface index the RR was discovered on, the type and class field of the RR found, and a byte array of the raw RR discovered. The raw RR data starts with the RR’s domain name, in the original casing, followed by the RR type, class, TTL and RDATA, in the binary format documented in<\/font> RFC\u00a01035<\/font><\/b> [3]<\/font><\/small> . For RRs that support name compression in the payload (such as MX or PTR), the compression is expanded in the returned data.<\/font><\/p>\nNote that currently, the class field has to be specified as IN or ANY. Specifying a different class will return an error indicating that look\u2212ups of this kind are unsupported. Similarly, some special types are not supported either (AXFR, OPT, …). While systemd\u2212resolved parses and validates resource 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.<\/font><\/p>\nResolveService()<\/b> may be used to resolve a DNS SRV service record, as well as the hostnames referenced in it, and possibly an accompanying DNS\u2212SD TXT record containing additional service metadata. The primary benefit of using this method over ResolveRecord()<\/b> 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:<\/font><\/p>\n1. To resolve a DNS\u2212SD service, specify the service name (e.g. “Lennart’s Files”), the service type (e.g. “_webdav._tcp”) and the domain to search in (e.g. “local”) as the three service parameters. The service name must be in UTF\u22128 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS\u2212SD specifications). However, if necessary, IDNA conversion is applied to the domain parameter.<\/font><\/p>\n2. 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.)<\/font><\/p>\n3. 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 coversion is applied in this mode.)<\/font><\/p>\nThe family<\/i> parameter of the ResolveService()<\/b> method encodes the desired family of the addresses to resolve (use AF_INET<\/b>, AF_INET6<\/b>, or AF_UNSPEC<\/b>). If this is enabled (Use the NO_ADDRESS<\/b> flag to turn address resolution off, see below). The flags<\/i> parameter takes a couple of flags that may be used to alter the resolver operation.<\/font><\/p>\nOn completion, ResolveService()<\/b> 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\u2212SD look\u2212ups 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<\/i> field is returned that contains information about the resolver operation performed.<\/font><\/p>\nThe ResetStatistics()<\/b> method resets the various statistics counters that systemd\u2212resolved maintains to zero. (For details, see the statistics properties below.)<\/font><\/p>\nThe GetLink()<\/b> method takes a network interface index and returns the object path to the org.freedesktop.resolve1.Link object corresponding to it.<\/font><\/p>\nThe SetLinkDNS()<\/b> method sets the DNS servers to use on a specific interface. This method (and the following ones) may be used by network management software to configure per\u2212interface DNS settings. It takes a network interface index as well as an array of DNS server IP address records. Each array item consists of an address family (either AF_INET<\/b> or AF_INET6<\/b>), followed by a 4\u2212byte or 16\u2212byte array with the raw address data. This method is a one\u2212step shortcut for retrieving the Link object for a network interface using GetLink()<\/b> (see above) and then invoking the SetDNS()<\/b> method (see below) on it.<\/font><\/p>\nSetLinkDNSEx()<\/b> is similar to SetLinkDNS()<\/b>, but allows an IP port (instead of the default 53) and DNS name to be specified for each DNS server. The server name is used for Server Name Indication (SNI), which is useful when DNS\u2212over\u2212TLS is used. C.f. DNS=<\/i> in resolved.conf<\/b>(5).<\/font><\/p>\nSetLinkDefaultRoute()<\/b> specifies whether the link shall be used as the default route for name queries. See the description of name routing in systemd-resolved.service<\/b>(8) for details.<\/font><\/p>\nThe SetLinkDomains()<\/b> method sets the search and routing domains to use on a specific network interface for DNS look\u2212ups. It takes a network interface index and an array of domains, each with a boolean parameter indicating whether the specified domain shall be used as a search domain (false), or just as a routing domain (true). Search domains are used for qualifying single\u2212label names into FQDN when looking up hostnames, as well as for making routing decisions on which interface to send queries ending in the domain to. Routing domains are only used for routing decisions and not used for single\u2212label name qualification. Pass the search domains in the order they should be used.<\/font><\/p>\nThe SetLinkLLMNR()<\/b> method enables or disables LLMNR support on a specific network interface. It takes a network interface index as well as a string that may either be empty or one of “yes”, “no” or “resolve”. If empty, the systemd\u2212wide default LLMNR setting is used. If “yes”, LLMNR is used for resolution of single\u2212label names and the local hostname is registered on all local LANs for LLMNR resolution by peers. If “no”, LLMNR is turned off fully on this interface. If “resolve”, LLMNR is only enabled for resolving names, but the local hostname is not registered for other peers to use.<\/font><\/p>\nSimilarly, the SetLinkMulticastDNS()<\/b> method enables or disables MulticastDNS support on a specific interface. It takes the same parameters as SetLinkLLMNR()<\/b> described above.<\/font><\/p>\nThe SetLinkDNSSEC()<\/b> method enables or disables DNSSEC validation on a specific network interface. It takes a network interface index as well as a string that may either be empty or one of “yes”, “no”, or “allow\u2212downgrade”. When empty, the system\u2212wide default DNSSEC setting is used. If “yes”, full DNSSEC validation is done for all look\u2212ups. If the selected DNS server does not support DNSSEC, look\u2212ups will fail if this mode is used. If “no”, DNSSEC validation is fully disabled. If “allow\u2212downgrade”, DNSSEC validation is enabled, but is turned off automatically if the selected server does not support it (thus opening up behaviour to downgrade attacks). Note that DNSSEC only applies to traditional DNS, not to LLMNR or MulticastDNS.<\/font><\/p>\nThe SetLinkDNSSECNegativeTrustAnchors()<\/b> method may be used to configure DNSSEC Negative Trust Anchors (NTAs) for a specific network interface. It takes a network interface index and a list of domains as arguments.<\/font><\/p>\nThe SetLinkDNSOverTLS()<\/b> method enables or disables DNS\u2212over\u2212TLS. C.f. DNSOverTLS=<\/i> in systemd-resolved.service<\/b>(8) for details.<\/font><\/p>\nNetwork management software integrating with systemd\u2212resolved should call SetLinkDNS()<\/b> or SetLinkDNSEx()<\/b>, SetLinkDefaultRoute()<\/b>, SetLinkDomains()<\/b> and others after the interface appeared in the kernel (and thus after a network interface index has been assigned), but before the network interfaces is activated (IFF_UP<\/b> set) so that all settings take effect during the full time the network interface is up. It is safe to alter settings while the interface is up, however. Use RevertLink()<\/b> (described below) to reset all per\u2212interface settings.<\/font><\/p>\nThe RevertLink()<\/b> method may be used to revert all per\u2212link settings described above to the defaults.<\/font><\/p>\nThe Flags Parameter<\/big><\/b><\/font><\/p>\nThe four methods above accept and return a 64\u2212bit flags value. In most cases passing 0 is sufficient and recommended. However, the following flags are defined to alter the look\u2212up:<\/font><\/p>\n#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)<\/font><\/p>\nOn input, the first five flags control the protocols to use for the look\u2212up. They refer to classic unicast DNS, LLMNR via IPv4\/UDP and IPv6\/UDP respectively, as well as MulticastDNS via IPv4\/UDP and IPv6\/UDP. If all of these five bits are off on input (which is strongly recommended) the look\u2212up will be done via all suitable protocols for the specific look\u2212up. Note that these flags operate as filter only, but cannot force a look\u2212up to be done via a protocol. Specifically, systemd\u2212resolved will only route look\u2212ups within the .local TLD to MulticastDNS (plus some reverse look\u2212up address domains), and single\u2212label names to LLMNR (plus some reverse 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.<\/font><\/p>\nOn output, these five flags indicate which protocol was used to execute the operation, and hence where the data was found.<\/font><\/p>\nThe primary use cases for these five flags are follow\u2212up look\u2212ups based on DNS data retrieved earlier. In this case it is often a good idea to limit the follow\u2212up look\u2212up to the protocol that was used to discover the first DNS result.<\/font><\/p>\nThe NO_CNAME flag controls whether CNAME\/DNAME resource records shall be followed during the look\u2212up. This flag is only available at input, none of the functions will return it on output. If a CNAME\/DNAME RR is discovered while resolving a hostname, an error is returned instead. By default, when the flag is off, CNAME\/DNAME RRs are followed.<\/font><\/p>\nThe NO_TXT and NO_ADDRESS flags only influence operation of the ResolveService()<\/b> method. They are only defined for input, not output. If NO_TXT set, the DNS\u2212SD TXT RR look\u2212up is not done in the same operation. If NO_ADDRESS is specified, the hostnames discovered are not implicitly translated to their addresses.<\/font><\/p>\nThe NO_SEARCH flag turns off the search domain logic. It is only defined for input in ResolveHostname()<\/b>. When specified, single\u2212label hostnames are not qualified using defined search domains, if any are configured. Note that ResolveRecord()<\/b> will never qualify single\u2212label domain names using search domains. Also note that multi\u2212label hostnames are never subject to search list expansion.<\/font><\/p>\nThe 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\u2212protected 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\u2212resolved 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).<\/font><\/p>\nProperties<\/b>
The LLMNR<\/i> and MulticastDNS<\/i> properties report whether LLMNR and MulticastDNS are (globally) enabled. Each may be one of “yes”, “no”, and “resolve”. See SetLinkLLMNR()<\/b> and SetLinkMulticastDNS()<\/b> above.<\/font><\/p>\nLLMNRHostname<\/i> contains the hostname currently exposed on the network via LLMNR. It usually follows the system hostname as may be queried via gethostname<\/b>(3), but may differ if a conflict is detected on the network.<\/font><\/p>\nDNS<\/i> and DNSEx<\/i> contain arrays of all DNS servers currently used by systemd\u2212resolved. DNS<\/i> contains information similar to the DNS server data in \/run\/systemd\/resolve\/resolv.conf. Each structure in the array consists of a numeric network interface index, an address family, and a byte array containing the DNS server address (either 4 bytes in length for IPv4 or 16 bytes in lengths for IPv6). DNSEx<\/i> is similar, but additionally contains the IP port and server name (used for Server Name Indication, SNI). Both arrays contain DNS servers configured system\u2212wide, including those possibly read from a foreign \/etc\/resolv.conf or the DNS=<\/i> setting in \/etc\/systemd\/resolved.conf, as well as per\u2212interface DNS server information either retrieved from systemd-networkd<\/b>(8), or configured by external software via SetLinkDNS()<\/b> or SetLinkDNSEx()<\/b> (see above). The network interface index will be 0 for the system\u2212wide configured services and non\u2212zero for the per\u2212link servers.<\/font><\/p>\nFallbackDNS<\/i> and FallbackDNSEx<\/i> contain arrays of all DNS servers configured as fallback servers, if any, using the same format as DNS<\/i> and DNSEx<\/i> described above. See the description of FallbackDNS=<\/i> in resolved.conf<\/b>(5) for the description of when those servers are used.<\/font><\/p>\nCurrentDNSServer<\/i> and CurrentDNSServerEx<\/i> specify the server that is currently used for query resolution, in the same format as a single entry in the DNS<\/i> and DNSEx<\/i> arrays described above.<\/font><\/p>\nSimilarly, the Domains<\/i> property contains an array of all search and routing domains currently used by systemd\u2212resolved. Each entry consists of a network interface index (again, 0 encodes system\u2212wide entries), the actual domain name, and whether the entry is used only for routing (true) or for both routing and searching (false).<\/font><\/p>\nThe TransactionStatistics<\/i> property contains information about the number of transactions systemd\u2212resolved has processed. It contains a pair of unsigned 64\u2212bit counters, the first containing the number of currently ongoing transactions, the second the number of total transactions systemd\u2212resolved is processing or has processed. The latter value may be reset using the ResetStatistics()<\/b> method described above. Note that the number of transactions does not directly map to the number of issued resolver bus method calls. While simple look\u2212ups usually require a single transaction only, more complex look\u2212ups might result in more, for example when CNAMEs or DNSSEC are in use.<\/font><\/p>\nThe CacheStatistics<\/i> property contains information about the executed cache operations so far. It exposes three 64\u2212bit counters: the first being the total number of current cache entries (both positive and negative), the second the number of cache hits, and the third the number of cache misses. The latter counters may be reset using ResetStatistics()<\/b> (see above).<\/font><\/p>\nThe DNSSEC<\/i> property specifies current status of DNSSEC validation. It is one of “yes” (validation is enforced), “no” (no validation is done), “allow\u2212downgrade” (validation is done if the current DNS server supports it). See the description of DNSSEC=<\/i> in resolved.conf<\/b>(5).<\/font><\/p>\nThe DNSSECStatistics<\/i> property contains information about the DNSSEC validations executed so far. It contains four 64\u2212bit counters: the number of secure, insecure, bogus, and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and each non\u2212existance proof. The secure counter is increased for each operation that successfully verified a signed reply, the insecure counter is increased for each operation that successfully verified that an unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the validation did not check out and the data is likely to have been tempered with. Finally the indeterminate counter is increased for each operation which did not complete because the necessary keys could not be acquired or the cryptographic algorithms were unknown.<\/font><\/p>\nThe DNSSECSupported<\/i> boolean property reports whether DNSSEC is enabled and the selected DNS servers support it. It combines information about system\u2212wide and per\u2212link DNS settings (see below), and only reports true if DNSSEC is enabled and supported on every interface for which DNS is configured and for the system\u2212wide settings if there are any. Note that systemd\u2212resolved assumes DNSSEC is supported by DNS servers until it verifies that this is not the case. Thus, the reported value may initially be true, until the first transactions are executed.<\/font><\/p>\nThe DNSOverTLS<\/i> boolean property reports whether DNS\u2212over\u2212TLS is enabled.<\/font><\/p>\nThe ResolvConfMode<\/i> property exposes how \/etc\/resolv.conf is managed on the host. Currently, the values “uplink”, “stub”, “static” (these three correspond to the three different files systemd\u2212resolved.service provides), “foreign” (the file is managed by admin or another service, systemd\u2212resolved.service just consumes it), “missing” (\/etc\/resolv.conf is missing).<\/font><\/p>\nThe DNSStubListener<\/i> property reports whether the stub listener on port 53 is enabled. Possible values are “yes” (enabled), “no” (disabled), “udp” (only the UDP listener is enabled), and “tcp” (only the TCP listener is enabled).<\/font><\/p>\n