s/openldap.org/example.com/

[openldap] / doc / guide / admin / intro.sdf

# $OpenLDAP$
# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Introduction to slapd and slurpd

This document describes how to build, configure, and run the stand-alone
{{TERM:LDAP}} daemon, {{slapd}}(8) and the stand-alone LDAP update replication
daemon, {{slurpd}}(8). It is intended for newcomers and experienced
administrators alike. This section provides a basic introduction to
directory services and, in particular, the directory services provided
by {{slapd}}(8).



H2: What is a directory service?

A directory is specialized database optimized for reading, browsing and
searching.  Directories tend to contain descriptive, attribute-based
information and support sophisticated filtering capabilities.  Directories
are generally do not support complicated transaction or roll-back schemes
found in database management systems designed for handling high-volume
complex updates.  Directory updates are typically simple all-or-nothing
changes, if they are allowed at all.  Directories are tuned to give
quick-response to high-volume lookup or search operations. They may have
the ability to replicate information widely in order to increase
availability and reliability, while reducing response time.  When
directory information is replicated, temporary inconsistencies between
the replicas may be OK, as long as they get in sync eventually.

There are many different ways to provide a directory service. Different
methods allow different kinds of information to be stored in the directory,
place different requirements on how that information can be referenced,
queried and updated, how it is protected from unauthorized access, etc.
Some directory services are {{local}}, providing service to a restricted 
context (e.g., the finger service on a single machine). Other services are 
global, providing service to a much broader context (e.g., the entire Internet).
Global services are usually {{distributed}}, meaning that the data they
contain is spread across many machines, all of which cooperate to provide
the directory service. Typically a global service defines a uniform
{{namespace}} which gives the same view of the data no matter where
you are in relation to the data itself.  The Internet {{TERM[expand]DNS}}
is an example of a globally distributed directory service.



H2: What is LDAP?

{{slapd}}'s model for directory service is based on a global directory
model called {{TERM:LDAP}}.  LDAP stands for {{TERM[expand]LDAP}}.
LDAP is a directory access protocol that runs over
{{TERM:TCP}}/{{TERM:IP}}. The nitty-gritty details of LDAP are defined in
{{REF:RFC2251}} "The Lightweight Directory Access Protocol (v3)."
This section gives an overview of LDAP from a user's perspective.

{{What kind of information can be stored in the directory?}}
The LDAP information model is based on {{entries}}. An entry is a
collection of attributes that has a globally-unique
{{TERM[expand]DN}} (DN). 
The DN is used to refer to the entry unambiguously. Each of the 
entry's attributes has a {{type}} and one or more {{values}}. 
The types are typically mnemonic strings, like "{{EX:cn}}" for common
name, or "{{EX:mail}}" for email address. The syntax of values depend
on the attribute type is.  For example, {{EX:cn}} attribute might
be the value {{EX: Babs Jensen}}.  A {{EX:mail}} attribute might
contain the value "{{EX:babs@example.com}}". A {{EX:jpegPhoto}}
attribute would contain a photograph in the JPEG (binary) format.

{{How is the information arranged?}}
In LDAP, directory entries are arranged in a hierarchical tree-like
structure.  Traditionally, this structure reflected the geographic
and/or organizational boundaries.  Entries representing countries
appeared at the top of the tree. Below them are entries representing
states and national organizations. Below them might be entries
representing organizational units, people, printers, documents,
or just about anything else you can think of.  Figure 1.1 shows an
example LDAP directory tree using traditional naming.

!import "intro_tree.gif"; align="center"; \
        title="LDAP directory tree (traditional naming)"
FT[align="Center"] Figure 1.1: LDAP directory tree (traditional naming)

The tree may also be arranged based upon Internet domain names.
Figure 1.2 shows an example using this increasing popular naming approach.

!import "intro_dctree.gif"; align="center"; \
        title="LDAP directory tree (Internet naming)"
FT[align="Center"] Figure 1.2: LDAP directory tree (Internet naming)

