AUTHOR:   Randy McMurchy <randy_at_linuxfromscratch.org>

DATE:     2005-10-27

LICENSE:  Creative Commons Attribution-NonCommercial-ShareAlike License
          http://creativecommons.org/licenses/by-nc-sa/1.0/

SYNOPSIS: Installing the nss_db library and creating the NSS db files

DESCRIPTION:

This hint will guide you through the installation of the nss_db package and
population of the NSS db files. Additionally, the hint covers making the
necessary changes to /etc/nsswitch.conf as well as providing another way to
populate some of the db files.

ATTACHMENTS:

http://www.linuxfromscratch.org/patches/downloads/nss_db/nss_db-2.2-update-2.patch

PREREQUISITES:

An LFS system using Glibc-2.3.x.

HINT:

=========
CONTENTS:
=========

        1. Introduction
        2. Package Dependencies
        3. Package Installation
            Download the package
            Patch the package
            Update the autotool programs
            Configure the build
            Build the package
            Checking the build
            Install the package
            Stripping the binaries
            Installation modifications
            Update /etc/ld.so.cache
        4. Creating the DB Files
        5. Configuring /etc/nsswitch.conf
        6. Testing the Installation
        7. Alternate Method to Populate Files
        8. Issues, Gotchas and Other Sundry Items
        9. To Do List
       10. Closing

================
1. INTRODUCTION:
================

Up until version 2.2.0 of Glibc, the nss_db library, as well as Berkeley DB,
were included with the Glibc package. Beginning with Glibc-2.2.0, nss_db and
DB were removed from Glibc as the maintainers could not control the version
of DB installed on the system. If DB was upgraded on the system, it could 
render nss_db unusable. So, at this point the decision was made to make
nss_db a separate package.

As official Glibc releases were made public, nss_db was left behind. There's
been no official updates to the nss_db package since Glibc-2.2.0. Some of the
mainstream Linux distro's have been keeping nss_db alive during this time.
This hint brings nss_db back to LFS users.

The following files are duplicated as db files and may be used as primary or
alternate nameservice files using the nss_db library.

1) /etc/passwd
2) /etc/group
3) /etc/shadow
4) /etc/services
5) /etc/protocols
6) /etc/rpc

There are many good uses for nss_db as a nameservice resolver on your system.

1) On a stand-alone Linux system, nss_db can be used to provide a backup
mechanism for the nameservice /etc/flatfiles. There are reports that if your
Linux system has very large /etc/flatfiles, using nss_db to resolve the 
nameservice information is faster than using the /etc/flatfiles.

2) In a networked environment, the administrator can create db files to 
supplement the /etc/flatfiles. These db files could be placed on an NFS
partition which is locally mounted by other systems, giving the administrator
a central location for updating nameservice information.

3) In a network environment where usernames are resolved over the network
(LDAP, WINS, etc.), copies of the username login authentication files
can be stored locally, eliminating the need to fetch this information from
the network. This is especially important for laptop users who may connect
to the network while on premises, but need to authenticate when not attached
to the physical network.

========================
2. PACKAGE DEPENDENCIES:
========================

Berkeley DB-4.x 

Instructions for installing the DB package can be found at:

Stable release:
http://www.linuxfromscratch.org/blfs/view/stable/server/databases.html#db

Development release:
http://www.linuxfromscratch.org/blfs/view/svn/server/databases.html#db

========================
3. PACKAGE INSTALLATION:
========================

---------------------
Download the package:
---------------------

The last available "official" release of nss_db is nss_db-2.2 and can be
downloaded using the following URL's:

Anonymous FTP:
ftp://ftp.gnu.org/gnu/glibc/nss_db-2.2.tar.gz

HTTP:
http://ftp.gnu.org/gnu/glibc/nss_db-2.2.tar.gz

------------------
Patch the package:
------------------

You must first download and install the patch. The patch is included as an
attachment to this hint. See the Attachments section at the beginning of the
hint for download locations.

First unpack the nss_db tarball and change into the newly created source
directory. Patch the package by running the following command:

patch -Np1 -i ../nss_db-2.2-update-2.patch

The patch does many things.

1) Allows building against Glibc-2.3.x.
2) Changes DB calls to use DB-4.x
3) Fixes a problem with a db-open routine.
4) Adds the necessary pthread LDFLAGS to the Makefile.
5) Allows a user-specified db directory using --localstatedir as a switch to
   the configure script.
6) Modifies the Makefile used to create the db files to reflect the directory
   used to store the files, then copies the Makefile into this db directory.

-----------------------------
Update the autotool programs:
-----------------------------

Run the following commands to create the proper autotool programs and
scripts:

aclocal
automake -a
libtoolize -f
autoconf

You may receive warnings when running the "aclocal", "automake" and
"autoconf" programs. You can safely ignore these warnings.

--------------------
Configure the Build:
--------------------

./configure --prefix=/usr --localstatedir=/var/lib/nss_db

Command explanations:

--prefix=/usr: installs the library in /lib, the .so symlink to the library
in /usr/lib and the makedb program in /usr/bin

--localstatedir=/var/lib/nss_db: points to the location of the actual db files
created by the makedb program. The default location is /var/db, however there
is no mention of this directory in the FHS guidelines. You may choose any
directory you wish. If you desire the Glibc default of /var/db, simply leave
off the --localstatedir switch altogether.

------------------
Build the Package:
------------------

Simply running the "make" command will build the package.

-------------------
Checking the Build:
-------------------

There are no "check" rules in the various subdirectory makefiles, so there's
nothing to check. Running the "make check" command is pointless.

