NSS

This page has information about NSS, the "Name Service Switch" mechanisms that allows to store things like users and passwords somewhere else than in plain old files. Read on for a more complete description.

As long as databases are stored in local system files, NSS is not needed and therefore nothing needs to be installed. NSS becomes relevant only when the first data source that provides non-local information is installed. This is documented further down under the "LDAP data source" section. This section also contains the Debian packages that need to be installed.

References

nscd (name service caching daemon)

man nscd

nslcd (local LDAP name service daemon)

man nslcd

GNU C Library

http://www.gnu.org/software/libc/manual/html_node/NSS-Basics.html

Wikipedia

http://en.wikipedia.org/wiki/Name_Service_Switch

RFC 2307 (definitions for nis.schema)

ftp://ftp.rfc-editor.org/in-notes/rfc2307.txt

Glossary

NSS

Name Service Switch

Configuration database

A database that contains a collection of names of the same "type". For instance: "user names", "group names", "passwords".

Source

A source that provides a configuration database. For instance: a local file (/etc/passwd), LDAP directory, MySQL database

Overview: What is NSS

NSS decouples applications that need certain system information from the source that provides this information. Applications are not aware whether or not NSS is enabled - actually they don't even know that a concept such as NSS exists! Applications call system functions and NSS is encapsulated behind these system functions.

A rough overview of how NSS is involved when an application makes a system call:

• A program has the ID of a system user and needs the user's name
• The program uses a C system call
• The system function notices that NSS is enabled
• If the nscd caching daemon is running a query is made to the daemon whether a cached user name is available
• If the daemon is running and has a cached user name, the system function returns the desired user name to the program
• If the daemon is not running or has no cached user name, the system function queries the NSS configuration about possible sources for the database "user names"
• The system function queries each source in the configured order
• The first source that is able to satisfy the system function's request is used
• If the nscd caching daemon is running the system function caches the result in nscd
• The system function returns the desired user name to the program

NSS database types

aliases

Mail aliases

ethers

Ethernet numbers

group

Groups of users. Traditionally stored in /etc/group

hosts

Host names and numbers. Traditionally provided by DNS (dynamic) and stored in /etc/hosts (static)

netgroup

Network wide list of host and users

networks

Network names and numbers. . Traditionally provided by DNS (dynamic) and stored in /etc/networks (static)

protocols

Network protocols. Traditionally stored in /etc/protocols

passwd

User passwords. Traditionally stored in /etc/passwd

rpc

Remote procedure call names and numbers

services

Network services. Traditionally stored in /etc/services

shadow

Shadow user passwords. Traditionally stored in /etc/shadow

LDAP data source

Debian Packages

libnss-ldapd
nscld (automatically installed)

Note: In older Debian releases the main package was named libnss-ldap. The modern name of that package is libnss-ldapd. The modern package still provides a virtual package under the old name, presumably so that dependencies do not need to be changed.

References

nss_ldapd web site

https://arthurdejong.org/nss-pam-ldapd/

Design description

https://arthurdejong.org/nss-pam-ldapd/design

Local documentation

/usr/share/doc/libnss-ldapd

Configuration

dpkg

These are the questions that were asked by dpkg when the package was still named libnss-ldap - it is not clear whether today the same questions would be asked for libnss-ldapd. Some of the questions appear only when dpkg-reconfigure is executed.

• LDAP server URI = ldapi:///
• Distinguished name of the search base = dc=herzbube,dc=ch
• LDAP version to use = 3
• Does the LDAP database require login? = Yes
• Make the configuration file readable/writeable by its owner only? = Yes
• LDAP account for root = cn=libnss-ldap-root,ou=users,dc=herzbube,dc=ch (used for password changes)
• LDAP root account password = secret
• Unprivileged database user = cn=libnss-ldap,ou=users,dc=herzbube,dc=ch
• Password for database login account = secret

The answers are stored in this file:

/etc/nslcd.conf

Some of the questions/answers are shared with the package libpam-ldapd, so if that package has already been installed some questions may not be asked, the answers are simply taken from the DebConf database. To see a complete list of questions and answers that are stored in the DebConf database:

debconf-show libnss-ldap

