nss_exec

This is an extremely basic Name Service Switch module that will execute an arbitrary command so you can extend NSS easier with your amazing scripting abilities. It is the natural partner to pam_exec, allowing complete and scripted control over the low level configuration in your system..

What can you do with this plugin?

• Mimic libnss-ato, where all users will map to one. See the examples.
• Add additional logging.
• Simulate that a user exists.

Caching for More Speed

It is highly recommended that you run nscd or unscd (both are name service caching daemons) to avoid calling the script frequently.

When debugging, make sure to not run the caching daemon because they can mask problems by serving entries in the cache.

Compiling and Installation

There are virtually no external dependencies that are required. The only thing that might be needed is pthreads. Just cd into the libnss_http directory and run:

# This builds the library
make

# Build the test tool as well
make nss_exec_test

Now you should write a script that handles the various calls your mechanism supports. After you get the script written and installed as /sbin/nss_exec then you can install this library.

# This installs it to the system
sudo make install

Now update /etc/nsswitch.conf and add exec to the bits you support. In this example we want the nss_exec to be called for passwd, group and shadow entries.

passwd:         exec compat
group:          exec compat
shadow:         exec compat

Scripting and Debugging

The lookup script lives at /sbin/nss_exec and gets one or two parameters:

# This is with only one parameter.
# This call resets the passwd counter.
/sbin/nss_exec setpwent

# Here is a sample call with two parameters.
# Gets the first passwd entry.
/sbin/nss_exec getpwent 1

To help create and debug your script you should build nss_test

# Build the test tool - this is built automatically with the library
make

# Run the test tool
nss_exec_test

The test tool will run ./nss_exec (the nss_exec script in the current working directory) so you can work on a copy of the script and later move it to /sbin/nss_exec once it is fully tested.

The test tool lets you simulate calls to the script. For example, you can see what is returned by a getpwnam() call by running this command:

./nss_exec_test getpwnam username_goes_here

SELinux

If things are not working with sshd or other services, double check your SELinux rules. They can mess things up without giving you any diagnostic information in log files.

NSS Function Signatures

It is difficult to find a list of all functions that NSS calls. This list was generated by looking at the exported functions of all of the standard nss modules installed on an Ubuntu 15.04 system. If this list is incomplete, please help me fill it in.

Not all functions are enabled in this library. The most common use cases for the module are for users and passwords. It is not hard to add support for more NSS modules. Pull requests welcome, as would be any positive feedback asking for additional modules to be added.

Replace XXX with your NSS module name.

