1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>nsss: the nsssd library interface</title>
<meta name="Description" content="nsss: the nsssd library interface" />
<meta name="Keywords" content="NSS pwd group shadow library backend nsssd daemon libnsssd skarnet" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="../">nsss</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>nsssd</tt> library interface </h1>
<h2> General information </h2>
<p>
<tt>libnsssd</tt> is a library that can be used by external applications
to implement extra nsss backends, in the style of
<a href="../nsssd-unix.html">nsssd-unix</a> and
<a href="../nsssd-nslcd.html">nsssd-nslcd</a>, without learning the
details of the nsss protocol or having to perform IO themselves.
</p>
<h2> Compiling </h2>
<ul>
<li> Make sure the nsss headers, as well as the skalibs headers,
are visible in your header search path. </li>
<li> Use <tt>#include <skalibs/strerr2.h></tt> and
<tt>#include <nsss/nsssd.h></tt> </li>
</ul>
<h2> Linking </h2>
<ul>
<li> Make sure the nsssd library, as well as the skalibs library,
are visible in your library search path. </li>
<li> Link against <tt>-lnsssd</tt>, <tt>-lskarnet</tt>, </li>
<tt>`cat $SYSDEPS/socket.lib`</tt> and
<tt>`cat $SYSDEPS/sysclock.lib`</tt>, $SYSDEPS being your skalibs
sysdeps directory. </li>
</ul>
<h2> Programming </h2>
<ul>
<li> In your <tt>main()</tt> function, start with assigning
the name of your program to the PROG variable. Example:
<tt>PROG = "nsssd-foobar";</tt> </li>
<li> Your <tt>main()</tt> function can parse options and
take command line arguments as it sees fit. But once it's done
parsing options, give control to the <tt>nsssd_main()</tt>
function, using your <em>argv</em> and <em>envp</em> as
arguments: <tt>return nsssd_main(argv, envp);</tt> </li>
</ul>
<p>
The rest of your program should implement the functions needed by
<tt>nsssd_main()</tt>. Here is what those functions are:
</p>
<h4><code>void *nsssd_handle_init (void)</code></h4>
<p>
This function must return a pointer to an <em>uninitialized</em>
handle. The handle can be whatever you need to implement your
backend; the pointer to your handle will be passed to every
subsequent function. The function must not return NULL.
</p>
<h4><code>int nsssd_handle_start (void *handle, char const *const *argv, char const *const *envp)</code></h4>
<p>
This function must <em>initialize the handle</em>. The arguments
it receives are the <em>argv</em> and <em>envp</em> that have been
passed to <tt>nsssd_main()</tt>. This allows you to write daemons
that can be somewhat configured via the command line: it is how
<a href="../nsssd-nslcd.html">nsssd-nslcd</a> takes an argument
telling it where the nslcd socket is, and uses that argument in
its own <tt>nsssd_handle_start</tt> to actually connect to the
nslcd daemon. <br />
The function must return nonzero if it succeeds, and 0 if it
fails, setting errno appropriately.
</p>
<h4><code>void nsssd_handle_end (void *handle)</code></h4>
<p>
This function must deinitialize the handle and free all
related resources: close connections to external processes, etc.
</p>
<h4><code>int nsssd_pwd_start (void *handle)</code></h4>
<p>
This function will be called at the start of a passwd enumeration.
It must return nonzero on success and 0 on error.
</p>
<h4><code>int nsssd_pwd_rewind (void *handle)</code></h4>
<p>
This function will be called on a <em>setpwent()</em> call.
It must rewind the current enumeration to the start of the
database.
It must return nonzero on success and 0 on error.
</p>
<h4><code>int nsssd_pwd_get (void *handle, struct passwd *pw)</code></h4>
<p>
This function will be called on every <em>getpwent()</em> call, i.e.
on every iteration of an enumeration. On error, it must return 0; on
success, it must return nonzero and store the obtained passwd structure
into <em>*pw</em>.
</p>
<h4><code>void nsssd_pwd_end (void *handle)</code></h4>
<p>
This function will be called at the end of a passwd enumeration.
</p>
<h4><code>int nsssd_pwd_getbyuid (void *handle, struct passwd *pw, uid_t uid)</code></h4>
<p>
This function must implement a <em>getpwuid(uid)</em> call. On error, it must
return 0; on success, it must return nonzero and store the result into
<em>*pw</em>.
</p>
<h4><code>int nsssd_pwd_getbyname (void *handle, struct passwd *pw, char const *name)</code></h4>
<p>
This function must implement a <em>getpwnam(name)</em> call. On error, it must
return 0; on success, it must return nonzero and store the result into
<em>*pw</em>.
</p>
<p>
Similar functions for the group and shadow databases must also be implemented.
The full list can be found in the
<a href="//git.skarnet.org/cgi-bin/cgit.cgi/nsss/tree/src/include/nsss/nsssd.h">nsss/nsssd.h</a> header.
</p>
</body>
</html>
|
