<!doctype html public "-//W30//DTD W3 HTML 2.0//EN">
<HTML>
<!-- This file was generated using SDF 2.001 by
Ian Clatworthy (ianc@mincom.com). SDF is freely
available from http://www.mincom.com/mtr/sdf. -->
<HEAD>
<TITLE>OpenLDAP Software 2.4 Administrator's Guide: A Quick-Start Guide</TITLE>
</HEAD>
<BODY>
<DIV CLASS="header">
<A HREF="http://www.OpenLDAP.org/">
<P><IMG SRC="../images/LDAPlogo.gif" ALIGN="Left" BORDER=0></P>
</A>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="index.html">Contents</A> | <A HREF="index.html">Parent Topic</A> | <A HREF="intro.html">Previous Topic</A> | <A HREF="config.html">Next Topic</A> <BR><A HREF="http://www.openldap.org/">Home</A> | <A HREF="../index.html">Catalog</A></P>
</DIV>
<BR CLEAR="Left">
</DIV>
<DIV CLASS="main">
<H1>2. A Quick-Start Guide</H1>
<P>The following is a quick start guide to OpenLDAP Software 2.4, including the Standalone <TERM>LDAP</TERM> Daemon, <EM>slapd</EM>(8).</P>
<P>It is meant to walk you through the basic steps needed to install and configure <A HREF="http://www.openldap.org/software/">OpenLDAP Software</A>. 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 <TT>INSTALL</TT> document) or on the <A HREF="http://www.openldap.org/">OpenLDAP</A> web site (<A HREF="http://www.OpenLDAP.org">http://www.OpenLDAP.org</A>), in particular the OpenLDAP Software <TERM>FAQ</TERM> (<A HREF="http://www.OpenLDAP.org/faq/?file=2">http://www.OpenLDAP.org/faq/?file=2</A>).</P>
<P>If you intend to run OpenLDAP Software seriously, you should review all of this document before attempting to install the software.</P>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>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.
<HR WIDTH="80%" ALIGN="Left"></P>
<P><HR WIDTH="80%" ALIGN="Left">
<STRONG>Note: </STRONG>This section has been modified to reflect differences as applicable when using the packages distributed with Mageia Linux.
<HR WIDTH="80%" ALIGN="Left"></P>
<UL>
</UL><OL>
<LI><B>Get the software</B>
<BR>
You can obtain a copy of the software by following the instructions on the OpenLDAP Software download page (<A HREF="http://www.openldap.org/software/download/">http://www.openldap.org/software/download/</A>). It is recommended that new users start with the latest <EM>release</EM>.
<BR>
<BR>
Note: This step, and the next 6 (up to 7) can be accomplished on Mageia Linux by running:
<BR>
<TT>urpmi openldap-servers openldap-clients</TT>
<BR>
assuming the versions provided in Mageia Linux are up-to-date enough for your requirements.
<BR>
<LI><B>Unpack the distribution</B>
<BR>
Pick a directory for the source to live under, change directory to there, and unpack the distribution using the following commands:<UL>
<TT>gunzip -c openldap-VERSION.tgz | tar xvfB -</TT></UL>
<BR>
then relocate yourself into the distribution directory:<UL>
<TT>cd openldap-VERSION</TT></UL>
<BR>
You'll have to replace <TT>VERSION</TT> with the version name of the release.
<BR>
<LI><B>Review documentation</B>
<BR>
You should now review the <TT>COPYRIGHT</TT>, <TT>LICENSE</TT>, <TT>README</TT> and <TT>INSTALL</TT> documents provided with the distribution. The <TT>COPYRIGHT</TT> and <TT>LICENSE</TT> provide information on acceptable use, copying, and limitation of warranty of OpenLDAP Software.
<BR>
<BR>
You should also review other chapters of this document. In particular, the <A HREF="install.html">Building and Installing OpenLDAP Software</A> chapter of this document provides detailed information on prerequisite software and installation procedures.
<BR>
<LI><B>Run <TT>configure</TT></B>
<BR>
You will need to run the provided <TT>configure</TT> script to <EM>configure</EM> the distribution for building on your system. The <TT>configure</TT> 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 <TT>configure</TT> accepts, use the <TT>--help</TT> option:<UL>
<TT>./configure --help</TT></UL>
<BR>
However, given that you are using this guide, we'll assume you are brave enough to just let <TT>configure</TT> determine what's best:<UL>
<TT>./configure</TT></UL>
<BR>
Assuming <TT>configure</TT> doesn't dislike your system, you can proceed with building the software. If <TT>configure</TT> did complain, well, you'll likely need to go to the Software FAQ <EM>Installation</EM> section (<A HREF="http://www.openldap.org/faq/?file=8">http://www.openldap.org/faq/?file=8</A>) and/or actually read the <A HREF="install.html">Building and Installing OpenLDAP Software</A> chapter of this document.
<BR>
<LI><B>Build the software</B>.
<BR>
The next step is to build the software. This step has two parts, first we construct dependencies and then we compile the software:<UL>
<TT>make depend</TT>
<BR>
<TT>make</TT></UL>
<BR>
Both makes should complete without error.
<BR>
<LI><B>Test the build</B>.
<BR>
To ensure a correct build, you should run the test suite (it only takes a few minutes):<UL>
<TT>make test</TT></UL>
<BR>
Tests which apply to your configuration will run and they should pass. Some tests, such as the replication test, may be skipped.
<BR>
<BR>
Note: Mageia Linux packages run <TT>make test</TT> during the package build.
<BR>
<LI><B>Install the software</B>.
<BR>
You are now ready to install the software; this usually requires <EM>super-user</EM> privileges:<UL>
<TT>su root -c 'make install'</TT></UL>
<BR>
Everything should now be installed under <TT>/usr/local</TT> (or whatever installation prefix was used by <TT>configure</TT>).
<BR>
<LI><B>Edit the configuration file</B>.
<BR>
Use your favorite editor to edit the provided <EM>slapd.ldif</EM> example (usually installed as <TT>/usr/local/etc/openldap/slapd.ldif</TT>) to contain a MDB database definition of the form:<UL>
<TT>dn: olcDatabase=mdb,cn=config</TT>
<BR>
<TT>objectClass: olcDatabaseConfig</TT>
<BR>
<TT>objectClass: olcMdbConfig</TT>
<BR>
<TT>olcDatabase: mdb</TT>
<BR>
<TT>OlcDbMaxSize: 1073741824</TT>
<BR>
<TT>olcSuffix: dc=<MY-DOMAIN>,dc=<COM></TT>
<BR>
<TT>olcRootDN: cn=Manager,dc=<MY-DOMAIN>,dc=<COM></TT>
<BR>
<TT>olcRootPW: secret</TT>
<BR>
<TT>olcDbDirectory: /usr/local/var/openldap-data</TT>
<BR>
<TT>olcDbIndex: objectClass eq</TT></UL>
<BR>
Be sure to replace <TT><MY-DOMAIN></TT> and <TT><COM></TT> with the appropriate domain components of your domain name. For example, for <TT>example.com</TT>, use:<UL>
<TT>dn: olcDatabase=mdb,cn=config</TT>
<BR>
<TT>objectClass: olcDatabaseConfig</TT>
<BR>
<TT>objectClass: olcMdbConfig</TT>
<BR>
<TT>olcDatabase: mdb</TT>
<BR>
<TT>OlcDbMaxSize: 1073741824</TT>
<BR>
<TT>olcSuffix: dc=example,dc=com</TT>
<BR>
<TT>olcRootDN: cn=Manager,dc=example,dc=com</TT>
<BR>
<TT>olcRootPW: secret</TT>
<BR>
<TT>olcDbDirectory: /usr/local/var/openldap-data</TT>
<BR>
<TT>olcDbIndex: objectClass eq</TT></UL>
<BR>
If your domain contains additional components, such as <TT>eng.uni.edu.eu</TT>, use:<UL>
<TT>dn: olcDatabase=mdb,cn=config</TT>
<BR>
<TT>objectClass: olcDatabaseConfig</TT>
<BR>
<TT>objectClass: olcMdbConfig</TT>
<BR>
<TT>olcDatabase: mdb</TT>
<BR>
<TT>OlcDbMaxSize: 1073741824</TT>
<BR>
<TT>olcSuffix: dc=eng,dc=uni,dc=edu,dc=eu</TT>
<BR>
<TT>olcRootDN: cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu</TT>
<BR>
<TT>olcRootPW: secret</TT>
<BR>
<TT>olcDbDirectory: /usr/local/var/openldap-data</TT>
<BR>
<TT>olcDbIndex: objectClass eq</TT></UL>
<BR>
Details regarding configuring <EM>slapd</EM>(8) can be found in the <EM>slapd-config</EM>(5) manual page and the <A HREF="slapdconf2.html">Configuring slapd</A> chapter of this document. Note that the specified olcDbDirectory must exist prior to starting <EM>slapd</EM>(8).
<BR>
<BR>
Note: The OpenLDAP packages provided by Mageia Linux use the configuration file <TT>/etc/openldap/slapd.conf</TT>, which will by default use the directory <TT>/var/lib/ldap</TT> for the default database.
<BR>
<LI><B>Import the configuration database</B>
<BR>
You are now ready to import your configration database for use by <EM>slapd</EM>(8), by running the command:<UL>
<TT> su root -c /usr/local/sbin/slapadd -n 0 -F /usr/local/etc/slapd.d -l /usr/local/etc/openldap/slapd.ldif</TT></UL>
<BR>
<LI><B>Start SLAPD</B>.
<BR>
You are now ready to start the Standalone LDAP Daemon, <EM>slapd</EM>(8), by running the command:<UL>
<TT>su root -c /usr/local/libexec/slapd -F /usr/local/etc/slapd.d</TT></UL>
<BR>
<BR>
Note: When using the Mageia Linux OpenLDAP packages, you can start slapd using systemd with <TT>systemctl start slapd</TT>. Optional configuration of this init script may be done in the file <TT>/etc/sysconfig/slapd</TT>.
<BR>
<BR>
To check to see if the server is running and configured correctly, you can run a search against it with <EM>ldapsearch</EM>(1). By default, <EM>ldapsearch</EM> is installed as <TT>/usr/local/bin/ldapsearch</TT>:<UL>
<TT>ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts</TT></UL>
<BR>
Note the use of single quotes around command parameters to prevent special characters from being interpreted by the shell. This should return:<UL>
<TT>dn:</TT>
<BR>
<TT>namingContexts: dc=example,dc=com</TT></UL>
<BR>
Details regarding running <EM>slapd</EM>(8) can be found in the <EM>slapd</EM>(8) manual page and the <A HREF="runningslapd.html">Running slapd</A> chapter of this document.
<BR>
<LI><B>Add initial entries to your directory</B>.
<BR>
You can use <EM>ldapadd</EM>(1) to add entries to your LDAP directory. <EM>ldapadd</EM> expects input in <TERM>LDIF</TERM> form. We'll do it in two steps:<OL>
<LI>create an LDIF file
<LI>run ldapadd</OL>
<BR>
Use your favorite editor and create an LDIF file that contains:<UL>
<TT>dn: dc=<MY-DOMAIN>,dc=<COM></TT>
<BR>
<TT>objectclass: dcObject</TT>
<BR>
<TT>objectclass: organization</TT>
<BR>
<TT>o: <MY ORGANIZATION></TT>
<BR>
<TT>dc: <MY-DOMAIN></TT>
<BR>
<TT></TT>
<BR>
<TT>dn: cn=Manager,dc=<MY-DOMAIN>,dc=<COM></TT>
<BR>
<TT>objectclass: organizationalRole</TT>
<BR>
<TT>cn: Manager</TT></UL>
<BR>
Be sure to replace <TT><MY-DOMAIN></TT> and <TT><COM></TT> with the appropriate domain components of your domain name. <TT><MY ORGANIZATION></TT> should be replaced with the name of your organization. When you cut and paste, be sure to trim any leading and trailing whitespace from the example.<UL>
<TT>dn: dc=example,dc=com</TT>
<BR>
<TT>objectclass: dcObject</TT>
<BR>
<TT>objectclass: organization</TT>
<BR>
<TT>o: Example Company</TT>
<BR>
<TT>dc: example</TT>
<BR>
<TT></TT>
<BR>
<TT>dn: cn=Manager,dc=example,dc=com</TT>
<BR>
<TT>objectclass: organizationalRole</TT>
<BR>
<TT>cn: Manager</TT></UL>
<BR>
Now, you may run <EM>ldapadd</EM>(1) to insert these entries into your directory.<UL>
<TT>ldapadd -x -D "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f example.ldif</TT></UL>
<BR>
Be sure to replace <TT><MY-DOMAIN></TT> and <TT><COM></TT> with the appropriate domain components of your domain name. You will be prompted for the "<TT>secret</TT>" specified in <TT>slapd.conf</TT>. For example, for <TT>example.com</TT>, use:<UL>
<TT>ldapadd -x -D "cn=Manager,dc=example,dc=com" -W -f example.ldif</TT></UL>
<BR>
where <TT>example.ldif</TT> is the file you created above.<UL>
<TT> </TT></UL>
<BR>
Additional information regarding directory creation can be found in the <A HREF="dbtools.html">Database Creation and Maintenance Tools</A> chapter of this document.
<BR>
<LI><B>See if it works</B>.
<BR>
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 <EM>ldapsearch</EM>(1) tool. Remember to replace <TT>dc=example,dc=com</TT> with the correct values for your site:<UL>
<TT>ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'</TT></UL>
<BR>
This command will search for and retrieve every entry in the database.</OL>
<P>You are now ready to add more entries using <EM>ldapadd</EM>(1) or another LDAP client, experiment with various configuration options, backend arrangements, etc..</P>
<P>Note that by default, the <EM>slapd</EM>(8) database grants <EM>read access to everybody</EM> excepting the <EM>super-user</EM> (as specified by the <TT>rootdn</TT> configuration directive). It is highly recommended that you establish controls to restrict access to authorized users. Access controls are discussed in the <A HREF="access-control.html">Access Control</A> chapter. You are also encouraged to read the <A HREF="security.html">Security Considerations</A>, <A HREF="sasl.html">Using SASL</A> and <A HREF="tls.html">Using TLS</A> sections.</P>
<P>The following chapters provide more detailed information on making, installing, and running <EM>slapd</EM>(8).</P>
<P></P>
</DIV>
<DIV CLASS="footer">
<HR>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="index.html">Contents</A> | <A HREF="index.html">Parent Topic</A> | <A HREF="intro.html">Previous Topic</A> | <A HREF="config.html">Next Topic</A> <BR><A HREF="http://www.openldap.org/">Home</A> | <A HREF="../index.html">Catalog</A></P>
</DIV>
<P>
<FONT COLOR="#808080" FACE="Arial,Verdana,Helvetica" SIZE="1"><B>
________________<BR>
<SMALL>© Copyright 2011, <A HREF="http://www.OpenLDAP.org/foundation/">OpenLDAP Foundation</A>, <A HREF="mailto:info@OpenLDAP.org">info@OpenLDAP.org</A></SMALL></B></FONT>
</DIV>
</BODY>
</HTML>
