~ted-m-cox/serverguide/zentyal-review

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 

	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [

<!ENTITY % globalent SYSTEM "../../libs/global.ent">

%globalent;

<!ENTITY % xinclude SYSTEM "../../libs/xinclude.mod">

%xinclude;

<!ENTITY language "&EnglishAmerican;">

]>

<chapter id="network-authentication" status="review">

	<title>Network Authentication</title>

        <para>

        This section applies LDAP to network authentication and authorization.

        </para>

	<sect1 id="openldap-server" status="review">

	<title>OpenLDAP Server</title>

	<para>

	The Lightweight Directory Access Protocol, or LDAP, is a protocol for 

    querying and modifying a X.500-based directory service running over TCP/IP. 

	The current LDAP version is LDAPv3, as defined in <ulink 

    url="http://tools.ietf.org/html/rfc4510">RFC4510</ulink>, and the 

    implementation in Ubuntu is OpenLDAP."

    </para>

	<para>

	So the LDAP protocol accesses LDAP directories. Here are some key concepts and terms:

	</para>

	<itemizedlist>

		<listitem>

		<para>

		A LDAP directory is a tree of data <emphasis>entries</emphasis> that is hierarchical in nature and is called

		the Directory Information Tree (DIT).

		</para>

		</listitem>

		<listitem>

		<para>

		An entry consists of a set of <emphasis>attributes</emphasis>.

		</para>

		</listitem>

		<listitem>

		<para>

		An attribute has a <emphasis>type</emphasis> (a name/description) and one or more <emphasis>values</emphasis>.

		</para>

		</listitem>

		<listitem>

		<para>

		Every attribute must be defined in at least one <emphasis>objectClass</emphasis>.

		</para>

		</listitem>

		<listitem>

		<para>

		Attributes and objectclasses are defined in <emphasis>schemas</emphasis> (an objectclass is actually

		considered as a special kind of attribute).

		</para>

		</listitem>

		<listitem>

		<para>

		Each entry has a unique identifier: its <emphasis>Distinguished Name</emphasis> (DN or dn). This, in turn, consists

		of a <emphasis>Relative Distinguished Name</emphasis> (RDN) followed by the parent entry's DN.

		</para>

		</listitem>

		<listitem>

		<para>

		The entry's DN is not an attribute. It is not considered part of the entry itself.

		</para>

		</listitem>

	</itemizedlist>

	<note>

		<para>

		The terms <emphasis>object</emphasis>, <emphasis>container</emphasis>, and <emphasis>node</emphasis> have certain

		connotations but they all essentially mean the same thing as <emphasis>entry</emphasis>, the technically correct term.

		</para>

	</note>

	<para>

	For example, below we have a single entry consisting of 11 attributes where the following is true:

	</para>

	<itemizedlist mark='bullet'>

		<listitem>

		<para>

		DN is "cn=John Doe,dc=example,dc=com"

		</para>

		</listitem>

		<listitem>

		<para>

		RDN is "cn=John Doe"

		</para>

		</listitem>

		<listitem>

		<para>

		parent DN is "dc=example,dc=com"

		</para>

		</listitem>

	</itemizedlist>

<programlisting>

 dn: cn=John Doe,dc=example,dc=com

 cn: John Doe

 givenName: John

 sn: Doe

 telephoneNumber: +1 888 555 6789

 telephoneNumber: +1 888 555 1232

 mail: john@example.com

 manager: cn=Larry Smith,dc=example,dc=com

 objectClass: inetOrgPerson

 objectClass: organizationalPerson

 objectClass: person

 objectClass: top

