# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: A Quick-Start Guide
-The following is a quick start guide to OpenLDAP software,
+The following is a quick start guide to [[DOC_NAME]],
including the stand-alone LDAP daemon, {{slapd}}(8).
-It is meant to step you through the basic steps needed to install
-and configure OpenLDAP software. It should be used in conjunction
-with the other chapters of this document, manual pages, and
-other materials provided with the distribution (e.g. the {{F:INSTALL}}
-document) or on the OpenLDAP web site (in particular, the
-OpenLDAP Software FAQ).
+It is meant to walk you through the basic steps needed to install
+and configure OpenLDAP Software. It should be used in conjunction
+with the other chapters of this document, manual pages, and other
+materials provided with the distribution (e.g. the {{F:INSTALL}}
+document) or on the OpenLDAP web site (in particular, the OpenLDAP
+Software {{TERM:FAQ}}).
-If you intend to run OpenLDAP seriously, you should review the all
-of this document before attempt to install the software.
+If you intend to run OpenLDAP Software seriously, you should review
+all of this document before attempting to install the software.
-Note: This quick start guide does not use strong authentication nor
-any privacy and integrity protection services. These services are
-described in other chapters of the OpenLDAP Administrator's Guide.
+Note: This quick start guide does not use strong authentication
+nor any integrity or confidential protection services. These
+services are described in other chapters of the OpenLDAP Administrator's
+Guide.
.{{S: }}
^{{B: Get the software}}
. You can obtain a copy of the software by following the
-instructions on the OpenLDAP download
-page ({{URL: http://www.openldap.org/software/download/}}).
-It is recommended that new users start with either the (latest)
-{{release}} or the (most) {{stable}} release.
+instructions on the OpenLDAP download page
+({{URL: http://www.openldap.org/software/download/}}). It is
+recommended that new users start with the latest {{release}}.
.{{S: }}
+{{B: Unpack the distribution}}
-.Pick a directory for the LDAP source to live under, change
+.Pick a directory for the source to live under, change
directory to there, and unpack the distribution using the
following commands:
. then relocate yourself into the distribution directory:
-..{{EX:cd openldap-VERSION.tgz}}
+..{{EX:cd openldap-VERSION}}
. You'll have to replace {{F:VERSION}} with the version
name of the release.
.{{S: }}
-+{{B: Review the release documents}}
++{{B: Review documentation}}
-. You should review the {{F:COPYRIGHT}}, {{F:LICENSE}}, {{F:README}}
-and {{F:INSTALL}} documents provided with the distribution.
+. You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}},
+{{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. The {{F:README}} and {{F:INSTALL}} documents provide
-detailed information on prerequisite software and installation
-procedures.
+software.
+
+.{{S: }}
+. You should also review other chapters of this document.
+In particular, the {{SECT:Building and Installing OpenLDAP Software}}
+chapter of this document provides detailed information on prerequisite
+software and installation procedures.
.{{S: }}
+{{B: Run {{EX:configure}}}}
. You will need to run the provided {{EX:configure}} script to
-{{configure}} to the distribution for building on your system. The
-{{EX:configure}} accepts many command line options that enable or
+{{configure}} the distribution for building on your system. The
+{{EX:configure}} script 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}}
-. However, given that you using this guide, we'll assume you'll
-are brave enough to just let {{EX:configure}} to determine
+. However, given that you are using this guide, we'll assume you
+are brave enough to just let {{EX:configure}} determine
what's best:
..{{EX:./configure}}
.{{S: }}
+{{B:Install the software}}.
-. You are now ready to install the software, this usually requires
-{{super-user}} privledges:
+. You are now ready to install the software; this usually requires
+{{super-user}} privileges:
..{{EX:su root -c 'make install'}}
. Everything should now be installed under {{F:/usr/local}} (or
-whatever installation prefix was used by {{EX:configure}}.
+whatever installation prefix was used by {{EX:configure}}).
.{{S: }}
+{{B:Edit the configuration file}}.
. Use your favorite editor to edit the provided {{slapd.conf}}(5)
-example (usually installed as {{F:/usr/local/etc/slapd.conf}}) to
-contain an LDBM database definition of the form:
+example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}})
+to contain a BDB database definition of the form:
-..{{EX:database ldbm}}
-..{{EX:suffix "dc=<MY-DOMAIN>, dc=<COM>"}}
-..{{EX:rootdn "cn=Manager, dc=<MY-DOMAIN, dc=<COM>"}}
+..{{EX:database bdb}}
+..{{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}}
+..{{EX:directory /usr/local/var/openldap-data}}
. Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with
the appropriate domain components of your domain name. For
example, for {{EX:example.com}}, use:
-..{{EX:database ldbm}}
-..{{EX:suffix "dc=example, dc=com"}}
-..{{EX:rootdn "cn=Manager, dc=example, dc=com"}}
+..{{EX:database bdb}}
+..{{EX:suffix "dc=example,dc=com"}}
+..{{EX:rootdn "cn=Manager,dc=example,dc=com"}}
..{{EX:rootpw secret}}
-..{{EX:directory /usr/local/var/openldap-ldbm}}
+..{{EX:directory /usr/local/var/openldap-data}}
.If your domain contains additional components, such as
{{EX:eng.uni.edu.eu}}, use:
-..{{EX:database ldbm}}
-..{{EX:suffix "dc=eng, dc=uni, dc=edu, dc=eu"}}
-..{{EX:rootdn "cn=Manager, dc=eng, dc=uni, dc=edu, dc=eu"}}
+..{{EX:database bdb}}
+..{{EX:suffix "dc=eng,dc=uni,dc=edu,dc=eu"}}
+..{{EX:rootdn "cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu"}}
..{{EX:rootpw secret}}
-..{{EX:directory /usr/local/var/openldap-ldbm}}
+..{{EX:directory /usr/local/var/openldap-data}}
. Details regarding configuring {{slapd}}(8) can be found
-in the {{slapd.conf}}(5) manual page and the
-{{SECT:The slapd Configuration File}} chapter of this
-document.
+in the {{slapd.conf}}(5) manual page and the {{SECT:The slapd
+Configuration File}} chapter of this document. Note that the
+specified directory must exist prior to starting {{slapd}}(8).
+
.{{S: }}
+{{B:Start SLAPD}}.
-. You are now ready to start the stand-alone LDAP server, slapd(8),
+. You are now ready to start the stand-alone LDAP server, {{slapd}}(8),
by running the command:
..{{EX:su root -c /usr/local/libexec/slapd}}
. To check to see if the server is running and configured correctly,
-you can run search it with {{ldapsearch}}(1). By default, ldapsearch
-is installed as {{F:/usr/local/bin/ldapsearch}}:
+you can run a search against 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:
+special characters from being interpreted by the shell. This should return:
..{{EX:dn:}}
-..{{EX:namingContexts: dc=example, dc=com}}
+..{{EX:namingContexts: dc=example,dc=com}}
. Details regarding running {{slapd}}(8) can be found
in the {{slapd}}(8) manual page and the
+{{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 two steps:
+{{ldapadd}} expects input in LDIF form. We'll do it in two steps:
-^^ create LDIF file
+^^ create an LDIF file
++ run ldapadd
. Use your favorite editor and create an LDIF file that contains:
-..{{EX:dn: dc=<MY-DOMAIN>, dc=<COM>}}
+..{{EX:dn: dc=<MY-DOMAIN>,dc=<COM>}}
..{{EX:objectclass: dcObject}}
..{{EX:objectclass: organization}}
..{{EX:o: <MY ORGANIZATION>}}
..{{EX:dc: <MY-DOMAIN>}}
-..{{EX: }}
-..{{EX:dn: cn=Manager, dc=<MY-DOMAIN>, dc=<COM>}}
-..{{EX:objectclass: person}}
+..{{EX:}}
+..{{EX:dn: cn=Manager,dc=<MY-DOMAIN>,dc=<COM>}}
+..{{EX:objectclass: organizationalRole}}
..{{EX:cn: Manager}}
-..{{EX:sn: Manager}}
-. Be sure to replace <MY-DOMAIN> and <COM> with the appropriate domain
-components of your domain name. <MY ORGANIZATION> should be replaced
-with the name of your organization. If you cut and paste, be sure
-to trim any leading whitespace from the example:
+. Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the
+appropriate domain components of your domain name. {{EX:<MY
+ORGANIZATION>}} should be replaced with the name of your organization.
+When you cut and paste, be sure to trim any leading and trailing
+whitespace from the example.
-..{{EX:dn: dc=example, dc=com}}
+..{{EX:dn: dc=example,dc=com}}
..{{EX:objectclass: dcObject}}
..{{EX:objectclass: organization}}
..{{EX:o: Example Company}}
..{{EX:dc: example}}
-..{{EX: }}
-..{{EX:dn: cn=Bob Smith, dc=example, dc=com}}
-..{{EX:objectclass: person}}
-..{{EX:cn: Bob Smith}}
-..{{EX:sn: Smith}}
+..{{EX:}}
+..{{EX:dn: cn=Manager,dc=example,dc=com}}
+..{{EX:objectclass: organizationalRole}}
+..{{EX:cn: Manager}}
. Now, you may run {{ldapadd}}(1) to insert these entries into
your directory.
-..{{EX:ldapadd -D "cn=Manager, dc=<MY-DOMAIN>, dc=<COM>" -W -f example.ldif}}
+..{{EX:ldapadd -x -D "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f example.ldif}}
. Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the
appropriate domain components of your domain name. You will be
prompted for the "{{EX:secret}}" specified in {{F:slapd.conf}}.
For example, for {{EX:example.com}}, use:
-..{{EX:ldapadd -x -D "cn=Manager, dc=example, dc=com" -W -f example.ldif}}
+..{{EX:ldapadd -x -D "cn=Manager,dc=example,dc=com" -W -f example.ldif}}
. where {{F:example.ldif}} is the file you created above.
..{{EX: }}
-. Additional informaton regarding directory creation can be found
+. Additional information regarding directory creation can be found
in the {{SECT:Database Creation and Maintenance Tools}} chapter of
this document.
You are now ready to add more entries using {{ldapadd}}(1) or
another LDAP client, experiment with various configuration options,
-backend arrangements, etc.
+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 the {{SECT:Access Control}} section of the
-{{SECT:The slapd Configuration File}} chapter.
+{{EX:rootdn}} configuration directive). It is highly recommended
+that you establish controls to restrict access to authorized users.
+Access controls are discussed in the {{SECT:Access Control}} section
+of {{SECT:The slapd Configuration File}} chapter. You are also
+encouraged to read the {{SECT:Security Considerations}}, {{SECT:Using
+SASL}} and {{SECT:Using TLS}} sections.
The following chapters provide more detailed information on making,
installing, and running {{slapd}}(8).