2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"nss-resolve" conditional='ENABLE_NSS_RESOLVE'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>nss-resolve
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>nss-resolve
</refentrytitle>
16 <manvolnum>8</manvolnum>
20 <refname>nss-resolve
</refname>
21 <refname>libnss_resolve.so
.2</refname>
22 <refpurpose>Hostname resolution via
<filename>systemd-resolved.service
</filename></refpurpose>
26 <para><filename>libnss_resolve.so
.2</filename></para>
30 <title>Description
</title>
32 <para><command>nss-resolve
</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the
33 GNU C Library (
<command>glibc
</command>) enabling it to resolve hostnames via the
34 <citerefentry><refentrytitle>systemd-resolved
</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network
35 name resolution service. It replaces the
<command>nss-dns
</command> plug-in module that traditionally resolves
36 hostnames via DNS.
</para>
38 <para>To activate the NSS module, add
<literal>resolve [!UNAVAIL=return]
</literal> to the line starting
39 with
<literal>hosts:
</literal> in
<filename>/etc/nsswitch.conf
</filename>. Specifically, it is
40 recommended to place
<literal>resolve
</literal> early in
<filename>/etc/nsswitch.conf
</filename>'s
41 <literal>hosts:
</literal> line. It should be before the
<literal>files
</literal> entry, since
42 <filename>systemd-resolved
</filename> supports
<filename>/etc/hosts
</filename> internally, but with
43 caching. To the contrary, it should be after
<literal>mymachines
</literal>, to give hostnames given to
44 local VMs and containers precedence over names received over DNS. Finally, we recommend placing
45 <literal>dns
</literal> somewhere after
<literal>resolve
</literal>, to fall back to
46 <command>nss-dns
</command> if
<filename>systemd-resolved.service
</filename> is not available.
</para>
48 <para>Note that
<command>systemd-resolved
</command> will synthesize DNS resource records in a few cases,
49 for example for
<literal>localhost
</literal> and the current local hostname, see
50 <citerefentry><refentrytitle>systemd-resolved
</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
51 the full list. This duplicates the functionality of
52 <citerefentry><refentrytitle>nss-myhostname
</refentrytitle><manvolnum>8</manvolnum></citerefentry>, but
53 it is still recommended (see examples below) to keep
<command>nss-myhostname
</command> configured in
54 <filename>/etc/nsswitch.conf
</filename>, to keep those names resolveable if
55 <command>systemd-resolved
</command> is not running.
</para>
57 <para>Please keep in mind that
<command>nss-myhostname
</command> (and
<command>nss-resolve
</command>) also resolve
58 in the other direction — from locally attached IP addresses to
59 hostnames. If you rely on that lookup being provided by DNS, you might
60 want to order things differently.
63 <para>Communication between
<command>nss-resolve
</command> and
64 <filename>systemd-resolved.service
</filename> takes place via the
65 <filename>/run/systemd/resolve/io.systemd.Resolve
</filename> <constant>AF_UNIX
</constant> socket.
</para>
69 <title>Environment variables
</title>
71 <variablelist class='environment-variables'
>
73 <term><varname>$SYSTEMD_NSS_RESOLVE_VALIDATE
</varname></term>
75 <listitem><para>Takes a boolean argument. When false, cryptographic validation of resource records
76 via DNSSEC will be disabled. This may be useful for testing, or when system time is known to be
79 <xi:include href=
"version-info.xml" xpointer=
"v250"/></listitem>
83 <variablelist class='environment-variables'
>
85 <term><varname>$SYSTEMD_NSS_RESOLVE_SYNTHESIZE
</varname></term>
87 <listitem><para>Takes a boolean argument. When false, synthetic records, e.g. for the local host
88 name, will not be returned. See section SYNTHETIC RECORDS in
89 <citerefentry><refentrytitle>systemd-resolved.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
90 for more information. This may be useful to query the
"public" resource records, independent of the
91 configuration of the local machine.
</para>
93 <xi:include href=
"version-info.xml" xpointer=
"v250"/></listitem>
97 <variablelist class='environment-variables'
>
99 <term><varname>$SYSTEMD_NSS_RESOLVE_CACHE
</varname></term>
101 <listitem><para>Takes a boolean argument. When false, the cache of previously queried records will
103 <citerefentry><refentrytitle>systemd-resolved
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
106 <xi:include href=
"version-info.xml" xpointer=
"v250"/></listitem>
110 <variablelist class='environment-variables'
>
112 <term><varname>$SYSTEMD_NSS_RESOLVE_ZONE
</varname></term>
114 <listitem><para>Takes a boolean argument. When false, answers using locally registered public
115 LLMNR/mDNS resource records will not be returned.
</para>
117 <xi:include href=
"version-info.xml" xpointer=
"v250"/></listitem>
121 <variablelist class='environment-variables'
>
123 <term><varname>$SYSTEMD_NSS_RESOLVE_TRUST_ANCHOR
</varname></term>
125 <listitem><para>Takes a boolean argument. When false, answers using locally configured trust anchors
126 will not be used.
</para>
128 <xi:include href=
"version-info.xml" xpointer=
"v250"/></listitem>
132 <variablelist class='environment-variables'
>
134 <term><varname>$SYSTEMD_NSS_RESOLVE_NETWORK
</varname></term>
136 <listitem><para>Takes a boolean argument. When false, answers will be returned without using the
137 network, i.e. either from local sources or the cache in
138 <citerefentry><refentrytitle>systemd-resolved
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
141 <xi:include href=
"version-info.xml" xpointer=
"v250"/></listitem>
147 <title>Example
</title>
149 <para>Here is an example
<filename>/etc/nsswitch.conf
</filename> file that enables
150 <command>nss-resolve
</command> correctly:
</para>
152 <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
153 <programlisting>passwd: files systemd
154 group: files [SUCCESS=merge] systemd
155 shadow: files systemd
156 gshadow: files systemd
158 hosts: mymachines
<command>resolve [!UNAVAIL=return]
</command> files myhostname dns
166 netgroup: nis
</programlisting>
170 <title>See Also
</title>
171 <para><simplelist type=
"inline">
172 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
173 <member><citerefentry><refentrytitle>systemd-resolved
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
174 <member><citerefentry><refentrytitle>nss-systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
175 <member><citerefentry><refentrytitle>nss-myhostname
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
176 <member><citerefentry><refentrytitle>nss-mymachines
</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
177 <member><citerefentry project='man-pages'
><refentrytitle>nsswitch.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
178 <member><citerefentry><refentrytitle>systemd.syntax
</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>