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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
.TH NSSCACHE.CONF 5 2018-04-22 "nsscache 0.36" "File formats"
.SH NAME
nsscache.conf - NSS local cache synchroniser configuration file
.SH SYNOPSIS
.B /etc/nsscache.conf
.SH DESCRIPTION
.B nsscache
synchronises a local NSS cache, and other databases, against a remote
data source. This approach allows the administrator to separate the
network from the NSS lookup codepath, improving speed and reliability
of name services.
The nsscache configuration file comprises of one DEFAULT section,
followed by zero or more map-specific configuration sections. The
file format is similar to that of ".ini" files.
The DEFAULT section must provide at least one
\fBsource\fP
keyword, specifying the data source to use, one
\fBcache\fP
keyword, specifying the means in which the cache data will be stored
locally, one
\fBmaps\fP
keyword, specifying which NSS maps should be cached, and one
\fBtimestamp_dir\fP
keyword, specifying the location of the timestamps used for
incremental updates.
Additional global defaults, such as LDAP search parameters, or the
filesystem location of the cache, may also be included in the DEFAULT
section.
Additional sections may be included that allow per-map overrides to
configuration options. For example, one might specify their global
LDAP search base as
\fBou=People\fP
but want to override that for the
\fIgroup\fP
mapping as
\fBou=Groups\fP
Apart from the \fIsource\fP, \fIcache\fP, and \fImaps\fP configuration
options, all options are prefixed by the name of the module that they
configure.
A complete list of configuration options follows.
.SH DEFAULT-only OPTIONS
.TP
\fBsource\fP
Specifies the source to use to retrieve NSS data from.
Valid Options:
.I ldap
.TP
.B cache
Specifies the cache method to use to store the data, which will be
queried by the NSS itself.
Valid options:
.I files
Store in a plain text file, similar in format to
.I /etc/passwd.
If the files-module option
.I files_cache_filename_suffix
is also set to
.B cache
then not only will the files be created with a \fB.cache\fP suffix, but also an index file will be written alongside, for use with the
.I nss-cache
NSS module. (See https://github.com/google/libnss-cache.)
.I nssdb
Store in a Berkeley DB file, for use with the
.I nss_db
NSS module. Please note that this option is deprecated in favour of
.I cache
.TP
.B maps
Specifies the names of the maps that will be queried and cached by
.I nsscache
Valid options:
.I passwd
.I group
.I shadow
.I netgroup
.I automount
.I sshkey
.TP
.B timestamp_dir
Specifies the directory where update and modify timestamps are stored.
.SH ldap SOURCE OPTIONS
These options configure the behaviour of the
.I ldap
source.
.TP
.B ldap_uri
The LDAP URI to connect to.
.TP
.B ldap_base
The base to perform LDAP searches under.
.TP
.B ldap_filter
The search filter to use when querying.
.TP
.B ldap_scope
The search scope to use. Defaults to
.I one
Valid options:
.I sub[tree]
.I one[level]
.I base
.TP
.B ldap_bind_dn
The bind DN to use when connecting to LDAP. Empty string is an
anonymous bind. Defaults to the empty string.
.TP
.B ldap_bind_password
The bind password to use when connecting to LDAP. Empty string is
used for anonymous binds. Defaults to the empty string.
.TP
.B ldap_timelimit
Timelimit in seconds for search results to return. \-1 means no limit.
Defaults to \-1.
.TP
.B ldap_retry_max
Number of retries on soft failures before giving up. Defaults to 3.
.TP
.B ldap_retry_delay
Delay in seconds between retries. Defaults to 5.
.TP
.B ldap_tls_require_cert
Sets expectations for SSL certificates, using TLS. One
of 'never', 'hard', 'demand', 'allow', or 'try' ('demand'
is the default). See \fBldap.conf\fP(5) for more information.
.TP
.B ldap_tls_cacertdir
Directory for trusted CA certificates. By default, the system's
default CA certificate directory will be used.
.TP
.B ldap_tls_cacertfile
Filename containing trusted CA certificates.
.TP
.B ldap_tls_certfile
Filename of an optional LDAP client certificate. If specified,
\fBldap_tls_keyfile\fP must also be specified.
.TP
.B ldap_tls_keyfile
Filename of an optional LDAP client key. Only plaintext (unencrypted) keys are
currently supported. If specified, \fBldap_tls_certfile\fP must also be
specified.
.TP
.B ldap_tls_starttls
Set to 1 to enable STARTTLS. Leave absent to disable.
.TP
.B ldap_uidattr
The uid-like attribute in your directory. Defaults to uid.
.TP
.B ldap_uidregex
A Python regex to extract uid components from the uid-like attribute.
All matching groups are concatenated without spaces.
For example: '(.*)@example.com' would return a uid to the left of
the @example.com domain. Default is no regex.
.TP
.B ldap_groupregex
A Python regex to extract group member components from the member or
memberOf attributes. All matching groups are concatenated without spaces.
For example: '(.*)@example.com' would return a member without the
the @example.com domain. Default is no regex.
.TP
.B ldap_override_shell
If specified, set every user's login shell to the given one. May be
useful on bastion hosts or to ensure uniformity.
.TP
.B ldap_rfc2307bis
Default uses rfc2307 schema. If rfc2307bis (groups stored as a list of DNs
in 'member' attr), set this to 1.
.TP
.B ldap_debug
Sets the debug level for the underlying C library. Defaults to no logging.
.SH nssdb CACHE OPTIONS
These options configure the behaviour of the
.I nssdb
cache.
.TP
.B nssdb_dir
Directory to store the Berkeley DB databases. Defaults to the current
directory. Note that
.B nss_db
hardcodes the path to
.I /var/lib/misc
on Debian systems, and
.I /var/db
on Red Hat systems.
.TP
.B nssdb_makedb
Path to the \fBmakedb\fP(1) command, which is used by the nssdb cache code
to ensure that the Berkeley DB version created by the module matches
that expected by the \fBnss_db\fP NSS module.
.SH files CACHE OPTIONS
These optiosn configure the behaviour of the
.I files
cache.
.TP
.B files_dir
Directory location to store the plain text files in. Defaults to the
current directory.
.TP
.B files_cache_filename_suffix
A suffix appended to the cache filename to differentiate it from, say,
system NSS databases. Defaults to '.cache'.
.TP
.B files_local_automount_master
A yes/no field only used for automount maps. A 'yes' value will cause nsscache
to update the auto.master file with the master map from the source. A 'no'
value will cause nsscache to leave auto.master alone, allowing the system to
manage this file in other ways. When set to 'no', nsscache will only update
other automount maps defined both locally and in the source. Defaults to 'yes'.
.TP
.B prefix
A regular expression to capture a prefix, or mount point.
.TP
.B suffix
A regular expression to modify the prefix.
.SH EXAMPLE
A typical example might look like this:
[DEFAULT]
source = ldap
cache = nssdb
maps = passwd, group, shadow
ldap_uri = ldap://ldap.example.com
ldap_base = ou=People,dc=example,dc=com
ldap_filter = (objectclass=posixAccount)
nssdb_dir = /var/lib/misc
[group]
ldap_base = ou=Group,dc=example,dc=com
ldap_filter = (objectclass=posixGroup)
[shadow]
ldap_filter = (objectclass=posixAccount)
And a complementary \fI\|/etc/nsswitch.conf\|\fP might look like this:
passwd: files db
group: files db
shadow: files db
.SH FILES
.TP
\fI\|/etc/nsscache.conf\|\fP
The system-wide nsscache configuration file
.SH "SEE ALSO"
.TP
\fInsscache\fP(1)
.TP
\fInsswitch.conf\fP(5)
The system name service switch configuration file
.TP
\fIldap.conf\fP(5)
Details on LDAP configuration options exposed by the LDAP client libraries.
.SH AUTHOR
Written by Jamie Wilkinson (jaq@google.com) and Vasilios Hoffman (vasilios@google.com).
.TP
The source code lives at https://github.com/google/nsscache
.SH COPYRIGHT
Copyright \(co 2007 Google, Inc.
.br
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.