H1: The Proxy Cache Engine
-LDAP servers typically hold one or more subtrees of a DIT. Replica
-(or shadow) servers hold shadow copies of entries held by one or
-more master servers. Changes are propagated from the master server
-to replica (slave) servers using LDAP Sync or {{slurpd}}(8). An
-LDAP cache is a special type of replica which holds entries
-corresponding to search filters instead of subtrees.
+{{TERM:LDAP}} servers typically hold one or more subtrees of a
+{{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
+entries held by one or more master servers. Changes are propagated
+from the master server to replica (slave) servers using LDAP Sync
+or {{slurpd}}(8). An LDAP cache is a special type of replica which
+holds entries corresponding to search filters instead of subtrees.
H2: Overview
H1: A Quick-Start Guide
The following is a quick start guide to [[DOC_NAME]],
-including the stand-alone LDAP daemon, {{slapd}}(8).
+including the stand-alone {{TERM:LDAP}} daemon, {{slapd}}(8).
It is meant to walk you through the basic steps needed to install
and configure OpenLDAP Software. It should be used in conjunction
^{{B: Get the software}}
. You can obtain a copy of the software by following the
-instructions on the OpenLDAP download page
+instructions on the OpenLDAP Software download page
({{URL: http://www.openldap.org/software/download/}}). It is
recommended that new users start with the latest {{release}}.
{{F:README}} and {{F:INSTALL}} documents provided with the distribution.
The {{F:COPYRIGHT}} and {{F:LICENSE}} provide information on
acceptable use, copying, and limitation of warranty of OpenLDAP
-software.
+Software.
.{{S: }}
. You should also review other chapters of this document.
+{{B:Add initial entries to your directory}}.
. You can use {{ldapadd}}(1) to add entries to your LDAP directory.
-{{ldapadd}} expects input in LDIF form. We'll do it in two steps:
+{{ldapadd}} expects input in {{TERM:LDIF}} form. We'll do it in two
+steps:
^^ create an LDIF file
++ run ldapadd
> -h <URLs>
This option specifies alternative listener configurations. The
-default is {{EX:ldap:///}} which implies LDAP over TCP on all
-interfaces on the default LDAP port 389. You can specify
-specific host-port pairs or other protocol schemes (such as
-ldaps:// or ldapi://). For example,
-{{EX:-h "ldaps:// ldap://127.0.0.1:666"}} will create
-two listeners: one for LDAP over SSL on all interfaces on
-the default LDAP/SSL port 636, and one for LDAP over TCP on
-the {{EX:localhost}} ({{loopback}}) interface on port 666.
-Hosts may be specified using IPv4 dotted-decimal form or
-using host names. Port values must be numeric.
+default is {{EX:ldap:///}} which implies {{TERM:LDAP}} over
+{{TERM:TCP}} on all interfaces on the default LDAP port 389. You
+can specify specific host-port pairs or other protocol schemes (such
+as {{EX:ldaps://}} or {{EX:ldapi://}}). For example, {{EX:-h
+"ldaps:// ldap://127.0.0.1:666"}} will create two listeners: one
+for the (non-standard) {{EX:ldaps://}} scheme on all interfaces on
+the default {{EX:ldaps://}} port 636, and one for the standard
+{{EX:ldap://}} scheme on the {{EX:localhost}} ({{loopback}}) interface
+on port 666. Hosts may be specified using using hostnames or
+{{TERM:IPv4}} or {{TERM:IPv6}} addresses. Port values must be
+numeric.
> -n <service-name>
debugging levels are
!block table; colaligns="RL"; align=Center; \
- title="Table 6.1: Debugging Levels"
+ title="Table 7.1: Debugging Levels"
Level Description
-1 enable all debugging
0 no debugging
H2: Stopping slapd
-To kill off slapd safely, you should give a command like this
+To kill off {{slapd}}(8) safely, you should give a command like this
> kill -INT `cat /usr/local/var/slapd.pid`
There are several industry standard authentication mechanisms that
can be used with SASL, including {{TERM:GSSAPI}} for {{TERM:Kerberos}}
-V, DIGEST-MD5, and PLAIN and EXTERNAL for use with {{TERM[expand]TLS}}
-(TLS).
+V, {{TERM:DIGEST-MD5}}, and {{TERM:PLAIN}} and {{TERM:EXTERNAL}}
+for use with {{TERM[expand]TLS}} (TLS).
The standard client tools provided with OpenLDAP Software, such as
{{ldapsearch}}(1) and {{ldapmodify}}(1), will by default attempt
-to authenticate the user to the {{slapd}}(8) server using SASL.
-Basic authentication service can be set up by the LDAP administrator
-with a few steps, allowing users to be authenticated to the slapd
-server as their LDAP entry. With a few extra steps, some users and
-services can be allowed to exploit SASL's proxy authorization
-feature, allowing them to authenticate themselves and then switch
-their identity to that of another user or service.
+to authenticate the user to the {{TERM:LDAP}} directory server using
+SASL. Basic authentication service can be set up by the LDAP
+administrator with a few steps, allowing users to be authenticated
+to the slapd server as their LDAP entry. With a few extra steps,
+some users and services can be allowed to exploit SASL's proxy
+authorization feature, allowing them to authenticate themselves and
+then switch their identity to that of another user or service.
This chapter assumes you have read {{Cyrus SASL for System
Administrators}}, provided with the {{PRD:Cyrus SASL}}
The DIGEST-MD5 mechanism is the mandatory-to-implement authentication
mechanism for LDAPv3. Though DIGEST-MD5 is not a strong authentication
mechanism in comparison with trusted third party authentication
-systems (such as Kerberos or public key systems), it does offer
-significant protections against a number of attacks. Unlike the
-CRAM-MD5 mechanism, it prevents chosen plaintext attacks. DIGEST-MD5
-is favored over the use of plaintext password mechanisms. The
-CRAM-MD5 mechanism is deprecated in favor of DIGEST-MD5. Use of
-{{SECT:DIGEST-MD5}} is discussed below.
-
-The GSSAPI mechanism utilizes Kerberos V to provide secure
-authentication services. The KERBEROS_V4 mechanism is available
-for those using Kerberos IV. Kerberos is viewed as a secure,
-distributed authentication system suitable for both small and large
-enterprises. Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}} are
-discussed below.
+systems (such as {{TERM:Kerberos}} or public key systems), it does
+offer significant protections against a number of attacks. Unlike
+the {{TERM:CRAM-MD5}} mechanism, it prevents chosen plaintext
+attacks. DIGEST-MD5 is favored over the use of plaintext password
+mechanisms. The CRAM-MD5 mechanism is deprecated in favor of
+DIGEST-MD5. Use of {{SECT:DIGEST-MD5}} is discussed below.
+
+The GSSAPI mechanism utilizes {{TERM:GSS-API}} {{TERM:Kerberos}} V
+to provide secure authentication services. The KERBEROS_V4 mechanism
+is available for those using Kerberos IV. Kerberos is viewed as a
+secure, distributed authentication system suitable for both small
+and large enterprises. Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}}
+are discussed below.
The EXTERNAL mechanism utilizes authentication services provided
by lower level network services such as {{TERM:TLS}} (TLS). When
H2: SASL Authentication
Getting basic SASL authentication running involves a few steps.
-The first step configures your slapd server environment so
-that it can communicate with client programs using the security
-system in place at your site. This usually involves setting up a
-service key, a public key, or other form of secret. The second step
-concerns mapping authentication identities to LDAP DN's, which
+The first step configures your slapd server environment so that it
+can communicate with client programs using the security system in
+place at your site. This usually involves setting up a service key,
+a public key, or other form of secret. The second step concerns
+mapping authentication identities to LDAP {{TERM:DN}}'s, which
depends on how entries are laid out in your directory. An explanation
of the first step will be given in the next section using Kerberos
V4 as an example mechanism. The steps necessary for your site's
authentication mechanism will be similar, but a guide to every
mechanism available under SASL is beyond the scope of this chapter.
-The second step is described in the section
-{{SECT:Mapping Authentication Identities}}.
+The second step is described in the section {{SECT:Mapping
+Authentication Identities}}.
H3: GSSAPI
H2: Distributed Schema Files
-OpenLDAP is distributed with a set of schema specifications for
+OpenLDAP Software is distributed with a set of schema specifications for
your use. Each set is defined in a file suitable for inclusion
(using the {{EX:include}} directive) in your {{slapd.conf}}(5)
file. These schema files are normally installed in the
> include /usr/local/etc/openldap/schema/inetorgperson.schema
Additional files may be available. Please consult the OpenLDAP
-FAQ ({{URL:http://www.openldap.org/faq/}}).
+{{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}).
Note: You should not modify any of the schema items defined
in provided files.
{{slapd}}(8) returns the first listed name when returning results.
The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
-(UTF-8 encoded Unicode) syntax. The syntax is specified by OID
-(1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
-syntax). A length recommendation of 32768 is specified. Servers
-should support values of this length, but may support longer values
-The field does NOT specify a size constraint, so is ignored on
-servers (such as slapd) which don't impose such size limits. In
-addition, the equality and substring matching uses case ignore
-rules. Below are tables listing commonly used syntax and
-matching rules (OpenLDAP supports these and many more).
+({{TERM:UTF-8}} encoded Unicode) syntax. The syntax is
+specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the
+directoryString syntax). A length recommendation of 32768 is
+specified. Servers should support values of this length, but may
+support longer values The field does NOT specify a size constraint,
+so is ignored on servers (such as slapd) which don't impose such
+size limits. In addition, the equality and substring matching uses
+case ignore rules. Below are tables listing commonly used syntax
+and matching rules ({{slapd}}(8) supports these and many more).
!block table; align=Center; coltags="EX,EX,N"; \
title="Table 8.3: Commonly Used Syntaxes"
Name OID Description
boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
directoryString 1.3.6.1.4.1.1466.115.121.1.15 Unicode (UTF-8) string
-distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP DN
+distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP {{TERM:DN}}
integer 1.3.6.1.4.1.1466.115.121.1.27 integer
numericString 1.3.6.1.4.1.1466.115.121.1.36 numeric string
OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
H2: Transferring Schema
Since the {{slapd.conf}}(5) schema directives use {{REF:RFC4512}}
-format values, you can extract schema elements published by
-any LDAPv3 server and easily construct directives for use with
+format values, you can extract schema elements published by any
+{{TERM:LDAPv3}} server and easily construct directives for use with
{{slapd}}(8).
LDAPv3 servers publish schema elements in special {{subschema}}
or consult the table below. The possible values for <integer> are:
!block table; colaligns="RL"; align=Center; \
- title="Table 5.1: Debugging Levels"
+ title="Table 6.1: Debugging Levels"
Level Description
-1 enable all debugging
0 no debugging
This directive marks the beginning of a backend declaration.
{{EX:<type>}} should be one of the
-supported backend types listed in Table 5.2.
+supported backend types listed in Table 6.2.
!block table; align=Center; coltags="EX,N"; \
title="Table 5.2: Database Backends"
This directive marks the beginning of a database instance
declaration.
{{EX:<type>}} should be one of the
-supported backend types listed in Table 5.2.
+supported backend types listed in Table 6.2.
\Example:
The following table summarizes entity specifiers:
!block table; align=Center; coltags="EX,N"; \
- title="Table 5.3: Access Entity Specifiers"
+ title="Table 6.3: Access Entity Specifiers"
Specifier|Entities
*|All, including anonymous and authenticated users
anonymous|Anonymous (non-authenticated) users
The kind of <access> granted can be one of the following:
!block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
- title="Table 5.4: Access Levels"
+ title="Table 6.4: Access Levels"
Level Privileges Description
none =0 no access
disclose =d needed for information disclosure on error
H1: LDAP Sync Replication
-The LDAP Sync replication engine, syncrepl for short, is a consumer-side
-replication engine that enables the consumer LDAP server to maintain
-a shadow copy of a DIT fragment. A syncrepl engine resides at the
-consumer-side as one of the {{slapd}} (8) threads. It creates and
-maintains a consumer replica by connecting to the replication
-provider to perform the initial DIT content load followed either
-by periodic content polling or by timely updates upon content
-changes.
+The LDAP Sync Replication engine, {{syncrepl}} for short, is a
+consumer-side replication engine that enables the consumer {{TERM:LDAP}}
+server to maintain a shadow copy of a DIT fragment. A syncrepl
+engine resides at the consumer-side as one of the {{slapd}} (8)
+threads. It creates and maintains a consumer replica by connecting
+to the replication provider to perform the initial {{TERM:DIT}}
+content load followed either by periodic content polling or by
+timely updates upon content changes.
Syncrepl uses the LDAP Content Synchronization (or LDAP Sync for
short) protocol as the replica synchronization protocol. It provides
OpenLDAP clients and servers are capable of using the
{{TERM[expand]TLS}} ({{TERM:TLS}}) framework to provide
integrity and confidentiality protections and to support
-LDAP authentication using the {{TERM:SASL}} EXTERNAL mechanism.
+LDAP authentication using the {{TERM:SASL}} {{TERM:EXTERNAL}} mechanism.
TLS is defined in {{REF:RFC4346}}.
H2: TLS Certificates
TLS uses {{TERM:X.509}} certificates to carry client and server
-identities. All servers are required to have valid certificates,
-whereas client certificates are optional. Clients must have a
+identities. All servers are required to have valid certificates,
+whereas client certificates are optional. Clients must have a
valid certificate in order to authenticate via SASL EXTERNAL.
For more information on creating and managing certificates,
see the {{PRD:OpenSSL}} documentation.
H3: Server Certificates
-The DN of a server certificate must use the CN attribute
-to name the server, and the {{EX:CN}} must carry the server's
-fully qualified domain name. Additional alias names and wildcards
-may be present in the {{EX:subjectAltName}} certificate extension.
-More details on server certificate names are in {{REF:RFC4513}}.
+The {{TERM:DN}} of a server certificate must use the {{EX:CN}}
+attribute to name the server, and the {{EX:CN}} must carry the
+server's fully qualified domain name. Additional alias names and
+wildcards may be present in the {{EX:subjectAltName}} certificate
+extension. More details on server certificate names are in
+{{REF:RFC4513}}.
H3: Client Certificates
H4: TLSRandFile <filename>
This directive specifies the file to obtain random bits from when
-{{EX:/dev/urandom}} is not available. If the
-system provides {{EX:/dev/urandom}} then this option is not needed,
-otherwise a source of random data must be configured.
-Some systems (e.g. Linux)
-provide {{EX:/dev/urandom}} by default, while others (e.g. Solaris)
+{{FILE:/dev/urandom}} is not available. If the system provides
+{{FILE:/dev/urandom}} then this option is not needed, otherwise a
+source of random data must be configured. Some systems (e.g. Linux)
+provide {{FILE:/dev/urandom}} by default, while others (e.g. Solaris)
require the installation of a patch to provide it, and others may
not support it at all. In the latter case, EGD or PRNGD should be
installed, and this directive should specify the name of the EGD/PRNGD
-socket. The environment variable {{EX:RANDFILE}} can also be used to specify
-the filename. Also, in the absence of these options, the {{EX:.rnd}}
-file in the slapd user's home directory may be used if it exists. To
-use the {{EX:.rnd}} file, just create the file and copy a few hundred
-bytes of arbitrary data into the file. The file is only used to
-provide a seed for the pseudo-random number generator, and it doesn't
-need very much data to work.
+socket. The environment variable {{EX:RANDFILE}} can also be used
+to specify the filename. Also, in the absence of these options, the
+{{EX:.rnd}} file in the slapd user's home directory may be used if
+it exists. To use the {{EX:.rnd}} file, just create the file and
+copy a few hundred bytes of arbitrary data into the file. The file
+is only used to provide a seed for the pseudo-random number generator,
+and it doesn't need very much data to work.
H4: TLSEphemeralDHParamFile <filename>
-This directive specifies the file that contains parameters for Diffie-Hellman
-ephemeral key exchange. This is required in order to use a DSA certificate on
-the server side (i.e. {{EX:TLSCertificateKeyFile}} points to a DSA key).
-Multiple sets of parameters can be included in the file; all of them will
-be processed. Parameters can be generated using the following command
+This directive specifies the file that contains parameters for
+Diffie-Hellman ephemeral key exchange. This is required in order
+to use a DSA certificate on the server side (i.e.
+{{EX:TLSCertificateKeyFile}} points to a DSA key). Multiple sets
+of parameters can be included in the file; all of them will be
+processed. Parameters can be generated using the following command
> openssl dhparam [-dsaparam] -out <filename> <numbits>
individual users in their {{.ldaprc}} files.
The LDAP Start TLS operation is used in LDAP to initiate TLS
-negotatation. All OpenLDAP command line tools support a {{E:-Z}}
-and {{E:-ZZ}} flag to indicate whether a Start TLS operation is to
+negotatation. All OpenLDAP command line tools support a {{EX:-Z}}
+and {{EX:-ZZ}} flag to indicate whether a Start TLS operation is to
be issued. The latter flag indicates that the tool is to cease
processing if TLS cannot be started while the former allows the
command to continue.
projects / openldap / commitdiff