1# $OpenLDAP$ 2# Copyright 1999-2011 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: A Quick-Start Guide 6 7The following is a quick start guide to [[DOC_NAME]], 8including the Standalone {{TERM:LDAP}} Daemon, {{slapd}}(8). 9 10It is meant to walk you through the basic steps needed to install 11and configure {{PRD:OpenLDAP Software}}. It should be used in 12conjunction with the other chapters of this document, manual pages, 13and 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 16Software {{TERM:FAQ}} ({{URL: http://www.OpenLDAP.org/faq/?file=2}}). 17 18If you intend to run OpenLDAP Software seriously, you should review 19all of this document before attempting to install the software. 20 21Note: This quick start guide does not use strong authentication 22nor any integrity or confidential protection services. These 23services are described in other chapters of the 24OpenLDAP 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 31instructions on the OpenLDAP Software download page 32({{URL: http://www.openldap.org/software/download/}}). It is 33recommended 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 40directory to there, and unpack the distribution using the 41following 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 50name 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. 58The {{F:COPYRIGHT}} and {{F:LICENSE}} provide information on 59acceptable use, copying, and limitation of warranty of OpenLDAP 60Software. 61 62.{{S: }} 63. You should also review other chapters of this document. 64In particular, the {{SECT:Building and Installing OpenLDAP Software}} 65chapter of this document provides detailed information on prerequisite 66software 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 75disable optional software features. Usually the defaults are okay, 76but you may want to change them. To get a complete list of options 77that {{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 82are brave enough to just let {{EX:configure}} determine 83what's best: 84 85..{{EX:./configure}} 86 87. Assuming {{EX:configure}} doesn't dislike your system, you can 88proceed with building the software. If {{EX:configure}} did 89complain, well, you'll likely need to go to the Software FAQ 90{{Installation}} section ({{URL:http://www.openldap.org/faq/?file=8}}) 91and/or actually read the {{SECT:Building and Installing OpenLDAP Software}} 92chapter 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 99parts, first we construct dependencies and then we compile the 100software: 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 118should pass. Some tests, such as the replication test, may 119be 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 131whatever 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) 138example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}}) 139to 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 148the appropriate domain components of your domain name. For 149example, 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 167in the {{slapd.conf}}(5) manual page and the {{SECT:The slapd 168Configuration File}} chapter of this document. Note that the 169specified 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), 176by 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, 182you 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 188special 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 194in 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 203steps: 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 221appropriate domain components of your domain name. {{EX:<MY 222ORGANIZATION>}} should be replaced with the name of your organization. 223When you cut and paste, be sure to trim any leading and trailing 224whitespace 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 237your 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 242appropriate domain components of your domain name. You will be 243prompted for the "{{EX:secret}}" specified in {{F:slapd.conf}}. 244For 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 251in the {{SECT:Database Creation and Maintenance Tools}} chapter of 252this 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. 258You 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}} 260with 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 266You are now ready to add more entries using {{ldapadd}}(1) or 267another LDAP client, experiment with various configuration options, 268backend arrangements, etc.. 269 270Note that by default, the {{slapd}}(8) database grants {{read access 271to everybody}} excepting the {{super-user}} (as specified by the 272{{EX:rootdn}} configuration directive). It is highly recommended 273that you establish controls to restrict access to authorized users. 274Access controls are discussed in the {{SECT:Access Control}} chapter. 275You are also encouraged to read the {{SECT:Security Considerations}}, 276{{SECT:Using SASL}} and {{SECT:Using TLS}} sections. 277 278The following chapters provide more detailed information on making, 279installing, and running {{slapd}}(8). 280