1nss_ldap(5) File Formats Manual nss_ldap(5)
2
6 nss_ldap - LDAP nameservice provider
7
9 The nss_ldap module is a set of C library extensions which allows X.500
10 and LDAP directory servers to be used as a primary source of name ser‐
11 vice information. (Name service information typically includes users,
12 hosts, groups, and other such data historically stored in flat files or
13 NIS.)
14 Features of the PADL nss_ldap module include support for both the RFC
16 2307 and RFC 2307bis schema, a common implementation across multiple
17 platforms, Kerberos and SSL security, configurable schema mapping, and
18 configuration file compatibility with the pam_ldap(5) module.
19 Because LDAP is a hierarchical directory service, one can distribute
21 the information in a manner which reflects organizational structure.
22 This contrasts with the flat, single domain policy of NIS. LDAP has
23 many of the advantages of NIS+ (security and scalability) without the
24 complexity.
25 nss_ldap will work alongside existing NIS, NIS+, DNS and flat file name
27 services. More importantly, because it builds as a shared library, it
28 is not necessary to recompile any applications to take advantage of
29 LDAP.
30 The present version of nss_ldap supports AIX 4.3.3 and above, FreeBSD
32 5.1, HP-UX 11i, Linux and Solaris 2.6 and above. Many vendors provide
33 their own LDAP nameservice providers, often also called nss_ldap. This
34 manual page applies to the PADL nss_ldap module only. If you are using
35 a vendor provided module, consult the relevant documentation instead.
36 The features supported by the version of nss_ldap depend on which flags
38 were enabled when the software was built. Most features are enabled in
39 the configuration file, described below. (The location of the configu‐
40 ration file is configurable at compile time; the default path is
41 /etc/ldap.conf.) Also, some features may be unavailable on certain
42 operating systems or with certain LDAP libraries. For more information,
43 consult your vendor.
44
46 nss_ldap stores its configuration in the ldap.conf file, the location
47 of which is configurable at compile time. (It should be noted that
48 some LDAP client libraries, such as OpenLDAP, also use a configuration
49 file of the same name. nss_ldap supports many of the same configura‐
50 tion file options as OpenLDAP, but it adds several that are specific to
51 the functionality it provides. Additionally, it is not guaranteed that
52 nss_ldap will continue to match the configuration file semantics of
53 OpenLDAP. You may wish to use different files.)
54 Configuration file options consist of a keyword followed by a space and
56 any arguments. The following options are supported by both nss_ldap and
57 the PADL pam_ldap module:
58 host <name:port ...>
60 Specifies the name(s) or IP address(es) of the LDAP server(s) to
61 connect to. In the case that nss_ldap is used for host name res‐
62 olution, each server should be specified as an IP address or
63 name that can be resolved without using LDAP. Multiple servers
64 may be specified, each separated by a space. The failover time
65 depends on whether the LDAP client library supports configurable
66 network or connect timeouts (see bind_timelimit below).
67 base <base>
69 Specifies the default base distinguished name (DN) to use for
70 searches.
71 uri <ldap[is]://[name[:port]] ...>
73 For LDAP client libraries that support it, specifies the URI(s)
74 of the LDAP server(s) to connect to. The URI scheme may be ldap,
75 ldapi, or ldaps, specifying LDAP over TCP, IPC and SSL respec‐
76 tively. If applicable, a port number can be specified; the
77 default port number for the selected protocol is used if omit‐
78 ted. This option takes precedence over the host option; it is
79 not possible to combine the two.
80 ldap_version <version>
82 Specifies the version of the LDAP protocol to use. Presently
83 version must be 2 or 3. The default is to use the maximum ver‐
84 sion supported by the client library.
85 binddn <binddn>
87 Specifies the distinguished name with which to bind to the
88 directory server(s). This option is optional; the default is to
89 bind anonymously.
90 bindpw <bindpw>
92 Specifies the cleartext credentials with which to bind. This
93 option is only applicable when used with binddn above. The
94 default is no credential (anonymous bind). When binding to the
95 directory using SASL or other authentication mechanisms apart
96 from simple binds, this option is not used.
97 rootbinddn <binddn>
99 This option has the same syntax and effect as the binddn option
100 above, except it applies when the effective user ID is zero. If
101 not specified, then the identity specified in binddn is used
102 instead. Because the configuration file may be readable by many
103 users, the root bind DN credentials are stored in the
104 ldap.secret file instead. This file is usually in the same
105 directory as the configuration file.
106 port <port>
108 Specifies the port to connect to; this option is used with the
109 host option, and is ignored with the uri option.
110 scope <sub|one|base>
112 Specifies the search scope (subtree, one level or base object).
113 The default scope is subtree; base scope is almost never useful
114 for nameservice lookups.
115 deref <never|searching|finding|always>
117 Specifies the policy for dereferencing aliases. The default pol‐
118 icy is to never dereference aliases.
119 timelimit <timelimit>
121 Specifies the time limit (in seconds) to use when performing
122 searches. A value of zero (0), which is the default, is to wait
123 indefinitely for searches to be completed.
124 bind_timelimit <timelimit>
126 Specifies the time limit (in seconds) to use when connecting to
127 the directory server. This is distinct from the time limit spec‐
128 ified in timelimit and affects the initial server connection
129 only. (Server connections are otherwise cached.) Only some LDAP
130 client libraries have the underlying functionality necessary to
131 support this option. The default bind timelimit is 30 seconds.
132 referrals <yes|no>
134 Specifies whether automatic referral chasing should be enabled.
135 The default behaviour is specifed by the LDAP client library.
136 restart <yes|no>
138 Specifies whether the LDAP client library should restart the
139 select(2) system call when interrupted. This feature is not sup‐
140 ported by all client libraries.
141 logdir <directory>
143 Specifies the directory used for logging by the LDAP client
144 library. This feature is not supported by all client libraries.
145 debug <level>
147 Specifies the debug level used for logging by the LDAP client
148 library. This feature is not supported by all client libraries,
149 and does not apply to the nss_ldap and pam_ldap modules them‐
150 selves (debugging, if any, is configured separately and usually
151 at compile time).
152 ssl <on|off|start_tls>
154 Specifies whether to use SSL/TLS or not (the default is not to).
155 If start_tls is specified then StartTLS is used rather than raw
156 LDAP over SSL. Not all LDAP client libraries support both SSL
157 and StartTLS, and all related configuration options.
158 sslpath <cert7_path>
160 For the Netscape and Mozilla LDAP client libraries only, this
161 specifies the path to the X.509 certificate database.
162 tls_checkpeer <yes|no>
164 Specifies whether to require and verify the server certificate
165 or not, when using SSL/TLS with the OpenLDAP client library.
166 The default is to use the default behaviour of the client
167 library; for OpenLDAP 2.0 and earlier it is "no", for OpenLDAP
168 2.1 and later it is "yes". At least one of tls_cacertdir and
169 tls_cacertfile is required if peer verification is enabled.
170 tls_cacertdir <certificate_dir>
172 Specifies the directory containing X.509 certificates for peer
173 authentication.
174 tls_cacertfile <certificate_file>
176 Specifies the path to the X.509 certificate for peer authentica‐
177 tion.
178 tls_randfile <entropy_file>
180 Specifies the path to an entropy source.
181 tls_ciphers <ciphers>
183 Specifies the ciphers to use for TLS. See your TLS implementa‐
184 tion's documentation for further information.
185 tls_cert <certificate_file>
187 Specifies the path to the file containing the local certificate
188 for client TLS authentication.
189 tls_key <key_file>
191 Specifies the path to the file containing the private key for
192 client TLS authentication.
193 The following configuration options apply to nss_ldap only:
195 bind_policy <hard_open|hard_init|soft>
197 Specifies the policy to use for reconnecting to an unavailable
198 LDAP server. The default is hard_open, which reconnects if open‐
199 ing the connection to the directory server failed. By contrast,
200 hard_init reconnects if initializing the connection failed. Ini‐
201 tializing may not actually contact the directory server, and it
202 is possible that a malformed configuration file will trigger
203 reconnection. If soft is specified, then nss_ldap will return
204 immediately on server failure. All "hard" reconnect policies
205 block with exponential backoff before retrying.
206 nss_connect_policy <persist|oneshot>
208 Determines whether nss_ldap persists connections. The default is
209 for the connection to the LDAP server to remain open after the
210 first request.
211 idle_timelimit <timelimit>
213 Specifies the time (in seconds) after which nss_ldap will close
214 connections to the directory server. The default is not to time
215 out connections.
216 sasl_authid <authid>
218 Specifies the authorization identity to be used when performing
219 SASL authentication.
220 rootsasl_auth_id <authid>
222 Specifies the authorization identity to be used when performing
223 SASL authentication as root (when the effective user ID is
224 zero).
225 sasl_secprops <properties>
227 Specifies Cyrus SASL security properties. Allowed values are
228 described in the ldap.conf(5) manual page.
229 rootuse_sasl <yes|no>
231 Specifies whether SASL authentication should be used when the
232 effective user ID is zero.
233 krb5_ccname <PREFIX:args>
235 If nss_ldap is built with configurable GSS-API credentials cache
236 name support, specifies the Kerberos credentials cache to use.
237 nss_paged_results <yes|no>
239 Enables support for paged results.
240 pagesize <pagesize>
242 When paged results are enabled (see above), specifies the number
243 of entries to return in a single page. The default is 1000.
244 nss_base_<map> <basedn?scope?filter>
246 Specify the search base, scope and filter to be used for spe‐
247 cific maps. (Note that map forms part of the configuration file
248 keyword and is one of passwd, shadow, group, hosts, services,
249 networks, protocols, rpc, ethers, netmasks, bootparams, aliases
250 and netgroup.) The syntax of basedn and scope are the same as
251 for the configuration file options of the same name, with the
252 addition of being able to omit the trailing suffix of the base
253 DN (in which case the global base DN will be appended instead).
254 The filter is a search filter to be added to the default search
255 filter for a specific map, such that the effective filter is the
256 logical intersection of the two. The base DN, scope and filter
257 are separated with literal question marks (?) as given above;
258 this is for compatibility with the DUA configuration profile
259 schema and the ldapprofile tool. This option may be specified
260 multiple times.
261 nss_map_attribute <from_attribute> <to_attribute>
263 This option may be specified multiple times, and directs
264 nss_ldap to use the attribute to_attribute instead of the RFC
265 2307 attribute from_attribute in all lookups. If nss_ldap was
266 built without schema mapping support, then this option is
267 ignored.
268 nss_map_objectclass <from_objectclass> <to_objectclass>
270 This option may be specified multiple times, and directs
271 nss_ldap to use the object class to_objectclass instead of the
272 RFC 2307 object class from_objectclass in all lookups. If
273 nss_ldap was built without schema mapping support, then this
274 option is ignored.
275 nss_default_attribute_value <attribute> <value>
277 Specifies the default value to use for entries that lack the
278 specified attribute. This option may be specified multiple
279 times, for different attributes. If nss_ldap was built without
280 schema mapping support, then this option is ignored.
281 nss_override_attribute_value <attribute> <value>
283 Specifies a value to use for the specified attribute in prefer‐
284 ence to that contained in the actual entry. This option may be
285 specified multiple times, for different attributes. If nss_ldap
286 was built without schema mapping support, then this option is
287 ignored.
288 nss_schema <rfc2307bis|rfc2307>
290 If the value of this option is rfc2307bis then support for the
291 RFC2307bis schema (distinguished names in groups) will be
292 enabled.
293 nss_initgroups <backlink>
295 This option directs the nss_ldap implementation of initgroups(3)
296 to determine a user's group membership by reading the memberOf
297 attribute of their directory entry (and of any nested groups),
298 rather than querying on uniqueMember. This may provide increased
299 performance with certain directory servers that have peculiar
300 indexing configurations. If RFC2307bis support is disabled,
301 then this option is ignored.
302 nss_initgroups_ignoreusers <user1,user2,...,userN>
304 This option directs the nss_ldap implementation of initgroups(3)
305 to return NSS_STATUS_NOTFOUND if called with a listed users as
306 its argument.
307 nss_srv_domain <domain>
309 This option determines the DNS domain used for performing SRV
310 lookups.
311
313 The nss_ldap module was developed by PADL Software Pty Ltd
314 (www.padl.com).
315
318 /etc/ldap.conf, /etc/ldap.secret, /etc/nsswitch.conf
319
321 nsswitch.conf(5)
322 nss_ldap(5)