</programlisting>

	<para>

	The above entry is in <emphasis>LDIF</emphasis> format (LDAP Data Interchange Format). Any information that you feed

	into your DIT must also be in such a format. It is defined in <ulink url="http://tools.ietf.org/html/rfc2849">RFC2849</ulink>.

	</para>

	<para>

        Although this guide will describe how to use it for central authentication, LDAP is good for anything that involves a large number

	of access requests to a mostly-read, attribute-based (name:value) backend. Examples include an address book, a list of email addresses,

	and a mail server's configuration.

        </para>

		<sect2 id="openldap-server-installation" status="review">

		<title>Installation</title>

   	<para>

	Install the OpenLDAP server daemon and the traditional LDAP management utilities. These are found in packages <application>slapd</application>

	and <application>ldap-utils</application> respectively. 

	</para>

	<para>

        The installation of slapd will create a working configuration. In particular, it will create a database instance that you

	can use to store your data.  However, the suffix (or base DN) of this instance will be determined from the domain name of the localhost.

	If you want something different, edit <filename>/etc/hosts</filename> and replace the domain name with one that will give you the

	suffix you desire.  For instance, if you want a suffix of <emphasis>dc=example,dc=com</emphasis> then your file would have a line

	similar to this:

	</para>

<programlisting>

127.0.1.1       hostname.example.com	hostname

</programlisting>

	<para>

	You can revert the change after package installation.

	</para>

	<note>

		<para>

		This guide will use a database suffix of <emphasis>dc=example,dc=com</emphasis>.

		</para>

	</note>

	<para>

	Proceed with the install:

	</para>

<screen>

<command>sudo apt-get install slapd ldap-utils</command>

</screen>

        <para>

        Since Ubuntu 8.10 slapd is designed to be configured within slapd itself by dedicating a separate DIT for that purpose. This allows one

	to dynamically configure slapd without the need to restart the service. This configuration database consists of a collection of text-based

	LDIF files located under <filename>/etc/ldap/slapd.d</filename>. This way of working is known by several names: the slapd-config method,

	the RTC method (Real Time Configuration), or the cn=config method. You can still use the traditional flat-file method (slapd.conf) but it's

	not recommended; the functionality will be eventually phased out.

        </para>

	<note>

		<para>

		Ubuntu now uses the <emphasis>slapd-config</emphasis> method for slapd configuration and this

		guide reflects that.

		</para>

	</note>

	<para>

 	During the install you were prompted to define administrative credentials. These are LDAP-based credentials for the <emphasis>rootDN</emphasis>

	of your database instance. By default, this user's DN is <emphasis>cn=admin,dc=example,dc=com</emphasis>. Also by default, there is no

	administrative account created for the slapd-config database and you will therefore need to authenticate externally to LDAP in order to access it.

	We will see how to do this later on.

	</para>

	<para>

	Some classical schemas (cosine, nis, inetorgperson) come built-in with slapd nowadays. There is also an included "core" schema, a pre-requisite

	for any schema to work.

	</para>

		</sect2>

		<sect2 id="openldap-server-postinstall" status="review">

		<title>Post-install Inspection</title>

	<para>

	The installation process set up 2 DITs. One for slapd-config and one for your own data (dc=example,dc=com). Let's take a look.

	</para>

	<itemizedlist>

		<listitem>

		<para>

		This is what the slapd-config database/DIT looks like.  Recall that this database is

		LDIF-based and lives under <filename>/etc/ldap/slapd.d</filename>:

		</para>

<screen>

<computeroutput>

    /etc/ldap/slapd.d/

    /etc/ldap/slapd.d/cn=config

    /etc/ldap/slapd.d/cn=config/cn=module{0}.ldif

    /etc/ldap/slapd.d/cn=config/cn=schema

    /etc/ldap/slapd.d/cn=config/cn=schema/cn={0}core.ldif

    /etc/ldap/slapd.d/cn=config/cn=schema/cn={1}cosine.ldif

    /etc/ldap/slapd.d/cn=config/cn=schema/cn={2}nis.ldif

    /etc/ldap/slapd.d/cn=config/cn=schema/cn={3}inetorgperson.ldif

    /etc/ldap/slapd.d/cn=config/cn=schema.ldif

    /etc/ldap/slapd.d/cn=config/olcBackend={0}hdb.ldif

    /etc/ldap/slapd.d/cn=config/olcDatabase={0}config.ldif

    /etc/ldap/slapd.d/cn=config/olcDatabase={-1}frontend.ldif

    /etc/ldap/slapd.d/cn=config/olcDatabase={1}hdb.ldif

    /etc/ldap/slapd.d/cn=config.ldif

</computeroutput>

</screen>

	<note>

		<para>

		Do not edit the slapd-config database directly. Make changes via the LDAP protocol (utilities).

		</para>

	</note>

		</listitem>

		<listitem>

		<para>

		This is what the slapd-config DIT looks like via the LDAP protocol:

		</para>

