Align with current quick start guide

doc/guide/admin/quickstart.sdf

@@ -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: 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.
+
 
 .{{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.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.
 
-..{{EX:su root -c 'make install'}}
+. Both makes should complete without error.
 
 
 .{{S: }}
-+{{B:Edit the configuration file}}.
++{{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.
+
 
-.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.
+.{{S: }}
++{{B:Install the software}}.
 
-.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
+. You are now ready to install the software, this usually requires
+{{super-user}} privledges: 
 
-..{{EX:./configure --prefix=/opt/ldap}}
+..{{EX:su root -c 'make install'}}
 
-.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 
+. Everything should now be installed under {{F:/usr/local}} (or
+whatever installation prefix was used by {{EX:configure}}.
 
-..{{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.
+.{{S: }}
++{{B:Edit the configuration file}}.
 
-.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.
+. 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:
 
-..{{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 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 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}}.
+
+. You can use {{ldapadd}}(1) to add entries to your LDAP directory.
+{{ldapadd}} expects input in LDIF form. We'll do it two steps:
+
+^^ create 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 {{Database Creation and Maintenance Tools}} section
-of this document 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: 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.
-
-.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 -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 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).
-