2 # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: A Quick-Start Guide
7 The following is a quick start guide to OpenLDAP software,
8 including the stand-alone LDAP daemon, {{slapd}}(8).
10 It is meant to step you through the basic steps needed to install
11 and configure OpenLDAP software. It should be used in conjunction
12 with the other chapters of this document, manual pages, and
13 other materials provided with the distribution (e.g. the {{F:INSTALL}}
14 document) or on the OpenLDAP web site (in particular, the
15 OpenLDAP Software FAQ).
17 If you intend to run OpenLDAP seriously, you should review the all
18 of this document before attempt to install the software.
20 Note: This quick start guide does not use strong authentication nor
21 any privacy and integrity protection services. These services are
22 described in other chapters of the OpenLDAP Administrator's Guide.
26 ^{{B: Get the software}}
28 . You can obtain a copy of the software by following the
29 instructions on the OpenLDAP download
30 page ({{URL: http://www.openldap.org/software/download/}}).
31 It is recommended that new users start with either the (latest)
32 {{release}} or the (most) {{stable}} release.
36 +{{B: Unpack the distribution}}
38 .Pick a directory for the LDAP source to live under, change
39 directory to there, and unpack the distribution using the
42 ..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}}
44 . then relocate yourself into the distribution directory:
46 ..{{EX:cd openldap-VERSION}}
48 . You'll have to replace {{F:VERSION}} with the version
53 +{{B: Review the release documents}}
55 . You should review the {{F:COPYRIGHT}}, {{F:LICENSE}}, {{F:README}}
56 and {{F:INSTALL}} documents provided with the distribution.
57 The {{F:COPYRIGHT}} and {{F:LICENSE}} provide information on
58 acceptable use, copying, and limitation of warranty of OpenLDAP
59 software. The {{F:README}} and {{F:INSTALL}} documents provide
60 detailed information on prerequisite software and installation
65 +{{B: Run {{EX:configure}}}}
67 . You will need to run the provided {{EX:configure}} script to
68 {{configure}} to the distribution for building on your system. The
69 {{EX:configure}} script accepts many command line options that enable or
70 disable optional software features. Usually the defaults are okay,
71 but you may want to change them. To get a complete list of options
72 that {{EX:configure}} accepts, use the {{EX:--help}} option:
74 ..{{EX:./configure --help}}
76 . However, given that you using this guide, we'll assume you'll
77 are brave enough to just let {{EX:configure}} to determine
82 . Assuming {{EX:configure}} doesn't dislike your system, you can
83 proceed with building the software. If {{EX:configure}} did
84 complain, well, you'll likely need to go to the FAQ Installation
85 Section ({{URL:http://www.openldap.org/faq/}} and/or actually
86 read the {{SECT:Building and Installing OpenLDAP Software}}
87 chapter of this document.
91 +{{B:Build the software}}.
93 . The next step is to build the software. This step has two
94 parts, first we construct dependencies and then we compile the
101 . Both makes should complete without error.
105 +{{B:Test the build}}.
107 . To ensure a correct build, you should run the test suite
108 (it only takes a few minutes):
112 . Tests which apply to your configuration will run and they
113 should pass. Some tests, such as the replication test, may
118 +{{B:Install the software}}.
120 . You are now ready to install the software, this usually requires
121 {{super-user}} privledges:
123 ..{{EX:su root -c 'make install'}}
125 . Everything should now be installed under {{F:/usr/local}} (or
126 whatever installation prefix was used by {{EX:configure}}.
130 +{{B:Edit the configuration file}}.
132 . Use your favorite editor to edit the provided {{slapd.conf}}(5)
133 example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}})
134 to contain an LDBM database definition of the form:
136 ..{{EX:database ldbm}}
137 ..{{EX:suffix "dc=<MY-DOMAIN>, dc=<COM>"}}
138 ..{{EX:rootdn "cn=Manager, dc=<MY-DOMAIN>, dc=<COM>"}}
139 ..{{EX:rootpw secret}}
140 ..{{EX:directory /usr/local/var/openldap-ldbm}}
142 . Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with
143 the appropriate domain components of your domain name. For
144 example, for {{EX:example.com}}, use:
146 ..{{EX:database ldbm}}
147 ..{{EX:suffix "dc=example, dc=com"}}
148 ..{{EX:rootdn "cn=Manager, dc=example, dc=com"}}
149 ..{{EX:rootpw secret}}
150 ..{{EX:directory /usr/local/var/openldap-ldbm}}
152 .If your domain contains additional components, such as
153 {{EX:eng.uni.edu.eu}}, use:
155 ..{{EX:database ldbm}}
156 ..{{EX:suffix "dc=eng, dc=uni, dc=edu, dc=eu"}}
157 ..{{EX:rootdn "cn=Manager, dc=eng, dc=uni, dc=edu, dc=eu"}}
158 ..{{EX:rootpw secret}}
159 ..{{EX:directory /usr/local/var/openldap-ldbm}}
161 . Details regarding configuring {{slapd}}(8) can be found
162 in the {{slapd.conf}}(5) manual page and the
163 {{SECT:The slapd Configuration File}} chapter of this
169 . You are now ready to start the stand-alone LDAP server, slapd(8),
170 by running the command:
172 ..{{EX:su root -c /usr/local/libexec/slapd}}
175 . To check to see if the server is running and configured correctly,
176 you can run a search against it with {{ldapsearch}}(1). By default,
177 ldapsearch is installed as {{F:/usr/local/bin/ldapsearch}}:
179 ..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}}
181 . Note the use of single quotes around command parameters to prevent
182 special characters from being interpreted by the shell. This should return:
185 ..{{EX:namingContexts: dc=example, dc=com}}
187 . Details regarding running {{slapd}}(8) can be found
188 in the {{slapd}}(8) manual page and the
189 {{SECT:Running slapd}} chapter of this document.
193 +{{B:Add initial entries to your directory}}.
195 . You can use {{ldapadd}}(1) to add entries to your LDAP directory.
196 {{ldapadd}} expects input in LDIF form. We'll do it in two steps:
198 ^^ create an LDIF file
201 . Use your favorite editor and create an LDIF file that contains:
203 ..{{EX:dn: dc=<MY-DOMAIN>, dc=<COM>}}
204 ..{{EX:objectclass: dcObject}}
205 ..{{EX:objectclass: organization}}
206 ..{{EX:o: <MY ORGANIZATION>}}
207 ..{{EX:dc: <MY-DOMAIN>}}
209 ..{{EX:dn: cn=Manager, dc=<MY-DOMAIN>, dc=<COM>}}
210 ..{{EX:objectclass: person}}
214 . Be sure to replace <MY-DOMAIN> and <COM> with the appropriate domain
215 components of your domain name. <MY ORGANIZATION> should be replaced
216 with the name of your organization. If you cut and paste, be sure
217 to trim any leading whitespace from the example:
219 ..{{EX:dn: dc=example, dc=com}}
220 ..{{EX:objectclass: dcObject}}
221 ..{{EX:objectclass: organization}}
222 ..{{EX:o: Example Company}}
225 ..{{EX:dn: cn=Bob Smith, dc=example, dc=com}}
226 ..{{EX:objectclass: person}}
227 ..{{EX:cn: Bob Smith}}
230 . Now, you may run {{ldapadd}}(1) to insert these entries into
233 ..{{EX:ldapadd -D "cn=Manager, dc=<MY-DOMAIN>, dc=<COM>" -W -f example.ldif}}
235 . Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the
236 appropriate domain components of your domain name. You will be
237 prompted for the "{{EX:secret}}" specified in {{F:slapd.conf}}.
238 For example, for {{EX:example.com}}, use:
240 ..{{EX:ldapadd -x -D "cn=Manager, dc=example, dc=com" -W -f example.ldif}}
242 . where {{F:example.ldif}} is the file you created above.
244 . Additional informaton regarding directory creation can be found
245 in the {{SECT:Database Creation and Maintenance Tools}} chapter of
249 +{{B:See if it works}}.
251 . Now we're ready to verify the added entries are in your directory.
252 You can use any LDAP client to do this, but our example uses the
253 {{ldapsearch}}(1) tool. Remember to replace {{EX:dc=example,dc=com}}
254 with the correct values for your site:
256 ..{{EX:ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'}}
258 . This command will search for and retrieve every entry in the database.
260 You are now ready to add more entries using {{ldapadd}}(1) or
261 another LDAP client, experiment with various configuration options,
262 backend arrangements, etc.
264 Note that by default, the {{slapd}}(8) database grants {{read access
265 to everybody}} excepting the {{super-user}} (as specified by the
266 {{EX:rootdn}} configuration directive). It is highly recommended that
267 you establish controls to restrict access to authorized users. Access
268 controls are discussed in the {{SECT:Access Control}} section of the
269 {{SECT:The slapd Configuration File}} chapter.
271 The following chapters provide more detailed information on making,
272 installing, and running {{slapd}}(8).