The nss_wrapper library

A wrapper for the user, group and hosts NSS API

Clone with git · Report a bug

There are projects that need to be able to create, modify, and delete Unix users. Others just switch user IDs to interact with the system on behalf of another user (e.g. a user space file server). To be able to test applications like these, you need to grant privileges to modify the passwd and group files. With nss_wrapper it is possible to define your own passwd and group files to be used the software while it is under test. The nss_wrapper also allows you to create a hosts file to set up name resolution for the addresses you use with socket_wrapper.


  • Provides information for user and group accounts.
  • Network name resolution using a hosts file.
  • Loading and testing of NSS modules.

Detailed descriptions

  • The user, group, and hosts functionality are all defined as wrappers around the Name Service Switch (NSS) API.
  • For user and group accounts you need to create two files: 'passwd' and 'group'. The format of the passwd file is described in man 5 passwd and the group file in man 5 group. So you can fill these files with made up accounts. You point nss_wrapper to them using the two variables NSS_WRAPPER_PASSWD=/path/to/your/passwd and NSS_WRAPPER_GROUP=/path/to/your/group.
  • If you also need to emulate network name resolution in your enviornment, especially with socket_wrapper, you can write a hosts file. The format is described in man 5 hosts. Then you can point nss_wrapper to your hosts file using: NSS_WRAPPER_HOSTS=/path/to/your/hosts
  • If you need to return a hostname which is different from the one of your machine is using you can use:
  • If you have a project which also provides user and group information out of a database, you normally write your own nss modules. nss_wrapper is able to load nss modules and ask them first before looking into the faked passwd and group file. To point nss_wrapper to the module you can do that using NSS_WRAPPER_MODULE_SO_PATH=/path/to/ As each nss module has a special prefix like _nss_winbind_getpwnam() you need to set the prefix too so nss_wrapper can load the functions with NSS_WRAPPER_MODULE_FN_PREFIX=<prefix>.


$ echo "bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false" > passwd
$ echo "root:x:65534:65532:root gecos:/home/test/root:/bin/false" >> passwd
$ echo "users:x:1000:" > group
$ echo "root:x:65532:" >> group
NSS_WRAPPER_GROUP=group getent passwd bob
bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false
$ hostname
$ echo "fd00::5357:5faa" > hosts
$ echo "" >> hosts
# Now query ahostsv6 which returns only IPv6 addresses and
# calls getaddrinfo() for each the entry.
getent ahostsv6
fd00::5357:5faa DGRAM
fd00::5357:5faa STREAM