Debian Codegraph @

doc/nss_wrapper.1

raw
1 '\" t
2 .\" Title: nss_wrapper
3 .\" Author: Samba Team
4 .\" Generator: Asciidoctor 2.0.23
5 .\" Date: 2024-07-05
6 .\" Manual: \ \&
7 .\" Source: \ \&
8 .\" Language: English
9 .\"
10 .TH "NSS_WRAPPER" "1" "2024-07-05" "\ \&" "\ \&"
11 .ie \n(.g .ds Aq \(aq
12 .el .ds Aq '
13 .ss \n[.ss] 0
14 .nh
15 .ad l
16 .de URL
17 \fI\\$2\fP <\\$1>\\$3
18 ..
19 .als MTO URL
20 .if \n[.g] \{\
21 . mso www.tmac
22 . am URL
23 . ad l
24 . .
25 . am MTO
26 . ad l
27 . .
28 . LINKSTYLE blue R < >
29 .\}
30 .SH "NAME"
31 nss_wrapper \- A wrapper for the user, group and hosts NSS API
32 .SH "SYNOPSIS"
33 .sp
34 LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=/path/to/passwd NSS_WRAPPER_GROUP=/path/to/group NSS_WRAPPER_HOSTS=/path/to/host \fB./myapplication\fP
35 .SH "DESCRIPTION"
36 .sp
37 There are projects which provide daemons needing to be able to create, modify
38 and delete Unix users. Or just switch user ids to interact with the system e.g.
39 a user space file server. To be able to test that you need the privilege to
40 modify the passwd and groups file. With nss_wrapper it is possible to define
41 your own passwd and groups file which will be used by software to act correctly
42 while under test.
43 .sp
44 If you have a client and server under test they normally use functions to
45 resolve network names to addresses (dns) or vice versa. The nss_wrappers allow
46 you to create a hosts file to setup name resolution for the addresses you use
47 with socket_wrapper.
48 .sp
49 .RS 4
50 .ie n \{\
51 \h'-04'\(bu\h'+03'\c
52 .\}
53 .el \{\
54 . sp -1
55 . IP \(bu 2.3
56 .\}
57 Provides information for user and group accounts.
58 .RE
59 .sp
60 .RS 4
61 .ie n \{\
62 \h'-04'\(bu\h'+03'\c
63 .\}
64 .el \{\
65 . sp -1
66 . IP \(bu 2.3
67 .\}
68 Network name resolution using a hosts file.
69 .RE
70 .sp
71 .RS 4
72 .ie n \{\
73 \h'-04'\(bu\h'+03'\c
74 .\}
75 .el \{\
76 . sp -1
77 . IP \(bu 2.3
78 .\}
79 Loading and testing of NSS modules.
80 .RE
81 .SH "LIMITATIONS"
82 .sp
83 Some calls in nss_wrapper will only work if uid_wrapper is loaded and active.
84 One of this functions is initgroups() which needs to run setgroups() to set
85 the groups for the user. setgroups() is wrapped by uid_wrapper.
86 .SH "ENVIRONMENT VARIABLES"
87 .sp
88 \fBNSS_WRAPPER_PASSWD\fP, \fBNSS_WRAPPER_GROUP\fP
89 .RS 4
90 For user and group accounts you need to create two files: \fIpasswd\fP and \fIgroup\fP.
91 The format of the passwd file we support is:
92 .RE
93 .sp
94 name:password:UID:GID:GECOS:directory:shell
95 .sp
96 The format of the group file we support is:
97 .sp
98 group_name:password:GID:user_list
99 .sp
100 They are also described in \fIman passwd.5\fP and \fIman group.5\fP on Linux. You can
101 fill these files with made up accounts. You point
102 nss_wrapper to them using the two variables
103 NSS_WRAPPER_PASSWD=/path/to/your/passwd and
104 NSS_WRAPPER_GROUP=/path/to/your/group.
105 .sp
106 \fBNSS_WRAPPER_HOSTS\fP
107 .RS 4
108 If you also need to emulate network name resolution in your environment,
109 especially with socket_wrapper, you can write a hosts file. The format is
110 described in \fIman 5 hosts\fP. Then you can point nss_wrapper to your hosts
111 file using: NSS_WRAPPER_HOSTS=/path/to/your/hosts
112 .RE
113 .sp
114 \fBNSS_WRAPPER_HOSTNAME\fP
115 .RS 4
116 If you need to return a hostname which is different from the one of your
117 machine is using you can use: NSS_WRAPPER_HOSTNAME=test.example.org
118 .RE
119 .sp
120 \fBNSS_WRAPPER_MODULE_SO_PATH\fP, \fBNSS_WRAPPER_MODULE_FN_PREFIX\fP
121 .RS 4
122 If you have a project which also provides user and group information out of a
123 database, you normally write your own nss modules. nss_wrapper is able to load
124 nss modules and ask them first before looking into the faked passwd and group
125 file. To point nss_wrapper to the module you can do that using
126 NSS_WRAPPER_MODULE_SO_PATH=/path/to/libnss_yourmodule.so. As each nss module
127 has a special prefix like _nss_winbind_getpwnam() you need to set the prefix
128 too so nss_wrapper can load the functions with
129 NSS_WRAPPER_MODULE_FN_PREFIX=<prefix>.
130 .RE
131 .sp
132 For _nss_winbind_getpwnam() this would be:
133 .sp
134 .if n .RS 4
135 .nf
136 .fam C
137 NSS_WRAPPER_MODULE_FN_PREFIX=winbind
138 .fam
139 .fi
140 .if n .RE
141 .sp
142 \fBNSS_WRAPPER_DEBUGLEVEL\fP
143 .RS 4
144 If you need to see what is going on in nss_wrapper itself or try to find a
145 bug, you can enable logging support in nss_wrapper if you built it with
146 debug symbols.
147 .sp
148 .RS 4
149 .ie n \{\
150 \h'-04'\(bu\h'+03'\c
151 .\}
152 .el \{\
153 . sp -1
154 . IP \(bu 2.3
155 .\}
156 0 = ERROR
157 .RE
158 .sp
159 .RS 4
160 .ie n \{\
161 \h'-04'\(bu\h'+03'\c
162 .\}
163 .el \{\
164 . sp -1
165 . IP \(bu 2.3
166 .\}
167 1 = WARNING
168 .RE
169 .sp
170 .RS 4
171 .ie n \{\
172 \h'-04'\(bu\h'+03'\c
173 .\}
174 .el \{\
175 . sp -1
176 . IP \(bu 2.3
177 .\}
178 2 = DEBUG
179 .RE
180 .sp
181 .RS 4
182 .ie n \{\
183 \h'-04'\(bu\h'+03'\c
184 .\}
185 .el \{\
186 . sp -1
187 . IP \(bu 2.3
188 .\}
189 3 = TRACE
190 .RE
191 .RE
192 .sp
193 \fBNSS_WRAPPER_DISABLE_DEEPBIND\fP
194 .RS 4
195 This allows you to disable deep binding in nss_wrapper. This is useful for
196 running valgrind tools or sanitizers like (address, undefined, thread).
197 .RE
198 .SH "EXAMPLE"
199 .sp
200 .if n .RS 4
201 .nf
202 .fam C
203 $ echo "bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false" > passwd
204 $ echo "root:x:65534:65532:root gecos:/home/test/root:/bin/false" >> passwd
205 $ echo "users:x:1000:" > group
206 $ echo "root:x:65532:" >> group
207 $ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_PASSWD=passwd \(rs
208 NSS_WRAPPER_GROUP=group getent passwd bob
209 bob:x:1000:1000:bob gecos:/home/test/bob:/bin/false
210 $ LD_PRELOAD=libnss_wrapper.so NSS_WRAPPER_HOSTNAME=test.example.org hostname
211 test.example.org
212 .fam
213 .fi
214 .if n .RE
215 .SH "AUTHOR"
216 .sp
217 Samba Team