Title:	 nss_ndb
Version: 1.0.25
Author:  Peter Eriksson <[email protected]>
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