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 <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
 138 group:          compat [SUCCESS=merge] systemd
 139 shadow:         compat systemd
 140 gshadow:        files systemd
 141
 142 hosts:          mymachines <command>resolve [!UNAVAIL=return]</command> files myhostname dns
 143 networks:       files
 144
 145 protocols:      db files
 146 services:       db files
 147 ethers:         db files
 148 rpc:            db files
 149
 150 netgroup:       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>