01/03: doc: Document NSS incompatibility issues on foreign distros.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 9a5187b687e659da86000b32c951e2f55e1f74bb
Author: Ludovic Courtès <address@hidden>
Date:   Mon Nov 28 16:19:04 2016 +0100

    doc: Document NSS incompatibility issues on foreign distros.
    
    * doc/guix.texi (Application Setup)[Name Service Switch]: New
    subsection.
---
 doc/guix.texi |   50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 5747484..ce1e5d0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1242,6 +1242,56 @@ data in the right format.
 This is important because the locale data format used by different libc
 versions may be incompatible.
 
address@hidden Name Service Switch
+
address@hidden name service switch, glibc
address@hidden NSS (name service switch), glibc
address@hidden nscd (name service caching daemon)
address@hidden name service caching daemon (nscd)
+When using Guix on a foreign distro, we @emph{strongly recommend} that
+the system run the GNU C library's @dfn{name service cache daemon},
address@hidden, which should be listening on the
address@hidden/var/run/nscd/socket} socket.  Failing to do that, applications
+installed with Guix may fail to look up host names or user accounts, or
+may even crash.  The next paragraphs explain why.
+
address@hidden @file{nsswitch.conf}
+The GNU C library implements a @dfn{name service switch} (NSS), which is
+an extensible mechanism for ``name lookups'' in general: host name
+resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
+The GNU C Library Reference Manual}).
+
address@hidden Network information service (NIS)
address@hidden NIS (Network information service)
+Being extensible, the NSS supports @dfn{plugins}, which provide new name
+lookup implementations: for example, the @code{nss-mdns} plugin allow
+resolution of @code{.local} host names, the @code{nis} plugin allows
+user account lookup using the Network information service (NIS), and so
+on.  These extra ``lookup services'' are configured system-wide in
address@hidden/etc/nsswitch.conf}, and all the programs running on the system
+honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
+Reference Manual}).
+
+When they perform a name lookup---for instance by calling the
address@hidden function in C---applications first try to connect to
+the nscd; on success, nscd performs name lookups on their behalf.  If
+the nscd is not running, then they perform the name lookup by
+themselves, by loading the name lookup services into their own address
+space and running it.  These name lookup services---the
address@hidden files---are @code{dlopen}'d, but they may come from
+the host system's C library, rather than from the C library the
+application is linked against (the C library coming from Guix).
+
+And this is where the problem is: if your application is linked against
+Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
+another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
+likely crash or have its name lookups fail unexpectedly.
+
+Running @command{nscd} on the system, among other advantages, eliminates
+this binary incompatibility problem because those @code{libnss_*.so}
+files are loaded in the @command{nscd} process, not in applications
+themselves.
+
 @subsection X11 Fonts
 
 @cindex fonts