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=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
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  LDAP
140              library  should connect.  Each server's name can be specified as
141              a domain-style name or an IP address and optionally followed  by
142              a  ':'  and  the port number the ldap server is listening on.  A
143              space separated list of hosts may be provided.  HOST  is  depre‐
144              cated 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  of  no
149              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  is
154              deprecated in favor of URI.
155
156       REFERRALS <on/true/yes/off/false/no>
157              Specifies  if  the  client should automatically follow referrals
158              returned by LDAP servers.  The default is  on.   Note  that  the
159              command  line  tools  ldapsearch(1)  &co  always  override  this
160              option.
161
162       SIZELIMIT <integer>
163              Specifies a size limit (number of entries) to use when  perform‐
164              ing  searches.   The  number  should  be a non-negative integer.
165              SIZELIMIT of zero (0) specifies a request for  unlimited  search
166              size.   Please  note that the server may still apply any server-
167              side limit on the amount of entries that can be  returned  by  a
168              search operation.
169
170       TIMELIMIT <integer>
171              Specifies  a  time  limit  (in  seconds)  to use when performing
172              searches.  The number should be a non-negative  integer.   TIME‐
173              LIMIT  of  zero  (0) specifies unlimited search time to be used.
174              Please note that the server  may  still  apply  any  server-side
175              limit on the duration of a search operation.
176
177       VERSION {2|3}
178              Specifies what version of the LDAP protocol should be used.
179
180       TIMEOUT <integer>
181              Specifies  a  timeout (in seconds) after which calls to synchro‐
182              nous LDAP APIs will abort if no response is received.  Also used
183              for  any  ldap_result(3) calls where a NULL timeout parameter is
184              supplied.
185

SASL OPTIONS

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

GSSAPI OPTIONS

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

TLS OPTIONS

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

ENVIRONMENT VARIABLES

424       LDAPNOINIT
425              disable all defaulting
426
427       LDAPCONF
428              path of a configuration file
429
430       LDAPRC basename of ldaprc file in $HOME or $CWD
431
432       LDAP<option-name>
433              Set <option-name> as from ldap.conf
434

FILES

436       /etc/openldap/ldap.conf
437              system-wide ldap configuration file
438
439       $HOME/ldaprc, $HOME/.ldaprc
440              user ldap configuration file
441
442       $CWD/ldaprc
443              local ldap configuration file
444

SEE ALSO

446       ldap(3), ldap_set_option(3), ldap_result(3), openssl(1), sasl(3)
447

AUTHOR

449       Kurt Zeilenga, The OpenLDAP Project
450

ACKNOWLEDGEMENTS

452       OpenLDAP  Software  is developed and maintained by The OpenLDAP Project
453       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
454       versity of Michigan LDAP 3.3 Release.
455
456
457
458OpenLDAP 2.4.50                   2020/04/28                      LDAP.CONF(5)
Impressum