systemd/man/nss-resolve.xml
2023-12-25 15:51:47 +01:00

183 lines
8.2 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/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><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>