mirror of
https://git.openldap.org/openldap/openldap.git
synced 2026-01-18 04:44:17 -05:00
Align with current quick start guide
This commit is contained in:
Kurt Zeilenga
parent
ec92777753
commit
3c82fc8025
1 changed files with 184 additions and 123 deletions
|
|
@ -2,138 +2,179 @@
|
|||
# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
|
||||
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
|
||||
|
||||
H1: A Quick-Start Guide to Running slapd
|
||||
H1: A Quick-Start Guide
|
||||
|
||||
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.
|
||||
The following is a quick start guide to OpenLDAP software,
|
||||
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).
|
||||
|
||||
Note: This guide does not use strong authentication nor any
|
||||
privacy and integrity protection services. These services are
|
||||
described in detail in later chapters.
|
||||
If you intend to run OpenLDAP seriously, you should review the all
|
||||
of this document before attempt 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.
|
||||
|
||||
^{{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}}.
|
||||
^{{B: Get the software}}
|
||||
|
||||
.Pick a directory for the LDAP source to live under and change
|
||||
directory there, and untar it. For example:
|
||||
. 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.
|
||||
|
||||
..{{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
|
||||
.{{S: }}
|
||||
+{{B: Unpack the distribution}}
|
||||
|
||||
.Pick a directory for the LDAP source to live under, change
|
||||
directory to there, and unpack the distribution using the
|
||||
following commands:
|
||||
|
||||
..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}}
|
||||
|
||||
. then relocate yourself into the distribution directory:
|
||||
|
||||
..{{EX:cd openldap-VERSION.tgz}}
|
||||
|
||||
. You'll have to replace {{F:VERSION}} with the version
|
||||
name of the release.
|
||||
|
||||
|
||||
.{{S: }}
|
||||
+{{B: Configure the software}}.
|
||||
+{{B: Review the release documents}}
|
||||
|
||||
.You will need to run the {{EX:configure}} script to configure slapd.
|
||||
. You should 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.
|
||||
|
||||
..{{EX:./configure}}
|
||||
|
||||
. The {{EX:configure}} accepts many command line options that enable
|
||||
or disable optional software features. Usually the defaults are okay,
|
||||
.{{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
|
||||
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.
|
||||
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:
|
||||
. However, given that you using this guide, we'll assume you'll
|
||||
are brave enough to just let {{EX:configure}} to determine
|
||||
what's best:
|
||||
|
||||
..{{EX:./configure}}
|
||||
|
||||
. Assuming {{EX:configure}} doesn't dislike your system, you can
|
||||
proceed with building the software. If {{EX:configure}} did
|
||||
complain, well, you'll likely need to go to the FAQ Installation
|
||||
Section ({{URL:http://www.openldap.org/faq/}} and/or actually
|
||||
read the {SECT:Building and Installing OpenLDAP Software}}
|
||||
chapter of this document.
|
||||
|
||||
|
||||
.{{S: }}
|
||||
+{{B:Build the software}}.
|
||||
|
||||
. The next step is to build the software. This step has two
|
||||
parts, first we construct dependencies and then we compile the
|
||||
software:
|
||||
|
||||
..{{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.
|
||||
|
||||
. Both makes should complete without error.
|
||||
|
||||
|
||||
.{{S: }}
|
||||
+{{B:Test the build}}.
|
||||
|
||||
. To ensure a correct build, you should run the test suite
|
||||
(it only takes a few minutes):
|
||||
|
||||
..{{EX:make test}}
|
||||
|
||||
. Tests which apply to your configuration will run and they
|
||||
should pass. Some tests, such as the replication test, may
|
||||
be skipped.
|
||||
|
||||
|
||||
.{{S: }}
|
||||
+{{B:Install the software}}.
|
||||
|
||||
. You are now ready to install the software, this usually requires
|
||||
{{super-user}} privledges:
|
||||
|
||||
..{{EX:su root -c 'make install'}}
|
||||
|
||||
. Everything should now be installed under {{F:/usr/local}} (or
|
||||
whatever installation prefix was used by {{EX:configure}}.
|
||||
|
||||
|
||||
.{{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 the
|
||||
{{SECT:The slapd Configuration File}} chapter of this document.
|
||||
. 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:
|
||||
|
||||
.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 beginning 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 preceding
|
||||
line.
|
||||
|
||||
..{{EX:suffix "dc=my-domain, dc=com"}}
|
||||
..{{EX:rootdn "cn=Manager, dc=my-domain, dc=com"}}
|
||||
..{{EX:database ldbm}}
|
||||
..{{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.
|
||||
. 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:suffix "dc=example, dc=net"}}
|
||||
..{{EX:rootdn "cn=Manager, dc=example, dc=net"}}
|
||||
..{{EX:database ldbm}}
|
||||
..{{EX:suffix "dc=example, dc=com"}}
|
||||
..{{EX:rootdn "cn=Manager, dc=example, dc=com"}}
|
||||
..{{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.
|
||||
.If your domain contains additional components, such as
|
||||
{{EX:eng.uni.edu.eu}}, use:
|
||||
|
||||
Note: Use of rootpw is deprecated in favor of strong authentication
|
||||
mechanisms. These are described in later chapters.
|
||||
..{{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:rootpw secret}}
|
||||
..{{EX:directory /usr/local/var/openldap-ldbm}}
|
||||
|
||||
. 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.
|
||||
|
||||
.{{S: }}
|
||||
+{{B:Starting the server}}.
|
||||
+{{B:Start SLAPD}}.
|
||||
|
||||
.You are now ready to start the server by running the command
|
||||
{{slapd}}(8):
|
||||
. You are now ready to start the stand-alone LDAP server, slapd(8),
|
||||
by running the command:
|
||||
|
||||
..{{EX:/usr/local/libexec/slapd}}
|
||||
..{{EX:su root -c /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}}.
|
||||
|
||||
. 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}}:
|
||||
|
||||
..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}}
|
||||
|
||||
|
|
@ -141,71 +182,91 @@ installed as {{F:/usr/local/bin/ldapsearch}}.
|
|||
special characters from interpreted by the shell. This should return:
|
||||
|
||||
..{{EX:dn:}}
|
||||
..{{EX:namingContexts: dc=example, dc=net}}
|
||||
..{{EX:namingContexts: dc=example, dc=com}}
|
||||
|
||||
. Details regarding running {{slapd}}(8) can be found
|
||||
in the {{slapd}}(8) manual page and the
|
||||
{{SECT:Running slapd}} chapter of this document.
|
||||
|
||||
|
||||
.{{S: }}
|
||||
+{{B:Create a database}}.
|
||||
+{{B:Add initial entries to your directory}}.
|
||||
|
||||
. 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 {{Database Creation and Maintenance Tools}} section
|
||||
of this document for more details.
|
||||
. You can use {{ldapadd}}(1) to add entries to your LDAP directory.
|
||||
{{ldapadd}} expects input in LDIF form. We'll do it two steps:
|
||||
|
||||
..{{EX:dn: dc=example, dc=net}}
|
||||
^^ create LDIF file
|
||||
++ run ldapadd
|
||||
|
||||
. Use your favorite editor and create an LDIF file that contains:
|
||||
|
||||
..{{EX:dn: dc=<MY-DOMAIN>, dc=<COM>}}
|
||||
..{{EX:objectclass: dcObject}}
|
||||
..{{EX:objectclass: organization}}
|
||||
..{{EX:o: Example Network}}
|
||||
..{{EX:o: <MY ORGANIZATION>}}
|
||||
..{{EX:dc: <MY-DOMAIN>}}
|
||||
..{{EX: }}
|
||||
..{{EX:dn: cn=Manager, dc=<MY-DOMAIN>, dc=<COM>}}
|
||||
..{{EX:objectclass: person}}
|
||||
..{{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:
|
||||
|
||||
..{{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=net}}
|
||||
..{{EX:dn: cn=Bob Smith, dc=example, dc=com}}
|
||||
..{{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.
|
||||
. Now, you may run {{ldapadd}}(1) to insert these entries into
|
||||
your directory.
|
||||
|
||||
.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 -D "cn=Manager, dc=<MY-DOMAIN>, dc=<COM>" -W -f example.ldif}}
|
||||
|
||||
..{{EX:ldapadd -x -D 'cn=Manager,dc=example,dc=net' -w secret -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:
|
||||
|
||||
.Where {{F:example.ldif}} is the file you created above.
|
||||
|
||||
Note: Use of strong authentication and transport security services
|
||||
is highly recommended when updating the directory. These services
|
||||
are described in later chapters.
|
||||
..{{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
|
||||
in the {{SECT:Database Creation and Maintenance Tools}} chapter of
|
||||
this document.
|
||||
|
||||
.{{S: }}
|
||||
+{{B:See if it works}}.
|
||||
|
||||
.Now we're ready to verify the added entries are in your directory.
|
||||
. 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.
|
||||
{{ldapsearch}}(1) tool. Remember to replace {{EX:dc=example,dc=com}}
|
||||
with the correct values for your site:
|
||||
|
||||
..{{EX:ldapsearch -x -b 'dc=example,dc=net' '(objectclass=*)'}}
|
||||
..{{EX:ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'}}
|
||||
|
||||
.This command will search for and retrieve every entry in the database.
|
||||
. 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 the {{SECT:Access Control}} section of the
|
||||
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.
|
||||
|
||||
The following chapters provide more detailed information on making,
|
||||
installing, and running {{slapd}}(8).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue