1LDAP.CONF(5) File Formats Manual LDAP.CONF(5)
2
6 ldap.conf, .ldaprc - LDAP configuration file/environment variables
7
9 /etc/openldap/ldap.conf, ldaprc, .ldaprc, $LDAP<option-name>
10
12 If the environment variable LDAPNOINIT is defined, all defaulting is
13 disabled.
14 The ldap.conf configuration file is used to set system-wide defaults to
16 be applied when running ldap clients.
17 Users may create an optional configuration file, ldaprc or .ldaprc, in
19 their home directory which will be used to override the system-wide de‐
20 faults file. The file ldaprc in the current working directory is also
21 used.
22 Additional configuration files can be specified using the LDAPCONF and
24 LDAPRC environment variables. LDAPCONF may be set to the path of a
25 configuration file. This path can be absolute or relative to the cur‐
26 rent working directory. The LDAPRC, if defined, should be the basename
27 of a file in the current working directory or in the user's home direc‐
28 tory.
29 Environmental variables may also be used to augment the file based de‐
31 faults. The name of the variable is the option name with an added pre‐
32 fix of LDAP. For example, to define BASE via the environment, set the
33 variable LDAPBASE to the desired value.
34 Some options are user-only. Such options are ignored if present in the
36 ldap.conf (or file specified by LDAPCONF).
37 Thus the following files and variables are read, in order:
39 variable $LDAPNOINIT, and if that is not set:
40 system file /etc/openldap/ldap.conf,
41 user files $HOME/ldaprc, $HOME/.ldaprc, ./ldaprc,
42 system file $LDAPCONF,
43 user files $HOME/$LDAPRC, $HOME/.$LDAPRC, ./$LDAPRC,
44 variables $LDAP<uppercase option name>.
45 Settings late in the list override earlier ones.
46
48 The configuration options are case-insensitive; their value, on a case
49 by case basis, may be case-sensitive.
50 Blank lines are ignored.
52 Lines beginning with a hash mark (`#') are comments, and ignored.
53 Valid lines are made of an option's name (a sequence of non-blanks,
55 conventionally written in uppercase, although not required), followed
56 by a value. The value starts with the first non-blank character after
57 the option's name, and terminates at the end of the line, or at the
58 last sequence of blanks before the end of the line. The tokenization
59 of the value, if any, is delegated to the handler(s) for that option,
60 if any. Quoting values that contain blanks may be incorrect, as the
61 quotes would become part of the value. For example,
62 # Wrong - erroneous quotes:
64 URI "ldap:// ldaps://"
65 # Right - space-separated list of URIs, without quotes:
67 URI ldap:// ldaps://
68 # Right - DN syntax needs quoting for Example, Inc:
70 BASE ou=IT staff,o="Example, Inc",c=US
71 # or:
72 BASE ou=IT staff,o=Example\2C Inc,c=US
73 # Wrong - comment on same line as option:
75 DEREF never # Never follow aliases
76 A line cannot be longer than LINE_MAX, which should be more than 2000
78 bytes on all platforms. There is no mechanism to split a long line on
79 multiple lines, either for beautification or to overcome the above
80 limit.
81
83 The different configuration options are:
84 URI <ldap[si]://[name[:port]] ...>
86 Specifies the URI(s) of an LDAP server(s) to which the LDAP li‐
87 brary should connect. The URI scheme may be any of ldap, ldaps
88 or ldapi, which refer to LDAP over TCP, LDAP over SSL (TLS) and
89 LDAP over IPC (UNIX domain sockets), respectively. Each
90 server's name can be specified as a domain-style name or an IP
91 address literal. Optionally, the server's name can followed by
92 a ':' and the port number the LDAP server is listening on. If
93 no port number is provided, the default port for the scheme is
94 used (389 for ldap://, 636 for ldaps://). For LDAP over IPC,
95 name is the name of the socket, and no port is required, nor al‐
96 lowed; note that directory separators must be URL-encoded, like
97 any other characters that are special to URLs; so the socket
98 /usr/local/var/ldapi
100 must be specified as
102 ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi
104 A space separated list of URIs may be provided.
106 BASE <base>
108 Specifies the default base DN to use when performing ldap opera‐
109 tions. The base must be specified as a Distinguished Name in
110 LDAP format.
111 BINDDN <dn>
113 Specifies the default bind DN to use when performing ldap opera‐
114 tions. The bind DN must be specified as a Distinguished Name in
115 LDAP format. This is a user-only option.
116 DEREF <when>
118 Specifies how alias dereferencing is done when performing a
119 search. The <when> can be specified as one of the following key‐
120 words:
121 never Aliases are never dereferenced. This is the default.
123 searching
125 Aliases are dereferenced in subordinates of the base ob‐
126 ject, but not in locating the base object of the search.
127 finding
129 Aliases are only dereferenced when locating the base ob‐
130 ject of the search.
131 always Aliases are dereferenced both in searching and in locat‐
133 ing the base object of the search.
134 HOST <name[:port] ...>
137 Specifies the name(s) of an LDAP server(s) to which the LDAP li‐
138 brary should connect. Each server's name can be specified as a
139 domain-style name or an IP address and optionally followed by a
140 ':' and the port number the ldap server is listening on. A
141 space separated list of hosts may be provided. HOST is depre‐
142 cated in favor of URI.
143 KEEPALIVE_IDLE
145 Sets/gets the number of seconds a connection needs to remain
146 idle before TCP starts sending keepalive probes. Linux only.
147 KEEPALIVE_PROBES
149 Sets/gets the maximum number of keepalive probes TCP should send
150 before dropping the connection. Linux only.
151 KEEPALIVE_INTERVAL
153 Sets/gets the interval in seconds between individual keepalive
154 probes. Linux only.
155 NETWORK_TIMEOUT <integer>
157 Specifies the timeout (in seconds) after which the poll(2)/se‐
158 lect(2) following a connect(2) returns in case of no activity.
159 PORT <port>
161 Specifies the default port used when connecting to LDAP
162 servers(s). The port may be specified as a number. PORT is
163 deprecated in favor of URI.
164 REFERRALS <on/true/yes/off/false/no>
166 Specifies if the client should automatically follow referrals
167 returned by LDAP servers. The default is on. Note that the
168 command line tools ldapsearch(1) &co always override this op‐
169 tion.
170 SIZELIMIT <integer>
172 Specifies a size limit (number of entries) to use when perform‐
173 ing searches. The number should be a non-negative integer.
174 SIZELIMIT of zero (0) specifies a request for unlimited search
175 size. Please note that the server may still apply any server-
176 side limit on the amount of entries that can be returned by a
177 search operation.
178 SOCKET_BIND_ADDRESSES <IP>
180 Specifies the source bind IP to be used for connecting to target
181 LDAP server. Multiple IP addresses must be space separated.
182 Only one valid IPv4 address and/or one valid IPv6 address are
183 allowed in the list.
184 TIMELIMIT <integer>
186 Specifies a time limit (in seconds) to use when performing
187 searches. The number should be a non-negative integer. TIME‐
188 LIMIT of zero (0) specifies unlimited search time to be used.
189 Please note that the server may still apply any server-side
190 limit on the duration of a search operation.
191 VERSION {2|3}
193 Specifies what version of the LDAP protocol should be used.
194 TIMEOUT <integer>
196 Specifies a timeout (in seconds) after which calls to synchro‐
197 nous LDAP APIs will abort if no response is received. Also used
198 for any ldap_result(3) calls where a NULL timeout parameter is
199 supplied.
200
202 If OpenLDAP is built with Simple Authentication and Security Layer sup‐
203 port, there are more options you can specify.
204 SASL_MECH <mechanism>
206 Specifies the SASL mechanism to use.
207 SASL_REALM <realm>
209 Specifies the SASL realm.
210 SASL_AUTHCID <authcid>
212 Specifies the authentication identity. This is a user-only op‐
213 tion.
214 SASL_AUTHZID <authcid>
216 Specifies the proxy authorization identity. This is a user-only
217 option.
218 SASL_SECPROPS <properties>
220 Specifies Cyrus SASL security properties. The <properties> can
221 be specified as a comma-separated list of the following:
222 none (without any other properties) causes the properties de‐
224 faults ("noanonymous,noplain") to be cleared.
225 noplain
227 disables mechanisms susceptible to simple passive at‐
228 tacks.
229 noactive
231 disables mechanisms susceptible to active attacks.
232 nodict disables mechanisms susceptible to passive dictionary at‐
234 tacks.
235 noanonymous
237 disables mechanisms which support anonymous login.
238 forwardsec
240 requires forward secrecy between sessions.
241 passcred
243 requires mechanisms which pass client credentials (and
244 allows mechanisms which can pass credentials to do so).
245 minssf=<factor>
247 specifies the minimum acceptable security strength factor
248 as an integer approximate to effective key length used
249 for encryption. 0 (zero) implies no protection, 1 im‐
250 plies integrity protection only, 128 allows RC4, Blowfish
251 and other similar ciphers, 256 will require modern ci‐
252 phers. The default is 0.
253 maxssf=<factor>
255 specifies the maximum acceptable security strength factor
256 as an integer (see minssf description). The default is
257 INT_MAX.
258 maxbufsize=<factor>
260 specifies the maximum security layer receive buffer size
261 allowed. 0 disables security layers. The default is
262 65536.
263 SASL_NOCANON <on/true/yes/off/false/no>
265 Do not perform reverse DNS lookups to canonicalize SASL host
266 names. The default is off.
267 SASL_CBINDING <none/tls-unique/tls-endpoint>
269 The channel-binding type to use, see also LDAP_OPT_X_SASL_CBIND‐
270 ING. The default is none.
271
273 If OpenLDAP is built with Generic Security Services Application Pro‐
274 gramming Interface support, there are more options you can specify.
275 GSSAPI_SIGN <on/true/yes/off/false/no>
277 Specifies if GSSAPI signing (GSS_C_INTEG_FLAG) should be used.
278 The default is off.
279 GSSAPI_ENCRYPT <on/true/yes/off/false/no>
281 Specifies if GSSAPI encryption (GSS_C_INTEG_FLAG and
282 GSS_C_CONF_FLAG) should be used. The default is off.
283 GSSAPI_ALLOW_REMOTE_PRINCIPAL <on/true/yes/off/false/no>
285 Specifies if GSSAPI based authentication should try to form the
286 target principal name out of the ldapServiceName or dnsHostName
287 attribute of the targets RootDSE entry. The default is off.
288
290 If OpenLDAP is built with Transport Layer Security support, there are
291 more options you can specify. These options are used when an ldaps://
292 URI is selected (by default or otherwise) or when the application nego‐
293 tiates TLS by issuing the LDAP StartTLS operation.
294 When using OpenSSL, if neither TLS_CACERT nor TLS_CACERTDIR is set,
296 the system-wide default set of CA certificates is used.
297 TLS_CACERT <filename>
299 Specifies the file that contains certificates for all of the
300 Certificate Authorities the client will recognize.
301 TLS_CACERTDIR <path>
303 Specifies the path of directories that contain Certificate Au‐
304 thority certificates in separate individual files. Multiple di‐
305 rectories may be specified, separated by a semi-colon. The
306 TLS_CACERT is always used before TLS_CACERTDIR. The specified
307 directory must be managed with the OpenSSL c_rehash utility.
308 TLS_CERT <filename>
310 Specifies the file that contains the client certificate. This
311 is a user-only option.
312 TLS_ECNAME <name>
314 Specify the name of the curve(s) to use for Elliptic curve
315 Diffie-Hellman ephemeral key exchange. This option is only used
316 for OpenSSL. This option is not used with GnuTLS; the curves
317 may be chosen in the GnuTLS ciphersuite specification.
318 TLS_KEY <filename>
320 Specifies the file that contains the private key that matches
321 the certificate stored in the TLS_CERT file. Currently, the pri‐
322 vate key must not be protected with a password, so it is of
323 critical importance that the key file is protected carefully.
324 This is a user-only option.
325 TLS_CIPHER_SUITE <cipher-suite-spec>
327 Specifies acceptable cipher suite and preference order. <ci‐
328 pher-suite-spec> should be a cipher specification for the TLS
329 library in use (OpenSSL or GnuTLS). Example:
330 OpenSSL:
332 TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2
333 GnuTLS:
335 TLS_CIPHER_SUITE SECURE256:!AES-128-CBC
336 To check what ciphers a given spec selects in OpenSSL, use:
338 openssl ciphers -v <cipher-suite-spec>
340 With GnuTLS the available specs can be found in the manual page
342 of gnutls-cli(1) (see the description of the option --priority).
343 In older versions of GnuTLS, where gnutls-cli does not support
345 the option --priority, you can obtain the — more limited — list
346 of ciphers by calling:
347 gnutls-cli -l
349 TLS_PROTOCOL_MIN <major>[.<minor>]
351 Specifies minimum SSL/TLS protocol version that will be negoti‐
352 ated. If the server doesn't support at least that version, the
353 SSL handshake will fail. To require TLS 1.x or higher, set this
354 option to 3.(x+1), e.g.,
355 TLS_PROTOCOL_MIN 3.2
357 would require TLS 1.1. Specifying a minimum that is higher than
359 that supported by the OpenLDAP implementation will result in it
360 requiring the highest level that it does support. This parame‐
361 ter is ignored with GnuTLS.
362 TLS_RANDFILE <filename>
364 Specifies the file to obtain random bits from when /dev/[u]ran‐
365 dom is not available. Generally set to the name of the EGD/PRNGD
366 socket. The environment variable RANDFILE can also be used to
367 specify the filename. This parameter is ignored with GnuTLS.
368 TLS_REQCERT <level>
370 Specifies what checks to perform on server certificates in a TLS
371 session. The <level> can be specified as one of the following
372 keywords:
373 never The client will not request or check any server certifi‐
375 cate.
376 allow The server certificate is requested. If a bad certificate
378 is provided, it will be ignored and the session proceeds
379 normally.
380 try The server certificate is requested. If a bad certificate
382 is provided, the session is immediately terminated.
383 demand | hard
385 These keywords are equivalent and the same as try. This
386 is the default setting.
387 TLS_REQSAN <level>
389 Specifies what checks to perform on the subjectAlternativeName
390 (SAN) extensions in a server certificate when validating the
391 certificate name against the specified hostname of the server.
392 The <level> can be specified as one of the following keywords:
393 never The client will not check any SAN in the certificate.
395 allow The SAN is checked against the specified hostname. If a
397 SAN is present but none match the specified hostname, the
398 SANs are ignored and the usual check against the certifi‐
399 cate DN is used. This is the default setting.
400 try The SAN is checked against the specified hostname. If no
402 SAN is present in the server certificate, the usual check
403 against the certificate DN is used. If a SAN is present
404 but doesn't match the specified hostname, the session is
405 immediately terminated. This setting may be preferred
406 when a mix of certs with and without SANs are in use.
407 demand | hard
409 These keywords are equivalent. The SAN is checked against
410 the specified hostname. If no SAN is present in the
411 server certificate, or no SANs match, the session is im‐
412 mediately terminated. This setting should be used when
413 only certificates with SANs are in use.
414 TLS_CRLCHECK <level>
416 Specifies if the Certificate Revocation List (CRL) of the CA
417 should be used to verify if the server certificates have not
418 been revoked. This requires TLS_CACERTDIR parameter to be set.
419 This parameter is ignored with GnuTLS. <level> can be specified
420 as one of the following keywords:
421 none No CRL checks are performed
423 peer Check the CRL of the peer certificate
425 all Check the CRL for a whole certificate chain
427 TLS_CRLFILE <filename>
429 Specifies the file containing a Certificate Revocation List to
430 be used to verify if the server certificates have not been re‐
431 voked. This parameter is only supported with GnuTLS.
432
434 LDAPNOINIT
435 disable all defaulting
436 LDAPCONF
438 path of a configuration file
439 LDAPRC basename of ldaprc file in $HOME or $CWD
441 LDAP<option-name>
443 Set <option-name> as from ldap.conf
444
446 /etc/openldap/ldap.conf
447 system-wide ldap configuration file
448 $HOME/ldaprc, $HOME/.ldaprc
450 user ldap configuration file
451 $CWD/ldaprc
453 local ldap configuration file
454
456 ldap(3), ldap_set_option(3), ldap_result(3), openssl(1), sasl(3)
457
459 Kurt Zeilenga, The OpenLDAP Project
460
462 OpenLDAP Software is developed and maintained by The OpenLDAP Project
463 <http://www.openldap.org/>. OpenLDAP Software is derived from the Uni‐
464 versity of Michigan LDAP 3.3 Release.
465OpenLDAP 2.6.6 2023/07/31 LDAP.CONF(5)