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
20       defaults  file.   The  file  ldaprc in the current working directory is
21       also 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
31       defaults.  The name of the variable is the option name  with  an  added
32       prefix  of  LDAP.  For example, to define BASE via the environment, set
33       the 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=Example2C 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
87              library  should  connect.   The  URI  scheme may be any of ldap,
88              ldaps or ldapi, which refer to LDAP  over  TCP,  LDAP  over  SSL
89              (TLS)  and  LDAP  over  IPC (UNIX domain sockets), respectively.
90              Each server's name can be specified as a domain-style name or an
91              IP  address literal.  Optionally, the server's name can followed
92              by a ':' and the port number the LDAP server  is  listening  on.
93              If  no  port number is provided, the default port for the scheme
94              is 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
96              allowed; note that directory  separators  must  be  URL-encoded,
97              like  any  other  characters  that  are  special to URLs; so the
98              socket
99
100                   /usr/local/var/ldapi
101
102              must be specified as
103
104                   ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi
105
106              A space separated list of URIs may be provided.
107
108       BASE <base>
109              Specifies the default base DN to use when performing ldap opera‐
110              tions.   The  base  must be specified as a Distinguished Name in
111              LDAP format.
112
113       BINDDN <dn>
114              Specifies the default bind DN to use when performing ldap opera‐
115              tions.  The bind DN must be specified as a Distinguished Name in
116              LDAP format.  This is a user-only option.
117
118       DEREF <when>
119              Specifies how alias dereferencing  is  done  when  performing  a
120              search. The <when> can be specified as one of the following key‐
121              words:
122
123              never  Aliases are never dereferenced. This is the default.
124
125              searching
126                     Aliases are dereferenced  in  subordinates  of  the  base
127                     object,  but  not  in  locating  the  base  object of the
128                     search.
129
130              finding
131                     Aliases are only  dereferenced  when  locating  the  base
132                     object of the search.
133
134              always Aliases  are dereferenced both in searching and in locat‐
135                     ing the base object of the search.
136
137
138       HOST <name[:port] ...>
139              Specifies the name(s) of an LDAP server(s) to  which  the
140              LDAP  library  should connect.  Each server's name can be
141              specified as a domain-style name or  an  IP  address  and
142              optionally followed by a ':' and the port number the ldap
143              server is listening on.  A space separated list of  hosts
144              may be provided.  HOST is deprecated in favor of URI.
145
146       NETWORK_TIMEOUT <integer>
147              Specifies  the  timeout  (in  seconds)  after  which  the
148              poll(2)/select(2) following a connect(2) returns in  case
149              of no activity.
150
151       PORT <port>
152              Specifies  the  default port used when connecting to LDAP
153              servers(s).  The port may be specified as a number.  PORT
154              is deprecated in favor of URI.
155
156       REFERRALS <on/true/yes/off/false/no>
157              Specifies  if  the  client  should  automatically  follow
158              referrals returned by LDAP servers.  The default  is  on.
159              Note that the command line tools ldapsearch(1) &co always
160              override this option.
161
162       SIZELIMIT <integer>
163              Specifies a size limit (number of entries)  to  use  when
164              performing searches.  The number should be a non-negative
165              integer.  SIZELIMIT of zero (0) specifies a  request  for
166              unlimited  search  size.  Please note that the server may
167              still apply  any  server-side  limit  on  the  amount  of
168              entries that can be returned by a search operation.
169
170       TIMELIMIT <integer>
171              Specifies  a time limit (in seconds) to use when perform‐
172              ing searches.  The number should be a non-negative  inte‐
173              ger.   TIMELIMIT  of  zero (0) specifies unlimited search
174              time to be used.  Please note that the server  may  still
175              apply  any  server-side limit on the duration of a search
176              operation.  VERSION {2|3} Specifies what version  of  the
177              LDAP protocol should be used.
178
179       TIMEOUT <integer>
180              Specifies  a  timeout  (in  seconds) after which calls to
181              synchronous LDAP  APIs  will  abort  if  no  response  is
182              received.  Also used for any ldap_result(3) calls where a
183              NULL timeout parameter is supplied.
184