<caution>

  <para>

    On Ubuntu server 14.10, and possibly higher, the following command may not work due to a <ulink url="https://bugs.launchpad.net/ubuntu/+source/apparmor/+bug/1392018">bug</ulink> 

  </para>

</caution>

<screen>

<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn</command>

<computeroutput>

dn: cn=config

dn: cn=module{0},cn=config

dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

dn: olcBackend={0}hdb,cn=config

dn: olcDatabase={-1}frontend,cn=config

dn: olcDatabase={0}config,cn=config

dn: olcDatabase={1}hdb,cn=config

</computeroutput>

</screen>

		<para>

		Explanation of entries:

		</para>

		<itemizedlist>

			<listitem>

			<para>

			<emphasis>cn=config</emphasis>: global settings

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>cn=module{0},cn=config</emphasis>: a dynamically loaded module

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>cn=schema,cn=config</emphasis>: contains hard-coded system-level schema

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>cn={0}core,cn=schema,cn=config</emphasis>: the hard-coded core schema

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>cn={1}cosine,cn=schema,cn=config</emphasis>: the cosine schema

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>cn={2}nis,cn=schema,cn=config</emphasis>: the nis schema

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>cn={3}inetorgperson,cn=schema,cn=config</emphasis>: the inetorgperson schema

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>olcBackend={0}hdb,cn=config</emphasis>: the 'hdb' backend storage type

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>olcDatabase={-1}frontend,cn=config</emphasis>: frontend database, default settings for other databases

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>olcDatabase={0}config,cn=config</emphasis>: slapd configuration database (cn=config)

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>olcDatabase={1}hdb,cn=config</emphasis>: your database instance (dc=examle,dc=com)

			</para>

			</listitem>

		</itemizedlist>

		</listitem>

		<listitem>

		<para>

		This is what the dc=example,dc=com DIT looks like:

		</para>

<screen>

<command>ldapsearch -x -LLL -H ldap:/// -b dc=example,dc=com dn</command>

<computeroutput>

dn: dc=example,dc=com

dn: cn=admin,dc=example,dc=com

</computeroutput>

</screen>

		<para>

		Explanation of entries:

		</para>

		<itemizedlist>

			<listitem>

			<para>

			<emphasis>dc=example,dc=com</emphasis>: base of the DIT

			</para>

			</listitem>

			<listitem>

			<para>

			<emphasis>cn=admin,dc=example,dc=com</emphasis>: administrator (rootDN) for this DIT (set up during package install)

			</para>

			</listitem>

		</itemizedlist>

		</listitem>

	</itemizedlist>

		</sect2>

		<sect2 id="openldap-server-populate" status="review">

		<title>Modifying/Populating your Database</title>

        <para>

	Let's introduce some content to our database.  We will add the following:

	</para>

	<itemizedlist>

	<listitem>

	<para>

	a node called <emphasis>People</emphasis> (to store users)

	</para>

        </listitem>

	<listitem>

	<para>

	a node called <emphasis>Groups</emphasis> (to store groups)

	</para>

        </listitem>

	<listitem>

	<para>

	a group called <emphasis>miners</emphasis>

	</para>

        </listitem>

	<listitem>

	<para>

	a user called <emphasis>john</emphasis>

	</para>

        </listitem>

	</itemizedlist>

	<para>

	Create the following LDIF file and call it <filename>add_content.ldif</filename>:

	</para>

<programlisting>

dn: ou=People,dc=example,dc=com

objectClass: organizationalUnit

ou: People

dn: ou=Groups,dc=example,dc=com

objectClass: organizationalUnit

ou: Groups

dn: cn=miners,ou=Groups,dc=example,dc=com

objectClass: posixGroup

cn: miners

gidNumber: 5000

dn: uid=john,ou=People,dc=example,dc=com

objectClass: inetOrgPerson

objectClass: posixAccount

objectClass: shadowAccount

uid: john

sn: Doe

givenName: John

cn: John Doe

displayName: John Doe

uidNumber: 10000

gidNumber: 5000

userPassword: johnldap

gecos: John Doe

loginShell: /bin/bash