Note: On my Debian system I run the command with the virtual (old) package name libnss-ldap, not the name of the actual (modern) package libnss-ldapd. This may be different on freshly installed systems. On my Debian system, which has several major OS upgrades behind it, the DebConf answers are still stored under the old package name.

Notes regarding permissions:

• The file /etc/nslcd.conf contains the passwords for both the privileged LDAP user libnss-ldap-root and the unprivileged LDAP user libnss-ldap.
• The file is owned by root:nslcd and has mode 640. The reason for the group-readable permission is that the nslcd daemon runs as user nslcd.

/etc/nsswitch.conf

Edit /etc/nsswitch.conf and add "ldap" to the databases that should be queried by libnss-ldapd:

passwd: compat ldap systemd
group: compat ldap systemd
shadow: compat ldap
[...]
# Only if host names are stored in LDAP
# hosts: files ldap dns
[...]

After the edit is finished, restart the nscd daemon to re-read the file. Note that this step may no longer be necessary on modern systems.

systemctl restart nscd.service

LDAP directory modifications

After configuring libnss-ldapd, modify the LDAP directory as follows:

• Add an LDAP user cn=libnss-ldap,ou=users,dc=herzbube,dc=ch to the directory
• Add an LDAP user cn=libnss-ldap-root,ou=users,dc=herzbube,dc=ch to the directory

Configure access rights in the LDAP directory (see the OpenLDAP wiki page), then restart the LDAP daemon.

• read-only access to the ou=users, ou=groups and ou=hosts tree for libnss-ldap
• same read-only access for libnss-ldap-root, with the additional read-only access to the userPassword attribute

Add user, group and host LDAP entries to the directory:

• User account LDAP entries must have the following structure so that libnss-ldapd can use them:
  • must be located below ou=users,dc=herzbube,dc=ch
  • must have object classes posixAccount and shadowAccount
  • apparently the gecos attribute cannot hold values with special characters (e.g. umlaut); for instance, I cannot add the value "Näf"
• Group LDAP entries must have the following structure so that libnss-ldapd can use them:
  • must be located below ou=groups,dc=herzbube,dc=ch
  • must have object class posixGroup
  • possibly obsolete the uniqueMember attribute is referenced by the libnss-ldapd documentation
    • I don't know exactly what this attribute is supposed to do
    • an example value: uid=patrick,ou=users,dc=herzbube,dc=ch
    • is an attribute from core.schema
    • attribute comes from RFC 2256 und has OID 2.5.4.50
    • the only object class with this attribute is groupOfUniqueNames (a structural object class, i.e. cannot be added to posixGroup)
    • at the moment I am simply ignoring this attribute since I cannot set it even if I knew what it is supposed to do
• Host LDAP entries must have the following structure so that libnss-ldapd can use them:
  • must be located below ou=hosts,dc=herzbube,dc=ch
  • must have object classes ipHost
  • because ipHost is an auxiliary object class, the entries also require a structural object class; RFC 2307 recommends object class device
  • the cn attribute holds the host names; the distinguished value is the canonical host name, all other values are the aliases

System files modifications

After everything is set up, the entries stored in LDAP can now be removed from the system files

• /etc/passwd
• /etc/group
• /etc/shadow
• /etc/hosts

Warning: The hostname pelargir must be present in /etc/hosts, otherwise the LDAP daemon slapd refuses to start up once it has been shut down. This probably is a bootstrap problem: slapd tries to lookup the IP for pelargir using a system call, which triggers libnss-ldapd to make an LDAP lookup, which of course fails since the daemon has not finished starting up.

nscd

Configuration file is

/etc/nscd.conf

Nowadays the default configuration is ok. In the past I had to manually make the following changes (although it's now obsolete, I keep this information for historical reasons):

enable-cache            hosts           yes

Explanation of the change:

• Host caching is disabled by default because of a bug in nscd which can cause problems when the IP address of the LDAP server changes
• See http://sourceware.org/bugzilla/show_bug.cgi?id=4428
• I think this will not affect me since I don't change my LDAP server to anything else than 127.0.0.1
• Anyway, performance on some things such as "ps aux" is very bad (don't ask me why there is a connection between the "ps" command and the hosts database), therefore I really need this caching