SASL OPTIONS

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

GSSAPI OPTIONS

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

TLS OPTIONS

277       If OpenLDAP is built  with  Transport  Layer  Security  support,
278       there  are more options you can specify.  These options are used
279       when an ldaps:// URI is selected (by default  or  otherwise)  or
280       when the application negotiates TLS by issuing the LDAP StartTLS
281       operation.
282
283       When using OpenSSL, if neither  TLS_CACERT nor TLS_CACERTDIR  is
284       set, the system-wide default set of CA certificates is used.
285
286       TLS_CACERT <filename>
287              Specifies  the file that contains certificates for all of
288              the Certificate Authorities the client will recognize.
289
290       TLS_CACERTDIR <path>
291              Specifies the path of a directory that contains  Certifi‐
292              cate Authority certificates in separate individual files.
293              The TLS_CACERT is always used before TLS_CACERTDIR.   The
294              specified  directory  must  be  managed  with the OpenSSL
295              c_rehash utility.  This parameter is ignored with GnuTLS.
296
297              When using Mozilla NSS, <path> may contain a Mozilla  NSS
298              cert/key  database.   If  <path>  contains  a Mozilla NSS
299              cert/key database and CA cert files,  OpenLDAP  will  use
300              the cert/key database and will ignore the CA cert files.
301
302       TLS_CERT <filename>
303              Specifies  the file that contains the client certificate.
304              This is a user-only option.
305
306              When using Mozilla NSS,  if  using  a  cert/key  database
307              (specified  with  TLS_CACERTDIR),  TLS_CERT specifies the
308              name of the certificate to use:
309                   TLS_CERT Certificate for Sam Carter
310              If using a token other than the internal built in  token,
311              specify the token name first, followed by a colon:
312                   TLS_CERT my hardware device:Certificate for Sam Carter
313              Use certutil -L to list the certificates by name:
314                   certutil -d /path/to/certdbdir -L
315
316       TLS_KEY <filename>
317              Specifies  the  file  that  contains the private key that
318              matches the certificate stored in the TLS_CERT file. Cur‐
319              rently,  the  private  key  must  not be protected with a
320              password, so it is of critical importance  that  the  key
321              file is protected carefully.  This is a user-only option.
322
323              When  using  Mozilla NSS, TLS_KEY specifies the name of a
324              file that contains the password for the key for the  cer‐
325              tificate  specified  with  TLS_CERT.  The modutil command
326              can be used to  turn  off  password  protection  for  the
327              cert/key  database.  For example, if TLS_CACERTDIR speci‐
328              fies  /home/scarter/.moznss  as  the  location   of   the
329              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 WARN‐
333              ING about the running browser.  Press 'Enter' for the new
334              password.
335
336
337       TLS_CIPHER_SUITE <cipher-suite-spec>
338              Specifies acceptable cipher suite and  preference  order.
339              <cipher-suite-spec>  should be a cipher specification for
340              the TLS library in use (OpenSSL, GnuTLS, or Mozilla NSS).
341              Example:
342
343                     OpenSSL:
344                            TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2
345
346                     GnuTLS:
347                            TLS_CIPHER_SUITE SECURE256:!AES-128-CBC
348
349              To  check  what  ciphers a given spec selects in OpenSSL,
350              use:
351
352                   openssl ciphers -v <cipher-suite-spec>
353
354              With GnuTLS the available specs can be found in the  man‐
355              ual  page  of  gnutls-cli(1)  (see the description of the
356              option --priority).
357
358              In older versions of GnuTLS, where  gnutls-cli  does  not
359              support  the option --priority, you can obtain the — more
360              limited — list of ciphers by calling:
361
362                   gnutls-cli -l
363
364              When using Mozilla NSS, the OpenSSL cipher suite specifi‐
365              cations  are  used  and  translated  into the format used
366              internally by Mozilla NSS.  There isn't an  easy  way  to
367              list  the  cipher  suites  from  the  command  line.  The
368              authoritative list is in the source code for Mozilla  NSS
369              in the file sslinfo.c in the structure
370                      static const SSLCipherSuiteInfo suiteInfo[]
371
372       TLS_PROTOCOL_MIN <major>[.<minor>]
373              Specifies  minimum  SSL/TLS protocol version that will be
374              negotiated.  If the server doesn't support at least  that
375              version, the SSL handshake will fail.  To require TLS 1.x
376              or higher, set this option to 3.(x+1), e.g.,
377
378                   TLS_PROTOCOL_MIN 3.2
379
380              would require TLS 1.1.   Specifying  a  minimum  that  is
381              higher than that supported by the OpenLDAP implementation
382              will result in it requiring the  highest  level  that  it
383              does support.  This parameter is ignored with GnuTLS.
384
385       TLS_RANDFILE <filename>
386              Specifies  the  file  to  obtain  random  bits  from when
387              /dev/[u]random is not available.  Generally  set  to  the
388              name  of  the EGD/PRNGD socket.  The environment variable
389              RANDFILE can also be used to specify the filename.   This
390              parameter is ignored with GnuTLS and Mozilla NSS.
391
392       TLS_REQCERT <level>
393              Specifies  what  checks to perform on server certificates
394              in a TLS session, if any. The <level> can be specified as
395              one of the following keywords:
396
397              never  The  client  will  not request or check any server
398                     certificate.
399
400              allow  The server certificate is requested.  If  no  cer‐
401                     tificate  is  provided,  the session proceeds nor‐
402                     mally. If a bad certificate is provided,  it  will
403                     be ignored and the session proceeds normally.
404
405              try    The  server  certificate  is requested. If no cer‐
406                     tificate is provided, the  session  proceeds  nor‐
407                     mally.  If a bad certificate is provided, the ses‐
408                     sion is immediately terminated.
409
410              demand | hard
411                     These keywords are equivalent. The server certifi‐
412                     cate  is requested. If no certificate is provided,
413                     or a bad certificate is provided, the  session  is
414                     immediately  terminated.  This is the default set‐
415                     ting.
416
417       TLS_CRLCHECK <level>
418              Specifies if the Certificate Revocation List (CRL) of the
419              CA  should  be  used to verify if the server certificates
420              have not been revoked. This requires TLS_CACERTDIR param‐
421              eter to be set. This parameter is ignored with GnuTLS and
422              Mozilla NSS.  <level> can be specified as one of the fol‐
423              lowing keywords:
424
425              none   No CRL checks are performed
426
427              peer   Check the CRL of the peer certificate
428
429              all    Check the CRL for a whole certificate chain
430
431       TLS_CRLFILE <filename>
432              Specifies  the  file  containing a Certificate Revocation
433              List to be used to verify if the server certificates have
434              not  been  revoked. This parameter is only supported with
435              GnuTLS and Mozilla NSS.
436

ENVIRONMENT VARIABLES

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

FILES

450       /etc/openldap/ldap.conf
451              system-wide ldap configuration file
452
453       $HOME/ldaprc, $HOME/.ldaprc
454              user ldap configuration file
455
456       $CWD/ldaprc
457              local ldap configuration file
458

SEE ALSO

460       ldap(3), ldap_set_option(3), ldap_result(3), openssl(1), sasl(3)
461

AUTHOR

463       Kurt Zeilenga, The OpenLDAP Project
464

ACKNOWLEDGEMENTS

466       OpenLDAP Software is developed and maintained  by  The  OpenLDAP
467       Project   <http://www.openldap.org/>.    OpenLDAP   Software  is
468       derived from the University of Michigan LDAP 3.3 Release.
469
470
471
472OpenLDAP 2.4.46                   2018/03/22                      LDAP.CONF(5)
Impressum