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       NETWORK_TIMEOUT <integer>
145              Specifies  the  timeout (in seconds) after which the poll(2)/se‐
146              lect(2) following a connect(2) returns in case of no activity.
147
148       PORT <port>
149              Specifies  the  default  port  used  when  connecting  to   LDAP
150              servers(s).   The  port  may  be specified as a number.  PORT is
151              deprecated in favor of URI.
152
153       REFERRALS <on/true/yes/off/false/no>
154              Specifies if the client should  automatically  follow  referrals
155              returned  by  LDAP  servers.   The default is on.  Note that the
156              command line tools ldapsearch(1) &co always  override  this  op‐
157              tion.
158
159       SIZELIMIT <integer>
160              Specifies  a size limit (number of entries) to use when perform‐
161              ing searches.  The number  should  be  a  non-negative  integer.
162              SIZELIMIT  of  zero (0) specifies a request for unlimited search
163              size.  Please note that the server may still apply  any  server-
164              side  limit  on  the amount of entries that can be returned by a
165              search operation.
166
167       TIMELIMIT <integer>
168              Specifies a time limit  (in  seconds)  to  use  when  performing
169              searches.   The  number should be a non-negative integer.  TIME‐
170              LIMIT of zero (0) specifies unlimited search time  to  be  used.
171              Please  note  that  the  server  may still apply any server-side
172              limit on the duration of a search operation.
173
174       VERSION {2|3}
175              Specifies what version of the LDAP protocol should be used.
176
177       TIMEOUT <integer>
178              Specifies a timeout (in seconds) after which calls  to  synchro‐
179              nous LDAP APIs will abort if no response is received.  Also used
180              for any ldap_result(3) calls where a NULL timeout  parameter  is
181              supplied.
182

SASL OPTIONS

184       If OpenLDAP is built with Simple Authentication and Security Layer sup‐
185       port, there are more options you can specify.
186
187       SASL_MECH <mechanism>
188              Specifies the SASL mechanism to use.
189
190       SASL_REALM <realm>
191              Specifies the SASL realm.
192
193       SASL_AUTHCID <authcid>
194              Specifies the authentication identity.  This is a user-only  op‐
195              tion.
196
197       SASL_AUTHZID <authcid>
198              Specifies the proxy authorization identity.  This is a user-only
199              option.
200
201       SASL_SECPROPS <properties>
202              Specifies Cyrus SASL security properties. The  <properties>  can
203              be specified as a comma-separated list of the following:
204
205              none   (without  any other properties) causes the properties de‐
206                     faults ("noanonymous,noplain") to be cleared.
207
208              noplain
209                     disables mechanisms susceptible  to  simple  passive  at‐
210                     tacks.
211
212              noactive
213                     disables mechanisms susceptible to active attacks.
214
215              nodict disables mechanisms susceptible to passive dictionary at‐
216                     tacks.
217
218              noanonymous
219                     disables mechanisms which support anonymous login.
220
221              forwardsec
222                     requires forward secrecy between sessions.
223
224              passcred
225                     requires mechanisms which pass  client  credentials  (and
226                     allows mechanisms which can pass credentials to do so).
227
228              minssf=<factor>
229                     specifies the minimum acceptable security strength factor
230                     as an integer approximating the effective key length used
231                     for  encryption.   0  (zero) implies no protection, 1 im‐
232                     plies integrity protection only, 56 allows DES  or  other
233                     weak  ciphers, 112 allows triple DES and other strong ci‐
234                     phers, 128 allows RC4, Blowfish and other  modern  strong
235                     ciphers.  The default is 0.
236
237              maxssf=<factor>
238                     specifies the maximum acceptable security strength factor
239                     as an integer (see minssf description).  The  default  is
240                     INT_MAX.
241
242              maxbufsize=<factor>
243                     specifies  the maximum security layer receive buffer size
244                     allowed.  0 disables security  layers.   The  default  is
245                     65536.
246
247       SASL_NOCANON <on/true/yes/off/false/no>
248              Do  not  perform  reverse  DNS lookups to canonicalize SASL host
249              names. The default is off.
250
251       SASL_CBINDING <none/tls-unique/tls-endpoint>
252              The channel-binding type to use, see also LDAP_OPT_X_SASL_CBIND‐
253              ING. The default is none.
254

GSSAPI OPTIONS

256       If  OpenLDAP  is  built with Generic Security Services Application Pro‐
257       gramming Interface support, there are more options you can specify.
258
259       GSSAPI_SIGN <on/true/yes/off/false/no>
260              Specifies if GSSAPI signing (GSS_C_INTEG_FLAG) should  be  used.
261              The default is off.
262
263       GSSAPI_ENCRYPT <on/true/yes/off/false/no>
264              Specifies    if    GSSAPI   encryption   (GSS_C_INTEG_FLAG   and
265              GSS_C_CONF_FLAG) should be used. The default is off.
266
267       GSSAPI_ALLOW_REMOTE_PRINCIPAL <on/true/yes/off/false/no>
268              Specifies if GSSAPI based authentication should try to form  the
269              target  principal name out of the ldapServiceName or dnsHostName
270              attribute of the targets RootDSE entry. The default is off.
271

