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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
<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 nsss library interface</title>
<meta name="Description" content="nsss: the nsss library interface" />
<meta name="Keywords" content="NSS pwd group shadow library libnsss 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>nsss</tt> library interface </h1>
<h2> General information </h2>
<p>
<tt>libnsss</tt> is the generic name for the nsss client library.
This library is made of several parts:
</p>
<ul>
<li> <a href="nsss-unix.html">nsss-unix</a>: this is a set of
functions to access the <tt>/etc/passwd</tt>, <tt>/etc/group</tt>
and <tt>/etc/shadow</tt> files. </li>
<li> <a href="nsss-switch.html">nsss-switch</a>: this is a set of
functions to connect to a <em>nsssd-service</em> and interact with
various server-side daemons such as
<a href="../nsssd-unix.html">nsssd-unix</a> or
<a href="../nsssd-nslcd.html">nsssd-nslcd</a>. </li>
<li> nsss-all: this is a set of
functions that try connecting to a nsssd service first, and fall
back to the <a href="nsss-unix.html">nsss-unix</a> implementation
if the connection fails (no nsssd service is running). </li>
</p>
<p>
Both <a href="nsss-unix.html">nsss-unix</a> and
<a href="nsss-switch.html">nsss-switch</a> are made of two parts:
</p>
<ul>
<li> An internal, clean API, that applications can use directly
if they include the <tt>nsss/nsss.h</tt> header, or the relevant
<tt>nsss/nsss-unix.h</tt> or <tt>nsss/nsss-switch.h</tt> header. </li>
<li> As a series of thin wrappers around the internal API, an
implementation of the standard following functions:
<ul>
<li> endpwent() </li>
<li> setpwent() </li>
<li> getpwent() </li>
<li> getpwent_r() </li>
<li> getpwuid() </li>
<li> getpwuid_r() </li>
<li> getpwnam() </li>
<li> getpwnam_r() </li>
<li> endgrent() </li>
<li> setgrent() </li>
<li> getgrent() </li>
<li> getgrent_r() </li>
<li> getgrgid() </li>
<li> getgrgid_r() </li>
<li> getgrnam() </li>
<li> getgrnam_r() </li>
<li> endspent() </li>
<li> setspent() </li>
<li> getspent() </li>
<li> getspent_r() </li>
<li> getspnam() </li>
<li> getspnam_r() </li>
</ul> </li>
The functions are prefixed with <tt>nsss_unix_</tt> or
<tt>nsss_switch_</tt>. For instance, <tt>nsss_unix_getpwnam()</tt>
is the implementation of <tt>getpwnam()</tt> that uses the
<tt>/etc/passwd</tt> backend. </li>
</ul>
<p>
nsss-all does not have an internal API. It only contains the
implementation of the above standard functions, as
<tt>nsss_all_getpwnam()</tt> and similar.
</p>
<h2> Compiling </h2>
<p>
Application programs can use the internal API directly, or
the prefixed <tt>nsss_</tt> functions directly. Most programs,
however, will simply use the standard
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pwd.h.html">pwd.h</a>,
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/grp.h.html">grp.h</a> or
<a href="http://man7.org/linux/man-pages/man3/getspnam.3.html">shadow.h</a>
interfaces. nsss provides a version of these standard headers: if an
application is built with these headers, then <tt>getpwnam()</tt>
will automatically be aliased to <tt>nsss_all_getpwnam()</tt>, and
the other functions will be aliased similarly.
</p>
<p>
If the NSSS_DISABLE_SWITCH macro is defined before inclusion of the
nsss headers, then <tt>getpwnam()</tt> will be aliased to
<tt>nsss_unix_getpwnam()</tt> instead, and the other functions will
follow the same pattern. If, instead, the NSSS_DISABLE_UNIX macro
is defined before inclusion of the nsss headers, then <tt>getpwnam()</tt>
will be aliased to <tt>nsss_switch_getpwnam()</tt>, and the other
functions will follow the same pattern.
</p>
<p>
So, the proper steps to compile an application with libnsss are:
</p>
<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 <nsss/nsss.h></tt> </li>
<li> To use the standard <tt>pwd.h</tt> interface, you can
just <tt>#include <pwd.h></tt>, which will work as long
as the <tt>nsss/pwd.h</tt> header is accessible in your header
search path. </li>
<li> Same thing for <tt>grp.h</tt> and <tt>shadow.h</tt>. </li>
<li> If don't want to use the nsss-all implementation of
"try nsss-switch and fall back to nsss-unix if it fails", then
compile with -DNSSS_DISABLE_SWITCH or -DNSSS_DISABLE_UNIX as
desired. </li>
</ul>
<h2> Linking </h2>
<ul>
<li> Make sure the nsss library, as well as the skalibs library,
are visible in your library search path. </li>
<li> Link against <tt>-lnsss</tt>, <tt>-lskarnet</tt>, </li>
<tt>`cat $SYSDEPS/socket.lib`</tt> and
<tt>`cat $SYSDEPS/tainnow.lib`</tt>, $SYSDEPS being your skalibs
sysdeps directory. </li>
</ul>
<h2> Programming </h2>
<ul>
<li> nsss-all, nsss-switch and nsss-unix implement the
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/getpwnam.html">POSIX
layer</a> of user database access, plus a few
<a href="http://man7.org/linux/man-pages/man3/getpwent_r.3.html">GNU extensions</a>. </li>
<li> The <a href="nsss-unix.html">nsss/nsss-unix.h</a> header
can be used to access the internal nsss-unix API. </li>
<li> The <a href="nsss-switch.html">nsss/nsss-switch.h</a> header
can be used to access the internal nsss-switch API. </li>
</ul>
</body>
</html>
|