In addition, LDAP allows you to control which attributes are required
and allowed in an entry through the use of a special attribute called 
{{objectClass}}.  The values of the {{objectClass}} attribute
determine the {{schema}} rules the entry must obey.

{{How is the information referenced?}}
An entry is referenced by its distinguished name, which is constructed
by taking the name of the entry itself (called the {{TERM[expand]RDN}}
or RDN) and concatenating the names of its ancestor entries. For
example, the entry for Barbara Jensen in the Internet naming example
above has an RDN of {{EX:uid=babs}} and a DN of
{{EX:uid=babs, ou=People, dc=example, dc=com}}". The full DN format is
described in {{REF:RFC2253}}, "Lightweight Directory Access Protocol (v3):
UTF-8 String Representation of Distinguished Names."

{{How is the information accessed?}}
LDAP defines operations for interrogating and updating the directory.
Operations are provided for adding and deleting
an entry from the directory, changing an existing entry, and changing the
name of an entry. Most of the time, though, LDAP is used to search for
information in the directory. The LDAP search operation allows some portion
of the directory to be searched for entries that match some criteria specified
by a search filter. Information can be requested from each entry that matches
the criteria.

For example, you might want to search the entire directory subtree at
and below {{EX:dc=example,dc=com}} for people with the name {{EX:Barbara
Jensen}}, retrieving the email address of each entry found. LDAP lets
you do this easily.  Or you might want to search the entries directly
below the {{EX:st=California, c=US}} entry for organizations with the
string {{EX:Acme}} in their name, and that have a fax number. LDAP lets
you do this too. The next section describes in more detail what you can
do with LDAP and how it might be useful to you.

{{How is the information protected from unauthorized access?}}
Some directory services provide no protection, allowing anyone to see
the information. LDAP provides a method for a client to authenticate,
or prove its identity to a directory server, paving the way for rich
access control to protect the information the server contains.


H2: How does LDAP work?

LDAP directory service is based on a {{client-server}} model. One or more
LDAP servers contain the data making up the LDAP directory tree. An LDAP
client connects to an LDAP server and asks it a question. The server
responds with the answer and/or with a pointer to where the client can
get additional information (typically, another LDAP server). No matter
which LDAP server a client connects to, it sees the same view of the
directory; a name presented to one LDAP server references the same
entry it would at another LDAP server. This is an important feature of
a global directory service, like LDAP.


H2: What is slapd and what can it do?

{{slapd}} is an LDAP directory server that runs on many different
platforms. You can use it to provide a directory service of your very own.
Your directory can contain pretty much anything you want to put in it. You
can connect it to the global LDAP directory service, or run a service all by
yourself. Some of slapd's more interesting features and capabilities include:

{{B:LDAPv2}} and {{B:LDAPv3}}: {{slapd}} supports both version 2 and 3
of the {{TERM[expand]LDAP}}.  {{slapd}} provides support
for the latest features while maintaining interoperability with existing
clients.  {{slapd}} supports both IPv4 and IPv6 protocols.

{{B:{{TERM[expand]SASL}}}}: {{slapd}} supports
strong authentication services through the use of SASL.  {{slapd}}'s
SASL implementation utilizes {{PRD:Cyrus}} software which supports
a number of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI.

{{B:{{TERM[expand]TLS}}}}: {{slapd}} provides privacy and 
integrity protections through the use of TLS (or SSL).  {{slapd}}'s
TLS implementation utilizes {{PRD:OpenSSL}} software.

{{B:Access control}}: {{slapd}} provides a rich and powerful access 
control facility, allowing you to control access to the information 
in your database(s). You can control access to entries based on 
LDAP authorization information, {{TERM:IP}} address, domain name
and other criteria.
{{slapd}} supports both {{static}} and {{dynamic}} access control
information.

{{B:Internationalization}}: {{slapd}} supports Unicode and language
tags.

