man/systemd-resolve.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2016 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="systemd-resolve" conditional='ENABLE_RESOLVE'
  27           xmlns:xi="http://www.w3.org/2001/XInclude">
  28
  29   <refentryinfo>
  30     <title>systemd-resolve</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>systemd-resolve</refentrytitle>
  45     <manvolnum>1</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>systemd-resolve</refname>
  50     <refpurpose>Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <cmdsynopsis>
  55       <command>systemd-resolve</command>
  56       <arg choice="opt" rep="repeat">OPTIONS</arg>
  57       <arg choice="plain" rep="repeat"><replaceable>HOSTNAME</replaceable></arg>
  58     </cmdsynopsis>
  59
  60     <cmdsynopsis>
  61       <command>systemd-resolve</command>
  62       <arg choice="opt" rep="repeat">OPTIONS</arg>
  63       <arg choice="plain" rep="repeat"><replaceable>ADDRESS</replaceable></arg>
  64     </cmdsynopsis>
  65
  66     <cmdsynopsis>
  67       <command>systemd-resolve</command>
  68       <arg choice="opt" rep="repeat">OPTIONS</arg>
  69       <command> --type=<replaceable>TYPE</replaceable></command>
  70       <arg choice="plain" rep="repeat"><replaceable>DOMAIN</replaceable></arg>
  71     </cmdsynopsis>
  72
  73     <cmdsynopsis>
  74       <command>systemd-resolve</command>
  75       <arg choice="opt" rep="repeat">OPTIONS</arg>
  76       <command> --service</command>
  77       <arg choice="plain"><arg choice="opt"><arg choice="opt"><replaceable>NAME</replaceable></arg>
  78       <replaceable>TYPE</replaceable></arg> <replaceable>DOMAIN</replaceable></arg>
  79     </cmdsynopsis>
  80
  81     <cmdsynopsis>
  82       <command>systemd-resolve</command>
  83       <arg choice="opt" rep="repeat">OPTIONS</arg>
  84       <command> --openpgp</command>
  85       <arg choice="plain"><replaceable>USER@DOMAIN</replaceable></arg>
  86     </cmdsynopsis>
  87
  88     <cmdsynopsis>
  89       <command>systemd-resolve</command>
  90       <arg choice="opt" rep="repeat">OPTIONS</arg>
  91       <command> --tlsa</command>
  92       <arg choice="plain"><replaceable>DOMAIN<optional>:PORT</optional></replaceable></arg>
  93     </cmdsynopsis>
  94
  95     <cmdsynopsis>
  96       <command>systemd-resolve</command>
  97       <arg choice="opt" rep="repeat">OPTIONS</arg>
  98       <command> --statistics</command>
  99     </cmdsynopsis>
 100
 101     <cmdsynopsis>
 102       <command>systemd-resolve</command>
 103       <arg choice="opt" rep="repeat">OPTIONS</arg>
 104       <command> --reset-statistics</command>
 105     </cmdsynopsis>
 106
 107   </refsynopsisdiv>
 108
 109   <refsect1>
 110     <title>Description</title>
 111
 112     <para><command>systemd-resolve</command> may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource
 113     records and services with the
 114     <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 115     resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4
 116     and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 operation the reverse operation is
 117     done, and a hostname is retrieved for the specified addresses.</para>
 118
 119     <para>The program's output contains information about the protocol used for the look-up and on which network
 120     interface the data was discovered. It also contains information on whether the information could be
 121     authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover all data
 122     originating from local, trusted sources is also reported authenticated, including resolution of the local host
 123     name, the <literal>localhost</literal> host name or all data from <filename>/etc/hosts</filename>.</para>
 124
 125     <para>The <option>--type=</option> switch may be used to specify a DNS resource record type (A, AAAA, SOA, MX, …) in
 126     order to request a specific DNS resource record, instead of the address or reverse address lookups.
 127     The special value <literal>help</literal> may be used to list known values.</para>
 128
 129     <para>The <option>--service</option> switch may be used to resolve <ulink
 130     url="https://tools.ietf.org/html/rfc2782">SRV</ulink> and <ulink
 131     url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> services (see below). In this mode, between one and three
 132     arguments are required. If three parameters are passed the first is assumed to be the DNS-SD service name, the
 133     second the SRV service type, and the third the domain to search in. In this case a full DNS-SD style SRV and TXT
 134     lookup is executed. If only two parameters are specified, the first is assumed to be the SRV service type, and the
 135     second the domain to look in. In this case no TXT RR is requested. Finally, if only one parameter is specified, it
 136     is assumed to be a domain name, that is already prefixed with an SRV type, and an SRV lookup is done (no
 137     TXT).</para>
 138
 139     <para>The <option>--openpgp</option> switch may be used to query PGP keys stored as
 140     <ulink url="https://tools.ietf.org/html/rfc7929">OPENPGPKEY</ulink> resource records.
 141     When this option is specified one or more e-mail address must be specified.</para>
 142
 143     <para>The <option>--tlsa</option> switch maybe be used to query TLS public
 144     keys stored as
 145     <ulink url="https://tools.ietf.org/html/rfc6698">TLSA</ulink> resource records.
 146     When this option is specified one or more domain names must be specified.</para>
 147
 148     <para>The <option>--statistics</option> switch may be used to show resolver statistics, including information about
 149     the number of successful and failed DNSSEC validations.</para>
 150
 151     <para>The <option>--reset-statistics</option> may be used to reset various statistics counters maintained the
 152     resolver, including those shown in the <option>--statistics</option> output. This operation requires root
 153     privileges.</para>
 154   </refsect1>
 155
 156   <refsect1>
 157     <title>Options</title>
 158     <variablelist>
 159       <varlistentry>
 160         <term><option>-4</option></term>
 161         <term><option>-6</option></term>
 162
 163         <listitem><para>By default, when resolving a hostname, both IPv4 and IPv6
 164         addresses are acquired. By specifying <option>-4</option> only IPv4 addresses are requested, by specifying
 165         <option>-6</option> only IPv6 addresses are requested.</para>
 166         </listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><option>-i</option> <replaceable>INTERFACE</replaceable></term>
 171         <term><option>--interface=</option><replaceable>INTERFACE</replaceable></term>
 172
 173         <listitem><para>Specifies the network interface to execute the query on. This may either be specified as numeric
 174         interface index or as network interface string (e.g. <literal>en0</literal>). Note that this option has no
 175         effect if system-wide DNS configuration (as configured in <filename>/etc/resolv.conf</filename> or
 176         <filename>/etc/systemd/resolve.conf</filename>) in place of per-link configuration is used.</para></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><option>-p</option> <replaceable>PROTOCOL</replaceable></term>
 181         <term><option>--protocol=</option><replaceable>PROTOCOL</replaceable></term>
 182
 183         <listitem><para>Specifies the network protocol for the query. May be one of <literal>dns</literal>
 184         (i.e. classic unicast DNS), <literal>llmnr</literal> (<ulink
 185         url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink>),
 186         <literal>llmnr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP
 187         protocols), <literal>mdns</literal> (<ulink url="https://www.ietf.org/rfc/rfc6762.txt">Multicast DNS</ulink>),
 188         <literal>mdns-ipv4</literal>, <literal>mdns-ipv6</literal> (MDNS via the indicated underlying IP protocols).
 189         By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of
 190         protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the
 191         same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with
 192         <literal>llmnr-ipv4</literal> and once via <literal>llmnr-ipv6</literal>. Note that this option does not force
 193         the service to resolve the operation with the specified protocol, as that might require a suitable network
 194         interface and configuration.
 195         The special value <literal>help</literal> may be used to list known values.
 196         </para></listitem>
 197       </varlistentry>
 198
 199       <varlistentry>
 200         <term><option>-t</option> <replaceable>TYPE</replaceable></term>
 201         <term><option>--type=</option><replaceable>TYPE</replaceable></term>
 202         <term><option>-c</option> <replaceable>CLASS</replaceable></term>
 203         <term><option>--class=</option><replaceable>CLASS</replaceable></term>
 204
 205         <listitem><para>Specifies the DNS resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to
 206         look up. If these options are used a DNS resource record set matching the specified class and type is
 207         requested. The class defaults to IN if only a type is specified.
 208         The special value <literal>help</literal> may be used to list known values.
 209         </para></listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term><option>--service</option></term>
 214
 215         <listitem><para>Enables service resolution. This enables DNS-SD and simple SRV service resolution, depending
 216         on the specified list of parameters (see above).</para></listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><option>--service-address=</option><replaceable>BOOL</replaceable></term>
 221
 222         <listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with
 223         <option>--service</option> the hostnames contained in the SRV resource records are resolved as well.</para></listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><option>--service-txt=</option><replaceable>BOOL</replaceable></term>
 228
 229         <listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with
 230         <option>--service</option> the TXT service metadata record is resolved as well.</para></listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term><option>--openpgp</option></term>
 235
 236         <listitem><para>Enables OPENPGPKEY resource record resolution (see above). Specified e-mail
 237         addresses are converted to the corresponding DNS domain name, and any OPENPGPKEY keys are
 238         printed.</para></listitem>
 239       </varlistentry>
 240
 241       <varlistentry>
 242         <term><option>--tlsa</option></term>
 243
 244         <listitem><para>Enables TLSA resource record resolution (see above).
 245         A query will be performed for each of the specified names prefixed with
 246         the port and family
 247         (<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>).
 248         The port number may be specified after a colon
 249         (<literal>:</literal>), otherwise <constant>443</constant> will be used
 250         by default. The family may be specified as an argument after
 251         <option>--tlsa</option>, otherwise <constant>tcp</constant> will be
 252         used.</para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><option>--cname=</option><replaceable>BOOL</replaceable></term>
 257
 258         <listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are
 259         followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is
 260         returned.</para></listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><option>--search=</option><replaceable>BOOL</replaceable></term>
 265
 266         <listitem><para>Takes a boolean parameter. If true (the default), any specified single-label hostnames will be
 267         searched in the domains configured in the search domain list, if it is non-empty. Otherwise, the search domain
 268         logic is disabled.</para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><option>--raw</option><optional>=payload|packet</optional></term>
 273
 274         <listitem><para>Dump the answer as binary data. If there is no argument or if the argument is
 275         <literal>payload</literal>, the payload of the packet is exported. If the argument is
 276         <literal>packet</literal>, the whole packet is dumped in wire format, prefixed by
 277         length specified as a little-endian 64-bit number. This format allows multiple packets
 278         to be dumped and unambiguously parsed.</para></listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term><option>--legend=</option><replaceable>BOOL</replaceable></term>
 283
 284         <listitem><para>Takes a boolean parameter. If true (the default), column headers and meta information about the
 285         query response are shown. Otherwise, this output is suppressed.</para></listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289         <term><option>--statistics</option></term>
 290
 291         <listitem><para>If specified general resolver statistics are shown, including information whether DNSSEC is
 292         enabled and available, as well as resolution and validation statistics.</para></listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><option>--reset-statistics</option></term>
 297
 298         <listitem><para>Resets the statistics counters shown in <option>--statistics</option> to zero.</para></listitem>
 299       </varlistentry>
 300
 301       <varlistentry>
 302         <term><option>--flush-caches</option></term>
 303
 304         <listitem><para>Flushes all DNS resource record caches the service maintains locally. This is mostly equivalent
 305         to sending the <constant>SIGUSR2</constant> to the <command>systemd-resolved</command>
 306         service.</para></listitem>
 307       </varlistentry>
 308
 309       <varlistentry>
 310         <term><option>--reset-server-features</option></term>
 311
 312         <listitem><para>Flushes all feature level information the resolver learnt about specific servers, and ensures
 313         that the server feature probing logic is started from the beginning with the next look-up request. This is
 314         mostly equivalent to sending the <constant>SIGRTMIN+1</constant> to the <command>systemd-resolved</command>
 315         service.</para></listitem>
 316       </varlistentry>
 317
 318       <varlistentry>
 319         <term><option>--status</option></term>
 320
 321         <listitem><para>Shows the global and per-link DNS settings in currently in effect.</para></listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term><option>--set-dns=SERVER</option></term>
 326         <term><option>--set-domain=DOMAIN</option></term>
 327         <term><option>--set-llmnr=MODE</option></term>
 328         <term><option>--set-mdns=MODE</option></term>
 329         <term><option>--set-dnssec=MODE</option></term>
 330         <term><option>--set-nta=DOMAIN</option></term>
 331
 332         <listitem><para>Set per-interface DNS configuration. These switches may be used to configure various DNS
 333         settings for network interfaces that aren't managed by
 334         <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. (These
 335         commands will fail when used on interfaces that are managed by <command>systemd-networkd</command>, please
 336         configure their DNS settings directly inside the <filename>.network</filename> files instead.) These switches
 337         may be used to inform <command>systemd-resolved</command> about per-interface DNS configuration determined
 338         through external means. Multiple of these switches may be passed on a single invocation of
 339         <command>systemd-resolve</command> in order to set multiple configuration options at once. If any of these
 340         switches is used, it must be combined with <option>--interface=</option> to indicate the network interface the
 341         new DNS configuration belongs to. The <option>--set-dns=</option> option expects an IPv4 or IPv6 address
 342         specification of a DNS server to use, and may be used multiple times to define multiple servers for the same
 343         interface. The <option>--set-domain=</option> option expects a valid DNS domain, possibly prefixed with
 344         <literal>~</literal>, and configures a per-interface search or route-only domain. It may be used multiple times
 345         to configure multiple such domains. The <option>--set-llmnr=</option>, <option>--set-mdns=</option> and
 346         <option>--set-dnssec=</option> options may be used to configure the per-interface LLMNR, MulticastDNS and
 347         DNSSEC settings. Finally, <option>--set-nta=</option> may be used to configure additional per-interface DNSSEC
 348         NTA domains and may also be used multiple times. For details about these settings, their possible values and
 349         their effect, see the corresponding options in
 350         <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 351         </listitem>
 352       </varlistentry>
 353
 354       <varlistentry>
 355         <term><option>--revert</option></term>
 356
 357         <listitem><para>Revert the per-interface DNS configuration. This option must be combined with
 358         <option>--interface=</option> to indicate the network interface the DNS configuration shall be reverted on. If
 359         the DNS configuration is reverted all per-interface DNS setting are reset to their defaults, undoing all
 360         effects of <option>--set-dns=</option>, <option>--set-domain=</option>, <option>--set-llmnr=</option>,
 361         <option>--set-mdns=</option>, <option>--set-dnssec=</option>, <option>--set-nta=</option>. Note that when a
 362         network interface disappears all configuration is lost automatically, an explicit reverting is not necessary in
 363         that case.</para></listitem>
 364       </varlistentry>
 365
 366       <xi:include href="standard-options.xml" xpointer="help" />
 367       <xi:include href="standard-options.xml" xpointer="version" />
 368       <xi:include href="standard-options.xml" xpointer="no-pager" />
 369     </variablelist>
 370   </refsect1>
 371
 372   <refsect1>
 373     <title>Examples</title>
 374
 375     <example>
 376       <title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title>
 377
 378       <programlisting>$ systemd-resolve www.0pointer.net
 379 www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
 380                   85.214.157.71
 381
 382 -- Information acquired via protocol DNS in 611.6ms.
 383 -- Data is authenticated: no
 384 </programlisting>
 385     </example>
 386
 387     <example>
 388       <title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title>
 389
 390       <programlisting>$ systemd-resolve 85.214.157.71
 391 85.214.157.71: gardel.0pointer.net
 392
 393 -- Information acquired via protocol DNS in 1.2997s.
 394 -- Data is authenticated: no
 395 </programlisting>
 396     </example>
 397
 398     <example>
 399       <title>Retrieve the MX record of the <literal>yahoo.com</literal> domain</title>
 400
 401       <programlisting>$ systemd-resolve -t MX yahoo.com --legend=no
 402 yahoo.com. IN MX    1 mta7.am0.yahoodns.net
 403 yahoo.com. IN MX    1 mta6.am0.yahoodns.net
 404 yahoo.com. IN MX    1 mta5.am0.yahoodns.net
 405 </programlisting>
 406     </example>
 407
 408     <example>
 409       <title>Resolve an SRV service</title>
 410
 411       <programlisting>$ systemd-resolve --service _xmpp-server._tcp gmail.com
 412 _xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0]
 413                              173.194.210.125
 414                              alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0]
 415                              173.194.65.125
 416                              …
 417 </programlisting>
 418     </example>
 419
 420     <example>
 421       <title>Retrieve a PGP key</title>
 422
 423       <programlisting>$ systemd-resolve --openpgp zbyszek@fedoraproject.org
 424 d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY
 425         mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf
 426         MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs
 427         …
 428 </programlisting>
 429     </example>
 430
 431     <example>
 432       <title>Retrieve a TLS key (<literal>=tcp</literal> and
 433       <literal>:443</literal> could be skipped)</title>
 434
 435       <programlisting>$ systemd-resolve --tlsa=tcp fedoraproject.org:443
 436 _443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
 437         -- Cert. usage: CA constraint
 438         -- Selector: Full Certificate
 439         -- Matching type: SHA-256
 440 </programlisting>
 441     </example>
 442   </refsect1>
 443
 444   <refsect1>
 445     <title>See Also</title>
 446     <para>
 447       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 448       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 449       <citerefentry><refentrytitle>systemd.dnssd</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 450       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 451     </para>
 452   </refsect1>
 453 </refentry>