-# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2001, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
-H1: A Quick-Start Guide to Running slapd
-
-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.
-
-
-^ {{B:Get the software}}. {{I:Slapd}} is part of the OpenLDAP distribution, which
-you can retrieve using this URL:
-.
-.{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
-.
-.If you are reading this guide, you have probably already done this.
-.
-
-+ {{B:Untar the distribution}}. Pick a place for the LDAP source to live, cd
-there, and untar it. For example:
-.
-.{{EX: cd /usr/local/src}}
-.{{EX: gunzip -c openldap-release.tgz | tar xvfB -}}
-.{{EX: cd ldap}}
-+{{B: Configure the software}}.
-.
-.You will have to edit two files to configure things for your site.
-.
-.{{EX: vi Make-common}}
-.{{EX:vi include/ldapconfig.h.edit}}
-.
-.Read the comments in Make-common and configure things
-.appropriately. If you have the Berkeley DB package installed, or the
-.GDBM package, you should set the LDBMBACKEND variable
-.accordingly. Otherwise, the defaults should be OK to get you started.
-.
-.In the include/ldapconfig.h.edit file, be sure to set the DEFAULT_BASE
-.and LDAPHOST variables to something appropriate for your site.
-.Other than that, the defaults should work OK.
-
-
-+{{B:Install the software}}. From the top level LDAP source directory,
-type:
-.
-.{{EX: su}}
-.{{EX: make install}}
-.
-.Examine the output of this command carefully to ensure everything is
-.installed properly.
-.
-
-
-+{{B:Make a configuration file}}. Create a file called myslapd.conf and
-.enter the following lines into it. See Section 5 for more details on this
-.file.
-.
-.{{EX:referral ldap://ldap.openldap.org}}
-.{{EX:database ldbm}}
-.{{EX:suffix "o=<YOUR ORGANIZATION>, c=US"}}
-.{{EX:rootdn "cn=<YOUR NAME>, o=<YOUR ORGANIZATION>, c=US"}}
-.{{EX:rootpw secret}}
-.
-.Be sure to replace "<YOUR ORGANIZATION>" with the name of your
-.organization and "<YOUR NAME>" with your name. If you are not in
-.the US, replace "US" with your two-letter country code. The rootdn
-.and rootpw lines are only required if later you want to easily add or
-.modify entries via LDAP.
-.
-
-
-+{{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.
-.
-.{{EX:dn: o=<YOUR ORGANIZATION>, c=US}}
-.{{EX:o: <YOUR ORGANIZATION>}}
-.{{EX:objectclass: organization}}
-.
-.{{EX:dn: cn=<YOUR NAME>, o=<YOUR ORGANIZATION>, c=US}}
-.{{EX:cn: <YOUR NAME>}}
-.{{EX:sn: <YOUR LAST NAME>}}
-.{{EX:mail: <YOUR EMAIL ADDRESS>}}
-.{{EX:objectclass: person}}
-.
-.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.
-.
-.{{EX:$(ETCDIR)/ldif2ldbm -f myslapd.conf -i myldif}}
-.
-.Where myslapd.conf is the configuration file you made in step 6, and
-.myldif is the file you made in step 7A above. By default, the database
-.files will be created in /usr/tmp. You may specify an alternate directory
-.via the directory option in the slapd.conf file.
-.
-
-
-+{{B:See if it works}}.You can use any LDAP client to do this, but our
-.example uses the ldapsearch tool.
-.
-.{{EX:ldapsearch -h 127.0.0.1 -b 'o=<YOUR ORGANIZATION>, c=US' 'objectclass=*'}}
-.
-.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.
-.
-.You are now ready to add more entries (e.g., using {{I:ldapadd}}(3) 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).
-.
-
-
-The following sections provide more detailed information on making,
-installing, and running slapd.
-
-PB:
+H1: A Quick-Start 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).
+
+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.
+
+
+.{{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}}
+
+.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.
+
+
+.{{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}} 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:
+
+..{{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
+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}}
+
+
+. 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 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}}
+
+. 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:rootpw secret}}
+..{{EX:directory /usr/local/var/openldap-ldbm}}
+
+.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: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:Start SLAPD}}.
+
+. 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 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=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: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
+
+. 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: <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 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:
+
+..{{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.
+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 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