homeDirectory: /home/john

</programlisting>

	<note>

		<para>

		It's important that uid and gid values in your directory do not collide with local values.  Use high number ranges, such as starting at 5000. 

		By setting the uid and gid values in ldap high, you also allow 

		for easier control of what can be done with a local user vs a 

		ldap one. More on that later.

		</para>

	</note>

	<para>

	Add the content:

	</para>

<screen>

<command>ldapadd -x -D cn=admin,dc=example,dc=com -W -f add_content.ldif</command>

<computeroutput>

Enter LDAP Password: <application>********</application>

adding new entry "ou=People,dc=example,dc=com"

adding new entry "ou=Groups,dc=example,dc=com"

adding new entry "cn=miners,ou=Groups,dc=example,dc=com"

adding new entry "uid=john,ou=People,dc=example,dc=com"

</computeroutput>

</screen>

	<para>

	We can check that the information has been correctly added with the <application>ldapsearch</application> utility:

	</para>

<screen>

<command>ldapsearch -x -LLL -b dc=example,dc=com 'uid=john' cn gidNumber</command>

<computeroutput>

dn: uid=john,ou=People,dc=example,dc=com

cn: John Doe

gidNumber: 5000

</computeroutput>

</screen>

	<para>

	Explanation of switches:

	</para>

	<itemizedlist>

	<listitem>

	<para>

	<emphasis>-x:</emphasis> "simple" binding; will not use the default SASL method

	</para>

        </listitem>

        <listitem>

	<para>

	<emphasis>-LLL:</emphasis> disable printing extraneous information

	</para>

        </listitem>

	<listitem>

	<para>

	<emphasis>uid=john:</emphasis> a "filter" to find the john user

	</para>

        </listitem>

	<listitem>

	<para>

	<emphasis>cn gidNumber:</emphasis> requests certain attributes to be displayed (the default is to show all attributes)

	</para>

        </listitem>

        </itemizedlist>

		</sect2>

		<sect2 id="openldap-configuration" status="review">

		<title>Modifying the slapd Configuration Database</title>

	<para>

       	The slapd-config DIT can also be queried and modified. Here are a few examples.

	</para>

       	<itemizedlist>

	<listitem>

	<para>

	Use <application>ldapmodify</application> to add an "Index" (DbIndex attribute) to your <application>{1}hdb,cn=config</application>

	database (dc=example,dc=com). Create a file, call it <filename>uid_index.ldif</filename>, with the following contents:              

	</para>

<programlisting>

dn: olcDatabase={1}hdb,cn=config

add: olcDbIndex

olcDbIndex: uid eq,pres,sub

</programlisting>

	<para>

	Then issue the command:

	</para>

<screen>

<command>sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f uid_index.ldif</command>

<computeroutput>

modifying entry "olcDatabase={1}hdb,cn=config"

</computeroutput>

</screen>

	<para>

	You can confirm the change in this way:

	</para>

<screen>

<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \

cn=config '(olcDatabase={1}hdb)' olcDbIndex</command>

<computeroutput>

dn: olcDatabase={1}hdb,cn=config

olcDbIndex: objectClass eq

olcDbIndex: uid eq,pres,sub

</computeroutput>

</screen>

	</listitem>

       	<listitem>

	<para>

	Let's add a schema. It will first need to be converted to LDIF format. You can find unconverted

	schemas in addition to converted ones in the <filename role="directory">/etc/ldap/schema</filename> directory.

	</para>

	<note>

        <itemizedlist>

       	<listitem>

	  	<para>

		It is not trivial to remove a schema from the slapd-config database. Practice adding schemas on a test system.

	  	</para>

	</listitem>

       	<listitem>

	  	<para>

		Before adding any schema, you should check which schemas are

		already installed (shown is a default, out-of-the-box output):

	  	</para>

<screen>

<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \

cn=schema,cn=config dn</command>

<computeroutput>

dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

</computeroutput>

</screen>

	</listitem>

        </itemizedlist>

	</note>

	<para>

	In the following example we'll add the CORBA schema.

	</para>

	<procedure>

	<step>

		<para>                  

		Create the conversion configuration file <filename>schema_convert.conf</filename> containing the 

		following lines:

		</para>

