man/resolvectl.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="resolvectl" conditional='ENABLE_RESOLVE'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>resolvectl</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>resolvectl</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>resolvectl</refname>
  21     <refname>resolvconf</refname>
  22     <refpurpose>Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services; introspect and reconfigure the DNS resolver</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <cmdsynopsis>
  27       <command>resolvectl</command>
  28       <arg choice="opt" rep="repeat">OPTIONS</arg>
  29       <arg choice="req">COMMAND</arg>
  30       <arg choice="opt" rep="repeat">NAME</arg>
  31     </cmdsynopsis>
  32   </refsynopsisdiv>
  33
  34   <refsect1>
  35     <title>Description</title>
  36
  37     <para><command>resolvectl</command> may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource
  38     records and services with the
  39     <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  40     resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4
  41     and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 addresses the reverse operation is
  42     done, and a hostname is retrieved for the specified addresses.</para>
  43
  44     <para>The program's output contains information about the protocol used for the look-up and on which network
  45     interface the data was discovered. It also contains information on whether the information could be
  46     authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover all data
  47     originating from local, trusted sources is also reported authenticated, including resolution of the local host
  48     name, the <literal>localhost</literal> hostname or all data from <filename>/etc/hosts</filename>.</para>
  49   </refsect1>
  50
  51   <refsect1>
  52     <title>Commands</title>
  53     <variablelist>
  54
  55       <varlistentry>
  56         <term><command>query</command> <replaceable>HOSTNAME|ADDRESS</replaceable>…</term>
  57
  58         <listitem><para>Resolve domain names, as well as IPv4 and IPv6 addresses. When used in conjunction
  59         with <option>--type=</option> or <option>--class=</option> (see below), resolves low-level DNS
  60         resource records.</para>
  61
  62         <para>If a single-label domain name is specified it is searched for according to the configured
  63         search domains — unless <option>--search=no</option> or
  64         <option>--type=</option>/<option>--class=</option> are specified, both of which turn this logic
  65         off.</para>
  66
  67         <para>If an international domain name is specified, it is automatically translated according to IDNA
  68         rules when resolved via classic DNS — but not for look-ups via MulticastDNS or LLMNR. If
  69         <option>--type=</option>/<option>--class=</option> is used IDNA translation is turned off and domain
  70         names are processed as specified.</para>
  71
  72         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
  73       </varlistentry>
  74
  75       <varlistentry>
  76         <term><command>service</command>
  77         [[<replaceable>NAME</replaceable>] <replaceable>TYPE</replaceable>]
  78         <replaceable>DOMAIN</replaceable></term>
  79
  80         <listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">RFC 6763 DNS-SD</ulink> and
  81         <ulink url="https://tools.ietf.org/html/rfc2782">RFC 2782 SRV</ulink> services, depending on the
  82         specified list of parameters. If three parameters are passed the first is assumed to be the DNS-SD
  83         service name, the second the <constant class='dns'>SRV</constant> service type, and the third the
  84         domain to search in. In this case a full DNS-SD style <constant class='dns'>SRV</constant> and
  85         <constant class='dns'>TXT</constant> lookup is executed. If only two parameters are specified, the
  86         first is assumed to be the <constant class='dns'>SRV</constant> service type, and the second the
  87         domain to look in. In this case no <constant class='dns'>TXT</constant> resource record is requested.
  88         Finally, if only one parameter is specified, it is assumed to be a domain name, that is already
  89         prefixed with an <constant class='dns'>SRV</constant> type, and an <constant
  90         class='dns'>SRV</constant> lookup is done (no <constant class='dns'>TXT</constant>).</para>
  91
  92         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term><command>openpgp</command> <replaceable>EMAIL@DOMAIN</replaceable>…</term>
  97
  98         <listitem><para>Query PGP keys stored as <constant class='dns'>OPENPGPKEY</constant> resource records,
  99         see <ulink url="https://tools.ietf.org/html/rfc7929">RFC 7929</ulink>. Specified e-mail addresses
 100         are converted to the corresponding DNS domain name, and any <constant class='dns'>OPENPGPKEY</constant>
 101         keys are printed.</para>
 102
 103         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 104       </varlistentry>
 105
 106       <varlistentry>
 107         <term><command>tlsa</command>
 108         [<replaceable>FAMILY</replaceable>]
 109         <replaceable>DOMAIN</replaceable>[:<replaceable>PORT</replaceable>]…</term>
 110
 111         <listitem><para>Query TLS public keys stored as <constant class='dns'>TLSA</constant> resource
 112         records, see <ulink url="https://tools.ietf.org/html/rfc6698">RFC 6698</ulink>. A query will be
 113         performed for each of the specified names prefixed with the port and family
 114         (<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>).
 115         The port number may be specified after a colon (<literal>:</literal>), otherwise
 116         <constant>443</constant> will be used by default. The family may be specified as the first argument,
 117         otherwise <constant>tcp</constant> will be used.</para>
 118
 119         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><command>status</command> [<replaceable>LINK</replaceable>…]</term>
 124
 125         <listitem><para>Shows the global and per-link DNS settings currently in effect. If no command is specified,
 126         this is the implied default.</para>
 127
 128         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 129       </varlistentry>
 130
 131       <varlistentry>
 132         <term><command>statistics</command></term>
 133
 134         <listitem><para>Shows general resolver statistics, including information whether DNSSEC is
 135         enabled and available, as well as resolution and validation statistics.</para>
 136
 137         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><command>reset-statistics</command></term>
 142
 143         <listitem><para>Resets the statistics counters shown in <command>statistics</command> to zero.
 144         This operation requires root privileges.</para>
 145
 146         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term><command>flush-caches</command></term>
 151
 152         <listitem><para>Flushes all DNS resource record caches the service maintains locally. This is mostly
 153         equivalent to sending the <constant>SIGUSR2</constant> to the <command>systemd-resolved</command>
 154         service.</para>
 155
 156         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term><command>reset-server-features</command></term>
 161
 162         <listitem><para>Flushes all feature level information the resolver learnt about specific servers, and ensures
 163         that the server feature probing logic is started from the beginning with the next look-up request. This is
 164         mostly equivalent to sending the <constant>SIGRTMIN+1</constant> to the <command>systemd-resolved</command>
 165         service.</para>
 166
 167         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><command>dns</command> [<replaceable>LINK</replaceable> [<replaceable>SERVER</replaceable>…]]</term>
 172         <term><command>domain</command> [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</term>
 173         <term><command>default-route</command> [<replaceable>LINK</replaceable> [<replaceable>BOOL</replaceable>…]]</term>
 174         <term><command>llmnr</command> [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</term>
 175         <term><command>mdns</command> [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</term>
 176         <term><command>dnssec</command> [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</term>
 177         <term><command>dnsovertls</command> [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</term>
 178         <term><command>nta</command> [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</term>
 179
 180         <listitem>
 181           <para>Get/set per-interface DNS configuration. These commands may be used to configure various DNS
 182           settings for network interfaces. These commands may be used to inform
 183           <command>systemd-resolved</command> or <command>systemd-networkd</command> about per-interface DNS
 184           configuration determined through external means. The <command>dns</command> command expects IPv4 or
 185           IPv6 address specifications of DNS servers to use. Each address can optionally take a port number
 186           separated with <literal>:</literal>, a network interface name or index separated with
 187           <literal>%</literal>, and a Server Name Indication (SNI) separated with <literal>#</literal>. When
 188           IPv6 address is specified with a port number, then the address must be in the square brackets. That
 189           is, the acceptable full formats are <literal>111.222.333.444:9953%ifname#example.com</literal> for
 190           IPv4 and <literal>[1111:2222::3333]:9953%ifname#example.com</literal> for IPv6. The
 191           <command>domain</command> command expects valid DNS domains, possibly prefixed with
 192           <literal>~</literal>, and configures a per-interface search or route-only domain. The
 193           <command>default-route</command> command expects a boolean parameter, and configures whether the
 194           link may be used as default route for DNS lookups, i.e. if it is suitable for lookups on domains no
 195           other link explicitly is configured for. The <command>llmnr</command>, <command>mdns</command>,
 196           <command>dnssec</command> and <command>dnsovertls</command> commands may be used to configure the
 197           per-interface LLMNR, MulticastDNS, DNSSEC and DNSOverTLS settings. Finally, <command>nta</command>
 198           command may be used to configure additional per-interface DNSSEC NTA domains.</para>
 199
 200           <para>Commands <command>dns</command>, <command>domain</command> and <command>nta</command> can take
 201           a single empty string argument to clear their respective value lists.</para>
 202
 203           <para>For details about these settings, their possible values and their effect, see the
 204           corresponding settings in
 205           <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 206
 207           <xi:include href="version-info.xml" xpointer="v239"/>
 208         </listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><command>revert <replaceable>LINK</replaceable></command></term>
 213
 214         <listitem><para>Revert the per-interface DNS configuration. If the DNS configuration is reverted all
 215         per-interface DNS setting are reset to their defaults, undoing all effects of <command>dns</command>,
 216         <command>domain</command>, <command>default-route</command>, <command>llmnr</command>,
 217         <command>mdns</command>, <command>dnssec</command>, <command>dnsovertls</command>,
 218         <command>nta</command>. Note that when a network interface disappears all configuration is lost
 219         automatically, an explicit reverting is not necessary in that case.</para>
 220
 221         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 222       </varlistentry>
 223
 224       <varlistentry>
 225         <term><command>monitor</command></term>
 226
 227         <listitem><para>Show a continuous stream of local client resolution queries and their
 228         responses. Whenever a local query is completed the query's DNS resource lookup key and resource
 229         records are shown. Note that this displays queries issued locally only, and does not immediately
 230         relate to DNS requests submitted to configured DNS servers or the LLMNR or MulticastDNS zones, as
 231         lookups may be answered from the local cache, or might result in multiple DNS transactions (for
 232         example to validate DNSSEC information). If CNAME/CNAME redirection chains are followed, a separate
 233         query will be displayed for each element of the chain. Use <option>--json=</option> to enable JSON
 234         output.</para>
 235
 236         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term><command>show-cache</command></term>
 241
 242         <listitem><para>Show current cache content, per scope. Use <option>--json=</option> to enable JSON
 243         output.</para>
 244
 245         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><command>show-server-state</command></term>
 250
 251         <listitem><para>Show detailed server state information, per DNS Server. Use <option>--json=</option>
 252         to enable JSON output.</para>
 253
 254         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 255       </varlistentry>
 256
 257       <xi:include href="systemctl.xml" xpointer="log-level" />
 258     </variablelist>
 259   </refsect1>
 260
 261   <refsect1>
 262     <title>Options</title>
 263     <variablelist>
 264       <varlistentry>
 265         <term><option>-4</option></term>
 266         <term><option>-6</option></term>
 267
 268         <listitem><para>By default, when resolving a hostname, both IPv4 and IPv6
 269         addresses are acquired. By specifying <option>-4</option> only IPv4 addresses are requested, by specifying
 270         <option>-6</option> only IPv6 addresses are requested.</para>
 271
 272         <xi:include href="version-info.xml" xpointer="v239"/>
 273         </listitem>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term><option>-i</option> <replaceable>INTERFACE</replaceable></term>
 278         <term><option>--interface=</option><replaceable>INTERFACE</replaceable></term>
 279
 280         <listitem><para>Specifies the network interface to execute the query on. This may either be specified as numeric
 281         interface index or as network interface string (e.g. <literal>en0</literal>). Note that this option has no
 282         effect if system-wide DNS configuration (as configured in <filename>/etc/resolv.conf</filename> or
 283         <filename>/etc/systemd/resolved.conf</filename>) in place of per-link configuration is used.</para>
 284
 285         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289         <term><option>-p</option> <replaceable>PROTOCOL</replaceable></term>
 290         <term><option>--protocol=</option><replaceable>PROTOCOL</replaceable></term>
 291
 292         <listitem><para>Specifies the network protocol for the query. May be one of <literal>dns</literal>
 293         (i.e. classic unicast DNS), <literal>llmnr</literal> (<ulink
 294         url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink>),
 295         <literal>llmnr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP
 296         protocols), <literal>mdns</literal> (<ulink url="https://www.ietf.org/rfc/rfc6762.txt">Multicast DNS</ulink>),
 297         <literal>mdns-ipv4</literal>, <literal>mdns-ipv6</literal> (MDNS via the indicated underlying IP protocols).
 298         By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of
 299         protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the
 300         same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with
 301         <literal>llmnr-ipv4</literal> and once via <literal>llmnr-ipv6</literal>. Note that this option does not force
 302         the service to resolve the operation with the specified protocol, as that might require a suitable network
 303         interface and configuration.
 304         The special value <literal>help</literal> may be used to list known values.
 305         </para>
 306
 307         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 308       </varlistentry>
 309
 310       <varlistentry>
 311         <term><option>-t</option> <replaceable>TYPE</replaceable></term>
 312         <term><option>--type=</option><replaceable>TYPE</replaceable></term>
 313         <term><option>-c</option> <replaceable>CLASS</replaceable></term>
 314         <term><option>--class=</option><replaceable>CLASS</replaceable></term>
 315
 316         <listitem><para>When used in conjunction with the <command>query</command> command, specifies the DNS
 317         resource record type (e.g. <constant class='dns'>A</constant>, <constant class='dns'>AAAA</constant>,
 318         <constant class='dns'>MX</constant>, …) and class (e.g. <constant>IN</constant>,
 319         <constant>ANY</constant>, …) to look up. If these options are used a DNS resource record set matching
 320         the specified class and type is requested. The class defaults to <constant>IN</constant> if only a
 321         type is specified. The special value <literal>help</literal> may be used to list known values.</para>
 322
 323         <para>Without these options <command>resolvectl query</command> provides high-level domain name to
 324         address and address to domain name resolution. With these options it provides low-level DNS resource
 325         record resolution. The search domain logic is automatically turned off when these options are used,
 326         i.e. specified domain names need to be fully qualified domain names. Moreover, IDNA internal domain
 327         name translation is turned off as well, i.e. international domain names should be specified in
 328         <literal>xn--…</literal> notation, unless look-up in MulticastDNS/LLMNR is desired, in which case
 329         UTF-8 characters should be used.</para>
 330
 331         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 332       </varlistentry>
 333
 334       <varlistentry>
 335         <term><option>--service-address=</option><replaceable>BOOL</replaceable></term>
 336
 337         <listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with
 338         <option>--service</option> the hostnames contained in the <constant class='dns'>SRV</constant>
 339         resource records are resolved as well.</para>
 340
 341         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <term><option>--service-txt=</option><replaceable>BOOL</replaceable></term>
 346
 347         <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup
 348         with <option>--service</option> the <constant class='dns'>TXT</constant> service metadata record is
 349         resolved as well.</para>
 350
 351         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 352       </varlistentry>
 353
 354       <varlistentry>
 355         <term><option>--cname=</option><replaceable>BOOL</replaceable></term>
 356
 357         <listitem><para>Takes a boolean parameter. If true (the default), DNS <constant
 358         class='dns'>CNAME</constant> or <constant class='dns'>DNAME</constant> redirections are
 359         followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is
 360         returned.</para>
 361
 362         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 363       </varlistentry>
 364
 365       <varlistentry>
 366         <term><option>--validate=</option><replaceable>BOOL</replaceable></term>
 367
 368         <listitem><para>Takes a boolean parameter; used in conjunction with <command>query</command>. If true
 369         (the default), DNSSEC validation is applied as usual — under the condition that it is enabled for the
 370         network and for <filename>systemd-resolved.service</filename> as a whole. If false, DNSSEC validation
 371         is disabled for the specific query, regardless of whether it is enabled for the network or in the
 372         service. Note that setting this option to true does not force DNSSEC validation on systems/networks
 373         where DNSSEC is turned off. This option is only suitable to turn off such validation where otherwise
 374         enabled, not enable validation where otherwise disabled.</para>
 375
 376         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 377       </varlistentry>
 378
 379       <varlistentry>
 380         <term><option>--synthesize=</option><replaceable>BOOL</replaceable></term>
 381
 382         <listitem><para>Takes a boolean parameter; used in conjunction with <command>query</command>. If true
 383         (the default), select domains are resolved on the local system, among them
 384         <literal>localhost</literal>, <literal>_gateway</literal>, <literal>_outbound</literal>,
 385         <literal>_localdnsstub</literal> and <literal>_localdnsproxy</literal> or entries from
 386         <filename>/etc/hosts</filename>. If false these domains are not resolved locally, and either fail (in
 387         case of <literal>localhost</literal>, <literal>_gateway</literal> or <literal>_outbound</literal> and
 388         suchlike) or go to the network via regular DNS/mDNS/LLMNR lookups (in case of
 389         <filename>/etc/hosts</filename> entries).</para>
 390
 391         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 392       </varlistentry>
 393
 394       <varlistentry>
 395         <term><option>--cache=</option><replaceable>BOOL</replaceable></term>
 396
 397         <listitem><para>Takes a boolean parameter; used in conjunction with <command>query</command>. If true
 398         (the default), lookups use the local DNS resource record cache. If false, lookups are routed to the
 399         network instead, regardless if already available in the local cache.</para>
 400
 401         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 402       </varlistentry>
 403
 404       <varlistentry>
 405         <term><option>--zone=</option><replaceable>BOOL</replaceable></term>
 406
 407         <listitem><para>Takes a boolean parameter; used in conjunction with <command>query</command>. If true
 408         (the default), lookups are answered from locally registered LLMNR or mDNS resource records, if
 409         defined. If false, locally registered LLMNR/mDNS records are not considered for the lookup
 410         request.</para>
 411
 412         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 413       </varlistentry>
 414
 415       <varlistentry>
 416         <term><option>--trust-anchor=</option><replaceable>BOOL</replaceable></term>
 417
 418         <listitem><para>Takes a boolean parameter; used in conjunction with <command>query</command>. If true
 419         (the default), lookups for DS and DNSKEY are answered from the local DNSSEC trust anchors if
 420         possible. If false, the local trust store is not considered for the lookup request.</para>
 421
 422         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 423       </varlistentry>
 424
 425       <varlistentry>
 426         <term><option>--network=</option><replaceable>BOOL</replaceable></term>
 427
 428         <listitem><para>Takes a boolean parameter; used in conjunction with <command>query</command>. If true
 429         (the default), lookups are answered via DNS, LLMNR or mDNS network requests if they cannot be
 430         synthesized locally, or be answered from the local cache, zone or trust anchors (see above). If false,
 431         the request is not answered from the network and will thus fail if none of the indicated sources can
 432         answer them.</para>
 433
 434         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term><option>--search=</option><replaceable>BOOL</replaceable></term>
 439
 440         <listitem><para>Takes a boolean parameter. If true (the default), any specified single-label
 441         hostnames will be searched in the domains configured in the search domain list, if it is
 442         non-empty. Otherwise, the search domain logic is disabled. Note that this option has no effect if
 443         <option>--type=</option> is used (see above), in which case the search domain logic is
 444         unconditionally turned off.</para>
 445
 446         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term><option>--raw</option><optional>=payload|packet</optional></term>
 451
 452         <listitem><para>Dump the answer as binary data. If there is no argument or if the argument is
 453         <literal>payload</literal>, the payload of the packet is exported. If the argument is
 454         <literal>packet</literal>, the whole packet is dumped in wire format, prefixed by
 455         length specified as a little-endian 64-bit number. This format allows multiple packets
 456         to be dumped and unambiguously parsed.</para>
 457
 458         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 459       </varlistentry>
 460
 461       <varlistentry>
 462         <term><option>--legend=</option><replaceable>BOOL</replaceable></term>
 463
 464         <listitem><para>Takes a boolean parameter. If true (the default), column headers and meta information about the
 465         query response are shown. Otherwise, this output is suppressed.</para>
 466
 467         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 468       </varlistentry>
 469
 470       <varlistentry>
 471         <term><option>--stale-data=</option><replaceable>BOOL</replaceable></term>
 472
 473         <listitem><para>Takes a boolean parameter; used in conjunction with <command>query</command>. If true
 474         (the default), lookups are answered with stale data (expired resource records) if
 475         possible. If false, the stale data is not considered for the lookup request.</para>
 476
 477         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 478       </varlistentry>
 479
 480       <xi:include href="standard-options.xml" xpointer="json" />
 481
 482       <varlistentry>
 483         <term><option>-j</option></term>
 484
 485         <listitem><para>Short for <option>--json=auto</option></para>
 486
 487         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 488       </varlistentry>
 489
 490       <xi:include href="standard-options.xml" xpointer="no-pager" />
 491       <xi:include href="standard-options.xml" xpointer="help" />
 492       <xi:include href="standard-options.xml" xpointer="version" />
 493     </variablelist>
 494   </refsect1>
 495
 496   <refsect1>
 497     <title>Compatibility with
 498     <citerefentry project="debian"><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry></title>
 499
 500     <para><command>resolvectl</command> is a multi-call binary. When invoked as <literal>resolvconf</literal>
 501     (generally achieved by means of a symbolic link of this name to the <command>resolvectl</command> binary) it
 502     is run in a limited
 503     <citerefentry project="debian"><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 504     compatibility mode. It accepts mostly the same arguments and pushes all data into
 505     <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 506     similar to how <option>dns</option> and <option>domain</option> commands operate. Note that
 507     <command>systemd-resolved.service</command> is the only supported backend, which is different from other
 508     implementations of this command.</para>
 509
 510     <para><filename>/etc/resolv.conf</filename> will only be updated with servers added with this command
 511     when <filename>/etc/resolv.conf</filename> is a symlink to
 512     <filename>/run/systemd/resolve/resolv.conf</filename>, and not a static file. See the discussion of
 513     <filename>/etc/resolv.conf</filename> handling in
 514     <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 515     </para>
 516
 517     <para>Not all operations supported by other implementations are supported natively. Specifically:</para>
 518
 519     <variablelist>
 520       <varlistentry>
 521         <term><option>-a</option></term>
 522         <listitem><para>Registers per-interface DNS configuration data with
 523         <command>systemd-resolved</command>. Expects a network interface name as only command line argument. Reads
 524         <citerefentry project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>-compatible
 525         DNS configuration data from its standard input. Relevant fields are <literal>nameserver</literal> and
 526         <literal>domain</literal>/<literal>search</literal>. This command is mostly identical to invoking
 527         <command>resolvectl</command> with a combination of <option>dns</option> and <option>domain</option>
 528         commands.</para>
 529
 530         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 531       </varlistentry>
 532
 533       <varlistentry>
 534         <term><option>-d</option></term>
 535         <listitem><para>Unregisters per-interface DNS configuration data with <command>systemd-resolved</command>. This
 536         command is mostly identical to invoking <command>resolvectl revert</command>.</para>
 537
 538         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 539       </varlistentry>
 540
 541       <varlistentry>
 542         <term><option>-f</option></term>
 543
 544         <listitem><para>When specified <option>-a</option> and <option>-d</option> will not complain about missing
 545         network interfaces and will silently execute no operation in that case.</para>
 546
 547         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 548       </varlistentry>
 549
 550       <varlistentry>
 551         <term><option>-x</option></term>
 552
 553         <listitem><para>This switch for "exclusive" operation is supported only partially. It is mapped to an
 554         additional configured search domain of <literal>~.</literal> — i.e. ensures that DNS traffic is preferably
 555         routed to the DNS servers on this interface, unless there are other, more specific domains configured on other
 556         interfaces.</para>
 557
 558         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 559       </varlistentry>
 560
 561       <varlistentry>
 562         <term><option>-m</option></term>
 563         <term><option>-p</option></term>
 564
 565         <listitem><para>These switches are not supported and are silently ignored.</para>
 566
 567         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 568       </varlistentry>
 569
 570       <varlistentry>
 571         <term><option>-u</option></term>
 572         <term><option>-I</option></term>
 573         <term><option>-i</option></term>
 574         <term><option>-l</option></term>
 575         <term><option>-R</option></term>
 576         <term><option>-r</option></term>
 577         <term><option>-v</option></term>
 578         <term><option>-V</option></term>
 579         <term><option>--enable-updates</option></term>
 580         <term><option>--disable-updates</option></term>
 581         <term><option>--are-updates-enabled</option></term>
 582
 583         <listitem><para>These switches are not supported and the command will fail if used.</para>
 584
 585         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 586       </varlistentry>
 587
 588     </variablelist>
 589
 590     <para>See
 591     <citerefentry project="debian"><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 592     for details on those command line options.</para>
 593   </refsect1>
 594
 595   <refsect1>
 596     <title>Examples</title>
 597
 598     <example>
 599       <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain (<constant class='dns'>A</constant> and <constant class='dns'>AAAA</constant> resource records)</title>
 600
 601       <programlisting>$ resolvectl query www.0pointer.net
 602 www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
 603                   85.214.157.71
 604
 605 -- Information acquired via protocol DNS in 611.6ms.
 606 -- Data is authenticated: no
 607 </programlisting>
 608     </example>
 609
 610     <example>
 611       <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address
 612       (<constant class='dns'>PTR</constant> resource record)</title>
 613
 614       <programlisting>$ resolvectl query 85.214.157.71
 615 85.214.157.71: gardel.0pointer.net
 616
 617 -- Information acquired via protocol DNS in 1.2997s.
 618 -- Data is authenticated: no
 619 </programlisting>
 620     </example>
 621
 622     <example>
 623       <title>Retrieve the <constant class='dns'>MX</constant> record of the <literal>yahoo.com</literal>
 624       domain</title>
 625
 626       <programlisting>$ resolvectl --legend=no -t MX query yahoo.com
 627 yahoo.com. IN MX    1 mta7.am0.yahoodns.net
 628 yahoo.com. IN MX    1 mta6.am0.yahoodns.net
 629 yahoo.com. IN MX    1 mta5.am0.yahoodns.net
 630 </programlisting>
 631     </example>
 632
 633     <example>
 634       <title>Resolve an <constant class='dns'>SRV</constant> service</title>
 635
 636       <programlisting>$ resolvectl service _xmpp-server._tcp gmail.com
 637 _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0]
 638                              173.194.210.125
 639                              alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0]
 640                              173.194.65.125
 641                              …
 642 </programlisting>
 643     </example>
 644
 645     <example>
 646       <title>Retrieve a PGP key (<constant class='dns'>OPENPGP</constant> resource record)</title>
 647
 648       <programlisting>$ resolvectl openpgp zbyszek@fedoraproject.org
 649 d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY
 650         mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf
 651         MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs
 652         …
 653 </programlisting>
 654     </example>
 655
 656     <example>
 657       <title>Retrieve a TLS key (<constant class='dns'>TLSA</constant> resource record)</title>
 658
 659       <programlisting>$ resolvectl tlsa tcp fedoraproject.org:443
 660 _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
 661         -- Cert. usage: CA constraint
 662         -- Selector: Full Certificate
 663         -- Matching type: SHA-256
 664 </programlisting>
 665
 666       <para><literal>tcp</literal> and <literal>:443</literal> are optional and could be skipped.</para>
 667     </example>
 668   </refsect1>
 669
 670   <refsect1>
 671     <title>See Also</title>
 672     <para>
 673       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 674       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 675       <citerefentry><refentrytitle>systemd.dnssd</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 676       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 677       <citerefentry><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 678     </para>
 679   </refsect1>
 680 </refentry>