shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-25 01:34:28 +03:00
Code
826c4f35c6
systemd/man/resolvectl.xml

445 lines
23 KiB
XML
Raw Normal View History

man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
man: standarize on one-line license header No need to waste space, and uniformity is good. $ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
2019-03-14 16:29:37 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<refentry id="resolvectl" conditional='ENABLE_RESOLVE'
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<title>resolvectl</title>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
<productname>systemd</productname>
</refentryinfo>
<refmeta>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<refentrytitle>resolvectl</refentrytitle>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<refname>resolvectl</refname>
man: briefly document the resolvconf(8) compatibility interface
2018-02-27 21:48:06 +03:00
<refname>resolvconf</refname>
<refpurpose>Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services; introspect and reconfigure the DNS resolver</refpurpose>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<command>resolvectl</command>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
<arg choice="opt" rep="repeat">OPTIONS</arg>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<arg choice="req">COMMAND</arg>
<arg choice="opt" rep="repeat">NAME</arg>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<para><command>resolvectl</command> may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
records and services with the
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4
and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 operation the reverse operation is
done, and a hostname is retrieved for the specified addresses.</para>
man: document what Authenticated: in the systemd-resolve output actually means (#3571) My educated guess is that #3561 was filed due to confusion around the systemd-resolve "Data Authenticated:" output. Let's try to clean up the confusion a bit, and document what it means in the man page.
2016-06-26 18:35:22 +03:00
<para>The program's output contains information about the protocol used for the look-up and on which network
interface the data was discovered. It also contains information on whether the information could be
authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover all data
originating from local, trusted sources is also reported authenticated, including resolution of the local host
name, the <literal>localhost</literal> host name or all data from <filename>/etc/hosts</filename>.</para>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</refsect1>
<refsect1>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-4</option></term>
<term><option>-6</option></term>
<listitem><para>By default, when resolving a hostname, both IPv4 and IPv6
addresses are acquired. By specifying <option>-4</option> only IPv4 addresses are requested, by specifying
<option>-6</option> only IPv6 addresses are requested.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option> <replaceable>INTERFACE</replaceable></term>
<term><option>--interface=</option><replaceable>INTERFACE</replaceable></term>
<listitem><para>Specifies the network interface to execute the query on. This may either be specified as numeric
interface index or as network interface string (e.g. <literal>en0</literal>). Note that this option has no
effect if system-wide DNS configuration (as configured in <filename>/etc/resolv.conf</filename> or
<filename>/etc/systemd/resolve.conf</filename>) in place of per-link configuration is used.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option> <replaceable>PROTOCOL</replaceable></term>
<term><option>--protocol=</option><replaceable>PROTOCOL</replaceable></term>
<listitem><para>Specifies the network protocol for the query. May be one of <literal>dns</literal>
(i.e. classic unicast DNS), <literal>llmnr</literal> (<ulink
url="https://tools.ietf.org/html/rfc4795">Link-Local Multicast Name Resolution</ulink>),
systemd-resolve: fix typo in man page
2016-02-19 16:42:38 +03:00
<literal>llmnr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP
resolve: Add support for mDNS to systemd-resolve utility Signed-off-by: Dmitry Rozhkov <dmitry.rozhkov@linux.intel.com>
2017-01-19 12:47:51 +03:00
protocols), <literal>mdns</literal> (<ulink url="https://www.ietf.org/rfc/rfc6762.txt">Multicast DNS</ulink>),
<literal>mdns-ipv4</literal>, <literal>mdns-ipv6</literal> (MDNS via the indicated underlying IP protocols).
By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the
same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with
<literal>llmnr-ipv4</literal> and once via <literal>llmnr-ipv6</literal>. Note that this option does not force
the service to resolve the operation with the specified protocol, as that might require a suitable network
resolve-host: add option to list protocols
2015-02-05 05:06:36 +03:00
interface and configuration.
The special value <literal>help</literal> may be used to list known values.
</para></listitem>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</varlistentry>
<varlistentry>
<term><option>-t</option> <replaceable>TYPE</replaceable></term>
<term><option>--type=</option><replaceable>TYPE</replaceable></term>
<term><option>-c</option> <replaceable>CLASS</replaceable></term>
<term><option>--class=</option><replaceable>CLASS</replaceable></term>
<listitem><para>Specifies the DNS resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to
look up. If these options are used a DNS resource record set matching the specified class and type is
resolve-host: add option to list protocols
2015-02-05 05:06:36 +03:00
requested. The class defaults to IN if only a type is specified.
The special value <literal>help</literal> may be used to list known values.
</para></listitem>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</varlistentry>
<varlistentry>
<term><option>--service-address=</option><replaceable>BOOL</replaceable></term>
<listitem><para>Takes a boolean parameter. If true (the default), when doing a service lookup with
<option>--service</option> the hostnames contained in the SRV resource records are resolved as well.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--service-txt=</option><replaceable>BOOL</replaceable></term>
<listitem><para>Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with
<option>--service</option> the TXT service metadata record is resolved as well.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--cname=</option><replaceable>BOOL</replaceable></term>
<listitem><para>Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are
followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is
returned.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--search=</option><replaceable>BOOL</replaceable></term>
<listitem><para>Takes a boolean parameter. If true (the default), any specified single-label hostnames will be
searched in the domains configured in the search domain list, if it is non-empty. Otherwise, the search domain
logic is disabled.</para></listitem>
</varlistentry>
systemd-resolve: allow whole packets to be dumped in binary form
2016-01-31 08:06:49 +03:00
<varlistentry>
<term><option>--raw</option><optional>=payload|packet</optional></term>
<listitem><para>Dump the answer as binary data. If there is no argument or if the argument is
<literal>payload</literal>, the payload of the packet is exported. If the argument is
<literal>packet</literal>, the whole packet is dumped in wire format, prefixed by
length specified as a little-endian 64-bit number. This format allows multiple packets
man: fix typos (#5109)
2017-01-19 18:54:22 +03:00
to be dumped and unambiguously parsed.</para></listitem>
systemd-resolve: allow whole packets to be dumped in binary form
2016-01-31 08:06:49 +03:00
</varlistentry>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
<varlistentry>
<term><option>--legend=</option><replaceable>BOOL</replaceable></term>
<listitem><para>Takes a boolean parameter. If true (the default), column headers and meta information about the
query response are shown. Otherwise, this output is suppressed.</para></listitem>
</varlistentry>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
<xi:include href="standard-options.xml" xpointer="no-pager" />
</variablelist>
</refsect1>
<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
<term><option>query <replaceable>HOSTNAME|ADDRESS</replaceable>…</option></term>
<listitem><para>Resolve domain names, IPv4 and IPv6 addresses.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>service [[<replaceable>NAME</replaceable>] <replaceable>TYPE</replaceable>] <replaceable>DOMAIN</replaceable></option></term>
<listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> and
<ulink url="https://tools.ietf.org/html/rfc2782">SRV</ulink> services, depending on the specified list of parameters.
If three parameters are passed the first is assumed to be the DNS-SD service name, the second the SRV service type,
and the third the domain to search in. In this case a full DNS-SD style SRV and TXT lookup is executed. If only two
parameters are specified, the first is assumed to be the SRV service type, and the second the domain to look in. In
this case no TXT RR is requested. Finally, if only one parameter is specified, it is assumed to be a domain name,
that is already prefixed with an SRV type, and an SRV lookup is done (no TXT).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>openpgp <replaceable>EMAIL@DOMAIN</replaceable>…</option></term>
<listitem><para>Query PGP keys stored as <ulink url="https://tools.ietf.org/html/rfc7929">OPENPGPKEY</ulink>
resource records. Specified e-mail addresses are converted to the corresponding DNS domain name, and any
OPENPGPKEY keys are printed.</para></listitem>
</varlistentry>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
<varlistentry>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>tlsa [<replaceable>FAMILY</replaceable>] <replaceable>DOMAIN</replaceable>[:<replaceable>PORT</replaceable>]…</option></term>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<listitem><para>Query TLS public keys stored as <ulink url="https://tools.ietf.org/html/rfc6698">TLSA</ulink>
resource records. A query will be performed for each of the specified names prefixed with the port and family
(<literal>_<replaceable>port</replaceable>._<replaceable>family</replaceable>.<replaceable>domain</replaceable></literal>).
The port number may be specified after a colon (<literal>:</literal>), otherwise <constant>443</constant> will be used
by default. The family may be specified as the first argument, otherwise <constant>tcp</constant> will be used.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>status [<replaceable>LINK</replaceable>…]</option></term>
<listitem><para>Shows the global and per-link DNS settings in currently in effect. If no command is specified,
this is the implied default.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>statistics</option></term>
<listitem><para>Shows general resolver statistics, including information whether DNSSEC is
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
enabled and available, as well as resolution and validation statistics.</para></listitem>
</varlistentry>
<varlistentry>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>reset-statistics</option></term>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<listitem><para>Resets the statistics counters shown in <option>statistics</option> to zero.
This operation requires root privileges.</para></listitem>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</varlistentry>
resolved: also add a way to flush all caches via the bus And expose it in "resolve-tool --flush-caches".
2016-06-10 21:40:30 +03:00
<varlistentry>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>flush-caches</option></term>
resolved: also add a way to flush all caches via the bus And expose it in "resolve-tool --flush-caches".
2016-06-10 21:40:30 +03:00
resolved: add support for explicitly forgetting everything we learnt about DNS server feature levels This adds "systemd-resolve --reset-server-features" for explicitly forgetting what we learnt. This might be useful for debugging purposes, and to force systemd-resolved to restart its learning logic for all DNS servers.
2017-09-29 22:19:54 +03:00
<listitem><para>Flushes all DNS resource record caches the service maintains locally. This is mostly equivalent
to sending the <constant>SIGUSR2</constant> to the <command>systemd-resolved</command>
service.</para></listitem>
</varlistentry>
<varlistentry>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>reset-server-features</option></term>
resolved: add support for explicitly forgetting everything we learnt about DNS server feature levels This adds "systemd-resolve --reset-server-features" for explicitly forgetting what we learnt. This might be useful for debugging purposes, and to force systemd-resolved to restart its learning logic for all DNS servers.
2017-09-29 22:19:54 +03:00
<listitem><para>Flushes all feature level information the resolver learnt about specific servers, and ensures
that the server feature probing logic is started from the beginning with the next look-up request. This is
mostly equivalent to sending the <constant>SIGRTMIN+1</constant> to the <command>systemd-resolved</command>
service.</para></listitem>
resolved: also add a way to flush all caches via the bus And expose it in "resolve-tool --flush-caches".
2016-06-10 21:40:30 +03:00
</varlistentry>
resolve: add "systemd-resolve --status" command The new command shows the per-link and global DNS configuration currently in effect. This is useful to quickly see the DNS settings resolved acquired from networkd and that was pushed into it via the bus APIs.
2016-06-15 22:43:36 +03:00
<varlistentry>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>dns [<replaceable>LINK</replaceable> [<replaceable>SERVER</replaceable>…]]</option></term>
<term><option>domain [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</option></term>
resolvectl: add support for reading/writing per-link 'default-route' boolean
2018-12-04 15:29:41 +03:00
<term><option>default-route [<replaceable>LINK</replaceable> [<replaceable>BOOL</replaceable>…]]</option></term>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>llmnr [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term>
<term><option>mdns [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term>
<term><option>dnssec [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term>
resolve: rename PrivateDNS to DNSOverTLS PrivateDNS is not considered a good name for this option, so rename it to DNSOverTLS
2018-06-13 21:26:24 +03:00
<term><option>dnsovertls [<replaceable>LINK</replaceable> [<replaceable>MODE</replaceable>]]</option></term>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>nta [<replaceable>LINK</replaceable> [<replaceable>DOMAIN</replaceable>…]]</option></term>
doc: fix resolvectl(1) per-interface DNS configuration documentation You can only have one listitem in each varlistentry. xmllint says: resolvectl.xml:269: element varlistentry: validity error : Element varlistentry content does not follow the DTD, expecting (term+ , listitem), got (term term term term term term term listitem listitem listitem )
2018-08-23 23:33:56 +03:00
<listitem>
resolvectl: add support for reading/writing per-link 'default-route' boolean
2018-12-04 15:29:41 +03:00
<para>Get/set per-interface DNS configuration. These commands may be used to configure various DNS settings
for network interfaces that aren't managed by
doc: fix resolvectl(1) per-interface DNS configuration documentation You can only have one listitem in each varlistentry. xmllint says: resolvectl.xml:269: element varlistentry: validity error : Element varlistentry content does not follow the DTD, expecting (term+ , listitem), got (term term term term term term term listitem listitem listitem )
2018-08-23 23:33:56 +03:00
<citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. (These
commands will fail when used on interfaces that are managed by <command>systemd-networkd</command>, please
configure their DNS settings directly inside the <filename>.network</filename> files instead.) These commands
may be used to inform <command>systemd-resolved</command> about per-interface DNS configuration determined
through external means. The <option>dns</option> command expects IPv4 or IPv6 address specifications of DNS
servers to use. The <option>domain</option> command expects valid DNS domains, possibly prefixed with
resolvectl: add support for reading/writing per-link 'default-route' boolean
2018-12-04 15:29:41 +03:00
<literal>~</literal>, and configures a per-interface search or route-only domain. The
codespell: fix spelling errors
2019-04-27 03:22:40 +03:00
<option>default-route</option> command expects a boolean parameter, and configures whether the link may be
resolvectl: add support for reading/writing per-link 'default-route' boolean
2018-12-04 15:29:41 +03:00
used as default route for DNS lookups, i.e. if it is suitable for lookups on domains no other link explicitly
is configured for. The <option>llmnr</option>, <option>mdns</option>, <option>dnssec</option> and
<option>dnsovertls</option> commands may be used to configure the per-interface LLMNR, MulticastDNS, DNSSEC
and DNSOverTLS settings. Finally, <option>nta</option> command may be used to configure additional
per-interface DNSSEC NTA domains.</para>
doc: fix resolvectl(1) per-interface DNS configuration documentation You can only have one listitem in each varlistentry. xmllint says: resolvectl.xml:269: element varlistentry: validity error : Element varlistentry content does not follow the DTD, expecting (term+ , listitem), got (term term term term term term term listitem listitem listitem )
2018-08-23 23:33:56 +03:00
<para>Options <option>dns</option>, <option>domain</option> and <option>nta</option> can take
a single empty string argument to clear their respective value lists.</para>
<para>For details about these settings, their possible values and their effect, see the corresponding options in
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
resolve: extend systemd-resolve so that it can push per-interface DNS configuration into systemd-resolved (#7576) This is useful to debug things, but also to hook up external post-up scripts with resolved. Eventually this code might be useful to implement a resolvconf(8)-compatible interface for compatibility purposes. Since the semantics don't map entirely cleanly as first step we add a native interface for pushing DNS configuration into resolved, that exposes the correct semantics, before adding any compatibility interface. See: #7202
2017-12-14 22:13:14 +03:00
</listitem>
</varlistentry>
<varlistentry>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<term><option>revert <replaceable>LINK</replaceable></option></term>
<listitem><para>Revert the per-interface DNS configuration. If the DNS configuration is reverted all
per-interface DNS setting are reset to their defaults, undoing all effects of <option>dns</option>,
resolvectl: add support for reading/writing per-link 'default-route' boolean
2018-12-04 15:29:41 +03:00
<option>domain</option>, <option>default-route</option>, <option>llmnr</option>, <option>mdns</option>,
<option>dnssec</option>, <option>dnsovertls</option>, <option>nta</option>. Note that when a network interface
disappears all configuration is lost automatically, an explicit reverting is not necessary in that
case.</para></listitem>
resolve: extend systemd-resolve so that it can push per-interface DNS configuration into systemd-resolved (#7576) This is useful to debug things, but also to hook up external post-up scripts with resolved. Eventually this code might be useful to implement a resolvconf(8)-compatible interface for compatibility purposes. Since the semantics don't map entirely cleanly as first step we add a native interface for pushing DNS configuration into resolved, that exposes the correct semantics, before adding any compatibility interface. See: #7202
2017-12-14 22:13:14 +03:00
</varlistentry>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</variablelist>
</refsect1>
man: briefly document the resolvconf(8) compatibility interface
2018-02-27 21:48:06 +03:00
<refsect1>
<title>Compatibility with <citerefentry><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry></title>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<para><command>resolvectl</command> is a multi-call binary. When invoked as <literal>resolvconf</literal>
(generally achieved by means of a symbolic link of this name to the <command>resolvectl</command> binary) it
man: briefly document the resolvconf(8) compatibility interface
2018-02-27 21:48:06 +03:00
is run in a limited <citerefentry><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry>
compatibility mode. It accepts mostly the same arguments and pushes all data into
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
similar to how <option>dns</option> and <option>domain</option> commands operate. Note that
man: briefly document the resolvconf(8) compatibility interface
2018-02-27 21:48:06 +03:00
<command>systemd-resolved.service</command> is the only supported backend, which is different from other
implementations of this command. Note that not all operations supported by other implementations are supported
natively. Specifically:</para>
<variablelist>
<varlistentry>
<term><option>-a</option></term>
<listitem><para>Registers per-interface DNS configuration data with
<command>systemd-resolved</command>. Expects a network interface name as only command line argument. Reads
<citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> compatible DNS
configuration data from its standard input. Relevant fields are <literal>nameserver</literal> and
<literal>domain</literal>/<literal>search</literal>. This command is mostly identical to invoking
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<command>resolvectl</command> with a combination of <option>dns</option> and
<option>domain</option> commands.</para></listitem>
man: briefly document the resolvconf(8) compatibility interface
2018-02-27 21:48:06 +03:00
</varlistentry>
<varlistentry>
<term><option>-d</option></term>
<listitem><para>Unregisters per-interface DNS configuration data with <command>systemd-resolved</command>. This
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
command is mostly identical to invoking <command>resolvectl revert</command>.</para></listitem>
man: briefly document the resolvconf(8) compatibility interface
2018-02-27 21:48:06 +03:00
</varlistentry>
<varlistentry>
<term><option>-f</option></term>
<listitem><para>When specified <option>-a</option> and <option>-d</option> will not complain about missing
network interfaces and will silently execute no operation in that case.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-x</option></term>
<listitem><para>This switch for "exclusive" operation is supported only partially. It is mapped to an
additional configured search domain of <literal>~.</literal> — i.e. ensures that DNS traffic is preferably
routed to the DNS servers on this interface, unless there are other, more specific domains configured on other
interfaces.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option></term>
<term><option>-p</option></term>
<listitem><para>These switches are not supported and are silently ignored.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option></term>
<term><option>-I</option></term>
<term><option>-i</option></term>
<term><option>-l</option></term>
<term><option>-R</option></term>
<term><option>-r</option></term>
<term><option>-v</option></term>
<term><option>-V</option></term>
<term><option>--enable-updates</option></term>
<term><option>--disable-updates</option></term>
<term><option>--are-updates-enabled</option></term>
<listitem><para>These switches are not supported and the command will fail if used.</para></listitem>
</varlistentry>
</variablelist>
<para>See <citerefentry><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details on this command line options.</para>
</refsect1>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
<refsect1>
<title>Examples</title>
<example>
<title>Retrieve the addresses of the <literal>www.0pointer.net</literal> domain</title>
man: add missing 'query' command in examples of resolvectl
2018-05-08 06:09:31 +03:00
<programlisting>$ resolvectl query www.0pointer.net
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74
85.214.157.71
-- Information acquired via protocol DNS in 611.6ms.
-- Data is authenticated: no
</programlisting>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</example>
<example>
<title>Retrieve the domain of the <literal>85.214.157.71</literal> IP address</title>
man: add missing 'query' command in examples of resolvectl
2018-05-08 06:09:31 +03:00
<programlisting>$ resolvectl query 85.214.157.71
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
85.214.157.71: gardel.0pointer.net
-- Information acquired via protocol DNS in 1.2997s.
-- Data is authenticated: no
</programlisting>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</example>
<example>
man: update mx record example (#4257)
2016-10-01 18:11:38 +03:00
<title>Retrieve the MX record of the <literal>yahoo.com</literal> domain</title>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
man: add missing 'query' command in examples of resolvectl
2018-05-08 06:09:31 +03:00
<programlisting>$ resolvectl --legend=no -t MX query yahoo.com
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
yahoo.com. IN MX 1 mta7.am0.yahoodns.net
yahoo.com. IN MX 1 mta6.am0.yahoodns.net
yahoo.com. IN MX 1 mta5.am0.yahoodns.net
</programlisting>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</example>
<example>
<title>Resolve an SRV service</title>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<programlisting>$ resolvectl service _xmpp-server._tcp gmail.com
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
_xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0]
173.194.210.125
alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0]
173.194.65.125
man: use unicode ellipsis in more places As requested in https://github.com/systemd/systemd/pull/4864#pullrequestreview-12372557. docbook will substitute triple dots for the ellipsis in man output, so this has no effect on the troff output, only on HTML, making it infinitesimally nicer. In some places we show output from programs, which use dots, and those places should not be changed. In some tables, the alignment would change if dots were changed to the ellipsis which is only one character. Since docbook replaces the ellipsis automatically, we should leave those be. This patch changes all other places.
2016-12-12 01:01:07 +03:00
…
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
</programlisting>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</example>
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
<example>
<title>Retrieve a PGP key</title>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<programlisting>$ resolvectl openpgp zbyszek@fedoraproject.org
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY
mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf
MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs
man: use unicode ellipsis in more places As requested in https://github.com/systemd/systemd/pull/4864#pullrequestreview-12372557. docbook will substitute triple dots for the ellipsis in man output, so this has no effect on the troff output, only on HTML, making it infinitesimally nicer. In some places we show output from programs, which use dots, and those places should not be changed. In some tables, the alignment would change if dots were changed to the ellipsis which is only one character. Since docbook replaces the ellipsis automatically, we should leave those be. This patch changes all other places.
2016-12-12 01:01:07 +03:00
…
systemd-resolve: easy querying of TLSA records $ systemd-resolve --tlsa fedoraproject.org _443._tcp.fedoraproject.org IN TLSA 0 0 1 GUAL5bejH7czkXcAeJ0vCiRxwMnVBsDlBMBsFtfLF8A= -- Cert. usage: CA constraint -- Selector: Full Certificate -- Matching type: SHA-256 $ systemd-resolve --tlsa=tcp fedoraproject.org:443 _443._tcp.fedoraproject.org IN TLSA 0 0 1 GUAL5bejH7czkXcAeJ0vCiRxwMnVBsDlBMBsFtfLF8A= ... $ systemd-resolve --tlsa=udp fedoraproject.org _443._udp.fedoraproject.org: resolve call failed: '_443._udp.fedoraproject.org' not found v2: - use uint16_t - refuse port 0
2016-02-18 05:08:57 +03:00
</programlisting>
</example>
<example>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<title>Retrieve a TLS key (<literal>tcp</literal> and
systemd-resolve: easy querying of TLSA records $ systemd-resolve --tlsa fedoraproject.org _443._tcp.fedoraproject.org IN TLSA 0 0 1 GUAL5bejH7czkXcAeJ0vCiRxwMnVBsDlBMBsFtfLF8A= -- Cert. usage: CA constraint -- Selector: Full Certificate -- Matching type: SHA-256 $ systemd-resolve --tlsa=tcp fedoraproject.org:443 _443._tcp.fedoraproject.org IN TLSA 0 0 1 GUAL5bejH7czkXcAeJ0vCiRxwMnVBsDlBMBsFtfLF8A= ... $ systemd-resolve --tlsa=udp fedoraproject.org _443._udp.fedoraproject.org: resolve call failed: '_443._udp.fedoraproject.org' not found v2: - use uint16_t - refuse port 0
2016-02-18 05:08:57 +03:00
<literal>:443</literal> could be skipped)</title>
man: create man page for resolvectl
2018-04-18 21:25:25 +03:00
<programlisting>$ resolvectl tlsa tcp fedoraproject.org:443
resolve: print TLSA packets in hexadecimal https://tools.ietf.org/html/rfc6698#section-2.2 says: > The certificate association data field MUST be represented as a string > of hexadecimal characters. Whitespace is allowed within the string of > hexadecimal characters
2016-02-17 04:36:10 +03:00
_443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0
systemd-resolve: easy querying of TLSA records $ systemd-resolve --tlsa fedoraproject.org _443._tcp.fedoraproject.org IN TLSA 0 0 1 GUAL5bejH7czkXcAeJ0vCiRxwMnVBsDlBMBsFtfLF8A= -- Cert. usage: CA constraint -- Selector: Full Certificate -- Matching type: SHA-256 $ systemd-resolve --tlsa=tcp fedoraproject.org:443 _443._tcp.fedoraproject.org IN TLSA 0 0 1 GUAL5bejH7czkXcAeJ0vCiRxwMnVBsDlBMBsFtfLF8A= ... $ systemd-resolve --tlsa=udp fedoraproject.org _443._udp.fedoraproject.org: resolve call failed: '_443._udp.fedoraproject.org' not found v2: - use uint16_t - refuse port 0
2016-02-18 05:08:57 +03:00
-- Cert. usage: CA constraint
-- Selector: Full Certificate
-- Matching type: SHA-256
man: show output in example systemd-resolve commands I think example output allows the reader of the man page to see what functionlity is provided without running the commands themselves. Specific values in the examples are bound to get out of date but this is not a problem.
2016-02-13 21:53:18 +03:00
</programlisting>
</example>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
resolve: extend systemd-resolve so that it can push per-interface DNS configuration into systemd-resolved (#7576) This is useful to debug things, but also to hook up external post-up scripts with resolved. Eventually this code might be useful to implement a resolvconf(8)-compatible interface for compatibility purposes. Since the semantics don't map entirely cleanly as first step we add a native interface for pushing DNS configuration into resolved, that exposes the correct semantics, before adding any compatibility interface. See: #7202
2017-12-14 22:13:14 +03:00
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.dnssd</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
man: briefly document the resolvconf(8) compatibility interface
2018-02-27 21:48:06 +03:00
<citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>resolvconf</refentrytitle><manvolnum>8</manvolnum></citerefentry>
man: document systemd-resolve(8) This also links up the new manpage from systemd-resolved.service(8), and makes a couple of unrelated additions.
2016-01-21 02:04:19 +03:00
</para>
</refsect1>
</refentry>
Copy Permalink