man/nss-resolve.xml

   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           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>nss-resolve</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>nss-resolve</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>nss-resolve</refname>
  21     <refname>libnss_resolve.so.2</refname>
  22     <refpurpose>Hostname resolution via <filename>systemd-resolved.service</filename></refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para><filename>libnss_resolve.so.2</filename></para>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  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>
  37
  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>
  47
  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>
  56
  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.
  61     </para>
  62
  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>
  66   </refsect1>
  67
  68   <refsect1>
  69     <title>Environment variables</title>
  70
  71     <variablelist class='environment-variables'>
  72       <varlistentry>
  73         <term><varname>$SYSTEMD_NSS_RESOLVE_VALIDATE</varname></term>
  74
  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
  77         unreliable.</para>
  78
  79         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
  80       </varlistentry>
  81     </variablelist>
  82
  83     <variablelist class='environment-variables'>
  84       <varlistentry>
  85         <term><varname>$SYSTEMD_NSS_RESOLVE_SYNTHESIZE</varname></term>
  86
  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>
  92
  93         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
  94       </varlistentry>
  95     </variablelist>
  96
  97     <variablelist class='environment-variables'>
  98       <varlistentry>
  99         <term><varname>$SYSTEMD_NSS_RESOLVE_CACHE</varname></term>
 100
 101         <listitem><para>Takes a boolean argument. When false, the cache of previously queried records will
 102         not be used by
 103         <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 104         </para>
 105
 106         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 107       </varlistentry>
 108     </variablelist>
 109
 110     <variablelist class='environment-variables'>
 111       <varlistentry>
 112         <term><varname>$SYSTEMD_NSS_RESOLVE_ZONE</varname></term>
 113
 114         <listitem><para>Takes a boolean argument. When false, answers using locally registered public
 115         LLMNR/mDNS resource records will not be returned.</para>
 116
 117         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 118       </varlistentry>
 119     </variablelist>
 120
 121     <variablelist class='environment-variables'>
 122       <varlistentry>
 123         <term><varname>$SYSTEMD_NSS_RESOLVE_TRUST_ANCHOR</varname></term>
 124
 125         <listitem><para>Takes a boolean argument. When false, answers using locally configured trust anchors
 126         will not be used.</para>
 127
 128         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 129       </varlistentry>
 130     </variablelist>
 131
 132     <variablelist class='environment-variables'>
 133       <varlistentry>
 134         <term><varname>$SYSTEMD_NSS_RESOLVE_NETWORK</varname></term>
 135
 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>.
 139         </para>
 140
 141         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 142       </varlistentry>
 143     </variablelist>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Example</title>
 148
 149     <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
 150     <command>nss-resolve</command> correctly:</para>
 151
 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
 157
 158 hosts:          mymachines <command>resolve [!UNAVAIL=return]</command> files myhostname dns
 159 networks:       files
 160
 161 protocols:      db files
 162 services:       db files
 163 ethers:         db files
 164 rpc:            db files
 165
 166 netgroup:       nis</programlisting>
 167   </refsect1>
 168
 169   <refsect1>
 170     <title>See Also</title>
 171     <para>
 172       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 173       <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 174       <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 177       <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 179     </para>
 180   </refsect1>
 181
 182 </refentry>