summaryrefslogtreecommitdiffstats
path: root/man/nss-resolve.xml
blob: d633be2c3dd1796d356e9dcd1af689c48015c257 (plain)
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.2/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 resolveable 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>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>