summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2015-02-04 21:58:15 +0100
committerLudovic Courtès <ludo@gnu.org>2015-02-04 22:49:35 +0100
commit996ed73948e92eb2005a2a282856753d707f452c (patch)
tree3dd45afdbbb22c01652cd2df9b7b61742440c6ab /doc
parentffd74de0c6de7435fcdc8e340efade032c365081 (diff)
downloadpatches-996ed73948e92eb2005a2a282856753d707f452c.tar
patches-996ed73948e92eb2005a2a282856753d707f452c.tar.gz
system: Add bindings to configure libc's NSS.
* gnu/system/nss.scm: New file. * gnu-system.am (GNU_SYSTEM_MODULES): Add it. * gnu.scm (%public-modules): Add it. * gnu/system.scm (<operating-system>)[name-service-switch]: New field. (etc-directory): Add #:nss parameter and honor it. (operating-system-etc-directory): Adjust call accordingly. * doc/guix.texi (operating-system Reference): Document 'name-service-switch'. (Name Service Switch): New section.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi116
1 files changed, 116 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index fa3aa6d66d..e489d414bc 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -142,6 +142,7 @@ System Configuration
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
@@ -3642,6 +3643,7 @@ instance to support new system services.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
@@ -3827,6 +3829,11 @@ Library Reference Manual}). @xref{Locales}, for more information.
The list of locale definitions to be compiled and that may be used at
run time. @xref{Locales}.
+@item @code{name-service-switch} (default: @var{%default-nss})
+Configuration of libc's name service switch (NSS)---a
+@code{<name-service-switch>} object. @xref{Name Service Switch}, for
+details.
+
@item @code{services} (default: @var{%base-services})
A list of monadic values denoting system services. @xref{Services}.
@@ -4648,6 +4655,115 @@ Under the hood, the actual setuid programs are created in the
files in this directory refer to the ``real'' binaries, which are in the
store.
+@node Name Service Switch
+@subsection Name Service Switch
+
+@cindex name service switch
+@cindex NSS
+The @code{(gnu system nss)} module provides bindings to the
+configuration file of libc's @dfn{name service switch} or @dfn{NSS}
+(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
+Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
+extended with new ``name'' lookup methods for system databases, which
+includes host names, service names, user accounts, and more (@pxref{Name
+Service Switch, System Databases and Name Service Switch,, libc, The GNU
+C Library Reference Manual}).
+
+The NSS configuration specifies, for each system database, which lookup
+method is to be used, and how the various methods are chained
+together---for instance, under which circumstances NSS should try the
+next method in the list. The NSS configuration is given in the
+@code{name-service-switch} field of @code{operating-system} declarations
+(@pxref{operating-system Reference, @code{name-service-switch}}).
+
+@c See <http://0pointer.de/lennart/projects/nss-mdns/>.
+As an example, the declaration below configures the NSS to use the
+@code{nss-mdns} back-end for host name lookups:
+
+@example
+(name-service-switch
+ (hosts (list %files ;first, check /etc/hosts
+
+ ;; If the above did not succeed, try
+ ;; with 'mdns_minimal'.
+ (name-service
+ (name "mdns_minimal")
+
+ ;; 'mdns_minimal' is authoritative for
+ ;; '.local'. When it returns "not found",
+ ;; no need to try the next methods.
+ (reaction (lookup-specification
+ (not-found => return))))
+
+ ;; Then fall back to DNS.
+ (name-service
+ (name "dns"))
+
+ ;; Finally, try with the "full" 'mdns'.
+ (name-service
+ (name "mdns")))))
+@end example
+
+The reference for name service switch configuration is given below. It
+is a direct mapping of the C library's configuration file format, so
+please refer to the C library manual for more information (@pxref{NSS
+Configuration File,,, libc, The GNU C Library Reference Manual}).
+Compared to libc's NSS configuration file format, it has the advantage
+not only of adding this warm parenthetic feel that we like, but also
+static checks: you'll know about syntax errors and typos as soon as you
+run @command{guix system}.
+
+@defvr {Scheme Variable} %default-nss
+This is the default name service switch configuration, a
+@code{name-service-switch} object.
+@end defvr
+
+@deftp {Data Type} name-service-switch
+
+This is the data type representation the configuration of libc's name
+service switch (NSS). Each field below represents one of the supported
+system databases.
+
+@table @code
+@item aliases
+@itemx ethers
+@itemx group
+@itemx gshadow
+@itemx hosts
+@itemx initgroups
+@itemx netgroup
+@itemx networks
+@itemx password
+@itemx public-key
+@itemx rpc
+@itemx services
+@itemx shadow
+The system databases handled by the NSS. Each of these fields must be a
+list of @code{<name-service>} objects (see below.)
+@end table
+@end deftp
+
+@deftp {Data Type} name-service
+
+This is the data type representing an actual name service and the
+associated lookup action.
+
+@table @code
+@item name
+A string denoting the name service (@pxref{Services in the NSS
+configuration,,, libc, The GNU C Library Reference Manual}).
+
+@item reaction
+An action specified using the @code{lookup-specification} macro
+(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
+Reference Manual}). For example:
+
+@example
+(lookup-specification (unavailable => continue)
+ (success => return))
+@end example
+@end table
+@end deftp
@node Initial RAM Disk
@subsection Initial RAM Disk