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
   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
  98         <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  99         </para></listitem>
 100       </varlistentry>
 101     </variablelist>
 102
 103     <variablelist class='environment-variables'>
 104       <varlistentry>
 105         <term><varname>$SYSTEMD_NSS_RESOLVE_ZONE</varname></term>
 106
 107         <listitem><para>Takes a boolean argument. When false, answers using locally registered public
 108         LLMNR/mDNS resource records will not be returned.</para></listitem>
 109       </varlistentry>
 110     </variablelist>
 111
 112     <variablelist class='environment-variables'>
 113       <varlistentry>
 114         <term><varname>$SYSTEMD_NSS_RESOLVE_TRUST_ANCHOR</varname></term>
 115
 116         <listitem><para>Takes a boolean argument. When false, answers using locally configured trust anchors
 117         will not be used.</para></listitem>
 118       </varlistentry>
 119     </variablelist>
 120
 121     <variablelist class='environment-variables'>
 122       <varlistentry>
 123         <term><varname>$SYSTEMD_NSS_RESOLVE_NETWORK</varname></term>
 124
 125         <listitem><para>Takes a boolean argument. When false, answers will be returned without using the
 126         network, i.e. either from local sources or the cache in
 127         <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 128         </para></listitem>
 129       </varlistentry>
 130     </variablelist>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>Example</title>
 135
 136     <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
 137     <command>nss-resolve</command> correctly:</para>
 138
 139     <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
 140 <programlisting>passwd:         compat systemd
 141 group:          compat [SUCCESS=merge] systemd
 142 shadow:         compat systemd
 143 gshadow:        files systemd
 144
 145 hosts:          mymachines <command>resolve [!UNAVAIL=return]</command> files myhostname dns
 146 networks:       files
 147
 148 protocols:      db files
 149 services:       db files
 150 ethers:         db files
 151 rpc:            db files
 152
 153 netgroup:       nis</programlisting>
 154   </refsect1>
 155
 156   <refsect1>
 157     <title>See Also</title>
 158     <para>
 159       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 160       <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 161       <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 162       <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 163       <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 164       <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 166     </para>
 167   </refsect1>
 168
 169 </refentry>