• group
  • nss_status _nss_XXX_endgrent(void)
  • nss_status _nss_XXX_getgrent_r(struct group *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_getgrgid_r(gid_t gid, struct group *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_getgrnam_r(const char *name, struct group *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_setgrent(int stay_open)
• passwd
  • nss_status _nss_XXX_endpwent(void)
  • nss_status _nss_XXX_getpwent_r(struct passwd *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_getpwnam_r(const char *name, struct passwd *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_getpwuid_r(uid_t uid, struct passwd *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_setpwent(int stay_open)
• shadow
  • nss_status _nss_XXX_endspent(void)
  • nss_status _nss_XXX_getspent_r(struct spwd *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_getspnam_r(const char *name, struct spwd *result, char *buffer, size_t buffer_length, int *errnop)
  • nss_status _nss_XXX_setspent(int stay_open)
• Currently unsupported functions from various modules
  • nss_status _nss_XXX_endaliasent(?)
  • nss_status _nss_XXX_endetherent(?)
  • nss_status _nss_XXX_endhostent(?)
  • nss_status _nss_XXX_endnetent(?)
  • nss_status _nss_XXX_endnetgrent(?)
  • nss_status _nss_XXX_endprotoent(?)
  • nss_status _nss_XXX_endrpcent(?)
  • nss_status _nss_XXX_endservent(?)
  • nss_status _nss_XXX_endsgent(?)
  • nss_status _nss_XXX_getaliasbyname_r(?)
  • nss_status _nss_XXX_getaliasent_r(?)
  • nss_status _nss_XXX_getcanonname_r(?)
  • nss_status _nss_XXX_getetherent_r(?)
  • nss_status _nss_XXX_gethostbyaddr2_r(?)
  • nss_status _nss_XXX_gethostbyaddr_r(?)
  • nss_status _nss_XXX_gethostbyname2_r(?)
  • nss_status _nss_XXX_gethostbyname3_r(?)
  • nss_status _nss_XXX_gethostbyname4_r(?)
  • nss_status _nss_XXX_gethostbyname_r(?)
  • nss_status _nss_XXX_gethostent_r(?)
  • nss_status _nss_XXX_gethostton_r(?)
  • nss_status _nss_XXX_getnetbyaddr_r(?)
  • nss_status _nss_XXX_getnetbyname_r(?)
  • nss_status _nss_XXX_getnetent_r(?)
  • nss_status _nss_XXX_getnetgrent_r(?)
  • nss_status _nss_XXX_getntohost_r(?)
  • nss_status _nss_XXX_getprotobyname_r(?)
  • nss_status _nss_XXX_getprotobynumber_r(?)
  • nss_status _nss_XXX_getprotoent_r(?)
  • nss_status _nss_XXX_getpublickey(?)
  • nss_status _nss_XXX_getrpcbyname_r(?)
  • nss_status _nss_XXX_getrpcbynumber_r(?)
  • nss_status _nss_XXX_getrpcent_r(?)
  • nss_status _nss_XXX_getsecretkey(?)
  • nss_status _nss_XXX_getservbyname_r(?)
  • nss_status _nss_XXX_getservbyport_r(?)
  • nss_status _nss_XXX_getservent_r(?)
  • nss_status _nss_XXX_getsgent_r(?)
  • nss_status _nss_XXX_getsgnam_r(?)
  • nss_status _nss_XXX_init(?)
  • nss_status _nss_XXX_initgroups_dyn(?)
  • nss_status _nss_XXX_minimal_gethostbyaddr_r(?)
  • nss_status _nss_XXX_minimal_gethostbyname2_r(?)
  • nss_status _nss_XXX_minimal_gethostbyname_r(?)
  • nss_status _nss_XXX_netname2user(?)
  • nss_status _nss_XXX_parse_etherent(?)
  • nss_status _nss_XXX_parseline(?)
  • nss_status _nss_XXX_parse_netent(?)
  • nss_status _nss_XXX_parse_protoent(?)
  • nss_status _nss_XXX_parse_rpcent(?)
  • nss_status _nss_XXX_parse_servent(?)
  • nss_status _nss_XXX_setaliasent(?)
  • nss_status _nss_XXX_setetherent(?)
  • nss_status _nss_XXX_sethostent(?)
  • nss_status _nss_XXX_setnetent(?)
  • nss_status _nss_XXX_setnetgrent(?)
  • nss_status _nss_XXX_setprotoent(?)
  • nss_status _nss_XXX_setrpcent(?)
  • nss_status _nss_XXX_setservent(?)
  • nss_status _nss_XXX_setsgent(?)

NSS Function Meaning

The set*ent(), get*ent() and end*ent() functions are for enumarating through the list. First, set*ent() is called to reset the list pointer to the top. Next, get*ent() is called repeatedly. If you run out of entries early, get*ent() returns NSS_STATUS_NOTFOUND. When done, end*ent() is called.

NSS Function Return Codes

The shell function's return codes are remapped to ones that NSS understands.

Shell return code	NSS Name	NSS Value
0	NSS_STATUS_SUCCESS	1
1	NSS_STATUS_NOTFOUND	0
2	NSS_STATUS_TRYAGAIN	-2
3 (and anything else)	NSS_STATUS_UNAVAIL	-1

NSS_STATUS_RETURN (2) is only supposed to be used internally and so this library does not have a mapping for it.

The above return codes are not applied for the getXXent functions. Any error code returned will get mapped to ENOENT (2) and most likely the caller will next call endXXent to finish listing the entries.

Credits

Many thanks to libnss_http for the beginnings of this project.

Development Information

Patches should match the existing coding style. Any warnings while building should be cleaned up. If adding support for a new function call, make sure to also add it to nss_exec_test. Add new test or fix existing ones. Ensure make test runs these tests properly.

This project is licensed under an MIT License.