| 1 |
nss_wrapper(1) |
| 2 |
============== |
| 3 |
:revdate: 2019-05-21 |
| 4 |
:author: Samba Team |
| 5 |
|
| 6 |
NAME |
| 7 |
---- |
| 8 |
|
| 9 |
nss_wrapper - A wrapper for the user, group and hosts NSS API |
| 10 |
|
| 11 |
SYNOPSIS |
| 12 |
-------- |
| 13 |
|
| 14 |
LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=/path/to/passwd NSS_WRAPPER_GROUP=/path/to/group NSS_WRAPPER_HOSTS=/path/to/host *./myapplication* |
| 15 |
|
| 16 |
DESCRIPTION |
| 17 |
----------- |
| 18 |
|
| 19 |
There are projects which provide daemons needing to be able to create, modify |
| 20 |
and delete Unix users. Or just switch user ids to interact with the system e.g. |
| 21 |
a user space file server. To be able to test that you need the privilege to |
| 22 |
modify the passwd and groups file. With nss_wrapper it is possible to define |
| 23 |
your own passwd and groups file which will be used by software to act correctly |
| 24 |
while under test. |
| 25 |
|
| 26 |
If you have a client and server under test they normally use functions to |
| 27 |
resolve network names to addresses (dns) or vice versa. The nss_wrappers allow |
| 28 |
you to create a hosts file to setup name resolution for the addresses you use |
| 29 |
with socket_wrapper. |
| 30 |
|
| 31 |
- Provides information for user and group accounts. |
| 32 |
- Network name resolution using a hosts file. |
| 33 |
- Loading and testing of NSS modules. |
| 34 |
|
| 35 |
LIMITATIONS |
| 36 |
----------- |
| 37 |
|
| 38 |
Some calls in nss_wrapper will only work if uid_wrapper is loaded and active. |
| 39 |
One of this functions is initgroups() which needs to run setgroups() to set |
| 40 |
the groups for the user. setgroups() is wrapped by uid_wrapper. |
| 41 |
|
| 42 |
ENVIRONMENT VARIABLES |
| 43 |
--------------------- |
| 44 |
|
| 45 |
*NSS_WRAPPER_PASSWD*:: |
| 46 |
*NSS_WRAPPER_GROUP*:: |
| 47 |
|
| 48 |
For user and group accounts you need to create two files: 'passwd' and 'group'. |
| 49 |
The format of the passwd file we support is: |
| 50 |
|
| 51 |
name:password:UID:GID:GECOS:directory:shell |
| 52 |
|
| 53 |
The format of the group file we support is: |
| 54 |
|
| 55 |
group_name:password:GID:user_list |
| 56 |
|
| 57 |
They are also described in 'man passwd.5' and 'man group.5' on Linux. You can |
| 58 |
fill these files with made up accounts. You point |
| 59 |
nss_wrapper to them using the two variables |
| 60 |
NSS_WRAPPER_PASSWD=/path/to/your/passwd and |
| 61 |
NSS_WRAPPER_GROUP=/path/to/your/group. |
| 62 |
|
| 63 |
*NSS_WRAPPER_HOSTS*:: |
| 64 |
|
| 65 |
If you also need to emulate network name resolution in your environment, |
| 66 |
especially with socket_wrapper, you can write a hosts file. The format is |
| 67 |
described in 'man 5 hosts'. Then you can point nss_wrapper to your hosts |
| 68 |
file using: NSS_WRAPPER_HOSTS=/path/to/your/hosts |
| 69 |
|
| 70 |
*NSS_WRAPPER_HOSTNAME*:: |
| 71 |
|
| 72 |
If you need to return a hostname which is different from the one of your |
| 73 |
machine is using you can use: NSS_WRAPPER_HOSTNAME=test.example.org |
| 74 |
|
| 75 |
*NSS_WRAPPER_MODULE_SO_PATH*:: |
| 76 |
*NSS_WRAPPER_MODULE_FN_PREFIX*:: |
| 77 |
|
| 78 |
If you have a project which also provides user and group information out of a |
| 79 |
database, you normally write your own nss modules. nss_wrapper is able to load |
| 80 |
nss modules and ask them first before looking into the faked passwd and group |
| 81 |
file. To point nss_wrapper to the module you can do that using |
| 82 |
NSS_WRAPPER_MODULE_SO_PATH=/path/to/libnss_yourmodule.so. As each nss module |
| 83 |
has a special prefix like _nss_winbind_getpwnam() you need to set the prefix |
| 84 |
too so nss_wrapper can load the functions with |
| 85 |
NSS_WRAPPER_MODULE_FN_PREFIX=<prefix>. |
| 86 |
|
| 87 |
For _nss_winbind_getpwnam() this would be: |
| 88 |
|
| 89 |
NSS_WRAPPER_MODULE_FN_PREFIX=winbind |
| 90 |
|
| 91 |
*NSS_WRAPPER_DEBUGLEVEL*:: |
| 92 |
|
| 93 |
If you need to see what is going on in nss_wrapper itself or try to find a |
| 94 |
bug, you can enable logging support in nss_wrapper if you built it with |
| 95 |
debug symbols. |
| 96 |
|
| 97 |
- 0 = ERROR |
| 98 |
- 1 = WARNING |
| 99 |
- 2 = DEBUG |
| 100 |
- 3 = TRACE |
| 101 |
|
| 102 |
*NSS_WRAPPER_DISABLE_DEEPBIND*:: |
| 103 |
|
| 104 |
This allows you to disable deep binding in nss_wrapper. This is useful for |
| 105 |
running valgrind tools or sanitizers like (address, undefined, thread). |
| 106 |
|
| 107 |
EXAMPLE |
| 108 |
------- |
| 109 |
|
| 110 |
$ echo "bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false" > passwd |
| 111 |
$ echo "root:x:65534:65532:root gecos:/home/test/root:/bin/false" >> passwd |
| 112 |
$ echo "users:x:1000:" > group |
| 113 |
$ echo "root:x:65532:" >> group |
| 114 |
$ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=passwd \ |
| 115 |
NSS_WRAPPER_GROUP=group getent passwd bob |
| 116 |
bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false |
| 117 |
$ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_HOSTNAME=test.example.org hostname |
| 118 |
test.example.org |