From 9053aaad4255a1d01a50f8e44784cd7eebe8f95c Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 23 Feb 2016 18:24:03 +0100
Subject: 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.
---
 man/nss-resolve.xml | 45 +++++++++++++++++++--------------------------
 1 file changed, 19 insertions(+), 26 deletions(-)

(limited to 'man/nss-resolve.xml')

diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml
index 8b0928145f..d9e56453e8 100644
--- a/man/nss-resolve.xml
+++ b/man/nss-resolve.xml
@@ -56,37 +56,36 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>nss-resolve</command> is a plugin module for the
-    GNU Name Service Switch (NSS) functionality of the GNU C Library
-    (<command>glibc</command>) enabling it to resolve host names via
-    the
-    <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    local network name resolution service.</para>
-
-    <para>To activate the NSS module, <literal>resolve</literal>
-    has to be added to the line starting with
-    <literal>hosts:</literal> in
-    <filename>/etc/nsswitch.conf</filename>.</para>
-
-    <para>It is recommended to place <literal>resolve</literal> early
-    in the <filename>nsswitch.conf</filename> line (but after the
-    <literal>files</literal> entry), replacing the
-    <literal>dns</literal> entry if it exists, to ensure DNS queries
-    are always routed via
+    <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 host names 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</literal> to the line starting with
+    <literal>hosts:</literal> in <filename>/etc/nsswitch.conf</filename>.</para>
+
+    <para>It is recommended to place <literal>resolve</literal> early in <filename>/etc/nsswitch.conf</filename>'
+    <literal>hosts:</literal> line (but after the <literal>files</literal> or <literal>mymachines</literal> entries),
+    replacing the <literal>dns</literal> entry if it exists, to ensure DNS queries are always routed via
     <citerefentry><refentrytitle>systemd-resolved</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+    <para>Note that <command>nss-resolve</command> will chain-load <command>nss-dns</command> if
+    <filename>systemd-resolved.service</filename> is not running, ensuring that basic DNS resolution continues to work
+    if the service is down.</para>
   </refsect1>
 
   <refsect1>
     <title>Example</title>
 
-    <para>Here is an example <filename>/etc/nsswitch.conf</filename>
-    file that enables <command>resolve</command> correctly:</para>
+    <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables <command>nss-resolve</command>
+    correctly:</para>
 
 <programlisting>passwd:         compat mymachines
 group:          compat mymachines
 shadow:         compat
 
-hosts:          files <command>resolve</command> mymachines myhostname
+hosts:          files mymachines <command>resolve</command> myhostname
 networks:       files
 
 protocols:      db files
@@ -96,12 +95,6 @@ rpc:            db files
 
 netgroup:       nis</programlisting>
 
-    <para>Note that <command>nss-resolve</command> will chain-load
-    <command>nss-dns</command> if
-    <filename>systemd-resolved.service</filename> is not running,
-    ensuring that basic DNS resolution continues to work if the
-    service is down.</para>
-
   </refsect1>
 
   <refsect1>
-- 
cgit v1.2.1