<programlisting>

include /etc/ldap/schema/core.schema

include /etc/ldap/schema/collective.schema

include /etc/ldap/schema/corba.schema

include /etc/ldap/schema/cosine.schema

include /etc/ldap/schema/duaconf.schema

include /etc/ldap/schema/dyngroup.schema

include /etc/ldap/schema/inetorgperson.schema

include /etc/ldap/schema/java.schema

include /etc/ldap/schema/misc.schema

include /etc/ldap/schema/nis.schema

include /etc/ldap/schema/openldap.schema

include /etc/ldap/schema/ppolicy.schema

include /etc/ldap/schema/ldapns.schema

include /etc/ldap/schema/pmi.schema

</programlisting>

	</step>

	<step>

		<para>

		Create the output directory <filename>ldif_output</filename>.

		</para> 

	</step>

	<step>

		<para>

		Determine the index of the schema:

		</para> 

<screen>

<command>slapcat -f schema_convert.conf -F ldif_output -n 0 | grep corba,cn=schema</command>

<computeroutput>

cn={1}corba,cn=schema,cn=config

</computeroutput>

</screen>

		<note>

			<para>

			When slapd ingests objects with the same parent DN it will create an <emphasis>index</emphasis> for that object.

			An index is contained within braces: <application>{X}</application>.

			</para>

		</note>

	</step>

	<step>

		<para>

		Use <application>slapcat</application> to perform the conversion:

		</para>

<screen>

<command>slapcat -f schema_convert.conf -F ldif_output -n0 -H \

ldap:///cn={1}corba,cn=schema,cn=config -l cn=corba.ldif</command>

</screen>

		<para>

		The converted schema is now in <filename>cn=corba.ldif</filename>

		</para>

	</step>

	<step>

		<para>

		Edit <filename>cn=corba.ldif</filename> to arrive at the following attributes:

		</para> 

<programlisting>

dn: cn=corba,cn=schema,cn=config

...

cn: corba

</programlisting>

		<para>

		Also remove the following lines from the bottom:

		</para> 

<programlisting>

structuralObjectClass: olcSchemaConfig

entryUUID: 52109a02-66ab-1030-8be2-bbf166230478

creatorsName: cn=config

createTimestamp: 20110829165435Z

entryCSN: 20110829165435.935248Z#000000#000#000000

modifiersName: cn=config

modifyTimestamp: 20110829165435Z

</programlisting>

		<para>

		Your attribute values will vary.

		</para>

	</step>

	<step>

		<para>

		Finally, use <application>ldapadd</application> to add the new schema to the slapd-config DIT:

		</para>

<screen>

<command>sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f cn\=corba.ldif</command>

<computeroutput>

adding new entry "cn=corba,cn=schema,cn=config"

</computeroutput>

</screen>

	</step>

	<step>

		<para>

		Confirm currently loaded schemas:

		</para> 

<screen>

<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn</command>

<computeroutput>

dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

dn: cn={4}corba,cn=schema,cn=config

</computeroutput>

</screen>

	</step>

	</procedure>

	</listitem>

       	</itemizedlist>

	<note>

	  	<para>

	  	For external applications and clients to authenticate using LDAP they will each need to be specifically

		configured to do so.  Refer to the appropriate client-side documentation for details.	 

	  	</para>

	</note>

		</sect2>

		<sect2 id="openldap-server-logging" status="review">

		<title>Logging</title>

	<para>

	Activity logging for slapd is indispensible when implementing an OpenLDAP-based solution yet it must be manually enabled after

	software installation. Otherwise, only rudimentary messages will appear in the logs. Logging, like any other slapd configuration,

	is enabled via the slapd-config database.

	</para>

	<para>

	OpenLDAP comes with multiple logging subsystems (levels) with each one containing the lower one (additive). A good level to

	try is <emphasis>stats</emphasis>. The <ulink url="http://manpages.ubuntu.com/manpages/en/man5/slapd-config.5.html">slapd-config</ulink>

	man page has more to say on the different subsystems.

	</para>

	<para>

	Create the file <filename>logging.ldif</filename> with the following contents:

	</para>

<programlisting>

dn: cn=config

changetype: modify

replace: olcLogLevel

