1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="nss-resolve" conditional='ENABLE_NSS_RESOLVE'>
7
8  <refentryinfo>
9    <title>nss-resolve</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>nss-resolve</refentrytitle>
15    <manvolnum>8</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>nss-resolve</refname>
20    <refname>libnss_resolve.so.2</refname>
21    <refpurpose>Hostname resolution via <filename>systemd-resolved.service</filename></refpurpose>
22  </refnamediv>
23
24  <refsynopsisdiv>
25    <para><filename>libnss_resolve.so.2</filename></para>
26  </refsynopsisdiv>
27
28  <refsect1>
29    <title>Description</title>
30
31    <para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the
32    GNU C Library (<command>glibc</command>) enabling it to resolve hostnames via the
33    <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> local network
34    name resolution service. It replaces the <command>nss-dns</command> plug-in module that traditionally resolves
35    hostnames via DNS.</para>
36
37    <para>To activate the NSS module, add <literal>resolve [!UNAVAIL=return]</literal> to the line starting
38    with <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>. Specifically, it is
39    recommended to place <literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>'s
40    <literal>hosts:</literal> line. It should be before the <literal>files</literal> entry, since
41    <filename>systemd-resolved</filename> supports <filename>/etc/hosts</filename> internally, but with
42    caching. To the contrary, it should be after <literal>mymachines</literal>, to give hostnames given to
43    local VMs and containers precedence over names received over DNS. Finally, we recommend placing
44    <literal>dns</literal> somewhere after <literal>resolve</literal>, to fall back to
45    <command>nss-dns</command> if <filename>systemd-resolved.service</filename> is not available.</para>
46
47    <para>Note that <command>systemd-resolved</command> will synthesize DNS resource records in a few cases,
48    for example for <literal>localhost</literal> and the current local hostname, see
49    <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
50    the full list. This duplicates the functionality of
51    <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, but
52    it is still recommended (see examples below) to keep <command>nss-myhostname</command> configured in
53    <filename>/etc/nsswitch.conf</filename>, to keep those names resolveable if
54    <command>systemd-resolved</command> is not running.</para>
55
56    <para>Please keep in mind that <command>nss-myhostname</command> (and <command>nss-resolve</command>) also resolve
57    in the other direction — from locally attached IP addresses to
58    hostnames. If you rely on that lookup being provided by DNS, you might
59    want to order things differently.
60    </para>
61
62    <para>Communication between <command>nss-resolve</command> and
63    <filename>systemd-resolved.service</filename> takes place via the
64    <filename>/run/systemd/resolve/io.systemd.Resolve</filename> <constant>AF_UNIX</constant> socket.</para>
65  </refsect1>
66
67  <refsect1>
68    <title>Environment variables</title>
69
70    <variablelist class='environment-variables'>
71      <varlistentry>
72        <term><varname>$SYSTEMD_NSS_RESOLVE_VALIDATE</varname></term>
73
74        <listitem><para>Takes a boolean argument. When false, cryptographic validation of resource records
75        via DNSSEC will be disabled. This may be useful for testing, or when system time is known to be
76        unreliable.</para></listitem>
77      </varlistentry>
78    </variablelist>
79
80    <variablelist class='environment-variables'>
81      <varlistentry>
82        <term><varname>$SYSTEMD_NSS_RESOLVE_SYNTHESIZE</varname></term>
83
84        <listitem><para>Takes a boolean argument. When false, synthetic records, e.g. for the local host
85        name, will not be returned. See section SYNTHETIC RECORDS in
86        <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
87        for more information. This may be useful to query the "public" resource records, independent of the
88        configuration of the local machine.</para></listitem>
89      </varlistentry>
90    </variablelist>
91
92    <variablelist class='environment-variables'>
93      <varlistentry>
94        <term><varname>$SYSTEMD_NSS_RESOLVE_CACHE</varname></term>
95
96        <listitem><para>Takes a boolean argument. When false, the cache of previously queried records will
97        not be used by <command>systemd-resolved</command>.</para></listitem>
98      </varlistentry>
99    </variablelist>
100
101    <variablelist class='environment-variables'>
102      <varlistentry>
103        <term><varname>$SYSTEMD_NSS_RESOLVE_ZONE</varname></term>
104
105        <listitem><para>Takes a boolean argument. When false, answers using locally registered public
106        LLMNR/mDNS resource records will not be returned.</para></listitem>
107      </varlistentry>
108    </variablelist>
109
110    <variablelist class='environment-variables'>
111      <varlistentry>
112        <term><varname>$SYSTEMD_NSS_RESOLVE_TRUST_ANCHOR</varname></term>
113
114        <listitem><para>Takes a boolean argument. When false, answers using locally configured trust anchors
115        will not be used.</para></listitem>
116      </varlistentry>
117    </variablelist>
118
119    <variablelist class='environment-variables'>
120      <varlistentry>
121        <term><varname>$SYSTEMD_NSS_RESOLVE_NETWORK</varname></term>
122
123        <listitem><para>Takes a boolean argument. When false, answers will be returned without using the
124        network, i.e. either from local sources or the cache in <command>systemd-resolved</command>.
125        </para></listitem>
126      </varlistentry>
127    </variablelist>
128  </refsect1>
129
130  <refsect1>
131    <title>Example</title>
132
133    <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
134    <command>nss-resolve</command> correctly:</para>
135
136    <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
137<programlisting>passwd:         compat systemd
138group:          compat [SUCCESS=merge] systemd
139shadow:         compat systemd
140gshadow:        files systemd
141
142hosts:          mymachines <command>resolve [!UNAVAIL=return]</command> files myhostname dns
143networks:       files
144
145protocols:      db files
146services:       db files
147ethers:         db files
148rpc:            db files
149
150netgroup:       nis</programlisting>
151  </refsect1>
152
153  <refsect1>
154    <title>See Also</title>
155    <para>
156      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
157      <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
158      <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
159      <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
160      <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
161      <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
162      <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
163    </para>
164  </refsect1>
165
166</refentry>
167