This page has been obsoleted and replaced: https://www.freedesktop.org/software/systemd/man/org.freedesktop.resolve1.html.
resolved
systemd 229 and newer include a fully featured DNS resolver implementation in the systemd-resolved service. This is a small daemon that provides DNS and LLMNR based host name resolution and caching. Since it acts as DNSSEC validating stub resolver it is suitable for retrieving DNS certificate and SSH fingerprint resource records.
See systemd-resolved(8).service for more information.
systemd-resolved may be used via two interfaces: directly via its D-Bus interface (which is documented here), or via glibc NSS getaddrinfo(), in which case it provides forward and reverse hostname resolution. The former is useful to retrieve arbitrary DNS resource records or DNSSEC authentication information. It generally provides a more fine-grained control over the lookups made thatn the latter. In addition it provides calls to introspect and configure the DNS resolver.
This page contains an API reference only. If you are looking for a longer explanation how to use this API, please consult Writing Network Configuration Managers and Writing Resolver Clients.
The Manager Object
The service exposes the following interfaces on the Manager object on the bus:
node /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);
ResetStatistics();
GetLink(in i ifindex,
out o path);
SetLinkDNS(in i ifindex,
in a(iay) addresses);
SetLinkDomains(in i ifindex,
in a(sb) domains);
SetLinkLLMNR(in i ifindex,
in s mode);
SetLinkMulticastDNS(in i ifindex,
in s mode);
SetLinkDNSSEC(in i ifindex,
in s mode);
SetLinkDNSSECNegativeTrustAnchors(in i ifindex,
in as names);
RevertLink(in i ifindex);
properties:
readonly s LLMNRHostname = 'delta';
readonly a(iiay) DNS = [(0, 2, [0xac, 0x1f, 0x00, 0x01])];
readonly a(isb) Domains = [(0, 'fritz.box', false)];
readonly (tt) TransactionStatistics = (0, 846);
readonly (ttt) CacheStatistics = (55, 406, 439);
readonly (tttt) DNSSECStatistics = (0, 0, 0, 0);
readonly b DNSSECSupported = false;
};
interface org.freedesktop.DBus.Peer {
};
interface org.freedesktop.DBus.Introspectable {
};
interface org.freedesktop.DBus.Properties {
};
};
Methods
ResolveHostname() takes a hostname and acquires one or more IP addresses for it. 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 parameter specifies the hostname to resolve. Note that IDNA conversion is applied to this name when necessary, and when it is resolved via Unicast DNS, but not for resolution via LLMNR or MulticastDNS. The family parameter specifies the address family of the IP address to retrieve. It may be AF_INET, AF_INET6 or AF_UNSPEC, to request addresses of a specific family. If AF_UNSPEC 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 similar for IPv4). A 64bit flags field may be used to alter behaviour of the resolver operation (see below). The method returns an array of address records. Each address record consists of an 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 or AF_INET6. For IPv6, the returned address interface index should be used to initialize the .sin6_scope_id field of a struct sockaddr_in6, to permit support for resolution to link-local IP addresses. The address array is followed by the canonical name of the host, which may or may not be identical to the name looked up. Finally, a 64bit flags field is returned, that is defined similar to the flags 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 returned. In this case no network communication is done.
ResolveAddress() 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 if all suitable interfaces are OK. The family parameter indicates the address family of the IP address to resolve, it may be either AF_INET or AF_INET6. The address parameter takes the raw IP address data (as either 4 or 16 byte array). The flags input parameter may be used to alter the resolver operation (see below). The call returns an array of name records, consisting of an interface index plus the name each. The flags output field contains additional information about the resolver operation (see below).
ResolveRecord() 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 if it may be done on any suitable interface. The name parameter specifies the RR domain name to look up (no IDNA conversion is applied), followed by the 16bit class and type fields (which may be ANY). Finally, a flags field may be passed in to alter behaviour of the look-up (see below). On return 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 RFC 1035. For RRs that support name compression in the payload (such as MX or PTR), the compression is expanded in the returned data.
Note that the class field has to be specified as IN or ANY currently, and specifying a different class will return an error indicating that look-ups of this kind are unsupported. Similar, some special types are not supported either (AXFR, OPT, …). While resolved parses and validates resource record 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.
ResolveService() may be used to resolve a DNS SRV service record, as the hostnames referenced in it, and possibly an accompanying DNS-SD TXT record containing additional service metadata. The primary benefit of using this call 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. The call may be invoked in three different modes:
- To resolve a DNS-SD 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) in the three service parameters. The service name must be in UTF-8 format, and no IDNA conversion is applied to it in this mode (as mandated by the DNS-SD 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)
- 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)
The family parameter of the ResolveService() call encodes the desired family of the addresses to resolve (use AF_INET, AF_INET6, AF_UNSPEC), if this is enabled (Use the NO_ADDRESS flag to turn address resolution off, see below). The flags parameter takes a couple of flags that may be used to alter the resolver operation.
On return, ResolveService() returns an array of SRV record structures. Each item consists of the priority, weight and port fields and the hostname to contact, as encoded in the SRV record. Immediately following is an array with 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 with 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 to zero the various statistics counters resolved maintains. (For details, see the statistics properties below.)
The GetLink() method takes a network interface index and returns the object path to the org.freedesktop.resolve1.Link object corresponding to it.
The SetLinkDNS() method sets the DNS servers to use on a specific interface. This call (and the following ones) may be used by network management software to configure per-interface 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 or AF_INET6), followed by a 4-byte or 16-byte array with the raw address data. This call is a one-call shortcut for retrieving the Link object for a network interface using GetLink() (see above) and then invoking the SetDNS() call (see below) on it.
Network management software integrating with resolved is recommended to invoke this method (and the five below) after the interface appeared in the kernel (and thus after a network interface index has been assigned) but before the network interfaces is activated (set IFF_UP on) 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 the RevertLink() (described below) to reset all per-interface settings made.
The SetLinkDomains() method sets the search and routing domains to use on a specific network interface for DNS look-ups. It take a network interface index plus an array of domains, each with a boolean parameter indicating whether the specified domain shall be used as search domain (false), or just as routing domain (true). Search domains are used for qualifying single-label 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 not used for single-label name qualification, and are only used for routing decisions. Pass the search domains in the order they shall be used.
The SetLinkLLMNR() method enables or disables LLMNR support on a specific network interface. It takes a network interface index as well as a string that either may be empty, "yes", "no" or "resolve". If empty, the systemd-wide default LLMNR setting is used. If "yes" LLMNR is used for resolution of single-label 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 host name is not registered for other peers to use.
Similar, the SetLinkMulticastDNS() method enables or disables MulticastDNS support on a specific interface. It takes the same parameters as SetLinkLLMNR() described above.
The SetLinkDNSSEC() method enables or disables DNSSEC validation on a specific network interface. It takes a network interface index as well as a string that either may be empty, "yes", "no" or "allow-downgrade". If empty, the system-wide default DNSSEC setting is used. If "yes" full DNSSEC validation is done for all look-ups. If the selected DNS server does not support DNSSEC, look-ups will fail if this mode is used. If "no" DNSSEC validation is fully disabled. If "allow-downgrade" 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.
The SetLinkDNSSECNegativeTrustAnchors() 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 parameters.
The RevertLink() method may be used to revert all per-link settings done with the six calls described above to the defaults again.
Flags Parameter
The four calls above accept and return a 64bit flags value. In most cases passing 0 is sufficient 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)
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 IPv4/UDP and IPv6/UDP. If all of these five bits are off on input (which is strongly recommended) the look-up will be done via all suitable protocols for the specific look-up. Note that these flags operate as filter only, but cannot force a look-up to be done via a protocol. Specifically, resolved will only route look-ups within the .local TLD to MulticastDNS (plus some reverse look-up address domains), and single-label 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 multicasting.
On output these five flags indicate which protocol was used to execute the operation, and hence where the data was found.
The primary use case 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 used to discover the first DNS data look-up.
The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the look-up. 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.
The NO_TXT and NO_ADDRESS flags influence operation of the ResolveService() call only. 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.
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 using defined search domains, if any are configured. Note that ResolveRecord() will not qualify single-label domain names using search domains in any case. Also note that 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. Not that resolved will not return invalidated data in any case, hence this flag simply allows to discern the cases where data is known to be trustable, or where there's proof that the data is "rightfully" unauthenticated (which includes cases where the underlying protocol or server does not support authenticating data).
Properties
The LLMNRHostname contains the hostname currently exposed on the network via LLMNR. It usually follows the system hostname as may be queried via gethostname(), but may differ if a conflict is detected on the network.
The DNS contains an array containing all DNS servers currently used by resolved. It contains similar information as the DNS server data written to /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). The array contains DNS servers configured system-wide, including those possibly read from a foreign /etc/resolv.conf or the DNS= setting in /etc/systemd/resolved.conf, as well as per-interface DNS server information either retrieved from systemd-networkd or configured by external software via SetLinkDNS() (see above). The network interface index will be 0 for the system-wide configured services, and non-zero for the per-link servers.
Similar, the Domains property contains an array containing all search and routing domains currently used by resolved. Each entry consists of a network interface index (again, 0 encodes system-wide entries), the actual domain name, and whether the entry is used only for routing (true), or for both routing and searching (false).
The TransactionStatistics property contains information about the number of transactions resolved has been processing. It contains a pair of unsigned 64bit counters, the first containing the number of currently ongoing transactions, the second the number of total transactions resolved is processing or has processed. The latter value may be reset using the ResetStatistics() call described above. Note that the number of transaction does not directly map to the number of resolver bus calls issued. While simple look-ups usually require a single transaction only, more complex look-ups might result in more, for example when CNAMEs or DNSSEC are in use.
The CacheStatistics property contains information about the executed cache operations so far. It exposes three 64bit counters: the first being the total number of current cache entries (both positive and negative), the second number of cache hits, and the third the number of cache misses. The latter counters may be reset using ResetStatistics() (see above).
The DNSSECStatistics property contains information about the DNSSEC validations executed so far. It contains four 64bit counters: the number of secure, insecure, bogus, and indeterminate DNSSEC validations so far. The counters are increased for each validated RRset, and each non-existance 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 didn't complete because the necessary keys could not be acquired or the cryptographic algorithms were unknown.
The DNSSECSupported boolean properties reports whether DNSSEC is enabled and the selected DNS servers support it. It combines information about system-wide and per-link 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-wide settings if there are any. Note that resolved assumes DNSSEC is supported by DNS servers until it verified that this is not the case. Thus, the reported value may initially be true, until the first transactions are executed.
Link Object
node /org/freedesktop/resolve1/link/_34 {
interface org.freedesktop.resolve1.Link {
methods:
SetDNS(in a(iay) arg_0);
SetDomains(in a(sb) arg_0);
SetLLMNR(in s arg_0);
SetMulticastDNS(in s arg_0);
SetDNSSEC(in s arg_0);
SetDNSSECNegativeTrustAnchors(in as arg_0);
Revert();
signals:
properties:
readonly t ScopesMask = 6;
readonly a(iay) DNS = [];
readonly a(sb) Domains = [];
readonly s LLMNR = 'yes';
readonly s MulticastDNS = 'no';
readonly s DNSSEC = '';
readonly as DNSSECNegativeTrustAnchors = [];
readonly b DNSSECSupported = true;
};
interface org.freedesktop.DBus.Peer {
};
interface org.freedesktop.DBus.Introspectable {
};
interface org.freedesktop.DBus.Properties {
};
};
For each Linux network interface a "Link" object is created, which exposes per-link DNS configuration and state. Use GetLink() on the Manager interface to retrieve the object path for a link object given the network interface index (see above).
Methods
The various methods exposed by the Link interface are equivalent to their similar named counterparts on the Manager interface. e.g. SetDNS() on the Link object maps to SetLinkDNS() on the Manager object, the main difference being that the later expects an interface index to be speicified. Invoking the calls on the Manager interface has the benefit of reducing roundtrips, as it's not necessary to first request the Link object path via GetLink() before invoking the methods. For further details on these calls see the Manager documentation above.
Properties
ScopesMask defines which resolver scopes are currently active on this interface. This 64bit unsigned integer field is a bit mask, consisting of a subset of the bits as the flags parameter describe above. Specifically, it may have the DNS, LLMNR and MDNS bits (the latter in IPv4 and IPv6 flavours) set. Each individual bit is set when the protocol applies to a specific interface and is enabled for it. It is unset otherwise. Specifically, a multicast-capable interface in "UP" state with an IP address is suitable for LLMNR or MulticastDNS, and any interface that is UP and has an IP address is suitable for DNS. Note the relationship of the bits exposed here with the LLMNR and MulticastDNS properties also exposed on the Link interface. The latter expose what is configured to be used on the interface, the former expose what is actually used on the interface, taking into account the abilities of the interface.
DNSSECSupported exposes a boolean field that indicates whether DNSSEC is currently configured and in use on the interface. Note that if DNSSEC is enabled on an interface it is assumed available until it is detected that the configured server does not actually support it. Thus, this property may initially report that DNSSEC is supported on an interface.
The other properties reflect the state of the various configuration settings for the link, which may be set with the various methods calls such as SetDNS() or SetLLMNR().
Common Errors
Many bus calls resolved exposes (in particular the resolver calls such as ResolveHostname() on the Manager interface) return some of the following errors:
org.freedesktop.resolve1.NoNameServersis returned when no suitable DNS servers have been found to resolve a request.org.freedesktop.resolve1.InvalidReply: a response from the selected DNS server could not be understood.org.freedesktop.resolve1.NoSuchRR: the requested name exists, but there's not resource record of the requested type for it. (This is the DNS NODATA case)org.freedesktop.resolve1.CNameLoop: the look-up failed because a CNAME or DNAME loop was detected.org.freedesktop.resolve1.Aborted: the look-up was aborted, because the selected protocol became unavailable while the operation was ongoing.org.freedesktop.resolve1.NoSuchService: 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.org.freedesktop.resolve1.NoTrustAnchor: no chain of trust could be established for the response, to a configured DNSSEC trust anchor.org.freedesktop.resolve1.ResourceRecordTypeUnsupported: the requested resource record type is not supported on the selected DNS servers. This error is generated for example when an RRSIG record is requested from a DNS server that does not support DNSSEC.org.freedesktop.resolve1.NoSuchLink: no network interface with the specified network interface index existsorg.freedesktop.resolve1.LinkBusy: the requested configuration change can not be made, because systemd-networkd already took possesion of the interface and supplied configuration data for it.org.freedesktop.resolve1.NetworkDown: the requested look-up failed because the system is currently not connected to any suitable network.org.freedesktop.resolve1.DnsError.NXDOMAIN,org.freedesktop.resolve1.DnsError.REFUSED, … the look-up failed with a DNS return code reporting a failure. The error names used as suffixes here are defined at IANA.