1RESOLVECTL(1)                     resolvectl                     RESOLVECTL(1)
2
3
4

NAME

6       resolvectl, resolvconf - Resolve domain names, IPV4 and IPv6 addresses,
7       DNS resource records, and services; introspect and reconfigure the DNS
8       resolver
9

SYNOPSIS

11       resolvectl [OPTIONS...] {COMMAND} [NAME...]
12

DESCRIPTION

14       resolvectl may be used to resolve domain names, IPv4 and IPv6
15       addresses, DNS resource records and services with the systemd-
16       resolved.service(8) resolver service. By default, the specified list of
17       parameters will be resolved as hostnames, retrieving their IPv4 and
18       IPv6 addresses. If the parameters specified are formatted as IPv4 or
19       IPv6 operation the reverse operation is done, and a hostname is
20       retrieved for the specified addresses.
21
22       The program's output contains information about the protocol used for
23       the look-up and on which network interface the data was discovered. It
24       also contains information on whether the information could be
25       authenticated. All data for which local DNSSEC validation succeeds is
26       considered authenticated. Moreover all data originating from local,
27       trusted sources is also reported authenticated, including resolution of
28       the local host name, the "localhost" hostname or all data from
29       /etc/hosts.
30

COMMANDS

32       query HOSTNAME|ADDRESS...
33           Resolve domain names, IPv4 and IPv6 addresses.
34
35       service [[NAME] TYPE] DOMAIN
36           Resolve DNS-SD[1] and SRV[2] services, depending on the specified
37           list of parameters. If three parameters are passed the first is
38           assumed to be the DNS-SD service name, the second the SRV service
39           type, and the third the domain to search in. In this case a full
40           DNS-SD style SRV and TXT lookup is executed. If only two parameters
41           are specified, the first is assumed to be the SRV service type, and
42           the second the domain to look in. In this case no TXT RR is
43           requested. Finally, if only one parameter is specified, it is
44           assumed to be a domain name, that is already prefixed with an SRV
45           type, and an SRV lookup is done (no TXT).
46
47       openpgp EMAIL@DOMAIN...
48           Query PGP keys stored as OPENPGPKEY[3] resource records. Specified
49           e-mail addresses are converted to the corresponding DNS domain
50           name, and any OPENPGPKEY keys are printed.
51
52       tlsa [FAMILY] DOMAIN[:PORT]...
53           Query TLS public keys stored as TLSA[4] resource records. A query
54           will be performed for each of the specified names prefixed with the
55           port and family ("_port._family.domain"). The port number may be
56           specified after a colon (":"), otherwise 443 will be used by
57           default. The family may be specified as the first argument,
58           otherwise tcp will be used.
59
60       status [LINK...]
61           Shows the global and per-link DNS settings currently in effect. If
62           no command is specified, this is the implied default.
63
64       statistics
65           Shows general resolver statistics, including information whether
66           DNSSEC is enabled and available, as well as resolution and
67           validation statistics.
68
69       reset-statistics
70           Resets the statistics counters shown in statistics to zero. This
71           operation requires root privileges.
72
73       flush-caches
74           Flushes all DNS resource record caches the service maintains
75           locally. This is mostly equivalent to sending the SIGUSR2 to the
76           systemd-resolved service.
77
78       reset-server-features
79           Flushes all feature level information the resolver learnt about
80           specific servers, and ensures that the server feature probing logic
81           is started from the beginning with the next look-up request. This
82           is mostly equivalent to sending the SIGRTMIN+1 to the
83           systemd-resolved service.
84
85       dns [LINK [SERVER...]], domain [LINK [DOMAIN...]], default-route [LINK
86       [BOOL...]], llmnr [LINK [MODE]], mdns [LINK [MODE]], dnssec [LINK
87       [MODE]], dnsovertls [LINK [MODE]], nta [LINK [DOMAIN...]]
88           Get/set per-interface DNS configuration. These commands may be used
89           to configure various DNS settings for network interfaces. These
90           commands may be used to inform systemd-resolved or systemd-networkd
91           about per-interface DNS configuration determined through external
92           means. The dns command expects IPv4 or IPv6 address specifications
93           of DNS servers to use. Each address can optionally take a port
94           number separated with ":", a network interface name or index
95           separated with "%", and a Server Name Indication (SNI) separated
96           with "#". When IPv6 address is specified with a port number, then
97           the address must be in the square brackets. That is, the acceptable
98           full formats are "111.222.333.444:9953%ifname#example.com" for IPv4
99           and "[1111:2222::3333]:9953%ifname#example.com" for IPv6. The
100           domain command expects valid DNS domains, possibly prefixed with
101           "~", and configures a per-interface search or route-only domain.
102           The default-route command expects a boolean parameter, and
103           configures whether the link may be used as default route for DNS
104           lookups, i.e. if it is suitable for lookups on domains no other
105           link explicitly is configured for. The llmnr, mdns, dnssec and
106           dnsovertls commands may be used to configure the per-interface
107           LLMNR, MulticastDNS, DNSSEC and DNSOverTLS settings. Finally, nta
108           command may be used to configure additional per-interface DNSSEC
109           NTA domains.
110
111           Commands dns, domain and nta can take a single empty string
112           argument to clear their respective value lists.
113
114           For details about these settings, their possible values and their
115           effect, see the corresponding settings in systemd.network(5).
116
117       revert LINK
118           Revert the per-interface DNS configuration. If the DNS
119           configuration is reverted all per-interface DNS setting are reset
120           to their defaults, undoing all effects of dns, domain,
121           default-route, llmnr, mdns, dnssec, dnsovertls, nta. Note that when
122           a network interface disappears all configuration is lost
123           automatically, an explicit reverting is not necessary in that case.
124
125       log-level [LEVEL]
126           If no argument is given, print the current log level of the
127           manager. If an optional argument LEVEL is provided, then the
128           command changes the current log level of the manager to LEVEL
129           (accepts the same values as --log-level= described in systemd(1)).
130

