shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-28 11:21:59 +03:00
Code
1ab6ecd109
systemd/man/nss-resolve.xml

183 lines
8.2 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: document nss-resolve
2015-08-26 12:00:09 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document nss-resolve
2015-08-26 12:00:09 +03:00
man: Add xinclude namespace This will be used by the next commit to add version information to the nodes.
2023-08-22 19:52:02 +03:00
<refentry id="nss-resolve" conditional='ENABLE_NSS_RESOLVE'
xmlns:xi="http://www.w3.org/2001/XInclude">
man: document nss-resolve
2015-08-26 12:00:09 +03:00
<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>
tree-wide: fixes for assorted grammar and spelling issues Fixes #16363. Also includes some changes where I generalized the pattern.
2020-07-06 11:49:59 +03:00
<refpurpose>Hostname resolution via <filename>systemd-resolved.service</filename></refpurpose>
man: document nss-resolve
2015-08-26 12:00:09 +03:00
</refnamediv>
<refsynopsisdiv>
<para><filename>libnss_resolve.so.2</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
man: change recommended order of NSS modules in /etc/nsswitch.conf So far we recommended placing "nss-mymachines" after "nss-resolve" in the order of preference in /etc/nsswitch.conf. This change reverse this order. Rationale: single-label names are resolved via LLMNR by resolved, which has to time out if no peer by that name exists. By placing "nss-mymachines" first (which always responds immediately) we avoid running into this timeout for most containers. Both modules should return the same data if LLMNR is used by the container anyway. While we are at it, improve the man pages of the three NSS modules in other ways a bit.
2016-02-23 20:24:03 +03:00
<para><command>nss-resolve</command> is a plug-in module for the GNU Name Service Switch (NSS) functionality of the
tree-wide: use "hostname" spelling everywhere It's not that I think that "hostname" is vastly superior to "host name". Quite the opposite — the difference is small, and in some context the two-word version does fit better. But in the tree, there are ~200 occurrences of the first, and >1600 of the other, and consistent spelling is more important than any particular spelling choice.
2020-04-14 11:37:40 +03:00
GNU C Library (<command>glibc</command>) enabling it to resolve hostnames via the
man: change recommended order of NSS modules in /etc/nsswitch.conf So far we recommended placing "nss-mymachines" after "nss-resolve" in the order of preference in /etc/nsswitch.conf. This change reverse this order. Rationale: single-label names are resolved via LLMNR by resolved, which has to time out if no peer by that name exists. By placing "nss-mymachines" first (which always responds immediately) we avoid running into this timeout for most containers. Both modules should return the same data if LLMNR is used by the container anyway. While we are at it, improve the man pages of the three NSS modules in other ways a bit.
2016-02-23 20:24:03 +03:00
<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>
man: move "files" after "resolve" in the suggested configuration resolved caches files, so we should move nss-files after nss-resolve to speed up local access (and yes, people like to have thousands of lines in /etc/hosts). See https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/LCX6YXLM62QEYJSOLJBWXXVXTZVL73GI/ for the background.
2020-04-15 19:05:39 +03:00
<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>
man: describe the relationship between nss-myhostname and nss-resolved Fixes #1605.
2017-06-29 03:43:37 +03:00
man: move 'files' module in NSS 'hosts:' line before myhostname I am pretty sure /etc/hosts (i.e. an explicitly configured, local, trusted database) should be useful for overriding the automatic myhostname logic. resolved's internal logic handles it that way and hence we should suggest it in the NSS fallback line, too. Let's also bring the factory file back into sync with what the docs say. And update the prose a bit too, to actually match what we recommend.
2020-08-17 10:10:32 +03:00
<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
man: describe the relationship between nss-myhostname and nss-resolved Fixes #1605.
2017-06-29 03:43:37 +03:00
<filename>/etc/nsswitch.conf</filename>, to keep those names resolveable if
<command>systemd-resolved</command> is not running.</para>
man: document nss-{resolve,myhostname} resolving in the other direction, too
2021-07-17 20:49:42 +03:00
<para>Please keep in mind that <command>nss-myhostname</command> (and <command>nss-resolve</command>) also resolve
tree-wide: fix typo
2021-08-18 13:14:31 +03:00
in the other direction — from locally attached IP addresses to
man: document nss-{resolve,myhostname} resolving in the other direction, too
2021-07-17 20:49:42 +03:00
hostnames. If you rely on that lookup being provided by DNS, you might
want to order things differently.
</para>
man: document how nss-resolve and systemd-resolved communicate Fixes: #20925
2021-10-28 11:53:55 +03:00
<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>
man: document nss-resolve
2015-08-26 12:00:09 +03:00
</refsect1>
man: describe $SYSTEMD_NSS_RESOLVE_VALIDATE This variable has a pretty important effect, but we didn't mention it anywhere in the docs. It was added in aee9d18c8d909eb7aca2838e4bce5da018b6a112.
2021-12-14 20:48:25 +03:00
<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
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
unreliable.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
man: describe $SYSTEMD_NSS_RESOLVE_VALIDATE This variable has a pretty important effect, but we didn't mention it anywhere in the docs. It was added in aee9d18c8d909eb7aca2838e4bce5da018b6a112.
2021-12-14 20:48:25 +03:00
</varlistentry>
</variablelist>
nss-resolve: expose various source-disablement settings as variables Fixes https://bugzilla.redhat.com/show_bug.cgi?id=2006761: > systemd-resolved always (reverse)-resolves the host's IP addresses and FQDN. > This can be harmful when an application (for instance, a DNS zone manager) is > installed on the same server instance. That application would expect > NXDOMAIN to be returned if the current server's IP does not belong in an > already managed reverse zone. This allows clients of nss-resolve to use the same config options that are available through the dbus api and as command-line options to resolvectl. The man page text is is mostly copied directly from c6f20515ab600098b5c2871bae2e9ecab3b41555.
2021-12-20 16:16:44 +03:00
<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
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
configuration of the local machine.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
nss-resolve: expose various source-disablement settings as variables Fixes https://bugzilla.redhat.com/show_bug.cgi?id=2006761: > systemd-resolved always (reverse)-resolves the host's IP addresses and FQDN. > This can be harmful when an application (for instance, a DNS zone manager) is > installed on the same server instance. That application would expect > NXDOMAIN to be returned if the current server's IP does not belong in an > already managed reverse zone. This allows clients of nss-resolve to use the same config options that are available through the dbus api and as command-line options to resolvectl. The man page text is is mostly copied directly from c6f20515ab600098b5c2871bae2e9ecab3b41555.
2021-12-20 16:16:44 +03:00
</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
man: fixes for assorted issues reported by the manpage-l10n project Fixes #26761.
2023-05-17 13:24:04 +03:00
not be used by
<citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
nss-resolve: expose various source-disablement settings as variables Fixes https://bugzilla.redhat.com/show_bug.cgi?id=2006761: > systemd-resolved always (reverse)-resolves the host's IP addresses and FQDN. > This can be harmful when an application (for instance, a DNS zone manager) is > installed on the same server instance. That application would expect > NXDOMAIN to be returned if the current server's IP does not belong in an > already managed reverse zone. This allows clients of nss-resolve to use the same config options that are available through the dbus api and as command-line options to resolvectl. The man page text is is mostly copied directly from c6f20515ab600098b5c2871bae2e9ecab3b41555.
2021-12-20 16:16:44 +03:00
</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
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
LLMNR/mDNS resource records will not be returned.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
nss-resolve: expose various source-disablement settings as variables Fixes https://bugzilla.redhat.com/show_bug.cgi?id=2006761: > systemd-resolved always (reverse)-resolves the host's IP addresses and FQDN. > This can be harmful when an application (for instance, a DNS zone manager) is > installed on the same server instance. That application would expect > NXDOMAIN to be returned if the current server's IP does not belong in an > already managed reverse zone. This allows clients of nss-resolve to use the same config options that are available through the dbus api and as command-line options to resolvectl. The man page text is is mostly copied directly from c6f20515ab600098b5c2871bae2e9ecab3b41555.
2021-12-20 16:16:44 +03:00
</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
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
will not be used.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
nss-resolve: expose various source-disablement settings as variables Fixes https://bugzilla.redhat.com/show_bug.cgi?id=2006761: > systemd-resolved always (reverse)-resolves the host's IP addresses and FQDN. > This can be harmful when an application (for instance, a DNS zone manager) is > installed on the same server instance. That application would expect > NXDOMAIN to be returned if the current server's IP does not belong in an > already managed reverse zone. This allows clients of nss-resolve to use the same config options that are available through the dbus api and as command-line options to resolvectl. The man page text is is mostly copied directly from c6f20515ab600098b5c2871bae2e9ecab3b41555.
2021-12-20 16:16:44 +03:00
</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
man: fixes for assorted issues reported by the manpage-l10n project Fixes #26761.
2023-05-17 13:24:04 +03:00
network, i.e. either from local sources or the cache in
<citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
man: add version info This tries to add information about when each option was added. It goes back to version 183. The version info is included from a separate file to allow generating it, which would allow more control on the formatting of the final output.
2023-08-22 19:52:36 +03:00
</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
nss-resolve: expose various source-disablement settings as variables Fixes https://bugzilla.redhat.com/show_bug.cgi?id=2006761: > systemd-resolved always (reverse)-resolves the host's IP addresses and FQDN. > This can be harmful when an application (for instance, a DNS zone manager) is > installed on the same server instance. That application would expect > NXDOMAIN to be returned if the current server's IP does not belong in an > already managed reverse zone. This allows clients of nss-resolve to use the same config options that are available through the dbus api and as command-line options to resolvectl. The man page text is is mostly copied directly from c6f20515ab600098b5c2871bae2e9ecab3b41555.
2021-12-20 16:16:44 +03:00
</varlistentry>
</variablelist>
man: describe $SYSTEMD_NSS_RESOLVE_VALIDATE This variable has a pretty important effect, but we didn't mention it anywhere in the docs. It was added in aee9d18c8d909eb7aca2838e4bce5da018b6a112.
2021-12-14 20:48:25 +03:00
</refsect1>
man: document nss-resolve
2015-08-26 12:00:09 +03:00
<refsect1>
<title>Example</title>
man: various issues reported in #22432 Fixes #22432.
2022-02-23 00:54:23 +03:00
<para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
<command>nss-resolve</command> correctly:</para>
man: document nss-resolve
2015-08-26 12:00:09 +03:00
man,factory: update factory config for nsswitch.conf to match the man pages Also add a note in the man pages to remind people to adjust the factory config and other man pages at the same time.
2018-11-27 19:02:20 +03:00
<!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
docs: excorcise NIS from nsswitch.conf Let's replace the "compat" module in our proposed nsswitch.conf configuration with "files", since it is not 1995 anymore. Fedora and other distros have deprecated and removed NIS support a while back. While others still retain some support I am not sure we should advertise it in our examples. Downstream can of course still use "compat" instead of "files" if they want to, but let's not confuse people who don't care about NIS anymore with this. Also, bring the nsswitch.conf snippet in README in line with what our man pages say. Also see: https://fedoraproject.org/wiki/Changes/retire_NIS_user_space_utils
2023-09-20 12:50:20 +03:00
<programlisting>passwd: files systemd
group: files [SUCCESS=merge] systemd
shadow: files systemd
nss-systemd: synthesize NSS shadow/gshadow records from userdb, as well This ensures we not only synthesize regular paswd/group records of userdb records, but shadow records as well. This should make sure that userdb can be used as comprehensive superset of the classic passwd/group/shadow/gshadow functionality.
2021-05-05 17:11:26 +03:00
gshadow: files systemd
man: document nss-resolve
2015-08-26 12:00:09 +03:00
man: move 'files' module in NSS 'hosts:' line before myhostname I am pretty sure /etc/hosts (i.e. an explicitly configured, local, trusted database) should be useful for overriding the automatic myhostname logic. resolved's internal logic handles it that way and hence we should suggest it in the NSS fallback line, too. Let's also bring the factory file back into sync with what the docs say. And update the prose a bit too, to actually match what we recommend.
2020-08-17 10:10:32 +03:00
hosts: mymachines <command>resolve [!UNAVAIL=return]</command> files myhostname dns
man: document nss-resolve
2015-08-26 12:00:09 +03:00
networks: files
protocols: db files
services: db files
ethers: db files
rpc: db files
netgroup: nis</programlisting>
</refsect1>
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-22 21:09:32 +03:00
<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>
man: document nss-resolve
2015-08-26 12:00:09 +03:00
</refsect1>
</refentry>
Copy Permalink