{{B:Choice of databases}}: {{slapd}} comes with a variety of different
backend databases you can choose from. They include
{{TERM:LDBM}}, a high-performance disk-based {{embedded}} database;
SHELL, a database interface to arbitrary shell scripts; and
PASSWD, a simple password file database.  LDBM utilizes either
{{PRD:BerkeleyDB}} or {{PRD:GDBM}}.

{{B:Multiple database instances}}: {{slapd}} can be configured to serve 
multiple databases at the same time. This means that a single {{slapd}}
server can respond to requests for many logically different portions 
of the LDAP tree, using the same or different backend databases.

{{B:Generic modules API}}: If you require even more customization,
{{slapd}} lets you write your own modules easily. {{slapd}} 
consists of two distinct parts: a front end that handles protocol 
communication with LDAP clients; and modules which handles specific
tasks such as database operations. Because these two pieces communicate
via a well-defined C API, you can write your own customized modules
which extend {{slapd}} in numerous ways.  Also, a number of
{{programmable database}} modules are provided.  These allowing you
to expose external data sources to {{slapd}} using popular programming
languages ({{PRD:Perl}}, {{Shell}}, {{PRD:SQL}}, and {{PRD:TCL}}.

{{B:Threads}}: {{slapd}} is threaded for high performance. A 
single multi-threaded {{slapd}} process handles all incoming 
requests, reducing the amount of system overhead required.

{{B:Replication}}: {{slapd}} can be configured to maintain replica 
copies of its database. This {{single-master/multiple-slave}}
replication scheme is vital in high-volume environments where a
single {{slapd}} just doesn't provide the necessary availability
or reliability.  {{slapd}}
also includes experimental support for {{multi-master}} replication.

{{B:Configuration}}: {{slapd}} is highly configurable through a 
single configuration file which allows you to change just about 
everything you'd ever want to change.  Configuration options have 
reasonable defaults, making your job much easier.

{{slapd}} also has its limitations, of course. The main LDBM
database backend does not handle range queries or negation queries
very well. These features and more will be coming in a future release.



H2: What about X.500?

Technically, LDAP is a directory access protocol to an {{TERM:X.500}}
directory service, the {{TERM:OSI}} directory service.  Initial
LDAP servers were were gateway between LDAP and the X.500
{{TERM[expand]DAP}} ({{TERM:DAP}}).
DAP is a heavyweight protocol that runs over a full OSI protocol stack
and requires a significant amount of computing resources to run.
LDAP is designed to operate over {{TERM:TCP}}/{{TERM:IP}} and provides
most of the functionality of DAP at a much lower cost.

This use of LDAP makes it easy to access the X.500 directory, but still
requires a full X.500 service to make data available to the many LDAP
clients being developed. As with full X.500 DAP clients, a full X.500
DAP server is no small piece of software to run.

The stand-alone LDAP daemon, or {{slapd}}(8), is meant to remove much
of the burden from the server side just as LDAP itself removed much of
the burden from clients. If you are already running an X.500 DAP service
and you want to continue to do so, you can probably stop reading this
guide, which is all about running LDAP via {{slapd}}, without running
X.500 DAP. If you are not running X.500 DAP, want to stop running
X.500 DAP, or have no immediate plans to run X.500 DAP, read on.

It is possible to replicate data from a {{slapd}} directory 
server to a X.500 {{TERM:DSA}}, which allows your organization to
make your data available as part of the global X.500 DAP directory
service on a "read-only" basis. This is discussed in section 11.6.

Another way to make data in a {{slapd}} server available to the
X.500 community would be by using a X.500 DAP to LDAP gateway. At
this time, no such software has been written (to the best of our
knowledge), but hopefully some group will see fit to write such a
gateway.


H2: What is slurpd and what can it do?

{{slurpd}}(8) is a daemon that helps {{slapd}} provide 
replicated service. It is responsible for distributing changes made 
to the master {{slapd}} database out to the various {{slapd}} 
replicas. It frees {{slapd}} from having to worry that some
replicas might be down or unreachable when a change comes through;
{{slurpd}} handles retrying failed requests automatically. 
{{slapd}} and {{slurpd}} communicate through a simple text 
file that is used to log changes.