--------------------
Install the Package:
--------------------

****************************************************************************
*****                                                                  *****
*****  The remainder of this hint must be performed by the root user   *****
*****                                                                  *****
****************************************************************************

Simply issue a "make install" command to install the package. If desired,
create a /usr/share/doc/nss_db-2.2 directory and copy the README, INSTALL
and this hint file into the directory. This will serve as the installed
documentation for nss_db.

Additionally, you may wish to remove the /lib/libnss_db.so file, as it was
also installed into /usr/lib (where it belongs). Lastly, you can move the
/lib/libnss_db.la file into /usr/lib, as this is the proper location for the
file.

-----------------------
Stripping the Binaries:
-----------------------

If desired, strip the unnecessary symbols from the installed binaries by
issuing the following commands:

strip --strip-all /usr/bin/makedb
strip --strip-debug /lib/libnss_db.so.2.0.0

---------------------------
Installation Modifications:
---------------------------

If your system's /usr directory is not part of the root partition and is not
mounted when in single-user mode, you may wish to copy the DB libraries to /lib
so that the nss_db library can find them during times when /usr is not mounted.

The following commands move libraries created by Berkeley DB-4.3.28. If you
have installed a different version of DB, you may need to change the following
commands to reflect the actual names of the DB libraries.

Use the following commands to move the DB libraries and create symlinks in
/usr/lib pointing back to /lib so that programs looking for DB in /usr/lib
won't break.

mv /usr/lib/libdb-4.3.so /lib
mv /usr/lib/libdb-4.so /lib
ln -s ../../lib/libdb-4.3.so /usr/lib
ln -s ../../lib/libdb-4.so /usr/lib

------------------------
Update /etc/ld.so.cache:
------------------------

Update the linker's library cache file by issuing the "ldconfig" command:

ldconfig -v

=========================
4. CREATING THE DB FILES:
=========================

To create the db files, simply run the following command:

make -f /var/lib/nss_db/Makefile

You should substitute the correct path to the Makefile if you omitted or used
a different path on the --localstatedir switch to the configure command
during installation of the package.

After creating the initial db files, if you modify any of the /etc/flatfiles
and want to update the db files, simply run the command again. The
appropriate db files will be updated to reflect the changes in the /etc
files.

=================================
5. CONFIGURING /etc/nsswitch.conf
=================================

So that Glibc can use the db files, you'll need to make appropriate changes
to the /etc/nsswitch.conf file. I won't insult you by recommending any
necessary changes. If you're installing the nss_db package, you should know
how to use it! If you need a refresher, start by looking at the man page for
nsswitch.conf. This reference doesn't explicitly cover the use of db files,
though you should be able to get the drift from the example files given.

The actual files used by nss_db that can be referenced in the nsswitch.conf
file are listed in the Introduction section of this hint. 

============================
6. TESTING THE INSTALLATION:
============================

Testing the installation is simple. Modify any of the /etc/flatfiles and
run the make script to update the db files. Then remove the modifications
from the /etc files and test. You can test by logging into the system as
a user identified only in the db files, or by using a service only identified
in the services.db or protocol.db file.

You can also test using the id and getent programs. The id program has a
man page and getent --help will show you how to use getent.

Alternately, if you've already created the db files and don't wish to add
anything to them, make backup copies and remove a user from /etc/passwd
or an entry in /etc/services, or any other file you've identified in the
/etc/nsswitch.conf file to resolve using nss_db and test.

======================================
7. ALTERNATE METHOD TO POPULATE FILES:
======================================

The procedures up to this point provide a way to duplicate the information
in /etc/flatfiles. You can also use nss_db to resolve information from other
sources. This section deals with using sources other than /etc for the passwd
and group files. 

If your system resolves user and group names using sources other than
/etc/passwd and /etc/group, you can create db files using another method.
This method requires the use of the nss_updatedb package provided by PADL
software.

The instructions for downloading and installing the nss_updatedb package can
be found in my ldap_nameservice.txt hint, right now located at:
http://www.mcmurchy.com/lfs/ldap-nameservice.txt

Note: If you specified a custom directory (other than /var/db) using the
--localstatedir switch to the configure script when you built the nss_db
package, you'll need to install the patch I created for the nss_updatedb
package. By default, the nss_updatedb package creates/updates files in the
/var/db directory. Instructions for downloading and installing the patch are
included in the ldap_nameservice.txt hint.

See the README file included with the nss_updatedb package for instructions
on using the package to create/update the passwd and group db files.

==========================================
8. ISSUES, GOTCHAS AND OTHER SUNDRY ITEMS:
==========================================

None noted.

========
9. TODO:
========

1) Test nss_db using nss_updatedb to create passwd and group files based on
   WINS data.

============
10. CLOSING:
============

During the testing and experimenting with an installation using LDAP and
Kerberos is where my idea of resurrecting nss_db came about. I wanted a way
to have local access to the LDAP user/group information. Because PADL
software already had the nss_updatedb package, all there was for me to do was
figure out how my LFS system could use nss_db. Thanks to the help of the 
folks mentioned below and a little perseverance on my part, nss_db is now
available to LFS users. Enjoy!

ACKNOWLEDGEMENTS:

Luke Howard <lukeh_at_padl_dot_com> for a fix to an nss_db db-open bug
DJ Lucas <dj_at_lucasit_dot_com> for the research and assistance
The folks at Red Hat for continuing to maintain nss_db from where
many of the patches have been acquired.

CHANGELOG:

[2004-06-08]
    * Original draft

[2005-10-27]
    * Updates to fix issues using newer versions of Glibc and Berkeley DB