TLS OPTIONS

273       If OpenLDAP is built with Transport Layer Security support,  there  are
274       more  options you can specify.  These options are used when an ldaps://
275       URI is selected (by default or otherwise) or when the application nego‐
276       tiates TLS by issuing the LDAP StartTLS operation.
277
278       When  using  OpenSSL,  if neither  TLS_CACERT nor TLS_CACERTDIR is set,
279       the system-wide default set of CA certificates is used.
280
281       TLS_CACERT <filename>
282              Specifies the file that contains certificates  for  all  of  the
283              Certificate Authorities the client will recognize.
284
285       TLS_CACERTDIR <path>
286              Specifies  the path of a directory that contains Certificate Au‐
287              thority certificates in separate individual files. The  TLS_CAC‐
288              ERT  is  always used before TLS_CACERTDIR.  The specified direc‐
289              tory must be managed with the OpenSSL  c_rehash  utility.   This
290              parameter is ignored with GnuTLS.
291
292              When  using  Mozilla  NSS,  <path>  may  contain  a  Mozilla NSS
293              cert/key database.  If <path> contains a  Mozilla  NSS  cert/key
294              database and CA cert files, OpenLDAP will use the cert/key data‐
295              base and will ignore the CA cert files.
296
297       TLS_CERT <filename>
298              Specifies the file that contains the client  certificate.   This
299              is a user-only option.
300
301              When  using Mozilla NSS, if using a cert/key database (specified
302              with TLS_CACERTDIR), TLS_CERT specifies the name of the certifi‐
303              cate to use:
304                   TLS_CERT Certificate for Sam Carter
305              If using a token other than the internal built in token, specify
306              the token name first, followed by a colon:
307                   TLS_CERT my hardware device:Certificate for Sam Carter
308              Use certutil -L to list the certificates by name:
309                   certutil -d /path/to/certdbdir -L
310
311       TLS_ECNAME <name>
312              Specify the name of the  curve(s)  to  use  for  Elliptic  curve
313              Diffie-Hellman ephemeral key exchange.  This option is only used
314              for OpenSSL.  This option is not used with  GnuTLS;  the  curves
315              may be chosen in the GnuTLS ciphersuite specification.
316
317       TLS_KEY <filename>
318              Specifies  the  file  that contains the private key that matches
319              the certificate stored in the TLS_CERT file. Currently, the pri‐
320              vate  key  must  not  be  protected with a password, so it is of
321              critical importance that the key file  is  protected  carefully.
322              This is a user-only option.
323
324              When  using  Mozilla  NSS,  TLS_KEY specifies the name of a file
325              that contains the password for the key for the certificate spec‐
326              ified  with  TLS_CERT.   The modutil command can be used to turn
327              off password protection for the cert/key database.  For example,
328              if TLS_CACERTDIR specifies /home/scarter/.moznss as the location
329              of the cert/key database, use modutil to change the password  to
330              the empty string:
331                   modutil -dbdir ~/.moznss -changepw 'NSS Certificate DB'
332              You  must  have  the  old  password, if any.  Ignore the WARNING
333              about the running browser.  Press 'Enter' for the new password.
334
335
336       TLS_CIPHER_SUITE <cipher-suite-spec>
337              Specifies acceptable cipher suite and  preference  order.   <ci‐
338              pher-suite-spec>  should  be  a cipher specification for the TLS
339              library in use (OpenSSL, GnuTLS, or Mozilla NSS).  Example:
340
341                     OpenSSL:
342                            TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2
343
344                     GnuTLS:
345                            TLS_CIPHER_SUITE SECURE256:!AES-128-CBC
346
347              To check what ciphers a given spec selects in OpenSSL, use:
348
349                   openssl ciphers -v <cipher-suite-spec>
350
351              With GnuTLS the available specs can be found in the manual  page
352              of gnutls-cli(1) (see the description of the option --priority).
353
354              In  older  versions of GnuTLS, where gnutls-cli does not support
355              the option --priority, you can obtain the — more limited —  list
356              of ciphers by calling:
357
358                   gnutls-cli -l
359
360              When  using Mozilla NSS, the OpenSSL cipher suite specifications
361              are used and translated  into  the  format  used  internally  by
362              Mozilla  NSS.  There isn't an easy way to list the cipher suites
363              from the command line.  The authoritative list is in the  source
364              code for Mozilla NSS in the file sslinfo.c in the structure
365                      static const SSLCipherSuiteInfo suiteInfo[]
366
367       TLS_PROTOCOL_MIN <major>[.<minor>]
368              Specifies  minimum SSL/TLS protocol version that will be negoti‐
369              ated.  If the server doesn't support at least that version,  the
370              SSL handshake will fail.  To require TLS 1.x or higher, set this
371              option to 3.(x+1), e.g.,
372
373                   TLS_PROTOCOL_MIN 3.2
374
375              would require TLS 1.1.  Specifying a minimum that is higher than
376              that  supported by the OpenLDAP implementation will result in it
377              requiring the highest level that it does support.  This  parame‐
378              ter is ignored with GnuTLS.
379
380       TLS_RANDFILE <filename>
381              Specifies  the file to obtain random bits from when /dev/[u]ran‐
382              dom is not available. Generally set to the name of the EGD/PRNGD
383              socket.   The  environment variable RANDFILE can also be used to
384              specify the filename.  This parameter is ignored with GnuTLS and
385              Mozilla NSS.
386
387       TLS_REQCERT <level>
388              Specifies what checks to perform on server certificates in a TLS
389              session, if any. The <level> can be specified as one of the fol‐
390              lowing keywords:
391
392              never  The  client will not request or check any server certifi‐
393                     cate.
394
395              allow  The server certificate is requested. If no certificate is
396                     provided,  the  session  proceeds normally. If a bad cer‐
397                     tificate is provided, it will be ignored and the  session
398                     proceeds normally.
399
400              try    The server certificate is requested. If no certificate is
401                     provided, the session proceeds normally. If  a  bad  cer‐
402                     tificate  is  provided, the session is immediately termi‐
403                     nated.
404
405              demand | hard
406                     These keywords are equivalent. The server certificate  is
407                     requested.  If  no certificate is provided, or a bad cer‐
408                     tificate is provided, the session is  immediately  termi‐
409                     nated. This is the default setting.
410
411       TLS_REQSAN <level>
412              Specifies  what  checks to perform on the subjectAlternativeName
413              (SAN) extensions in a server  certificate  when  validating  the
414              certificate  name  against the specified hostname of the server.
415              The <level> can be specified as one of the following keywords:
416
417              never  The client will not check any SAN in the certificate.
418
419              allow  The SAN is checked against the specified hostname.  If  a
420                     SAN is present but none match the specified hostname, the
421                     SANs are ignored and the usual check against the certifi‐
422                     cate DN is used.  This is the default setting.
423
424              try    The  SAN is checked against the specified hostname. If no
425                     SAN is present in the server certificate, the usual check
426                     against  the  certificate DN is used. If a SAN is present
427                     but doesn't match the specified hostname, the session  is
428                     immediately  terminated.  This  setting  may be preferred
429                     when a mix of certs with and without SANs are in use.
430
431              demand | hard
432                     These keywords are equivalent. The SAN is checked against
433                     the  specified  hostname.  If  no  SAN  is present in the
434                     server certificate, or no SANs match, the session is  im‐
435                     mediately  terminated.  This  setting should be used when
436                     only certificates with SANs are in use.
437
438       TLS_CRLCHECK <level>
439              Specifies if the Certificate Revocation List  (CRL)  of  the  CA
440              should  be  used  to  verify if the server certificates have not
441              been revoked. This requires TLS_CACERTDIR parameter to  be  set.
442              This  parameter is ignored with GnuTLS and Mozilla NSS.  <level>
443              can be specified as one of the following keywords:
444
445              none   No CRL checks are performed
446
447              peer   Check the CRL of the peer certificate
448
449              all    Check the CRL for a whole certificate chain
450
451       TLS_CRLFILE <filename>
452              Specifies the file containing a Certificate Revocation  List  to
453              be  used  to verify if the server certificates have not been re‐
454              voked. This parameter is only supported with GnuTLS and  Mozilla
455              NSS.
456

ENVIRONMENT VARIABLES

458       LDAPNOINIT
459              disable all defaulting
460
461       LDAPCONF
462              path of a configuration file
463
464       LDAPRC basename of ldaprc file in $HOME or $CWD
465
466       LDAP<option-name>
467              Set <option-name> as from ldap.conf
468

FILES

470       /etc/openldap/ldap.conf
471              system-wide ldap configuration file
472
473       $HOME/ldaprc, $HOME/.ldaprc
474              user ldap configuration file
475
476       $CWD/ldaprc
477              local ldap configuration file
478

SEE ALSO

480       ldap(3), ldap_set_option(3), ldap_result(3), openssl(1), sasl(3)
481

AUTHOR

483       Kurt Zeilenga, The OpenLDAP Project
484

ACKNOWLEDGEMENTS

486       OpenLDAP  Software  is developed and maintained by The OpenLDAP Project
487       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
488       versity of Michigan LDAP 3.3 Release.
489
490
491
492OpenLDAP                          2021/06/03                      LDAP.CONF(5)
Impressum