2 # Copyright 1999-2001, 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 2.1 software,
8 including the stand-alone LDAP daemon, {{slapd}}(8).
10 It is meant to walk 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 {{TERM:FAQ}}).
17 If you intend to run OpenLDAP seriously, you should review all
18 of this document before attempting to install the software.
20 Note: This quick start guide does not use strong authentication
21 nor any integrity or confidential protection services. These
22 services are described in other chapters of the OpenLDAP Administrator's
27 ^{{B: Get the software}}
29 . You can obtain a copy of the software by following the
30 instructions on the OpenLDAP download
31 page ({{URL: http://www.openldap.org/software/download/}}).
32 It is recommended that new users start with the (latest)
37 +{{B: Unpack the distribution}}
39 .Pick a directory for the LDAP source to live under, change
40 directory to there, and unpack the distribution using the
43 ..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}}
45 . then relocate yourself into the distribution directory:
47 ..{{EX:cd openldap-VERSION}}
49 . You'll have to replace {{F:VERSION}} with the version
54 +{{B: Review documentation}}
56 . You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}},
57 {{F:README}} and {{F:INSTALL}} documents provided with the distribution.
58 The {{F:COPYRIGHT}} and {{F:LICENSE}} provide information on
59 acceptable use, copying, and limitation of warranty of OpenLDAP
63 . You should also review other chapters of this document.
64 In particular, the {{SECT:Building and Installing OpenLDAP Software}}
65 chapter of this document provides detailed information on prerequisite
66 software and installation procedures.
70 +{{B: Run {{EX:configure}}}}
72 . You will need to run the provided {{EX:configure}} script to
73 {{configure}} the distribution for building on your system. The
74 {{EX:configure}} script accepts many command line options that enable or
75 disable optional software features. Usually the defaults are okay,
76 but you may want to change them. To get a complete list of options
77 that {{EX:configure}} accepts, use the {{EX:--help}} option:
79 ..{{EX:./configure --help}}
81 . However, given that you are using this guide, we'll assume you
82 are brave enough to just let {{EX:configure}} determine
87 . Assuming {{EX:configure}} doesn't dislike your system, you can
88 proceed with building the software. If {{EX:configure}} did
89 complain, well, you'll likely need to go to the FAQ Installation
90 Section ({{URL:http://www.openldap.org/faq/}} and/or actually
91 read the {{SECT:Building and Installing OpenLDAP Software}}
92 chapter of this document.
96 +{{B:Build the software}}.
98 . The next step is to build the software. This step has two
99 parts, first we construct dependencies and then we compile the
106 . Both makes should complete without error.
110 +{{B:Test the build}}.
112 . To ensure a correct build, you should run the test suite
113 (it only takes a few minutes):
117 . Tests which apply to your configuration will run and they
118 should pass. Some tests, such as the replication test, may
123 +{{B:Install the software}}.
125 . You are now ready to install the software; this usually requires
126 {{super-user}} privileges:
128 ..{{EX:su root -c 'make install'}}
130 . Everything should now be installed under {{F:/usr/local}} (or
131 whatever installation prefix was used by {{EX:configure}}).
135 +{{B:Edit the configuration file}}.
137 . Use your favorite editor to edit the provided {{slapd.conf}}(5)
138 example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}})
139 to contain a BDB database definition of the form:
141 ..{{EX:database bdb}}
142 ..{{EX:suffix "dc=<MY-DOMAIN>,dc=<COM>"}}
143 ..{{EX:rootdn "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>"}}
144 ..{{EX:rootpw secret}}
145 ..{{EX:directory /usr/local/var/openldap-data}}
147 . Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with
148 the appropriate domain components of your domain name. For
149 example, for {{EX:example.com}}, use:
151 ..{{EX:database bdb}}
152 ..{{EX:suffix "dc=example,dc=com"}}
153 ..{{EX:rootdn "cn=Manager,dc=example,dc=com"}}
154 ..{{EX:rootpw secret}}
155 ..{{EX:directory /usr/local/var/openldap-data}}
157 .If your domain contains additional components, such as
158 {{EX:eng.uni.edu.eu}}, use:
160 ..{{EX:database bdb}}
161 ..{{EX:suffix "dc=eng,dc=uni,dc=edu,dc=eu"}}
162 ..{{EX:rootdn "cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu"}}
163 ..{{EX:rootpw secret}}
164 ..{{EX:directory /usr/local/var/openldap-data}}
166 . Details regarding configuring {{slapd}}(8) can be found
167 in the {{slapd.conf}}(5) manual page and the
168 {{SECT:The slapd Configuration File}} chapter of this
171 Note: the directory specified must exist prior to starting slapd(8).
177 . You are now ready to start the stand-alone LDAP server, slapd(8),
178 by running the command:
180 ..{{EX:su root -c /usr/local/libexec/slapd}}
183 . To check to see if the server is running and configured correctly,
184 you can run a search against it with {{ldapsearch}}(1). By default,
185 ldapsearch is installed as {{F:/usr/local/bin/ldapsearch}}:
187 ..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}}
189 . Note the use of single quotes around command parameters to prevent
190 special characters from being interpreted by the shell. This should return:
193 ..{{EX:namingContexts: dc=example,dc=com}}
195 . Details regarding running {{slapd}}(8) can be found
196 in the {{slapd}}(8) manual page and the
197 {{SECT:Running slapd}} chapter of this document.
201 +{{B:Add initial entries to your directory}}.
203 . You can use {{ldapadd}}(1) to add entries to your LDAP directory.
204 {{ldapadd}} expects input in LDIF form. We'll do it in two steps:
206 ^^ create an LDIF file
209 . Use your favorite editor and create an LDIF file that contains:
211 ..{{EX:dn: dc=<MY-DOMAIN>,dc=<COM>}}
212 ..{{EX:objectclass: dcObject}}
213 ..{{EX:objectclass: organization}}
214 ..{{EX:o: <MY ORGANIZATION>}}
215 ..{{EX:dc: <MY-DOMAIN>}}
217 ..{{EX:dn: cn=Manager,dc=<MY-DOMAIN>,dc=<COM>}}
218 ..{{EX:objectclass: organizationalRole}}
221 . Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the appropriate domain
222 components of your domain name. {{EX:<MY ORGANIZATION>}} should be replaced
223 with the name of your organization. If you cut and paste, be sure
224 to trim any leading and trailing whitespace from the example.
226 ..{{EX:dn: dc=example,dc=com}}
227 ..{{EX:objectclass: dcObject}}
228 ..{{EX:objectclass: organization}}
229 ..{{EX:o: Example Company}}
232 ..{{EX:dn: cn=Manager,dc=example,dc=com}}
233 ..{{EX:objectclass: organizationalRole}}
236 . Now, you may run {{ldapadd}}(1) to insert these entries into
239 ..{{EX:ldapadd -x -D "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f example.ldif}}
241 . Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the
242 appropriate domain components of your domain name. You will be
243 prompted for the "{{EX:secret}}" specified in {{F:slapd.conf}}.
244 For example, for {{EX:example.com}}, use:
246 ..{{EX:ldapadd -x -D "cn=Manager,dc=example,dc=com" -W -f example.ldif}}
248 . where {{F:example.ldif}} is the file you created above.
250 . Additional information regarding directory creation can be found
251 in the {{SECT:Database Creation and Maintenance Tools}} chapter of
255 +{{B:See if it works}}.
257 . Now we're ready to verify the added entries are in your directory.
258 You can use any LDAP client to do this, but our example uses the
259 {{ldapsearch}}(1) tool. Remember to replace {{EX:dc=example,dc=com}}
260 with the correct values for your site:
262 ..{{EX:ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'}}
264 . This command will search for and retrieve every entry in the database.
266 You are now ready to add more entries using {{ldapadd}}(1) or
267 another LDAP client, experiment with various configuration options,
268 backend arrangements, etc.
270 Note that by default, the {{slapd}}(8) database grants {{read access
271 to everybody}} excepting the {{super-user}} (as specified by the
272 {{EX:rootdn}} configuration directive). It is highly recommended
273 that you establish controls to restrict access to authorized users.
274 Access controls are discussed in the {{SECT:Access Control}} section
275 of {{SECT:The slapd Configuration File}} chapter. You are also
276 encouraged to read the {{SECT:Security Considerations}}, {{SECT:Using
277 SASL}} and {{SECT:Using TLS}} sections.
279 The following chapters provide more detailed information on making,
280 installing, and running {{slapd}}(8).