11.13 Name Service Switch

The (gnu system nss) module provides bindings to the configuration file of the libc name service switch or NSS (see NSS Configuration File in 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 (see System Databases and Name Service Switch in 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 name-service-switch field of operating-system declarations (see name-service-switch).

As an example, the declaration below configures the NSS to use the nss-mdns back-end, which supports host name lookups over multicast DNS (mDNS) for host names ending in .local:

(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")))))

Do not worry: the %mdns-host-lookup-nss variable (see below) contains this configuration, so you will not have to type it if all you want is to have .local host lookup working.

Note that, in this case, in addition to setting the name-service-switch of the operating-system declaration, you also need to use avahi-service-type (see avahi-service-type), or %desktop-services, which includes it (see Desktop Services). Doing this makes nss-mdns accessible to the name service cache daemon (see nscd-service).

For convenience, the following variables provide typical NSS configurations.

Variable: %default-nss

This is the default name service switch configuration, a name-service-switch object.

Variable: %mdns-host-lookup-nss

This is the name service switch configuration with support for host name lookup over multicast DNS (mDNS) for host names ending in .local.

The reference for name service switch configuration is given below. It is a direct mapping of the configuration file format of the C library , so please refer to the C library manual for more information (see NSS Configuration File in The GNU C Library Reference Manual). Compared to the configuration file format of libc NSS, it has the advantage not only of adding this warm parenthetic feel that we like, but also static checks: you will know about syntax errors and typos as soon as you run guix system.

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.

aliases

ethers

group

gshadow

hosts

initgroups

netgroup

networks

password

public-key

rpc

services

shadow

The system databases handled by the NSS. Each of these fields must be a list of <name-service> objects (see below).

Data Type: name-service

This is the data type representing an actual name service and the associated lookup action.

name

A string denoting the name service (see Services in the NSS configuration in The GNU C Library Reference Manual).

Note that name services listed here must be visible to nscd. This is achieved by passing the #:name-services argument to nscd-service the list of packages providing the needed name services (see nscd-service).

reaction

An action specified using the lookup-specification macro (see Actions in the NSS configuration in The GNU C Library Reference Manual). For example:

(lookup-specification (unavailable => continue)
                      (success => return))