# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2001, 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 section provides a quick step-by-step guide to building,
-installing and running {{I:slapd}}. 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 2.1 software,
+including the stand-alone 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
+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}}).
-^ {{B:Get the software}}.
-. {{I:Slapd}} is part of the OpenLDAP distribution, which
-you can retrieve using this URL:
+If you intend to run OpenLDAP seriously, you should review all
+of this document before attempting to install the software.
-..{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
+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.
-.If you are reading this guide, you have probably already done this.
+.{{S: }}
+^{{B: Get the software}}
-+ {{B:Untar the distribution}}.
-.Pick a place for the LDAP source to live, cd
-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 the (latest)
+{{release}}.
-..{{EX:cd /usr/local/src}}
-..{{EX:gunzip -c openldap-release.tgz | tar xvfB -}}
-..{{EX:cd ldap}}
-+ {{B: Configure the software}}.
-. You will need to run the configure script to configure slapd.
+.{{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}}
+
+. You'll have to replace {{F:VERSION}} with the version
+name of the release.
-..{{EX:./configure}}
-. Configure accepts many command line options that enable or disable
-optional features in slapd. Usually the defaults are okay, but you
-may want to change them. To get a complete list of options that configure
-accepts, use the --help option.
+.{{S: }}
++{{B: Review documentation}}
+
+. 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.
+
+.{{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}} 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}}
-. Once OpenLDAP has been configured, it needs to be compiled.
-You'll need to make dependencies and then compile the software.
-For example:
+. 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}}
+
+. 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 /usr/local. This is typically done as root.
-..{{EX:su root}}
-..{{EX:make install}}
+. 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.
+
-+ {{B:Edit the configuration file}}.
-. Use this section as a brief guide. For more details on the configuration
-file, see chapter 5.
+.{{S: }}
++{{B:Install the software}}.
-. Now we need to edit the default configuration file that was installed
-earlier. By default the configuration file for slapd is located at
-{{FILE:/usr/local/etc/openldap/slapd.conf}}. If you specified the --prefix
-option when you ran configure, then replace {{FILE:/usr/local}} with the
-value you gave as the prefix.
+. You are now ready to install the software; this usually requires
+{{super-user}} privileges:
-. For example, if you ran configure as
-..{{EX:./configure --prefix=/opt/ldap}}
-. You would find your configuration file in {{FILE:/opt/ldap/etc/openldap/slapd.conf}}.
+..{{EX:su root -c 'make install'}}
-. Now look in the configuration file for a line that begins with
-..{{EX:database ldbm}}
+. Everything should now be installed under {{F:/usr/local}} (or
+whatever installation prefix was used by {{EX:configure}}).
-. This marks the begining of the database configuration for slapd. Everything
-you will need to change for this example is located after the line begining with
-..{{EX:database ldbm}}
-. Listed below are the default settings for the database in {{FILE:slapd.conf}}.
-Lines that begin with a # are considered to be comments by slapd, they have
-been removed from the listing below to save space.
+.{{S: }}
++{{B:Edit the configuration file}}.
-..{{EX:suffix "dc=my-domain, dc=com"}}
-..{{EX:rootdn "cn=Manager, dc=my-domain, dc=com"}}
+. Use your favorite editor to edit the provided {{slapd.conf}}(5)
+example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}})
+to contain a BDB database definition of the form:
+
+..{{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}}
-. Now we need to replace all of the references to my-domain with the correct
-value. For example, if your domain is 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 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}}
-+ {{B:Create a database}}.
-. This is a two-step process. Step A is to create
-a file (we'll call it myldif) containing the entries you want your database
-to contain. Use the following example as a guide, or see Section 7.3 for
-more details.
+.If your domain contains additional components, such as
+{{EX:eng.uni.edu.eu}}, use:
-..{{EX:dn: dc=example, dc=net}}
-..{{EX:objectclass: dcObject}}
-..{{EX:objectclass: organization}}
-..{{EX:o: Example Net Inc.}}
-..{{EX:dc: example}}
-..
-..{{EX:dn: cn=Bob Smith, dc=example, dc=net}}
-..{{EX:objectclass: person}}
-..{{EX:cn: Bob Smith}}
-..{{EX:sn: Smith}}
+..{{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-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.
-.Remember to replace dc=example,dc=net with the correct values for your
-site, and to put your name instead of Bob's.
+Note: the directory specified must exist prior to starting slapd(8).
-.You can include additional entries and attributes in this file if you want,
-or add them later via LDAP.
-.Step B is to run this file through a tool to create the slapd database.
+.{{S: }}
++{{B:Start SLAPD}}.
-.First we'll need to start slapd.
-To do this just run slapd.
-..{{EX:/usr/local/libexec/slapd}}
+. You are now ready to start the stand-alone LDAP server, slapd(8),
+by running the command:
-.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
-{{I:ldapsearch}}(1).
-By default ldapsearch is installed as {{FILE:/usr/local/bin/ldapsearch}}.
+..{{EX:su root -c /usr/local/libexec/slapd}}
-..{{EX:ldapsearch -x -b "" -s base '(objectclass=*)' namingContexts}}
-.This should return:
+. To check to see if the server is running and configured correctly,
+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 being interpreted by the shell. This should return:
..{{EX:dn:}}
-..{{EX:namingContexts: dc=example, dc=net}}
+..{{EX:namingContexts: dc=example,dc=com}}
-.We can use {{I:ldapadd}}(1) to populate the directory.
-Again remember to replace dc=example,dc=net with the correct values for your
-site. By default ldapadd is installed as {{FILE:/usr/local/bin/ldapadd}}.
+. Details regarding running {{slapd}}(8) can be found
+in the {{slapd}}(8) manual page and the
+{{SECT:Running slapd}} chapter of this document.
-..{{EX:ldapadd -x -D"cn=Manager,dc=example,dc=net" -w secret -f myldif}}
-.Where myldif is the file you made in step 7A above. By default, the database
-files will be created in {{FILE:/usr/local/var/openldap-ldbm}}.
-You may specify an alternate directory via the directory option in the
-{{FILE:slapd.conf}} file.
+.{{S: }}
++{{B:Add initial entries to your directory}}.
-+ {{B:See if it works}}.
-. Now we're ready to try everything out.
+. 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:
-. You can use any LDAP client to do this, but our
-example uses the ldapsearch tool. Remember to replace dc=example,dc=net with
-the correct values for your site.
+^^ create an LDIF file
+++ run ldapadd
-..{{EX:ldapsearch -x -b 'dc=example,dc=net' '(objectclass=*)'}}
+. Use your favorite editor and create an LDIF file that contains:
-. This command will search for and retrieve every entry in the database.
-Note the use of single quotes around the filter, which prevents the "*"
-from being interpreted by the shell.
+..{{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: organizationalRole}}
+..{{EX:cn: Manager}}
+
+. 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. If you cut and paste, be sure
+to trim any leading and trailing 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=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 -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:
-You are now ready to add more entries (e.g., using {{I:ldapadd}}(1) or
-another LDAP client), experiment with various configuration options,
-backend arrangements, etc. Note that by default, the {{I:slapd}} database
-grants {{EX:READ}} access to everybody. So if you want to add or modify
-entries over LDAP, you will have to bind as the rootdn specified in the
-config file (see Section 5.2.2), or change the default access control
-(see Section 5.3).
+..{{EX:ldapadd -x -D "cn=Manager,dc=example,dc=com" -W -f example.ldif}}
-The following sections provide more detailed information on making,
-installing, and running slapd.
+. where {{F:example.ldif}} is the file you created above.
+..{{EX: }}
+. Additional information 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.
+You can use any LDAP client to do this, but our example uses the
+{{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=com' '(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 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).
projects / openldap / blobdiff