<!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>