# $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 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 2.1 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. This guide should
-only be used in isolated environments (such as on a single
-host protected by a firewall).
+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 integrity or confidential 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: 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 the (latest)
+{{release}}.
+
.{{S: }}
-+{{B:Unpack the distribution}}.
++{{B: Unpack the distribution}}
-.Pick a directory for the LDAP source to live under and change
-directory there, and untar it. For example:
+.Pick a directory for the LDAP source to live under, change
+directory to there, and unpack the distribution using the
+following commands:
-..{{EX:cd /usr/local/src}}
-..{{EX:gunzip -c openldap-release.tgz | tar xvfB -}}
-..{{EX:cd openldap-release}}
+..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}}
-. You'll have to replace {{F:openldap-release}} with the full
+. 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.
.{{S: }}
-+{{B: Configure the software}}.
++{{B: Review documentation}}
-.You will need to run the {{EX:configure}} script to configure slapd.
+. 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.
-..{{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}} 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.
+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.
-..{{EX:su root -c 'make install'}}
+. Both makes should complete without error.
.{{S: }}
-+{{B:Edit the configuration file}}.
++{{B:Test the build}}.
-.Use this chapter as a brief tutorial. For more details on the
-configuration file, see slapd.conf(5) and chapter 5.
+. To ensure a correct build, you should run the test suite
+(it only takes a few minutes):
-.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:make test}}
-..{{EX:./configure --prefix=/opt/ldap}}
+. Tests which apply to your configuration will run and they
+should pass. Some tests, such as the replication test, may
+be skipped.
-.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}}
+.{{S: }}
++{{B:Install the software}}.
-.This marks the beginning of the database configuration for {{slapd}}.
-Everything you will need to change for this example is located
-after this line.
+. You are now ready to install the software, this usually requires
+{{super-user}} privledges:
-.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:su root -c 'make install'}}
-..{{EX:suffix "dc=my-domain, dc=com"}}
-..{{EX:rootdn "cn=Manager, dc=my-domain, dc=com"}}
+. 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 your favorite editor to edit the provided {{slapd.conf}}(5)
+example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}})
+to contain an LDBM 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: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 stand-alone LDAP server, slapd(8),
+by running the command:
-.You are now ready to start the server by running the command
-{{slapd}}(8):
+..{{EX:su root -c /usr/local/libexec/slapd}}
-..{{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}}.
+. 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 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=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}}.
+
+. 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:
+
+^^ create an LDIF file
+++ run ldapadd
-. 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.
+. Use your favorite editor and create an LDIF file that contains:
-..{{EX:dn: dc=example, dc=net}}
+..{{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 <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 and trailing whitespace from the example.
+
+..{{EX:dn: dc=example,dc=com}}
..{{EX:objectclass: dcObject}}
..{{EX:objectclass: organization}}
-..{{EX:o: Example Network}}
+..{{EX:o: Example Company}}
..{{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.
+..{{EX:}}
+..{{EX:dn: cn=Manager,dc=example,dc=com}}
+..{{EX:objectclass: organizationalRole}}
+..{{EX:cn: Manager}}
-.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}}.
+. Now, you may run {{ldapadd}}(1) to insert these entries into
+your directory.
-..{{EX:ldapadd -x -D 'cn=Manager,dc=example,dc=net' -w secret -f example.ldif}}
+..{{EX:ldapadd -x -D "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f example.ldif}}
-.Where {{F:example.ldif}} is the file you created above.
+. 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:
-Note: Use of transport security services is 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 a later chapter.
+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. You are also
+encouraged to read {{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