ldapnss - Automatically switch name resolution (libnss) between LDAP and local mode
This script is used to switch the name resolution machanism of the GNU C library automatically between LDAP and local mode. The motivation to implement this is that programs would hang (until a timeout or forever) if they try to resolve a host, a user or a group name while a configured LDAP server cannot be reached.
The GNU C library has a mechanism called name service switching implemented in a shared library called libnss. It has a corresponding configuration file named /etc/nsswitch.conf. The ldapnss script links this file either to /etc/nsswitch.conf.ldap or to /etc/nsswitch.conf.local depending on the availlibility of the LDAP server or on command line options.
A boot time the LDAP server gets polled to determine its state. At shutdown the script is invoked to switch libnss back to local mode. This is accomplished by hooks in /etc/network/if-up/ldapnss and /etc/network/if-up/ldapnss. Even if the network (or interface) is brought down (or restarted) manually these hooks let ldapnss do the right thing.
When used on a server ldapnss can take over the functionality of /etc/init.d/slapd to start or stop the LDAP server. In other words: if you stop LDAP via ldapnss the server side libnss will run in local mode, or if you start LDAP again you will be back to LDAP mode. This feature is nice for testing and for system maintenance.
This parameter is used from /etc/network/if-up/ldapnss and /etc/network/if-up/ldapnss to silently poll for the LDAP server at boot time. If you don't want to use these two hooks you can disable them by setting the AUTO parameter in /etc/defaults/ldapnss. Example: AUTO=local will invoke only the shutdown hook.
Use this if you have written custom code to detect the availlibility of the LDAP server. The option avoids extra console messages and is used as:
/etc/init.d/ldapnss --force --ldap -or- /etc/init.d/ldapnss --force --local
Switch to LDAP mode. If not used together with --force the server is polled. In case that it is unavaillable ldapnss switches to local mode.
Switch to local mode.
This parameter runs the setup code as described below.
Poll the LDAP server and report the status. The configuration will not be updated.
Initially ldapnss does nothing by itself. Only after invoking it with the --setup option it will configure your system so that it get's called automatically. Setup does the following changes:
You will use ldapnss to start or stop slapd. The behaviour can be disabled by the RUNSLAPD=no configuration setting.
So ldapnss get's involved during boot or shutdown even without the hook in /etc/network. But this should be seen only as a fallback for special cases (like run-level switches). At least at boot time the /etc/network hook is preferred as it is reached much earlier.
The purpose of these hooks is discussed in this document at various places.
This happens only if no previous version existed. In other words: an existing configuration is not updated.
The setup does not create /etc/nsswitch.conf.ldap and /etc/nsswitch.conf.local for you. Try the following:
cd /etc cp nsswitch.conf nsswitch.conf.ldap mv nsswitch.conf nsswitch.conf.local ln -s nsswitch.conf.local nsswitch.conf
Edit nsswitch.conf.local. Here an example:
# /etc/nsswitch.conf.local passwd: files db group: files db shadow: files db # ...
Edit nsswitch.conf.ldap. Here an example:
# /etc/nsswitch.conf.ldap passwd: files ldap [NOTFOUND=return] db group: files ldap [NOTFOUND=return] db shadow: files ldap [NOTFOUND=return] db # ...
You will need the package libnss-ldap to make nsswitch work together with LDAP - it's configuration is in /etc/libnss-ldap.conf. Also you might want to install and configure packages like libpam-ccred and nss-updatedb to allow users to login with cached credentials when the LDAP server is not availlable. Some pam modules should be installed and configured to make use of LDAP too. Finally nscd must be mentioned - you should use it on server and client side but make sure that it is configured correctly to work in an LDAP environment. Look for some example configuration files under /usr/share/doc/ldapnss.
The assumption is that your laptop, workstation or server has exactly one interface that is configured as static in /etc/network/interfaces. This will be the default for most machines. Under different scenarios you will have to write your own hook routines to replace the defaults in /etc/network/if-up/ldapnss and /etc/network/if-up/ldapnss.
On some hardware you will have to wait a few seconds before the interface is initialized and ready to be used. This is not handled inside ifup! The ldapnss script provides the DELAY configuration parameter in /etc/defaults/ldapnss for this purpose. As an example DELAY=1.5 would wait 1500 ms before trying to poll the LDAP server. An empty value or a 0 will disable this wait. In problematic cases you should also configure ldapnss to use ping instead of netcat for polling. The ping will be tried four times with a timeout of 1000 ms per try. Select USEPING=yes to enable this behaviour.
By default the autoconfiguration happens only at boot time or when the interface is manually brought down (or up again). You would have to invent your own daemon to poll the LDAP server after boot (you could use cron to periodically issue the command: /etc/init.d/ldapnss auto ldap).
Very early at boot time udev gets launched and wants to lookup some user and group names. When this happens after a crash ldapnss had no chance to revert to local mode (which happens nomally at each shutdown). To avoid a delay caused by libnss to wait for the ldap server you should add the entries that udev wants to retrieve to /etc/passwd and /etc/group. See the examples given in /usr/share/doc/ldapnss.
The configuration settings for ldapnss, including the URL of the LDAP server.
This is made a symbolic link either to /etc/nsswitch.conf.ldap or to /etc/nsswitch.conf.local. The ldapnss switch changes this link depending on the availlibility of the LDAP server. This happens automatically at boot time.
The libnss configuration used when the LDAP server is availlable.
The libnss configuration used when the LDAP server is not availlable.
These scripts are called when a network interfaces is brought up or down. This happens also at boot-time or when the system is shut down.
ifup(8) slapd(8) nsswitch.conf(5) and /usr/share/doc/ldapnss
ldapnss (C) 2006-2007 Dr. Juergen Pfennig
This software is published under a BSD style license and has been written for educational purposes only, no warranties! Try it at your own risk.