1LDAP.CONF(5)                  File Formats Manual                 LDAP.CONF(5)
2
3
4

NAME

6       ldap.conf, .ldaprc - LDAP configuration file/environment variables
7

SYNOPSIS

9       /etc/openldap/ldap.conf, ldaprc, .ldaprc, $LDAP<option-name>
10

DESCRIPTION

12       If  the  environment  variable LDAPNOINIT is defined, all defaulting is
13       disabled.
14
15       The ldap.conf configuration file is used to set system-wide defaults to
16       be applied when running ldap clients.
17
18       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
23       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
30       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
35       Some options are user-only.  Such options are ignored if present in the
36       ldap.conf (or file specified by LDAPCONF).
37
38       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

SYNTAX

48       The  configuration options are case-insensitive; their value, on a case
49       by case basis, may be case-sensitive.
50
51       Blank lines are ignored.
52       Lines beginning with a hash mark (`#') are comments, and ignored.
53
54       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
63            # Wrong - erroneous quotes:
64            URI     "ldap:// ldaps://"
65
66            # Right - space-separated list of URIs, without quotes:
67            URI     ldap:// ldaps://
68
69            # 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
74            # Wrong - comment on same line as option:
75            DEREF   never           # Never follow aliases
76
77       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

OPTIONS

83       The different configuration options are:
84
85       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
99                   /usr/local/var/ldapi
100
101              must be specified as
102
103                   ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi
104
105              A space separated list of URIs may be provided.
106
107       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
112       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
117       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
122              never  Aliases are never dereferenced. This is the default.
123
124              searching
125                     Aliases  are dereferenced in subordinates of the base ob‐
126                     ject, but not in locating the base object of the search.
127
128              finding
129                     Aliases are only dereferenced when locating the base  ob‐
130                     ject of the search.
131
132              always Aliases  are dereferenced both in searching and in locat‐
133                     ing the base object of the search.
134
135
136       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
144       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
148       KEEPALIVE_PROBES
149              Sets/gets the maximum number of keepalive probes TCP should send
150              before dropping the connection. Linux only.
151
152       KEEPALIVE_INTERVAL
153              Sets/gets  the  interval in seconds between individual keepalive
154              probes.  Linux only.
155
156       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
160       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
165       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
171       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
179       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
185       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
192       VERSION {2|3}
193              Specifies what version of the LDAP protocol should be used.
194
195       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

SASL OPTIONS

202       If OpenLDAP is built with Simple Authentication and Security Layer sup‐
203       port, there are more options you can specify.
204
205       SASL_MECH <mechanism>
206              Specifies the SASL mechanism to use.
207
208       SASL_REALM <realm>
209              Specifies the SASL realm.
210
211       SASL_AUTHCID <authcid>
212              Specifies the authentication identity.  This is a user-only  op‐
213              tion.
214
215       SASL_AUTHZID <authcid>
216              Specifies the proxy authorization identity.  This is a user-only
217              option.
218
219       SASL_SECPROPS <properties>
220              Specifies Cyrus SASL security properties. The  <properties>  can
221              be specified as a comma-separated list of the following:
222
223              none   (without  any other properties) causes the properties de‐
224                     faults ("noanonymous,noplain") to be cleared.
225
226              noplain
227                     disables mechanisms susceptible  to  simple  passive  at‐
228                     tacks.
229
230              noactive
231                     disables mechanisms susceptible to active attacks.
232
233              nodict disables mechanisms susceptible to passive dictionary at‐
234                     tacks.
235
236              noanonymous
237                     disables mechanisms which support anonymous login.
238
239              forwardsec
240                     requires forward secrecy between sessions.
241
242              passcred
243                     requires mechanisms which pass  client  credentials  (and
244                     allows mechanisms which can pass credentials to do so).
245
246              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
254              maxssf=<factor>
255                     specifies the maximum acceptable security strength factor
256                     as  an  integer (see minssf description).  The default is
257                     INT_MAX.
258
259              maxbufsize=<factor>
260                     specifies the maximum security layer receive buffer  size
261                     allowed.   0  disables  security  layers.  The default is
262                     65536.
263
264       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
268       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

GSSAPI OPTIONS

273       If OpenLDAP is built with Generic Security  Services  Application  Pro‐
274       gramming Interface support, there are more options you can specify.
275
276       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
280       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
284       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

TLS OPTIONS

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
295       When using OpenSSL, if neither  TLS_CACERT nor  TLS_CACERTDIR  is  set,
296       the system-wide default set of CA certificates is used.
297
298       TLS_CACERT <filename>
299              Specifies  the  file  that  contains certificates for all of the
300              Certificate Authorities the client will recognize.
301
302       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
309       TLS_CERT <filename>
310              Specifies the file that contains the client  certificate.   This
311              is a user-only option.
312
313       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
319       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
326       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
331                     OpenSSL:
332                            TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2
333
334                     GnuTLS:
335                            TLS_CIPHER_SUITE SECURE256:!AES-128-CBC
336
337              To check what ciphers a given spec selects in OpenSSL, use:
338
339                   openssl ciphers -v <cipher-suite-spec>
340
341              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
344              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
348                   gnutls-cli -l
349
350       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
356                   TLS_PROTOCOL_MIN 3.2
357
358              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
363       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
369       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
374              never  The client will not request or check any server  certifi‐
375                     cate.
376
377              allow  The server certificate is requested. If a bad certificate
378                     is provided, it will be ignored and the session  proceeds
379                     normally.
380
381              try    The server certificate is requested. If a bad certificate
382                     is provided, the session is immediately terminated.
383
384              demand | hard
385                     These keywords are equivalent and the same as try.   This
386                     is the default setting.
387
388       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
394              never  The client will not check any SAN in the certificate.
395
396              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
401              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
408              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
415       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
422              none   No CRL checks are performed
423
424              peer   Check the CRL of the peer certificate
425
426              all    Check the CRL for a whole certificate chain
427
428       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

ENVIRONMENT VARIABLES

434       LDAPNOINIT
435              disable all defaulting
436
437       LDAPCONF
438              path of a configuration file
439
440       LDAPRC basename of ldaprc file in $HOME or $CWD
441
442       LDAP<option-name>
443              Set <option-name> as from ldap.conf
444

FILES

446       /etc/openldap/ldap.conf
447              system-wide ldap configuration file
448
449       $HOME/ldaprc, $HOME/.ldaprc
450              user ldap configuration file
451
452       $CWD/ldaprc
453              local ldap configuration file
454

SEE ALSO

456       ldap(3), ldap_set_option(3), ldap_result(3), openssl(1), sasl(3)
457

AUTHOR

459       Kurt Zeilenga, The OpenLDAP Project
460

ACKNOWLEDGEMENTS

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.
465
466
467
468OpenLDAP 2.6.6                    2023/07/31                      LDAP.CONF(5)
Impressum