diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 116 |
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 |