2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2015-08-26 12:00:09 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2015-08-26 12:00:09 +03:00
2018-07-18 03:25:57 +03:00
<refentry id= "nss-resolve" conditional= 'ENABLE_NSS_RESOLVE' >
2015-08-26 12:00:09 +03:00
<refentryinfo >
<title > nss-resolve</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > nss-resolve</refentrytitle>
<manvolnum > 8</manvolnum>
</refmeta>
<refnamediv >
<refname > nss-resolve</refname>
<refname > libnss_resolve.so.2</refname>
2020-07-06 11:49:59 +03:00
<refpurpose > Hostname resolution via <filename > systemd-resolved.service</filename> </refpurpose>
2015-08-26 12:00:09 +03:00
</refnamediv>
<refsynopsisdiv >
<para > <filename > libnss_resolve.so.2</filename> </para>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
2016-02-23 20:24:03 +03:00
<para > <command > nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the
2020-04-14 11:37:40 +03:00
GNU C Library (<command > glibc</command> ) enabling it to resolve hostnames via the
2016-02-23 20:24:03 +03:00
<citerefentry > <refentrytitle > systemd-resolved</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> local network
name resolution service. It replaces the <command > nss-dns</command> plug-in module that traditionally resolves
hostnames via DNS.</para>
2020-04-15 19:05:39 +03:00
<para > To activate the NSS module, add <literal > resolve [!UNAVAIL=return]</literal> to the line starting
with <literal > hosts:</literal> in <filename > /etc/nsswitch.conf</filename> . Specifically, it is
recommended to place <literal > resolve</literal> early in <filename > /etc/nsswitch.conf</filename> 's
<literal > hosts:</literal> line. It should be before the <literal > files</literal> entry, since
<filename > systemd-resolved</filename> supports <filename > /etc/hosts</filename> internally, but with
caching. To the contrary, it should be after <literal > mymachines</literal> , to give hostnames given to
local VMs and containers precedence over names received over DNS. Finally, we recommend placing
<literal > dns</literal> somewhere after <literal > resolve</literal> , to fall back to
<command > nss-dns</command> if <filename > systemd-resolved.service</filename> is not available.</para>
2017-06-29 03:43:37 +03:00
2020-08-17 10:10:32 +03:00
<para > Note that <command > systemd-resolved</command> will synthesize DNS resource records in a few cases,
for example for <literal > localhost</literal> and the current local hostname, see
<citerefentry > <refentrytitle > systemd-resolved</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> for
the full list. This duplicates the functionality of
<citerefentry > <refentrytitle > nss-myhostname</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> , but
it is still recommended (see examples below) to keep <command > nss-myhostname</command> configured in
2017-06-29 03:43:37 +03:00
<filename > /etc/nsswitch.conf</filename> , to keep those names resolveable if
<command > systemd-resolved</command> is not running.</para>
2021-07-17 20:49:42 +03:00
<para > Please keep in mind that <command > nss-myhostname</command> (and <command > nss-resolve</command> ) also resolve
2021-08-18 13:14:31 +03:00
in the other direction — from locally attached IP addresses to
2021-07-17 20:49:42 +03:00
hostnames. If you rely on that lookup being provided by DNS, you might
want to order things differently.
</para>
2021-10-28 11:53:55 +03:00
<para > Communication between <command > nss-resolve</command> and
<filename > systemd-resolved.service</filename> takes place via the
<filename > /run/systemd/resolve/io.systemd.Resolve</filename> <constant > AF_UNIX</constant> socket.</para>
2015-08-26 12:00:09 +03:00
</refsect1>
2021-12-14 20:48:25 +03:00
<refsect1 >
<title > Environment variables</title>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_NSS_RESOLVE_VALIDATE</varname> </term>
<listitem > <para > Takes a boolean argument. When false, cryptographic validation of resource records
via DNSSEC will be disabled. This may be useful for testing, or when system time is known to be
unreliable.</para> </listitem>
</varlistentry>
</variablelist>
2021-12-20 16:16:44 +03:00
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_NSS_RESOLVE_SYNTHESIZE</varname> </term>
<listitem > <para > Takes a boolean argument. When false, synthetic records, e.g. for the local host
name, will not be returned. See section SYNTHETIC RECORDS in
<citerefentry > <refentrytitle > systemd-resolved.service</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry>
for more information. This may be useful to query the "public" resource records, independent of the
configuration of the local machine.</para> </listitem>
</varlistentry>
</variablelist>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_NSS_RESOLVE_CACHE</varname> </term>
<listitem > <para > Takes a boolean argument. When false, the cache of previously queried records will
not be used by <filename > systemd-resolved</filename> .</para> </listitem>
</varlistentry>
</variablelist>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_NSS_RESOLVE_ZONE</varname> </term>
<listitem > <para > Takes a boolean argument. When false, answers using locally registered public
LLMNR/mDNS resource records will not be returned.</para> </listitem>
</varlistentry>
</variablelist>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_NSS_RESOLVE_TRUST_ANCHOR</varname> </term>
<listitem > <para > Takes a boolean argument. When false, answers using locally configured trust anchors
will not be used.</para> </listitem>
</varlistentry>
</variablelist>
<variablelist class= 'environment-variables' >
<varlistentry >
<term > <varname > $SYSTEMD_NSS_RESOLVE_NETWORK</varname> </term>
<listitem > <para > Takes a boolean argument. When false, answers will be returned without using the
network, i.e. either from local sources or the cache in <filename > systemd-resolved</filename> .
</para> </listitem>
</varlistentry>
</variablelist>
2021-12-14 20:48:25 +03:00
</refsect1>
2015-08-26 12:00:09 +03:00
<refsect1 >
<title > Example</title>
2016-02-23 20:24:03 +03:00
<para > Here is an example <filename > /etc/nsswitch.conf</filename> file that enables <command > nss-resolve</command>
correctly:</para>
2015-08-26 12:00:09 +03:00
2018-11-27 19:02:20 +03:00
<!-- synchronize with other nss - * man pages and factory/etc/nsswitch.conf -->
2020-07-07 22:58:12 +03:00
<programlisting > passwd: compat systemd
2020-08-17 10:10:32 +03:00
group: compat [SUCCESS=merge] systemd
2021-05-05 17:11:26 +03:00
shadow: compat systemd
gshadow: files systemd
2015-08-26 12:00:09 +03:00
2020-08-17 10:10:32 +03:00
hosts: mymachines <command > resolve [!UNAVAIL=return]</command> files myhostname dns
2015-08-26 12:00:09 +03:00
networks: files
protocols: db files
services: db files
ethers: db files
rpc: db files
netgroup: nis</programlisting>
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > systemd-resolved</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2016-07-14 20:19:49 +03:00
<citerefentry > <refentrytitle > nss-systemd</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2015-08-26 12:00:09 +03:00
<citerefentry > <refentrytitle > nss-myhostname</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2016-07-14 20:19:49 +03:00
<citerefentry > <refentrytitle > nss-mymachines</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2021-12-14 20:48:25 +03:00
<citerefentry project= 'man-pages' > <refentrytitle > nsswitch.conf</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > systemd.syntax</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry>
2015-08-26 12:00:09 +03:00
</para>
</refsect1>
</refentry>