Title: nss_ndb Version: 1.0.25 Author: Peter Eriksson pen@lysator.liu.se Date: 2021-11-09

DESCRIPTION

This project consists of a NSS module (/usr/lib/nss_ndb.so.1) and a CLI utility (/usr/bin/makendb) that enables big passwd & group files to be handled efficiently via BTree databases stored in /var/db/nss_ndb/.

Enable via the "ndb" keyword in /etc/nsswitch.conf

Currently this project only supports FreeBSD (tested on 11 & 12).

It is currently in production use at a site with about 120 000 users in the passwd database and 2000+ groups (some huge) and effectively handles that.

% /usr/bin/time getent passwd | wc -l 0.63 real 0.36 user 0.26 sys 129272

DOWNLOADS

The source code for this project can be downloaded from:

https://github.com/ptrrkssn/nss_ndb

BUILD

Run the configure script to configure options. By default it will install under /usr/local but for a system install you probably want to use:

./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var

This is so it will be available early on during system boot in case /usr/local is on a filesystem not mounted directly.

You can also enable stripping of "workgroup" (WORKGROUP\name) and "realm" (name@REALM) from names before it looks up data in the database with the options:

--with-realm[=NAME] --with-workgroup[=NAME]

(If NAME is not specified then all realms and/or workgroups will be stripped).

Please note: If you are using this with Samba 4.15.2 and later (and not using nss_winbind) then these options are required!

It can also be configured from a config file if enabled with:

--with-config-file

Configuration options (for debug/test purposes) can also be set from an environment variable (NSS_NDB_CONFIG by default) if enabled via:

--with-config-var[=NAME]

By default it will compile and build using the old BerkeleyDB included in libc, but you may optionally build with DB18 or DB5 using:

--with-db[=yes|no|VER]

Where VER can (currently) be 18 or 5 . In order to find the modern DB versions you probably also need to add paths to where it is installed:

CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"

For example:

./configure --with-db=18 CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"

TESTING

First make sure you have created the database files in /var/db/nss_ndb and populated them with data.

Test before installation:

make USER=some-user-in-the-ndb-database check-ndb

Test the installed binaries (and everything via nsswitch.conf):

make USER=some-user-in-the-ndb-database check

Test with 'valgrind' for memory leaks:

make USER=some-user-in-the-ndb-database check-valgrind

This will use the "nsstest" tool and then run a number of validation tests on the code. To check for memory allocation errors make sure you have the tool 'valgrind' installed. Beware that this takes a bit longer if you have a lot of data in the databases:

USAGE

1. Create the /var/db/nss_ndb directory:

   mkdir /var/db/nss_ndb

2. Populate passwd and groups databases from some source:

   makendb -T passwd /var/db/nss_ndb/passwd </etc/master.passwd makendb -T group /var/db/nss_ndb/group </etc/group

3. Add the "ndb" keyword to /etc/nsswitch.conf, for example like this:

   passwd: files ndb group: files ndb

All done. You can dump the contents of the databases with:

makendb -p path-to-database

You can also use the perl script "ndbsync" to sync the NDB databases with data from an SQL database (mysql) - if you would have such a data source.

NDB DATABASE FORMAT

All tables use UTF-8.

passwd.byname (user:password:uid:gid:class:change:expire:gecos:home:shell\0): Key: annda757 Data: annda757:*:1000000036:100000000::0:0:Ann-Sofi Danielsson:/home/annda757:/bin/sh^@

passwd.byuid (user:password:uid:gid:class:change:expire:gecos:home:shell\0): Key: 1000000036 Data: annda757:*:1000000036:100000000::0:0:Ann-Sofi Danielsson:/home/annda757:/bin/sh^@

group.byname (group:password:gid:user,user,user,...\0): Key: wheel Data: wheel:*:0:root,Lpeter86,Lmikha02,Ljeamo93,fsAdm,Ldavby02^@

group.bygid (group:password:gid:user,user,user,...\0): Key: 0 Data: wheel:*:0:root,Lpeter86,Lmikha02,Ljeamo93,fsAdm,Ldavby02^@

group.byuser (user:gid,gid,gid,...\0): Key (user): peter86 Data: peter86:1003258,100,101,102^@

CONFIGURATION FILE

nss_ndb.conf (if enabled - in $(PREFIX)/etc - see Makefile)

A simple config file like this:

  # A config file for nss_ndb.conf
  debug 0
  workgroup AD
  realm our.realm.com

'workgroup and 'realm' controls if "workgroup" (WORKGROUP\user) and/or Kerberos "realm"
(user@realm) parts of user names and groups are stripped before matching users in the NDB database.
If either is set to '*' then any workgroup or realm found is stripped.

ENVIRONMENT VARIABLE

NSS_NDB_CONFIG (if enabled at build time - se Makefile)

Value is a comma separated list of:

  debug:LEVEL       Sets the debug level
  workgroup:WORKGROUP   Removes the workgroup part for specific workgroups only
  realm:REALM           Removes the realm part for specific realms only