olcLogLevel: stats

</programlisting>

	<para>

	Implement the change:

	</para>

<screen>

<command>sudo ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f logging.ldif</command>

</screen>

	<para>

	This will produce a significant amount of logging and you will want to throttle back to a less verbose level once your system

	is in production. While in this verbose mode your host's syslog engine (rsyslog) may have a hard time keeping up and may drop

	messages:

	</para>

<programlisting>

rsyslogd-2177: imuxsock lost 228 messages from pid 2547 due to rate-limiting

</programlisting>

	<para>

	You may consider a change to rsyslog's configuration. In <filename>/etc/rsyslog.conf</filename>, put:

	</para>

<programlisting>

# Disable rate limiting

# (default is 200 messages in 5 seconds; below we make the 5 become 0)

$SystemLogRateLimitInterval 0

</programlisting>

	<para>

	And then restart the rsyslog daemon:

	</para>

<screen>

<command>sudo service rsyslog restart</command>

</screen>

		</sect2>

		<sect2 id="openldap-server-replication" status="review">

		<title>Replication</title>

	<para>

	The LDAP service becomes increasingly important as more networked systems begin to depend on it. In such an environment,

	it is standard practice to build redundancy (high availability) into LDAP to prevent havoc should the LDAP server become

	unresponsive. This is done through <emphasis>LDAP replication</emphasis>. 

	</para>

	<para>

	Replication is achieved via the <emphasis>Syncrepl</emphasis> engine. This allows changes to be synchronized using a

	<emphasis>Consumer</emphasis> - <emphasis>Provider</emphasis> model. The specific kind of replication we will implement

	in this guide is a combination of the following modes: <emphasis>refreshAndPersist</emphasis> and <emphasis>delta-syncrepl</emphasis>.

	This has the Provider push changed entries to the Consumer as soon as they're made but, in addition, only actual changes will

	be sent, not entire entries.

	</para>

			<sect3 id="openldap-provider-configuration" status="review">

			<title>Provider Configuration</title>

	<para>

	Begin by configuring the <emphasis>Provider</emphasis>.

	</para>

        <procedure>

	<step>

		<para>

		Create an LDIF file with the following contents and name it <filename>provider_sync.ldif</filename>:

		</para>

<programlisting>

# Add indexes to the frontend db.

dn: olcDatabase={1}hdb,cn=config

changetype: modify

add: olcDbIndex

olcDbIndex: entryCSN eq

-

add: olcDbIndex

olcDbIndex: entryUUID eq

#Load the syncprov and accesslog modules.

dn: cn=module{0},cn=config

changetype: modify

add: olcModuleLoad

olcModuleLoad: syncprov

-

add: olcModuleLoad

olcModuleLoad: accesslog

# Accesslog database definitions

dn: olcDatabase={2}hdb,cn=config

objectClass: olcDatabaseConfig

objectClass: olcHdbConfig

olcDatabase: {2}hdb

olcDbDirectory: /var/lib/ldap/accesslog

olcSuffix: cn=accesslog

olcRootDN: cn=admin,dc=example,dc=com

olcDbIndex: default eq

olcDbIndex: entryCSN,objectClass,reqEnd,reqResult,reqStart

# Accesslog db syncprov.

dn: olcOverlay=syncprov,olcDatabase={2}hdb,cn=config

changetype: add

objectClass: olcOverlayConfig

objectClass: olcSyncProvConfig

olcOverlay: syncprov

olcSpNoPresent: TRUE

olcSpReloadHint: TRUE

# syncrepl Provider for primary db

dn: olcOverlay=syncprov,olcDatabase={1}hdb,cn=config

changetype: add

objectClass: olcOverlayConfig

objectClass: olcSyncProvConfig

olcOverlay: syncprov

olcSpNoPresent: TRUE

# accesslog overlay definitions for primary db

dn: olcOverlay=accesslog,olcDatabase={1}hdb,cn=config

objectClass: olcOverlayConfig

objectClass: olcAccessLogConfig

olcOverlay: accesslog

olcAccessLogDB: cn=accesslog

olcAccessLogOps: writes

olcAccessLogSuccess: TRUE

# scan the accesslog DB every day, and purge entries older than 7 days