OPTIONS

132       -4, -6
133           By default, when resolving a hostname, both IPv4 and IPv6 addresses
134           are acquired. By specifying -4 only IPv4 addresses are requested,
135           by specifying -6 only IPv6 addresses are requested.
136
137       -i INTERFACE, --interface=INTERFACE
138           Specifies the network interface to execute the query on. This may
139           either be specified as numeric interface index or as network
140           interface string (e.g.  "en0"). Note that this option has no effect
141           if system-wide DNS configuration (as configured in /etc/resolv.conf
142           or /etc/systemd/resolve.conf) in place of per-link configuration is
143           used.
144
145       -p PROTOCOL, --protocol=PROTOCOL
146           Specifies the network protocol for the query. May be one of "dns"
147           (i.e. classic unicast DNS), "llmnr" (Link-Local Multicast Name
148           Resolution[5]), "llmnr-ipv4", "llmnr-ipv6" (LLMNR via the indicated
149           underlying IP protocols), "mdns" (Multicast DNS[6]), "mdns-ipv4",
150           "mdns-ipv6" (MDNS via the indicated underlying IP protocols). By
151           default the lookup is done via all protocols suitable for the
152           lookup. If used, limits the set of protocols that may be used. Use
153           this option multiple times to enable resolving via multiple
154           protocols at the same time. The setting "llmnr" is identical to
155           specifying this switch once with "llmnr-ipv4" and once via
156           "llmnr-ipv6". Note that this option does not force the service to
157           resolve the operation with the specified protocol, as that might
158           require a suitable network interface and configuration. The special
159           value "help" may be used to list known values.
160
161       -t TYPE, --type=TYPE, -c CLASS, --class=CLASS
162           Specifies the DNS resource record type (e.g. A, AAAA, MX, ...) and
163           class (e.g. IN, ANY, ...) to look up. If these options are used a
164           DNS resource record set matching the specified class and type is
165           requested. The class defaults to IN if only a type is specified.
166           The special value "help" may be used to list known values.
167
168       --service-address=BOOL
169           Takes a boolean parameter. If true (the default), when doing a
170           service lookup with --service the hostnames contained in the SRV
171           resource records are resolved as well.
172
173       --service-txt=BOOL
174           Takes a boolean parameter. If true (the default), when doing a
175           DNS-SD service lookup with --service the TXT service metadata
176           record is resolved as well.
177
178       --cname=BOOL
179           Takes a boolean parameter. If true (the default), DNS CNAME or
180           DNAME redirections are followed. Otherwise, if a CNAME or DNAME
181           record is encountered while resolving, an error is returned.
182
183       --search=BOOL
184           Takes a boolean parameter. If true (the default), any specified
185           single-label hostnames will be searched in the domains configured
186           in the search domain list, if it is non-empty. Otherwise, the
187           search domain logic is disabled.
188
189       --raw[=payload|packet]
190           Dump the answer as binary data. If there is no argument or if the
191           argument is "payload", the payload of the packet is exported. If
192           the argument is "packet", the whole packet is dumped in wire
193           format, prefixed by length specified as a little-endian 64-bit
194           number. This format allows multiple packets to be dumped and
195           unambiguously parsed.
196
197       --legend=BOOL
198           Takes a boolean parameter. If true (the default), column headers
199           and meta information about the query response are shown. Otherwise,
200           this output is suppressed.
201
202       -h, --help
203           Print a short help text and exit.
204
205       --version
206           Print a short version string and exit.
207
208       --no-pager
209           Do not pipe output into a pager.
210

