]> git.sur5r.net Git - openldap/blob - doc/guide/admin/quickstart.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / quickstart.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: A Quick-Start Guide
6
7 The following is a quick start guide to [[DOC_NAME]],
8 including the Standalone {{TERM:LDAP}} Daemon, {{slapd}}(8).
9
10 It is meant to walk you through the basic steps needed to install
11 and configure {{PRD:OpenLDAP Software}}.  It should be used in
12 conjunction with the other chapters of this document, manual pages,
13 and other materials provided with the distribution (e.g. the
14 {{F:INSTALL}} document) or on the {{PRD:OpenLDAP}} web site
15 ({{URL: http://www.OpenLDAP.org}}), in particular the OpenLDAP
16 Software {{TERM:FAQ}} ({{URL: http://www.OpenLDAP.org/faq/?file=2}}).
17
18 If you intend to run OpenLDAP Software seriously, you should review
19 all of this document before attempting to install the software.
20
21 Note: This quick start guide does not use strong authentication
22 nor any integrity or confidential protection services.  These
23 services are described in other chapters of the
24 OpenLDAP Administrator's Guide.
25
26
27 .{{S: }}
28 ^{{B: Get the software}}
29
30 . You can obtain a copy of the software by following the
31 instructions on the OpenLDAP Software download page
32 ({{URL: http://www.openldap.org/software/download/}}).  It is
33 recommended that new users start with the latest {{release}}.
34
35
36 .{{S: }}
37 +{{B: Unpack the distribution}}
38
39 .Pick a directory for the source to live under, change
40 directory to there, and unpack the distribution using the
41 following commands:
42
43 ..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}}
44
45 . then relocate yourself into the distribution directory:
46
47 ..{{EX:cd openldap-VERSION}}
48
49 . You'll have to replace {{F:VERSION}} with the version
50 name of the release.
51
52
53 .{{S: }}
54 +{{B: Review documentation}}
55
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
60 Software. 
61
62 .{{S: }}
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.
67
68
69 .{{S: }}
70 +{{B: Run {{EX:configure}}}}
71
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:
78
79 ..{{EX:./configure --help}}
80
81 . However, given that you are using this guide, we'll assume you
82 are brave enough to just let {{EX:configure}} determine
83 what's best:
84
85 ..{{EX:./configure}}
86
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 Software FAQ
90 {{Installation}} section ({{URL:http://www.openldap.org/faq/?file=8}})
91 and/or actually read the {{SECT:Building and Installing OpenLDAP Software}}
92 chapter of this document.
93
94
95 .{{S: }}
96 +{{B:Build the software}}.
97
98 . The next step is to build the software.  This step has two
99 parts, first we construct dependencies and then we compile the
100 software:
101
102 ..{{EX:make depend}}
103 ..{{EX:make}}
104
105
106 . Both makes should complete without error.
107
108
109 .{{S: }}
110 +{{B:Test the build}}.
111
112 . To ensure a correct build, you should run the test suite
113 (it only takes a few minutes):
114
115 ..{{EX:make test}}
116
117 . Tests which apply to your configuration will run and they
118 should pass.  Some tests, such as the replication test, may
119 be skipped.
120
121
122 .{{S: }}
123 +{{B:Install the software}}.
124
125 . You are now ready to install the software; this usually requires
126 {{super-user}} privileges: 
127
128 ..{{EX:su root -c 'make install'}}
129
130 . Everything should now be installed under {{F:/usr/local}} (or
131 whatever installation prefix was used by {{EX:configure}}).
132
133
134 .{{S: }}
135 +{{B:Edit the configuration file}}.
136
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:
140
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}}
146
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:
150
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}}
156
157 .If your domain contains additional components, such as
158 {{EX:eng.uni.edu.eu}}, use:
159
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}}
165
166 . Details regarding configuring {{slapd}}(8) can be found
167 in the {{slapd.conf}}(5) manual page and the {{SECT:The slapd
168 Configuration File}} chapter of this document.  Note that the
169 specified directory must exist prior to starting {{slapd}}(8).
170
171
172 .{{S: }}
173 +{{B:Start SLAPD}}.
174
175 . You are now ready to start the Standalone LDAP Daemon, {{slapd}}(8),
176 by running the command:
177
178 ..{{EX:su root -c /usr/local/libexec/slapd}}
179
180
181 . To check to see if the server is running and configured correctly,
182 you can run a search against it with {{ldapsearch}}(1).  By default,
183 {{ldapsearch}} is installed as {{F:/usr/local/bin/ldapsearch}}:
184
185 ..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}}
186
187 . Note the use of single quotes around command parameters to prevent
188 special characters from being interpreted by the shell.  This should return:
189
190 ..{{EX:dn:}}
191 ..{{EX:namingContexts: dc=example,dc=com}}
192
193 . Details regarding running {{slapd}}(8) can be found
194 in the {{slapd}}(8) manual page and the
195 {{SECT:Running slapd}} chapter of this document.
196
197
198 .{{S: }}
199 +{{B:Add initial entries to your directory}}.
200
201 . You can use {{ldapadd}}(1) to add entries to your LDAP directory.
202 {{ldapadd}} expects input in {{TERM:LDIF}} form.  We'll do it in two
203 steps:
204
205 ^^ create an LDIF file
206 ++ run ldapadd
207
208 . Use your favorite editor and create an LDIF file that contains:
209
210 ..{{EX:dn: dc=<MY-DOMAIN>,dc=<COM>}}
211 ..{{EX:objectclass: dcObject}}
212 ..{{EX:objectclass: organization}}
213 ..{{EX:o: <MY ORGANIZATION>}}
214 ..{{EX:dc: <MY-DOMAIN>}}
215 ..{{EX:}}
216 ..{{EX:dn: cn=Manager,dc=<MY-DOMAIN>,dc=<COM>}}
217 ..{{EX:objectclass: organizationalRole}}
218 ..{{EX:cn: Manager}}
219
220 . Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the
221 appropriate domain components of your domain name.  {{EX:<MY
222 ORGANIZATION>}} should be replaced with the name of your organization.
223 When you cut and paste, be sure to trim any leading and trailing
224 whitespace from the example.
225
226 ..{{EX:dn: dc=example,dc=com}}
227 ..{{EX:objectclass: dcObject}}
228 ..{{EX:objectclass: organization}}
229 ..{{EX:o: Example Company}}
230 ..{{EX:dc: example}}
231 ..{{EX:}}
232 ..{{EX:dn: cn=Manager,dc=example,dc=com}}
233 ..{{EX:objectclass: organizationalRole}}
234 ..{{EX:cn: Manager}}
235
236 . Now, you may run {{ldapadd}}(1) to insert these entries into
237 your directory.
238
239 ..{{EX:ldapadd -x -D "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f example.ldif}}
240
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:
245
246 ..{{EX:ldapadd -x -D "cn=Manager,dc=example,dc=com" -W -f example.ldif}}
247
248 . where {{F:example.ldif}} is the file you created above.
249 ..{{EX: }}
250 . Additional information regarding directory creation can be found
251 in the {{SECT:Database Creation and Maintenance Tools}} chapter of
252 this document.
253
254 .{{S: }}
255 +{{B:See if it works}}.
256
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:
261
262 ..{{EX:ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'}}
263
264 . This command will search for and retrieve every entry in the database.
265
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..
269
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}} chapter.
275 You are also encouraged to read the {{SECT:Security Considerations}},
276 {{SECT:Using SASL}} and {{SECT:Using TLS}} sections.
277
278 The following chapters provide more detailed information on making,
279 installing, and running {{slapd}}(8).