nss_wrapper(1)

==============

:revdate: 2015-09-12

NAME

----

nss_wrapper - A wrapper for the user, group and hosts NSS API

SYNOPSIS

--------

LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=/path/to/passwd NSS_WRAPPER_GROUP=/path/to/group NSS_WRAPPER_HOSTS=/path/to/host *./myapplication*

DESCRIPTION

-----------

There are projects which provide daemons needing to be able to create, modify

and delete Unix users. Or just switch user ids to interact with the system e.g.

a user space file server. To be able to test that you need the privilege to

modify the passwd and groups file. With nss_wrapper it is possible to define

your own passwd and groups file which will be used by software to act correctly

while under test.

If you have a client and server under test they normally use functions to

resolve network names to addresses (dns) or vice versa. The nss_wrappers allow

you to create a hosts file to setup 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.

LIMITATIONS

-----------

Some calls in nss_wrapper will only work if uid_wrapper is loaded and active.

One of this functions is initgroups() which needs to run setgroups() to set

the groups for the user. setgroups() is wrapped by uid_wrapper.

ENVIRONMENT VARIABLES

---------------------

*NSS_WRAPPER_PASSWD*::

*NSS_WRAPPER_GROUP*::

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.

*NSS_WRAPPER_HOSTS*::

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

*NSS_WRAPPER_HOSTNAME*::

If you need to return a hostname which is different from the one of your

machine is using you can use: NSS_WRAPPER_HOSTNAME=test.example.org

*NSS_WRAPPER_MODULE_SO_PATH*::

*NSS_WRAPPER_MODULE_FN_PREFIX*::

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/libnss_yourmodule.so. 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>.

For _nss_winbind_getpwnam() this would be:

  NSS_WRAPPER_MODULE_FN_PREFIX=winbind

*NSS_WRAPPER_DEBUGLEVEL*::

If you need to see what is going on in nss_wrapper itself or try to find a

bug, you can enable logging support in nss_wrapper if you built it with

debug symbols.

- 0 = ERROR

- 1 = WARNING

- 2 = DEBUG

- 3 = TRACE

EXAMPLE

-------

  $ 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

  $ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=passwd \

    NSS_WRAPPER_GROUP=group getent passwd bob

  bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false

  $ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_HOSTNAME=test.example.org hostname

  test.example.org