olcAccessLogPurge: 07+00:00 01+00:00

</programlisting>

	<para>

	Change the rootDN in the LDIF file to match the one you have for your directory.

	</para>

        </step>

        <step>

		<para>

		The <application>apparmor</application> profile for slapd will not need to be adjusted for the 

		accesslog database location since <filename>/etc/apparmor.d/local/usr.sbin.slapd</filename> contains:

		</para>

<programlisting>

/var/lib/ldap/ r,

/var/lib/ldap/** rwk,

</programlisting>

		<para>

		Create a directory, set up a databse config file, and reload the apparmor profile:

		</para>

<screen>

<command>sudo -u openldap mkdir /var/lib/ldap/accesslog</command>

<command>sudo -u openldap cp /var/lib/ldap/DB_CONFIG /var/lib/ldap/accesslog</command>

<command>sudo service apparmor reload</command>

</screen>

	</step>

	<step>

		<para>

		Add the new content and, due to the apparmor change, restart the daemon:

		</para>

<screen>

<command>sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f provider_sync.ldif</command>

<command>sudo service slapd restart</command>

</screen>

	</step>

        </procedure>

        <para>

        The Provider is now configured.

        </para>

			</sect3>

			<sect3 id="openldap-consumer-configuration" status="review">

			<title>Consumer Configuration</title>

	<para>

	And now configure the <emphasis>Consumer</emphasis>.

	</para>

        <procedure>

	<step>

		<para>

		Install the software by going through <xref linkend="openldap-server-installation"/>. Make sure the slapd-config

		databse is identical to the Provider's. In particular, make sure schemas and the databse suffix are the same.

		</para>

	</step>

	<step>

		<para>

		Create an LDIF file with the following contents and name it <filename>consumer_sync.ldif</filename>:

		</para>

<programlisting>

dn: cn=module{0},cn=config

changetype: modify

add: olcModuleLoad

olcModuleLoad: syncprov

dn: olcDatabase={1}hdb,cn=config

changetype: modify

add: olcDbIndex

olcDbIndex: entryUUID eq

-

add: olcSyncRepl

olcSyncRepl: rid=0 provider=ldap://ldap01.example.com bindmethod=simple binddn="cn=admin,dc=example,dc=com" 

 credentials=secret searchbase="dc=example,dc=com" logbase="cn=accesslog" 

 logfilter="(&(objectClass=auditWriteObject)(reqResult=0))" schemachecking=on 

 type=refreshAndPersist retry="60 +" syncdata=accesslog

-

add: olcUpdateRef

olcUpdateRef: ldap://ldap01.example.com

</programlisting>

	<para>

	Ensure the following attributes have the correct values:

	</para>

	<itemizedlist>

	<listitem><para><emphasis>provider</emphasis> (Provider server's hostname -- ldap01.example.com in this example -- or IP address)</para></listitem>

	<listitem><para><emphasis>binddn</emphasis> (the admin DN you're using)</para></listitem>

	<listitem><para><emphasis>credentials</emphasis> (the admin DN password you're using)</para></listitem>

	<listitem><para><emphasis>searchbase</emphasis> (the database suffix you're using)</para></listitem>

	<listitem><para><emphasis>olcUpdateRef</emphasis> (Provider server's hostname or IP address)</para></listitem>

	<listitem><para><emphasis>rid</emphasis> (Replica ID, an unique 

	3-digit that identifies the replica. Each consumer should have at 

	least one rid)</para></listitem>

	</itemizedlist>

        </step>

	<step>

	<para>

	Add the new content:

	</para>

<screen>

<command>sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f consumer_sync.ldif</command>

</screen>

	</step>

        </procedure>

        <para>

        You're done. The two databases (suffix: dc=example,dc=com) should now be synchronizing.

        </para>

			</sect3>

			<sect3 id="openldap-testing" status="review">

			<title>Testing</title>

	<para>

	Once replication starts, you can monitor it by running

	</para>

<screen>

<command>ldapsearch -z1 -LLLQY EXTERNAL -H ldapi:/// -s base -b dc=example,dc=com contextCSN</command>

<computeroutput>

dn: dc=example,dc=com

contextCSN: 20120201193408.178454Z#000000#000#000000