Debian Codegraph @

doc/nss_wrapper.1.adoc

raw
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