# $OpenLDAP$
# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.

H1: A Quick-Start Guide to Running slapd

This chapter provides a quick step-by-step guide to building,
installing and running {{slapd}}(8). It is intended to provide
users with a simple and quick way to get started only.
If you intend to run slapd seriously, you should read the rest
of this guide.


Note: This guide does not use strong authentication nor any
privacy and integrity protection services.  These services are
described in detail in later chapters.  This guide should
only be used in isolated environments (such as on a single
host protected by a firewall).


^{{B:Get the software}}.

.{{slapd}} is part of the {{PRD:OpenLDAP}} distribution, which
you can retrieve from {{URL: http://www.openldap.org/software/download/}}
or {{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}.
If you are reading this guide, you have probably already done this.

.{{S: }}
+{{B:Unpack the distribution}}.

.Pick a directory for the LDAP source to live under and change
directory there, and untar it. For example:

..{{EX:cd /usr/local/src}}
..{{EX:gunzip -c openldap-release.tgz | tar xvfB -}}
..{{EX:cd openldap-release}}

. You'll have to replace {{F:openldap-release}} with the full
name of the release.


.{{S: }}
+{{B: Configure the software}}.

.You will need to run the {{EX:configure}} script to configure slapd.

..{{EX:./configure}}

. The {{EX:configure}} accepts many command line options that enable
or disable optional software features.  Usually the defaults are okay,
but you may want to change them.  To get a complete list of options
that {{EX:configure}} accepts, use the {{EX:--help}} option.

..{{EX:./configure --help}}

. Once OpenLDAP has been configured, it needs to be compiled.  
You'll need to construct dependencies and then compile the software
using {{make}}(1) utility.
For example:

..{{EX:make depend}}
..{{EX:make}}

. Once OpenLDAP is compiled you need to install it.  By default OpenLDAP 
is installed into {{F:/usr/local}}.  This is typically done as root.

..{{EX:su root -c 'make install'}}


.{{S: }}
+{{B:Edit the configuration file}}.

.Use this chapter as a brief tutorial.  For more details on the
configuration file, see slapd.conf(5) and chapter 5.

.Now we need to edit the default configuration file that was
installed earlier.  The {{slapd}} configuration file {{slapd.conf}}(5)
for is normally located at {{F:/usr/local/etc/openldap/slapd.conf}}.
If you specified the {{EX:--prefix}} option when you ran {{EX:configure}},
then replace {{F:/usr/local}} with the value you gave as the
prefix.  For example, if you ran {{EX:configure}} as

..{{EX:./configure --prefix=/opt/ldap}}

.You would find your configuration file in
{{F:/opt/ldap/etc/openldap/slapd.conf}}. 
Now look in the configuration file for a line that begins with 

..{{EX:database          ldbm}}

.This marks the begining of the database configuration for {{slapd}}.
Everything you will need to change for this example is located
after this line.

.Listed below are the default settings for the database in
{{F:slapd.conf}}(5).  Lines that begin with a sharp sign ('{{EX:#}}')
are considered to be comments by slapd, they have been removed
from the listing below to save space.  If a line starts with
white space it is considered a continuation of the preceeding
line.

..{{EX:suffix          "dc=my-domain, dc=com"}}
..{{EX:rootdn          "cn=Manager, dc=my-domain, dc=com"}}
..{{EX:rootpw          secret}}
..{{EX:directory       /usr/local/var/openldap-ldbm}}

. Now we need to replace all of the references to {{EX:my-domain}}
and {{EX:com}} with the correct value.  For example, if your domain
is {{EX:example.net}} we might use the following.

..{{EX:suffix          "dc=example, dc=net"}}
..{{EX:rootdn          "cn=Manager, dc=example, dc=net"}}
..{{EX:rootpw          secret}}
..{{EX:directory       /usr/local/var/openldap-ldbm}}

. By default, the database files will be created in
{{F:/usr/local/var/openldap-ldbm}}.
You may specify an alternate directory via the directory option
in the {{F:slapd.conf}} file.  The directory must exist before
you start the server.

Note: Use of rootpw is deprecated in favor of strong authentication
mechanisms.  These are described in later chapters.

.{{S: }}
+{{B:Starting the server}}.

.You are now ready to start the server by running the command
{{slapd}}(8):

..{{EX:/usr/local/libexec/slapd}}

. At this point the LDAP server is up and running, but there isn't
any data in the directory.  You can check to see if the server is
running and your naming context (the {{EX:suffix}} you specified above)
by searching it with {{ldapsearch}}(1).  By default ldapsearch is
installed as {{F:/usr/local/bin/ldapsearch}}.

..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}}

. Note the use of single quotes around command parameters to prevent
special characters from interpreted by the shell.  This should return:

..{{EX:dn:}}
..{{EX:namingContexts: dc=example, dc=net}}


.{{S: }}
+{{B:Create a database}}.

. This is a two-step process. The first step is to create a file
(we'll call it {{F:example.ldif}}) containing the entries you
want your database to contain. Use the following example as a
guide, or see Section 7.3 for more details.

..{{EX:dn: dc=example, dc=net}}
..{{EX:objectclass: dcObject}}
..{{EX:objectclass: organization}}
..{{EX:o: Example Network}}
..{{EX:dc: example}}
..{{EX: }}
..{{EX:dn: cn=Bob Smith, dc=example, dc=net}}
..{{EX:objectclass: person}}
..{{EX:cn: Bob Smith}}
..{{EX:sn: Smith}}

.Remember to replace {{EX:dc=example, dc=net}} with the correct
values for your site, and to put your name instead of Bob's.  You can
include additional entries and attributes in this file if you want,
or add them later via LDAP.

.The second step is to run a tool to add the contents of this file to the
your directory.  We use the tool {{ldapadd}}(1) to populate the directory.
Again remember to replace {{EX:dc=example, dc=net}} with the correct values
for your site.  By default ldapadd is installed as
{{F:/usr/local/bin/ldapadd}}.

..{{EX:ldapadd -x -D 'cn=Manager,dc=example,dc=net' -w secret -f example.ldif}}

.Where {{F:example.ldif}} is the file you created above.

Note: Use of transport security services is recommended when updating
the directory.  These services are described in later chapters.


.{{S: }}
+{{B:See if it works}}.

.Now we're ready to verify the added entries are in your directory.  
You can use any LDAP client to do this, but our example uses the
{{ldapsearch}}(1) tool.  Remember to replace {{EX:dc=example,dc=net}}
with the correct values for your site.

..{{EX:ldapsearch -x -b 'dc=example,dc=net' '(objectclass=*)'}}

.This command will search for and retrieve every entry in the database.

You are now ready to add more entries using {{ldapadd}}(1) or
another LDAP client, experiment with various configuration options,
backend arrangements, etc. Note that by default, the {{slapd}}(8)
database grants {{read access to everybody}} excepting the
{{super-user}} (as specified by the {{EX:rootdn}} configuration
directive).  It is highly recommended that you establish controls
to restrict access to authorized users.  Access controls are discussed
in a later chapter.

The following chapters provide more detailed information on making,
installing, and running {{slapd}}(8).