1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="nss-resolve" conditional='ENABLE_NSS_RESOLVE'
xmlns:xi="http://www.w3.org/2001/XInclude">
<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>
<refpurpose>Hostname resolution via <filename>systemd-resolved.service</filename></refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename>libnss_resolve.so.2</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the
GNU C Library (<command>glibc</command>) enabling it to resolve hostnames via the
<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>
<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>
<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
<filename>/etc/nsswitch.conf</filename>, to keep those names resolvable if
<command>systemd-resolved</command> is not running.</para>
<para>Please keep in mind that <command>nss-myhostname</command> (and <command>nss-resolve</command>) also resolve
in the other direction — from locally attached IP addresses to
hostnames. If you rely on that lookup being provided by DNS, you might
want to order things differently.
</para>
<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>
</refsect1>
<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>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
</variablelist>
<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>
<xi:include href="version-info.xml" xpointer="v250"/></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
<citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<xi:include href="version-info.xml" xpointer="v250"/></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>
<xi:include href="version-info.xml" xpointer="v250"/></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>
<xi:include href="version-info.xml" xpointer="v250"/></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
<citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Example</title>
<para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
<command>nss-resolve</command> correctly:</para>
<!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
<programlisting>passwd: files systemd
group: files [SUCCESS=merge] systemd
shadow: files systemd
gshadow: files systemd
hosts: mymachines <command>resolve [!UNAVAIL=return]</command> files myhostname dns
networks: files
protocols: db files
services: db files
ethers: db files
rpc: db files
netgroup: nis</programlisting>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>
|