COMPATIBILITY WITH RESOLVCONF(8)

212       resolvectl is a multi-call binary. When invoked as "resolvconf"
213       (generally achieved by means of a symbolic link of this name to the
214       resolvectl binary) it is run in a limited resolvconf(8) compatibility
215       mode. It accepts mostly the same arguments and pushes all data into
216       systemd-resolved.service(8), similar to how dns and domain commands
217       operate. Note that systemd-resolved.service is the only supported
218       backend, which is different from other implementations of this command.
219
220       /etc/resolv.conf will only be updated with servers added with this
221       command when /etc/resolv.conf is a symlink to
222       /run/systemd/resolve/resolv.conf, and not a static file. See the
223       discussion of /etc/resolv.conf handling in systemd-resolved.service(8).
224
225       Not all operations supported by other implementations are supported
226       natively. Specifically:
227
228       -a
229           Registers per-interface DNS configuration data with
230           systemd-resolved. Expects a network interface name as only command
231           line argument. Reads resolv.conf(5)-compatible DNS configuration
232           data from its standard input. Relevant fields are "nameserver" and
233           "domain"/"search". This command is mostly identical to invoking
234           resolvectl with a combination of dns and domain commands.
235
236       -d
237           Unregisters per-interface DNS configuration data with
238           systemd-resolved. This command is mostly identical to invoking
239           resolvectl revert.
240
241       -f
242           When specified -a and -d will not complain about missing network
243           interfaces and will silently execute no operation in that case.
244
245       -x
246           This switch for "exclusive" operation is supported only partially.
247           It is mapped to an additional configured search domain of "~."  —
248           i.e. ensures that DNS traffic is preferably routed to the DNS
249           servers on this interface, unless there are other, more specific
250           domains configured on other interfaces.
251
252       -m, -p
253           These switches are not supported and are silently ignored.
254
255       -u, -I, -i, -l, -R, -r, -v, -V, --enable-updates, --disable-updates,
256       --are-updates-enabled
257           These switches are not supported and the command will fail if used.
258
259       See resolvconf(8) for details on those command line options.
260

EXAMPLES

262       Example 1. Retrieve the addresses of the "www.0pointer.net" domain
263
264           $ resolvectl query www.0pointer.net
265           www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
266                             85.214.157.71
267
268           -- Information acquired via protocol DNS in 611.6ms.
269           -- Data is authenticated: no
270
271       Example 2. Retrieve the domain of the "85.214.157.71" IP address
272
273           $ resolvectl query 85.214.157.71
274           85.214.157.71: gardel.0pointer.net
275
276           -- Information acquired via protocol DNS in 1.2997s.
277           -- Data is authenticated: no
278
279       Example 3. Retrieve the MX record of the "yahoo.com" domain
280
281           $ resolvectl --legend=no -t MX query yahoo.com
282           yahoo.com. IN MX    1 mta7.am0.yahoodns.net
283           yahoo.com. IN MX    1 mta6.am0.yahoodns.net
284           yahoo.com. IN MX    1 mta5.am0.yahoodns.net
285
286       Example 4. Resolve an SRV service
287
288           $ resolvectl service _xmpp-server._tcp gmail.com
289           _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0]
290                                        173.194.210.125
291                                        alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0]
292                                        173.194.65.125
293                                        ...
294
295       Example 5. Retrieve a PGP key
296
297           $ resolvectl openpgp zbyszek@fedoraproject.org
298           d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY
299                   mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf
300                   MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs
301                   ...
302
303       Example 6. Retrieve a TLS key ("tcp" and ":443" could be skipped)
304
305           $ resolvectl tlsa tcp fedoraproject.org:443
306           _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
307                   -- Cert. usage: CA constraint
308                   -- Selector: Full Certificate
309                   -- Matching type: SHA-256
310

SEE ALSO

312       systemd(1), systemd-resolved.service(8), systemd.dnssd(5), systemd-
313       networkd.service(8), resolvconf(8)
314

NOTES

316        1. DNS-SD
317           https://tools.ietf.org/html/rfc6763
318
319        2. SRV
320           https://tools.ietf.org/html/rfc2782
321
322        3. OPENPGPKEY
323           https://tools.ietf.org/html/rfc7929
324
325        4. TLSA
326           https://tools.ietf.org/html/rfc6698
327
328        5. Link-Local Multicast Name Resolution
329           https://tools.ietf.org/html/rfc4795
330
331        6. Multicast DNS
332           https://www.ietf.org/rfc/rfc6762.txt
333
334
335
336systemd 246                                                      RESOLVECTL(1)
Impressum