~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="(&amp;(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
</computeroutput>
</screen>

	<para>
	on both the provider and the consumer. 
	Once the output 
	(<computeroutput>20120201193408.178454Z#000000#000#000000</computeroutput> 
	in the above example) for both machines match, you have replication. 
	Every time a change is done in the provider, this value will 
	change and so should the one in the consumer(s). 
	</para>

	<para>
	If your connection is slow and/or your ldap database large, it might 
	take a while for the consumer's  <emphasis>contextCSN</emphasis>
	match the provider's. But, you will know it is progressing since the
	consumer's  <emphasis>contextCSN</emphasis> will be steadly 
	increasing.
	</para>

	<para>
	If the consumer's  <emphasis>contextCSN</emphasis> is missing or does not
	match the provider, you should stop and figure out the issue before continuing.
	Try checking the slapd (syslog) and the auth log files in the provider
	to see if the consumer's authentication requests were successful or 
	its requests to retrieve data (they look like a lot of ldapsearch
	statements) return no errors.
	</para>

	<para>
	To test if it worked simply query, on the Consumer, the DNs in the database:
	</para>

<screen>
<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b dc=example,dc=com dn</command>
</screen>

	<para>
	You should see the user 'john' and the group 'miners' as well as the nodes 'People' and 'Groups'.
	</para>

			</sect3>

		</sect2>

		<sect2 id="openldap-server-acl" status="review">
		<title>Access Control</title>

	<para>
	The management of what type of access (read, write, etc) users should be granted to resources is known as
	<emphasis>access control</emphasis>. The configuration directives involved are called <emphasis>access control lists</emphasis> or ACL.
	</para>

	<para>
	When we installed the slapd package various ACL were set up automatically. We will look at a few important consequences of those
	defaults and, in so doing, we'll get an idea of how ACLs work and how they're configured.
	</para>

	<para>
	To get the effective ACL for an LDAP query we need to look at the ACL entries of the database being queried as well as those of the
	special frontend database instance. The ACLs belonging to the latter act as defaults in case those of the former do not match. The
	frontend database is the second to be consulted and the ACL to be applied is the first to match ("first match wins") among these 2
	ACL sources. The following commands will give, respectively, the ACLs of the hdb database ("dc=example,dc=com") and those of the
	frontend database:
	</para>

<screen>
<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \
cn=config '(olcDatabase={1}hdb)' olcAccess</command>
<computeroutput>
dn: olcDatabase={1}hdb,cn=config
olcAccess: {0}to attrs=userPassword,shadowLastChange by self write by anonymous
              auth by dn="cn=admin,dc=example,dc=com" write by * none
olcAccess: {1}to dn.base="" by * read
olcAccess: {2}to * by self write by dn="cn=admin,dc=example,dc=com" write by *
  read
</computeroutput>
</screen>

	<note>
	  	<para>
		The rootDN always has full rights to its database. Including it in an ACL does provide an explicit configuration but it also causes
		slapd to incur a performance penalty.
	  	</para>
	</note>

<screen>
<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \
cn=config '(olcDatabase={-1}frontend)' olcAccess</command>
<computeroutput>
dn: olcDatabase={-1}frontend,cn=config
olcAccess: {0}to * by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,
              cn=external,cn=auth manage by * break
olcAccess: {1}to dn.exact="" by * read
olcAccess: {2}to dn.base="cn=Subschema" by * read
</computeroutput>
</screen>

	<para>
	The very first ACL is crucial:
	</para>

<programlisting>
olcAccess: {0}to attrs=userPassword,shadowLastChange by self write by anonymous
              auth by dn="cn=admin,dc=example,dc=com" write by * none
</programlisting>

	<para>
	This can be represented differently for easier digestion:
	</para>

<programlisting>
to attrs=userPassword
	by self write
	by anonymous auth
	by dn="cn=admin,dc=example,dc=com" write
	by * none

to attrs=shadowLastChange
	by self write
	by anonymous auth
	by dn="cn=admin,dc=example,dc=com" write
	by * none
</programlisting>

	<para>
	This compound ACL (there are 2) enforces the following:
	</para>

	<itemizedlist>

	<listitem>
	<para>
	Anonymous 'auth' access is provided to the <emphasis>userPassword</emphasis> attribute for the initial connection to
	occur. Perhaps counter-intuitively, 'by anonymous auth' is needed even when anonymous access to the DIT is
	unwanted. Once the remote end is connected, howerver, authentication can occur (see next point).
	</para>
	</listitem>

	<listitem>
	<para>
	Authentication can happen because all users have 'read' (due to 'by self write') access to the <emphasis>userPassword</emphasis> attribute.
	</para>
	</listitem>

	<listitem>
	<para>
	The <emphasis>userPassword</emphasis> attribute is otherwise unaccessible by all other users, with the exception of the rootDN, who
	has complete access to it.
	</para>
	</listitem>

	<listitem>
	<para>
	In order for users to change their own password, using <command>passwd</command> or other utilities, the
	<emphasis>shadowLastChange</emphasis> attribute needs to be accessible once a user has authenticated. 
	</para>
	</listitem>

	</itemizedlist>

	<para>
	This DIT can be searched anonymously because of 'by * read' in this ACL:
	</para>

<programlisting>
to *
	by self write
	by dn="cn=admin,dc=example,dc=com" write
	by * read
</programlisting>

	<para>
	If this is unwanted then you need to change the ACLs. To force authentication during a bind request you can alternatively (or
	in combination with the modified ACL) use the 'olcRequire: authc' directive.
	</para>

	<para>
	As previously mentioned, there is no administrative account created for the slapd-config database. There is, however, a SASL
	identity that is granted full access to it. It represents the localhost's superuser (root/sudo). Here it is:
	</para>

<programlisting>
dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth 
</programlisting>

        <para>
        The following command will display the ACLs of the slapd-config database:
        </para>

<screen>
<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \
cn=config '(olcDatabase={0}config)' olcAccess</command>
<computeroutput>
dn: olcDatabase={0}config,cn=config
olcAccess: {0}to * by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,
              cn=external,cn=auth manage by * break
</computeroutput>
</screen>

        <para>
	Since this is a SASL identity we need to use a SASL <emphasis>mechanism</emphasis> when invoking the LDAP utility in question and
	we have seen it plenty of times in this guide. It is the EXTERNAL mechanism. See the previous command for an example. Note that:
	</para>
        
	<procedure>

	<step>
		<para>
		You must use <emphasis>sudo</emphasis> to become the root identity in order for the ACL to match.
		</para>
	</step>

	<step>
		<para>
		The EXTERNAL mechanism works via <emphasis>IPC</emphasis> (UNIX domain sockets). This means you must use the <emphasis>ldapi</emphasis>
		URI format.
		</para>
	</step>

	</procedure>

        <para>
	A succinct way to get all the ACLs is like this:
        </para>

<screen>
<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b \
cn=config '(olcAccess=*)' olcAccess olcSuffix</command>
</screen>

        <para>
        There is much to say on the topic of access control. See the man page for
	<ulink url="http://manpages.ubuntu.com/manpages/en/man5/slapd.access.5.html">slapd.access</ulink>.
        </para>

		</sect2>

		<sect2 id="openldap-tls" status="review">
		<title>TLS</title>

	<para>
	When authenticating to an OpenLDAP server it is best to do so using an encrypted session. This can be accomplished using Transport
	Layer Security (TLS).
	</para>

	<para>
	Here, we will be our own <emphasis>Certificate Authority</emphasis> and then create and sign our LDAP server certificate as that CA.
	Since <application>slapd</application> is compiled using the <application>gnutls</application> library, we will use the
	<application>certtool</application> utility to complete these tasks.
	</para>

	<procedure>

	<step>
		<para>
		Install the <application>gnutls-bin</application> and <application>ssl-cert</application> packages:
		</para>

<screen>
<command>sudo apt-get install gnutls-bin ssl-cert</command>
</screen>

	</step>

	<step>
		<para>
		Create a private key for the Certificate Authority:
		</para>

<screen>
<command>sudo sh -c "certtool --generate-privkey > /etc/ssl/private/cakey.pem"</command>
</screen>

	</step>

       	<step>
		<para>
		Create the template/file <filename>/etc/ssl/ca.info</filename> to define the CA:
		</para>

<programlisting>
cn = Example Company
ca
cert_signing_key
</programlisting>

	</step>

       	<step>
		<para>
		Create the self-signed CA certificate:
		</para>

<screen>
<command>sudo certtool --generate-self-signed \
--load-privkey /etc/ssl/private/cakey.pem \ 
--template /etc/ssl/ca.info \
--outfile /etc/ssl/certs/cacert.pem</command>
</screen>

	</step>

       	<step>
		<para>
		Make a private key for the server:
		</para>

<screen>
<command>sudo certtool --generate-privkey \
--bits 1024 \
--outfile /etc/ssl/private/ldap01_slapd_key.pem</command>
</screen>

		<note>
			<para>
			Replace <emphasis>ldap01</emphasis> in the filename with your server's hostname. Naming the certificate and
			key for the host and service that will be using them will help keep things clear.
			</para>
		</note>

	</step>

	<step>
		<para>
		Create the <filename>/etc/ssl/ldap01.info</filename> info file containing:
		</para>

<programlisting>
organization = Example Company
cn = ldap01.example.com
tls_www_server
encryption_key
signing_key
expiration_days = 3650
</programlisting>

		<para>
		The above certificate is good for 10 years. Adjust accordingly.
		</para>
	</step>

	<step>
		<para>
		Create the server's certificate:
		</para>

<screen>
<command>sudo certtool --generate-certificate \
--load-privkey /etc/ssl/private/ldap01_slapd_key.pem \
--load-ca-certificate /etc/ssl/certs/cacert.pem \
--load-ca-privkey /etc/ssl/private/cakey.pem \
--template /etc/ssl/ldap01.info \
--outfile /etc/ssl/certs/ldap01_slapd_cert.pem</command>
</screen>

	</step>

	</procedure>

	<para>
	Create the file <filename>certinfo.ldif</filename> with the following contents (adjust accordingly, our example assumes we created certs using https://www.cacert.org):
	</para>

<programlisting>
dn: cn=config
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/ssl/certs/cacert.pem
-
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/ssl/certs/ldap01_slapd_cert.pem
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/ssl/private/ldap01_slapd_key.pem
</programlisting>

        <para>
	Use the <application>ldapmodify</application> command to tell slapd about our TLS work via the slapd-config database:
        </para>

<screen>
<command>sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f /etc/ssl/certinfo.ldif</command>
</screen>
	
        <para>
        Contratry to popular belief, you do not need <emphasis>ldaps://</emphasis> in <filename>/etc/default/slapd</filename>
	in order to use encryption. You should have just:
        </para>

<programlisting>
SLAPD_SERVICES="ldap:/// ldapi:///"
</programlisting>

	<note>
		<para>
		LDAP over TLS/SSL (ldaps://) is deprecated in favour of <emphasis>StartTLS</emphasis>. The latter refers to an
		existing LDAP session (listening on TCP port 389) becoming protected by TLS/SSL whereas LDAPS, like HTTPS, is a
		distinct encrypted-from-the-start protocol that operates over TCP port 636.
		</para>
	</note>


	<para>
	Tighten up ownership and permissions:
	</para>

<screen>
<command>sudo adduser openldap ssl-cert</command>
<command>sudo chgrp ssl-cert /etc/ssl/private/ldap01_slapd_key.pem</command>
<command>sudo chmod g+r /etc/ssl/private/ldap01_slapd_key.pem</command>
<command>sudo chmod o-r /etc/ssl/private/ldap01_slapd_key.pem</command>
</screen>

	<para>
	Restart OpenLDAP:
	</para>

<screen>
<command>sudo service slapd restart</command>
</screen>

	<para>
	Check your host's logs (/var/log/syslog) to see if the server has started properly.
	</para>

		</sect2>

		<sect2 id="openldap-tls-replication" status="review">
		<title>Replication and TLS</title>

	<para>
	If you have set up replication between servers, it is common practice to encrypt (StartTLS) the replication traffic to prevent
	evesdropping. This is distinct from using encryption with authentication as we did above. In this section we will build on that
	TLS-authentication work.
	</para>

	<para>
	The assumption here is that you have set up replication between Provider and Consumer according to <xref linkend="openldap-server-replication"/>
	and have configured TLS for authentication on the Provider by following <xref linkend="openldap-tls"/>.
	</para>

	<para>
	As previously stated, the objective (for us) with replication is high availablity for the LDAP service. Since we have TLS for
	authentication on the Provider we will require the same on the Consumer. In addition to this, however, we want to encrypt
	replication traffic. What remains to be done is to create a key and certificate for the Consumer and then configure accordingly.
	We will generate the key/certificate on the Provider, to avoid having to create another CA certificate, and then transfer the
	necessary material over to the Consumer.
	</para>

	<procedure>

	<step>
                <para>
                On the Provider,
                </para>

                <para>
		Create a holding directory (which will be used for the eventual transfer) and then the Consumer's private key:
                </para>

<screen>
<command>mkdir ldap02-ssl</command>
<command>cd ldap02-ssl</command>
<command>sudo certtool --generate-privkey \
--bits 1024 \
--outfile ldap02_slapd_key.pem</command>
</screen>

                <para>
                Create an info file, <filename>ldap02.info</filename>, for the Consumer server, adjusting its values accordingly:
                </para>  

<programlisting>
organization = Example Company
cn = ldap02.example.com
tls_www_server
encryption_key
signing_key
expiration_days = 3650
</programlisting>

                <para>
                Create the Consumer's certificate:
                </para>

<screen>
<command>sudo certtool --generate-certificate \
--load-privkey ldap02_slapd_key.pem \
--load-ca-certificate /etc/ssl/certs/cacert.pem \
--load-ca-privkey /etc/ssl/private/cakey.pem \
--template ldap02.info \
--outfile ldap02_slapd_cert.pem</command>
</screen>

                <para>
                Get a copy of the CA certificate:
                </para>

<screen>
<command>cp /etc/ssl/certs/cacert.pem .</command>
</screen>

		<para>
		We're done. Now transfer the <filename>ldap02-ssl</filename> directory to the Consumer.  Here we use scp (adjust accordingly):
		</para>

<screen>
<command>cd ..</command>
<command>scp -r ldap02-ssl user@consumer:</command>
</screen>

	</step>

	<step>  
		<para>
		On the Consumer,
		</para>

		<para>
		Configure TLS authentication:
		</para>

<screen>
<command>sudo apt-get install ssl-cert</command>
<command>sudo adduser openldap ssl-cert</command>
<command>sudo cp ldap02_slapd_cert.pem cacert.pem /etc/ssl/certs</command>
<command>sudo cp ldap02_slapd_key.pem /etc/ssl/private</command>
<command>sudo chgrp ssl-cert /etc/ssl/private/ldap02_slapd_key.pem</command>
<command>sudo chmod g+r /etc/ssl/private/ldap02_slapd_key.pem</command>
<command>sudo chmod o-r /etc/ssl/private/ldap02_slapd_key.pem</command>
</screen>

		<para>
		Create the file <filename>/etc/ssl/certinfo.ldif</filename> with the following contents (adjust accordingly):
		</para>

<programlisting>
dn: cn=config
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/ssl/certs/cacert.pem
-
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/ssl/certs/ldap02_slapd_cert.pem
-
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/ssl/private/ldap02_slapd_key.pem
</programlisting>

		<para>
		Configure the slapd-config database:
		</para>

<screen>
<command>sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f certinfo.ldif</command>
</screen>
	
		<para>
		Configure <filename>/etc/default/slapd</filename> as on the Provider (SLAPD_SERVICES).
		</para>
	</step>

	<step>
		<para>
		On the Consumer,
		</para>

		<para>
		Configure TLS for Consumer-side replication. Modify the existing <emphasis>olcSyncrepl</emphasis> attribute by tacking
		on some TLS options. In so doing, we will see, for the first time, how to change an attribute's value(s).
		</para>

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

<programlisting>
dn: olcDatabase={1}hdb,cn=config
replace: 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="(&amp;(objectClass=auditWriteObject)(reqResult=0))"
 schemachecking=on type=refreshAndPersist retry="60 +" syncdata=accesslog
 starttls=critical tls_reqcert=demand
</programlisting>

		<para>
		The extra options specify, respectively, that the consumer must use StartTLS and that the CA certificate is required to verify the
		Provider's identity. Also note the LDIF syntax for changing the values of an attribute ('replace').
		</para>

		<para>
		Implement these changes:
		</para>

<screen>
<command>sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f consumer_sync_tls.ldif</command>
</screen>

		<para>
		And restart slapd:
		</para>

<screen>
<command>sudo service slapd restart</command>
</screen>

	</step>

	<step>
		<para>
		On the Provider,
		</para>

		<para>
		Check to see that a TLS session has been established. In <filename>/var/log/syslog</filename>, providing you have
		'conns'-level logging set up, you should see messages similar to:		      
		</para>

<programlisting>
slapd[3620]: conn=1047 fd=20 ACCEPT from IP=10.153.107.229:57922 (IP=0.0.0.0:389)
slapd[3620]: conn=1047 op=0 EXT oid=1.3.6.1.4.1.1466.20037
slapd[3620]: conn=1047 op=0 STARTTLS
slapd[3620]: conn=1047 op=0 RESULT oid= err=0 text=
slapd[3620]: conn=1047 fd=20 TLS established tls_ssf=128 ssf=128
slapd[3620]: conn=1047 op=1 BIND dn="cn=admin,dc=example,dc=com" method=128
slapd[3620]: conn=1047 op=1 BIND dn="cn=admin,dc=example,dc=com" mech=SIMPLE ssf=0
slapd[3620]: conn=1047 op=1 RESULT tag=97 err=0 text
</programlisting>

	</step>

	</procedure>

		</sect2>

		<sect2 id="openldap-auth-config" status="review">
		<title>LDAP Authentication</title>

	<para>
	Once you have a working LDAP server, you will need to install libraries on the client that will know how and when to contact it.
	On Ubuntu, this has been traditionally accomplished by installing the <application>libnss-ldap</application> package. This package
	will bring in other tools that will assist you in the configuration step. Install this package now:
	</para> 

<screen>
<command>sudo apt-get install libnss-ldap</command>
</screen>

        <para>
        You will be prompted for details of your LDAP server. If you make a mistake you can try again using:
        </para>
	
<screen>
<command>sudo dpkg-reconfigure ldap-auth-config</command>
</screen>

	<para>
	The results of the dialog can be seen in <filename>/etc/ldap.conf</filename>. If your server requires options not covered in the menu 
	edit this file accordingly.
	</para>

	<para>
	Now configure the LDAP profile for NSS:
	</para>

<screen>
<command>sudo auth-client-config -t nss -p lac_ldap</command>
</screen>
         
	<para>
	Configure the system to use LDAP for authentication:
	</para>

<screen>
<command>sudo pam-auth-update</command>
</screen>

	<para>
	From the menu, choose LDAP and any other authentication mechanisms you need.
	</para>

	<para>
	You should now be able to log in using LDAP-based credentials.
	</para> 

	<para>
	LDAP clients will need to refer to multiple servers if replication is in use. In <filename>/etc/ldap.conf</filename> you would
	have something like:
	</para>

<programlisting>
uri ldap://ldap01.example.com ldap://ldap02.example.com
</programlisting>

	<para>
	The request will time out and the Consumer (ldap02) will attempt to be reached if the Provider (ldap01) becomes unresponsive.
	</para>

	<para>
	If you are going to use LDAP to store Samba users you will need to configure the Samba server to authenticate using LDAP. See
	<xref linkend="samba-ldap"/> for details.
	</para>

	<note>
		<para>
		An alternative to the <application>libnss-ldap</application> package is the <application>libnss-ldapd</application>
		package. This, however, will bring in the <application>nscd</application> package which is problably not wanted. Simply
		remove it afterwards.
		</para>
	</note>
		
		</sect2>

		<sect2 id="ldap-usergroup-management" status="review">
		<title>User and Group Management</title>

	<para>
	The <application>ldap-utils</application> package comes with enough utilities to manage the directory but the long string of
	options needed can make them a burden to use. The <application>ldapscripts</application> package contains wrapper scripts to these
	utilities that some people find easier to use.
	</para>

	<para>
	Install the package:
	</para>

<screen>
<command>sudo apt-get install ldapscripts</command>
</screen>

	<para> 
	Then edit the file <filename>/etc/ldapscripts/ldapscripts.conf</filename> to arrive at something similar to the following:
	</para>       

<programlisting>
SERVER=localhost
BINDDN='cn=admin,dc=example,dc=com'
BINDPWDFILE="/etc/ldapscripts/ldapscripts.passwd"
SUFFIX='dc=example,dc=com'
GSUFFIX='ou=Groups'
USUFFIX='ou=People'
MSUFFIX='ou=Computers'
GIDSTART=10000
UIDSTART=10000
MIDSTART=10000
</programlisting>

	<para>
	Now, create the <filename>ldapscripts.passwd</filename> file to allow rootDN access to the directory:
	</para>

<screen>
<command>sudo sh -c "echo -n 'secret' > /etc/ldapscripts/ldapscripts.passwd"</command>
<command>sudo chmod 400 /etc/ldapscripts/ldapscripts.passwd</command>
</screen>

	<note>
		<para>
		Replace <quote>secret</quote> with the actual password for your database's rootDN user.
		</para>
	</note>

	<para>
	The scripts are now ready to help manage your directory. Here are some examples of how to use them:
	</para>

	<itemizedlist>

	<listitem>
		<para>
		Create a new user:
		</para>

<screen>
<command>sudo ldapadduser george example</command>
</screen>

		<para>
		This will create a user with uid <emphasis role="italic">george</emphasis> and set the user's primary group (gid) to
		<emphasis role="italic">example</emphasis>
		</para>
	</listitem>

	<listitem>
		<para>
		Change a user's password:
		</para>

<screen>
<command>sudo ldapsetpasswd george</command>
<computeroutput>Changing password for user uid=george,ou=People,dc=example,dc=com</computeroutput>
<userinput>New Password: </userinput>
<userinput>New Password (verify): </userinput>
</screen>

	</listitem>

	<listitem>
		<para>
		Delete a user:
		</para>

<screen>
<command>sudo ldapdeleteuser george</command>
</screen>

	</listitem>

	<listitem>
		<para>
		Add a group:
		</para>

<screen>
<command>sudo ldapaddgroup qa</command>
</screen>

	</listitem>

	<listitem>
		<para>
		Delete a group:
		</para>

<screen>
<command>sudo ldapdeletegroup qa</command>
</screen>

	</listitem>

	<listitem>
		<para>
		Add a user to a group:
		</para>

<screen>
<command>sudo ldapaddusertogroup george qa</command>
</screen>

		<para>
		You should now see a <emphasis>memberUid</emphasis> attribute for the <emphasis role="italic">qa</emphasis> group with 
		a value of <emphasis role="italic">george</emphasis>.
		</para>
	</listitem>

	<listitem>
		<para>
		Remove a user from a group:
		</para>

<screen>
<command>sudo ldapdeleteuserfromgroup george qa</command>
</screen>

		<para>
		The <emphasis>memberUid</emphasis> attribute should now be removed from the <emphasis role="italic">qa</emphasis>
		group.
		</para>
	</listitem>

	<listitem>
		<para>
		The <application>ldapmodifyuser</application> script allows you to add, remove, or replace a user's attributes.  
		The script uses the same syntax as the <application>ldapmodify</application> utility.  For example:
		</para>

<screen>
<command>sudo ldapmodifyuser george</command>
<computeroutput># About to modify the following entry :
dn: uid=george,ou=People,dc=example,dc=com
objectClass: account
objectClass: posixAccount
cn: george
uid: george
uidNumber: 1001
gidNumber: 1001
homeDirectory: /home/george
loginShell: /bin/bash
gecos: george
description: User account
userPassword:: e1NTSEF9eXFsTFcyWlhwWkF1eGUybVdFWHZKRzJVMjFTSG9vcHk=

# Enter your modifications here, end with CTRL-D.
dn: uid=george,ou=People,dc=example,dc=com</computeroutput>
<userinput>replace: gecos
gecos: George Carlin</userinput>
</screen>

		<para>
		The user's <emphasis>gecos</emphasis> should now be <quote>George Carlin</quote>.
		</para>
	</listitem>

	<listitem>
		<para>
		A nice feature of <application>ldapscripts</application> is the template system. Templates allow you to customize the
		attributes of user, group, and machine objects. For example, to enable the <emphasis>user</emphasis> template edit
		<filename>/etc/ldapscripts/ldapscripts.conf</filename> changing:
		</para>

<programlisting>
UTEMPLATE="/etc/ldapscripts/ldapadduser.template"
</programlisting>

		<para>
		There are <emphasis role="italic">sample</emphasis> templates in the <filename>/usr/share/doc/ldapscripts/examples</filename> directory.
		Copy or rename the <filename>ldapadduser.template.sample</filename> file to
		<filename>/etc/ldapscripts/ldapadduser.template</filename>:
		</para>

<screen>
<command>sudo cp /usr/share/doc/ldapscripts/examples/ldapadduser.template.sample \
/etc/ldapscripts/ldapadduser.template</command>
</screen>

		<para>
		Edit the new template to add the desired attributes. The following will create new users with an objectClass of
		inetOrgPerson:
		</para>

<programlisting>
dn: uid=&lt;user&gt;,&lt;usuffix&gt;,&lt;suffix&gt;
objectClass: inetOrgPerson
objectClass: posixAccount
cn: &lt;user&gt;
sn: &lt;ask&gt;
uid: &lt;user&gt;
uidNumber: &lt;uid&gt;
gidNumber: &lt;gid&gt;
homeDirectory: &lt;home&gt;
loginShell: &lt;shell&gt;
gecos: &lt;user&gt;
description: User account
title: Employee
</programlisting>

		<para>
		Notice the <emphasis>&lt;ask&gt;</emphasis> option used for the <emphasis>sn</emphasis> attribute. This 
		will make <application>ldapadduser</application> prompt you for its value.
		</para>
	</listitem>

	</itemizedlist>

        <para>
        There are utilities in the package that were not covered here. Here is a complete list:
        </para>

<programlisting>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldaprenamemachine.1.html">ldaprenamemachine</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapadduser.1.html">ldapadduser</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapdeleteuserfromgroup.1.html">ldapdeleteuserfromgroup</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapfinger.1.html">ldapfinger</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapid.1.html">ldapid</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapgid.1.html">ldapgid</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapmodifyuser.1.html">ldapmodifyuser</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldaprenameuser.1.html">ldaprenameuser</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/lsldap.1.html">lsldap</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapaddusertogroup.1.html">ldapaddusertogroup</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapsetpasswd.1.html">ldapsetpasswd</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapinit.1.html">ldapinit</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapaddgroup.1.html">ldapaddgroup</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapdeletegroup.1.html">ldapdeletegroup</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapmodifygroup.1.html">ldapmodifygroup</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapdeletemachine.1.html">ldapdeletemachine</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldaprenamegroup.1.html">ldaprenamegroup</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapaddmachine.1.html">ldapaddmachine</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapmodifymachine.1.html">ldapmodifymachine</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapsetprimarygroup.1.html">ldapsetprimarygroup</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man1/ldapdeleteuser.1.html">ldapdeleteuser</ulink>
</programlisting>
		
		</sect2>

		<sect2 id="ldap-backup" status="review">
		<title>Backup and Restore</title>

	<para>
	Now we have ldap running just the way we want, it is time to 
	ensure we can save all of our work and restore it as needed.
	</para>

	<para>
	What we need is a way to backup the ldap database(s), specifically
	the backend (cn=config) and frontend (dc=example,dc=com). 
	If we are going to backup those databases into, say, 
	<filename>/export/backup</filename>, we could use 
	<application>slapcat</application>
	as shown in the following script,
	called <filename>/usr/local/bin/ldapbackup</filename>:
	</para>

<programlisting>
#!/bin/bash

BACKUP_PATH=/export/backup
SLAPCAT=/usr/sbin/slapcat

nice ${SLAPCAT} -n 0 > ${BACKUP_PATH}/config.ldif
nice ${SLAPCAT} -n 1 > ${BACKUP_PATH}/example.com.ldif
nice ${SLAPCAT} -n 2 > ${BACKUP_PATH}/access.ldif
chmod 640 ${BACKUP_PATH}/*.ldif
</programlisting>

	<note>
		<para>
		These files are uncompressed text files containing
		everything in your ldap databases including the tree 
		layout, usernames, and every password. So, you might
		want to consider making <filename>/export/backup</filename>
		an encrypted partition and even having the script encrypt 
		those files as it creates them. Ideally you should do both,
		but that depends on your security requirements.
		</para>
	</note>

	<para>
	Then, it is just a matter of having a cron script to run this
	program as often as we feel comfortable with. For many, once a day 
	suffices. For others, more often is required. Here is an example
	of a cron script called <filename>/etc/cron.d/ldapbackup</filename>
	that is run every night at 22:45h:
	</para>

<programlisting>
MAILTO=backup-emails@domain.com
45 22 * * *  root    /usr/local/bin/ldapbackup
</programlisting>

	<para>
	Now the files are created, they should be copied to a backup
	server. 
	</para>

	<para>
	Assuming we did a fresh reinstall of ldap, the restore process 
	could be something like this:
	</para>

<screen>
<command>sudo service slapd stop</command>
<command>sudo mkdir /var/lib/ldap/accesslog</command>
<command>sudo slapadd -F /etc/ldap/slapd.d -n 0 -l /export/backup/config.ldif</command>
<command>sudo slapadd -F /etc/ldap/slapd.d -n 1 -l /export/backup/domain.com.ldif</command>
<command>sudo slapadd -F /etc/ldap/slapd.d -n 2 -l /export/backup/access.ldif</command>
<command>sudo chown -R openldap:openldap /etc/ldap/slapd.d/</command>
<command>sudo chown -R openldap:openldap /var/lib/ldap/</command>
<command>sudo service slapd start</command>
</screen>

		</sect2>

		<sect2 id="openldap-server-resources" status="review">
		<title>Resources</title>

	<itemizedlist>

	<listitem>
	<para>
	The primary resource is the upstream documentation: <ulink url="http://www.openldap.org/">www.openldap.org</ulink>
	</para>
	</listitem>

	<listitem>
	<para>
	There are many man pages that come with the slapd package. Here are some important ones, especially considering the material
	presented in this guide:
	</para>

<programlisting>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/slapd.8.html">slapd</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man5/slapd-config.5.html">slapd-config</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man5/slapd.access.5.html">slapd.access</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man5/slapo-syncprov.5.html">slapo-syncprov</ulink>
</programlisting>

	</listitem>

	<listitem>
	<para>
	Other man pages:
	</para>

<programlisting>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/auth-client-config.8.html">auth-client-config</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/pam-auth-update.8.html">pam-auth-update</ulink>
</programlisting>

	</listitem>

	<listitem>
	<para>
	Zytrax's <ulink url="http://www.zytrax.com/books/ldap/">LDAP for Rocket Scientists</ulink>; a less pedantic but comprehensive treatment of LDAP
	</para>
	</listitem>

	<listitem>
	<para>
	A Ubuntu community <ulink url="https://help.ubuntu.com/community/OpenLDAPServer">OpenLDAP wiki</ulink> page has a collection of notes
	</para>
	</listitem>

	<listitem>
	<para>
	O'Reilly's <ulink url="http://www.oreilly.com/catalog/ldapsa/">LDAP System Administration</ulink> (textbook; 2003)
	</para>
	</listitem>

	<listitem>
	<para>
	Packt's <ulink url="http://www.packtpub.com/OpenLDAP-Developers-Server-Open-Source-Linux/book">Mastering OpenLDAP</ulink> (textbook; 2007)
	</para>
	</listitem>

	</itemizedlist>
		</sect2>

	</sect1>

<sect1 id="samba-ldap" status="review">
<title>Samba and LDAP</title>

	<para>
	This section covers the integration of Samba with LDAP. The Samba server's role will be that of a "standalone" server and the LDAP
	directory will provide the authentication layer in addition to containing the user, group, and machine account information that Samba
	requires in order to function (in any of its 3 possible roles). The pre-requisite is an OpenLDAP server configured with a directory
	that can accept authentication requests. See <xref linkend="openldap-server"/> for details on fulfilling this requirement. Once this
	section is completed, you will need to decide what specifically you want Samba to do for you and then configure it accordingly.
	</para>

  <sect2 id="samba-ldap-installation" status="review">
  <title>Software Installation</title>
  
	<para>
	There are three packages needed when integrating Samba with LDAP: <application>samba</application>, <application>samba-doc</application>,
	and <application>smbldap-tools</application> packages.
	</para>

	<para>
	Strictly speaking, the <application>smbldap-tools</application> package isn't needed, but unless you have some other way to manage the various
	Samba entities (users, groups, computers) in an LDAP context then you should install it.  
	</para>

	<para>
	Install these packages now:
	</para>

<screen>
<command>sudo apt-get install samba samba-doc smbldap-tools</command>
</screen>

  </sect2>

  <sect2 id="samba-ldap-openldap-configuration" status="review">
  <title>LDAP Configuration</title>

	<para>
	We will now configure the LDAP server so that it can accomodate Samba data. We will perform three tasks in this section:
	</para>
	
	<procedure>

		<step>
		<para>Import a schema</para>
		</step>

		<step>
		<para>Index some entries</para>
		</step>

		<step>
		<para>Add objects</para>
		</step>

	</procedure>

    <sect3 id="samba-ldap-openldap-configuration-samba-schema" status="review">
    <title>Samba schema</title>

      	<para>
      	In order for OpenLDAP to be used as a backend for Samba, logically, the DIT will need to use attributes that can properly describe
	Samba data. Such attributes can be obtained by introducing a Samba LDAP schema. Let's do this now.
      	</para>
      
	<note>
		<para>
		For more information on schemas and their installation see <xref linkend="openldap-configuration"/>.
		</para>
	</note>

 	<procedure>

	<step>
		<para>
		The schema is found in the now-installed <application>samba-doc</application> package. It needs to be unzipped and copied to 
		the <filename>/etc/ldap/schema</filename> directory:
		</para>
        
<screen>
<command>sudo cp /usr/share/doc/samba-doc/examples/LDAP/samba.schema.gz /etc/ldap/schema</command>
<command>sudo gzip -d /etc/ldap/schema/samba.schema.gz</command>
</screen>

	</step>

	<step>
		<para>                  
		Have the configuration file <filename>schema_convert.conf</filename> that contains 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
include /etc/ldap/schema/samba.schema
</programlisting>

	</step>

       	<step>
                <para>
                Have the directory <filename>ldif_output</filename> hold output.
                </para> 
       	</step>

       	<step>
		<para>
		Determine the index of the schema:
		</para>

<screen>
<command>slapcat -f schema_convert.conf -F ldif_output -n 0 | grep samba,cn=schema</command>
<computeroutput>
dn: cn={14}samba,cn=schema,cn=config
</computeroutput>
</screen>

	</step>

       	<step>
                <para>
                Convert the schema to LDIF format:
                </para>

<screen>
<command>slapcat -f schema_convert.conf -F ldif_output -n0 -H \
ldap:///cn={14}samba,cn=schema,cn=config -l cn=samba.ldif</command>
</screen>

       	</step>

       	<step>
                <para>
                Edit the generated <filename>cn=samba.ldif</filename> file by removing index information to arrive at:
                </para> 

<programlisting>
dn: cn=samba,cn=schema,cn=config
...
cn: samba
</programlisting>
		
                <para>
                Remove the bottom lines:
                </para> 

<programlisting>
structuralObjectClass: olcSchemaConfig
entryUUID: b53b75ca-083f-102d-9fff-2f64fd123c95
creatorsName: cn=config
createTimestamp: 20080827045234Z
entryCSN: 20080827045234.341425Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20080827045234Z
</programlisting>

		<para>
		Your attribute values will vary.
		</para>
	</step>

       	<step>
                <para>
                Add the new schema:
                </para>

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

                <para>
                To query and view this new schema:
                </para>

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

	</step>

       	</procedure>

    </sect3>

    <sect3 id="samba-ldap-openldap-configuration-samba-indices" status="review">
    <title>Samba indices</title>

	<para>
	Now that slapd knows about the Samba attributes, we can set up some indices based on them. Indexing entries is a way to improve
	performance when a client performs a filtered search on the DIT.
	</para>

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

<programlisting>
dn: olcDatabase={1}hdb,cn=config
changetype: modify
add: olcDbIndex
olcDbIndex: uidNumber eq
olcDbIndex: gidNumber eq
olcDbIndex: loginShell eq
olcDbIndex: uid eq,pres,sub
olcDbIndex: memberUid eq,pres,sub
olcDbIndex: uniqueMember eq,pres
olcDbIndex: sambaSID eq
olcDbIndex: sambaPrimaryGroupSID eq
olcDbIndex: sambaGroupType eq
olcDbIndex: sambaSIDList eq
olcDbIndex: sambaDomainName eq
olcDbIndex: default sub
</programlisting>

	<para>
	Using the <application>ldapmodify</application> utility load the new indices:
	</para>

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

	<para>
	If all went well you should see the new indices using <application>ldapsearch</application>:
	</para>

<screen>
<command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H \
ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex</command>
</screen>

    </sect3>

    <sect3 id="samba-ldap-openldap-configuration-populating" status="review">
    <title>Adding Samba LDAP objects</title>
 
	<para>
	Next, configure the <application>smbldap-tools</application> package to match your environment.  The package 
	is supposed to come with a configuration helper script (smbldap-config.pl, formerly configure.pl) that will ask questions
	about the needed options but there is a <ulink url="https://bugs.launchpad.net/serverguide/+bug/997172">bug</ulink>
	whereby it is not installed (but found in the source code; 'apt-get source smbldap-tools').
	</para>

	<para>
	To manually configure the package, you need to create and edit the files <filename>/etc/smbldap-tools/smbldap.conf</filename> and
	<filename>/etc/smbldap-tools/smbldap_bind.conf</filename>.
	</para>

	<para>
	The <application>smbldap-populate</application> script will then add the LDAP objects required for Samba. It is a good idea to first
	make a backup of your DIT using <application>slapcat</application>:
	</para>

<screen>
<command>sudo slapcat -l backup.ldif</command>
</screen>
          
	<para>
	Once you have a backup proceed to populate your directory:
	</para>

<screen>
<command>sudo smbldap-populate</command>
</screen>

	<para>
	You can create a LDIF file containing the new Samba objects by executing <command>sudo smbldap-populate -e samba.ldif</command>.
	This allows you to look over the changes making sure everything is correct. If it is, rerun the script without the '-e'
	switch. Alternatively, you can take the LDIF file and import its data per usual.
	</para>

	<para>
	Your LDAP directory now has the necessary information to authenticate Samba users.
	</para>

    </sect3>

  </sect2>

  <sect2 id="samba-ldap-samba-configuration">
  <title>Samba Configuration</title>

	<para>
	There are multiple ways to configure Samba. For details on some common configurations see <xref linkend="samba"/>.      
	To configure Samba to use LDAP, edit its configuration file <filename>/etc/samba/smb.conf</filename> commenting out
	the default <emphasis>passdb backend</emphasis> parameter and adding some ldap-related ones:
	</para>

<programlisting>
#   passdb backend = tdbsam

# LDAP Settings
   passdb backend = ldapsam:ldap://hostname
   ldap suffix = dc=example,dc=com
   ldap user suffix = ou=People
   ldap group suffix = ou=Groups
   ldap machine suffix = ou=Computers
   ldap idmap suffix = ou=Idmap
   ldap admin dn = cn=admin,dc=example,dc=com
   ldap ssl = start tls
   ldap passwd sync = yes
...
   add machine script = sudo /usr/sbin/smbldap-useradd -t 0 -w "%u"
</programlisting>

	<para>
	Change the values to match your environment.
	</para>

	<para>
	Restart <application>samba</application> to enable the new settings:
	</para>

<screen>
<command>sudo restart smbd</command>
<command>sudo restart nmbd</command>
</screen>

	<para>
	Now inform Samba about the rootDN user's password (the one set during the installation of the slapd package):
	</para>

<screen>
<command>sudo smbpasswd -w password</command>
</screen>

	<para>
	If you have existing LDAP users that you want to include in your new LDAP-backed Samba they will, of course, also need to be given
	some of the extra attributes. The <application>smbpasswd</application> utility can do this as well (your host will need to be
	able to see (enumerate) those users via NSS; install and configure either <application>libnss-ldapd</application> or
	<application>libnss-ldap</application>):
	</para>

<screen>
<command>sudo smbpasswd -a username</command>
</screen>

	<para>
	You will prompted to enter a password. It will be considered as the new password for that user. Making it the same as before is reasonable.
	</para>

	<para>
	To manage user, group, and machine accounts use the utilities provided by the <application>smbldap-tools</application> package.
	Here are some examples:
	</para> 

	<itemizedlist>

		<listitem>
		<para>
		To add a new user:
		</para>

<screen>
<command>sudo smbldap-useradd -a -P username</command>
</screen>

		<para>
		The <emphasis>-a</emphasis> option adds the Samba attributes, and the <emphasis>-P</emphasis> option calls the 
		<application>smbldap-passwd</application> utility after the user is created allowing you to enter a password for the user.
		</para>
		</listitem>

		<listitem>
		<para>
		To remove a user:
		</para>

<screen>
<command>sudo smbldap-userdel username</command>
</screen>

		<para>
		In the above command, use the <emphasis>-r</emphasis> option to remove the user's home directory.
		</para>
		</listitem>

		<listitem>
		<para>
		To add a group:
		</para>

<screen>
<command>sudo smbldap-groupadd -a groupname</command>
</screen>

		<para>
		As for <application>smbldap-useradd</application>, the <emphasis>-a</emphasis> adds the Samba attributes.
		</para>
		</listitem>

		<listitem>
		<para>
		To make an existing user a member of a group:
		</para>

<screen>
<command>sudo smbldap-groupmod -m username groupname</command>
</screen>

		<para>
		The <emphasis>-m</emphasis> option can add more than one user at a time by listing them in comma-separated format.
		</para>
		</listitem>

		<listitem>
		<para>
		To remove a user from a group:
		</para>

<screen>
<command>sudo smbldap-groupmod -x username groupname</command>
</screen>

		</listitem>

		<listitem>
		<para>
		To add a Samba machine account:
		</para>

<screen>
<command>sudo smbldap-useradd -t 0 -w username</command>
</screen>

		<para>
		Replace <emphasis>username</emphasis> with the name of the workstation.  The <emphasis>-t 0</emphasis> option creates the machine account
		without a delay, while the <emphasis>-w</emphasis> option specifies the user as a machine account.  Also, note the 
		<emphasis>add machine script</emphasis> parameter in <filename>/etc/samba/smb.conf</filename> was changed to use <application>smbldap-useradd</application>.
		</para>
		</listitem>

	</itemizedlist>

	<para>
	There are utilities in the <application>smbldap-tools</application> package that were not covered here. Here is a complete list:
	</para>

<programlisting>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-groupadd.8.html">smbldap-groupadd</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-groupdel.8.html">smbldap-groupdel</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-groupmod.8.html">smbldap-groupmod</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-groupshow.8.html">smbldap-groupshow</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-passwd.8.html">smbldap-passwd</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-populate.8.html">smbldap-populate</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-useradd.8.html">smbldap-useradd</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-userdel.8.html">smbldap-userdel</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-userinfo.8.html">smbldap-userinfo</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-userlist.8.html">smbldap-userlist</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-usermod.8.html">smbldap-usermod</ulink>
<ulink url="http://manpages.ubuntu.com/manpages/en/man8/smbldap-usershow.8.html">smbldap-usershow</ulink>
</programlisting>

  </sect2>

  <sect2 id="samba-ldap-resources" status="review">
  <title>Resources</title>

	<itemizedlist>

		<listitem>
		<para>
		For more information on installing and configuring Samba see <xref linkend="samba"/> of this Ubuntu Server Guide.
		</para>
		</listitem>

		<listitem>
		<para>
		There are multiple places where LDAP and Samba is documented in the upstream
		<ulink url="http://samba.org/samba/docs/man/Samba-HOWTO-Collection/">Samba HOWTO Collection</ulink>.
		</para>
		</listitem>

		<listitem>
		<para>
		Regarding the above, see specifically the <ulink url="http://samba.org/samba/docs/man/Samba-HOWTO-Collection/passdb.html">passdb section</ulink>.
		</para>
		</listitem>

		<listitem>
		<para>
		Although dated (2007), the <ulink url="http://download.gna.org/smbldap-tools/docs/samba-ldap-howto/">Linux Samba-OpenLDAP HOWTO</ulink> contains valuable notes.
		</para>
		</listitem>

		<listitem>
		<para>
		The main page of the <ulink url="https://help.ubuntu.com/community/Samba#samba-ldap">Samba Ubuntu community documentation</ulink> has a plethora of links to
		articles that may prove useful.
		</para>
		</listitem>

	</itemizedlist>

  </sect2>

</sect1>

  <sect1 id="kerberos" status="review">
    <title>Kerberos</title>
    
    <para>
    <application>Kerberos</application> is a network authentication system based on the principal of a trusted third party.
    The other two parties being the user and the service the user wishes to authenticate to.  Not all services and applications
    can use Kerberos, but for those that can, it brings the network environment one step closer to being Single Sign On (SSO).
    </para>

    <para>
    This section covers installation and configuration of a Kerberos server, and some example client configurations.
    </para>
    
    <sect2 id="kerberos-overview" status="review">
      <title>Overview</title>

      <para>
      If you are new to Kerberos there are a few terms that are good to understand before setting up a Kerberos server.  Most of the terms
      will relate to things you may be familiar with in other environments:
      </para>

      <itemizedlist>
        <listitem>
          <para>
          <emphasis>Principal:</emphasis> any users, computers, and services provided by servers need to be defined as Kerberos Principals.
          </para>
        </listitem>
        <listitem>
          <para>
          <emphasis>Instances:</emphasis> are used for service principals and special administrative principals.
          </para>
        </listitem>
        <listitem>
          <para>
          <emphasis>Realms:</emphasis> the unique realm of control provided by the Kerberos installation.  
	  Think of it as the domain or group your hosts and users belong to.
	  Convention dictates the realm should be in uppercase.
	  By default, ubuntu will use the DNS domain converted to 
          uppercase (EXAMPLE.COM) as the realm.
          </para>
        </listitem>
        <listitem>
          <para>
          <emphasis>Key Distribution Center:</emphasis> (KDC) consist of three parts, a database of all principals, the authentication server,
          and the ticket granting server.  For each realm there must be at least one KDC.
          </para>
        </listitem>
        <listitem>
          <para>
          <emphasis>Ticket Granting Ticket:</emphasis> issued by the Authentication Server (AS), the Ticket Granting Ticket (TGT) is encrypted in 
          the user's password which is known only to the user and the KDC.
          </para>
        </listitem>
        <listitem>
          <para>
          <emphasis>Ticket Granting Server:</emphasis> (TGS) issues service tickets to clients upon request.
          </para>
        </listitem>
        <listitem>
          <para>
          <emphasis>Tickets:</emphasis> confirm the identity of the two principals.  One principal being a user and the other a service requested by 
          the user.  Tickets establish an encryption key used for secure communication during the authenticated session.
          </para>
        </listitem>
        <listitem>
          <para>
          <emphasis>Keytab Files:</emphasis> are files extracted from the KDC principal database and contain the encryption key for a service or
          host.
          </para>
        </listitem>
      </itemizedlist>

      <para>
      To put the pieces together, a Realm has at least one KDC, preferably more for redundancy, which contains a database of Principals.  When a 
      user principal logs into a workstation that is configured for Kerberos authentication, the KDC issues a Ticket Granting Ticket (TGT).  If the user
      supplied credentials match, the user is authenticated and can then request tickets for Kerberized services from the Ticket Granting Server
      (TGS).  The service tickets allow the user to authenticate to the service without entering another username and password.
      </para>
   
    </sect2>
    <sect2 id="kerberos-server" status="review">
      <title>Kerberos Server</title>    
      <sect3 id="kerberos-server-installation" status="review">
        <title>Installation</title>

        <para>
	For this discussion, we will create a MIT Kerberos domain with the 
	following features (edit them to fit your needs):
        </para>

        <itemizedlist>
          <listitem>
            <para>
            <emphasis>Realm:</emphasis> EXAMPLE.COM 
            </para>
          </listitem>
          <listitem>
            <para>
            <emphasis>Primary KDC:</emphasis> kdc01.example.com (192.168.0.1)
            </para>
          </listitem>
          <listitem>
            <para>
            <emphasis>Secondary KDC:</emphasis> kdc02.example.com (192.168.0.2)
            </para>
          </listitem>
          <listitem>
            <para>
            <emphasis>User principal:</emphasis> steve 
            </para>
          </listitem>
          <listitem>
            <para>
            <emphasis>Admin principal:</emphasis> steve/admin 
            </para>
          </listitem>
        </itemizedlist>

        <note> 
          <para>
          It is <emphasis>strongly</emphasis> recommended that your
	  network-authenticated users have their uid in a different range 
	  (say, starting at 5000) than that of your local users. 
          </para>
        </note> 
        <para> 
        Before installing the Kerberos server a properly configured DNS server is needed for your domain.  Since the Kerberos Realm by 
        convention matches the domain name, this section uses the <emphasis>EXAMPLE.COM</emphasis> domain configured in 
        <xref linkend="dns-primarymaster-configuration"/> of the DNS documentation.  
        </para>

        <para>
        Also, Kerberos is a time sensitive protocol.  So if the local system time between a client machine and the server differs by
        more than five minutes (by default), the workstation will not be able to authenticate.  To correct the problem all hosts 
        should have their time synchronized using the same
	<emphasis>Network Time Protocol (NTP)</emphasis> server.  For details
        on setting up NTP see <xref linkend="NTP"/>.
        </para>

        <para>
        The first step in creating a Kerberos Realm is to install the <application>krb5-kdc</application>  and 
        <application>krb5-admin-server</application> packages.  From a terminal enter:
        </para>

<screen>
<command>sudo apt-get install krb5-kdc krb5-admin-server</command>
</screen>

        <para>
        You will be asked at the end of the install to supply the hostname 
	for the Kerberos and Admin servers, which may or may not be the 
        same server, for the realm.
        </para>

        <note>
          <para>
          By default the realm is created from the KDC's domain name.
          </para>
        </note>

        <para>
        Next, create the new realm with the <application>kdb5_newrealm</application> utility:
        </para>

<screen>
<command>sudo krb5_newrealm</command>
</screen>

      </sect3>
      <sect3 id="kerberos-server-configuration" status="review">
        <title>Configuration</title>
      
        <para>
        The questions asked during installation are used to configure the <filename>/etc/krb5.conf</filename> file.  If you need to adjust 
        the Key Distribution Center (KDC) settings simply edit the file and restart the <application>krb5-kdc</application> daemon.
	If you need to reconfigure Kerberos from scratch, perhaps to change the realm name, you can do so by typing
        </para>

<screen>
<command>sudo dpkg-reconfigure krb5-kdc</command>
</screen>

        <procedure>
          <step>

            <para>
            Once the KDC is properly running, an admin user -- the
	    <emphasis>admin principal</emphasis> -- is needed.  
	    It is recommended to use a different username from your everyday username.  
            Using the <application>kadmin.local</application> utility in a terminal prompt enter:
            </para>

<screen>
<command>sudo kadmin.local</command>
<computeroutput>Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local:</computeroutput><userinput> addprinc steve/admin</userinput>
<computeroutput>WARNING: no policy specified for steve/admin@EXAMPLE.COM; defaulting to no policy
Enter password for principal "steve/admin@EXAMPLE.COM": 
Re-enter password for principal "steve/admin@EXAMPLE.COM": 
Principal "steve/admin@EXAMPLE.COM" created.
kadmin.local:</computeroutput><userinput> quit</userinput>
</screen>

            <para>
            In the above example <emphasis role="italic">steve</emphasis> is the <emphasis>Principal</emphasis>, 
            <emphasis role="italic">/admin</emphasis> is an <emphasis>Instance</emphasis>, and 
            <emphasis role="italic">@EXAMPLE.COM</emphasis> signifies the realm.  The <emphasis role="italic">"every day"</emphasis>
            Principal, 
	    a.k.a. the <emphasis role="italic">user principal</emphasis>,
	    would be <emphasis>steve@EXAMPLE.COM</emphasis>, and should have only normal user rights.            
            </para>

            <note>
              <para>
              Replace <emphasis>EXAMPLE.COM</emphasis> and <emphasis>steve</emphasis> with your Realm and admin username.
              </para>
            </note>

          </step>
          <step>
 
            <para>
            Next, the new admin user needs to have the appropriate Access Control List (ACL) permissions.
            The permissions are configured in the <filename>/etc/krb5kdc/kadm5.acl</filename> file:
            </para>

<programlisting>
steve/admin@EXAMPLE.COM        *
</programlisting>

            <para>
            This entry grants <emphasis>steve/admin</emphasis> the ability to perform any operation on all principals in the realm.
	    You can configure principals with more restrictive privileges,
	    which is convenient if you need an admin principal that junior 
	    staff can use
	    in Kerberos clients. Please see the 
	    <emphasis>kadm5.acl</emphasis> man page for details.
            </para>

          </step>
          <step>

            <para>
            Now restart the <application>krb5-admin-server</application> for the new ACL to take affect:
            </para>

<screen>
<command>sudo service krb5-admin-server restart</command>
</screen>

          </step>
          <step>

            <para>
            The new user principal can be tested using the <application>kinit utility</application>:
            </para>

<screen>
<command>kinit steve/admin</command>
<computeroutput>steve/admin@EXAMPLE.COM's Password:</computeroutput>
</screen>          

            <para>
            After entering the password, use the <application>klist</application> utility to view information about the 
            Ticket Granting Ticket (TGT):
            </para>

<screen>
<command>klist</command>
<computeroutput>Credentials cache: FILE:/tmp/krb5cc_1000
        Principal: steve/admin@EXAMPLE.COM

  Issued           Expires          Principal
Jul 13 17:53:34  Jul 14 03:53:34  krbtgt/EXAMPLE.COM@EXAMPLE.COM</computeroutput>
</screen>

            <para>
	    Where the cache filename <filename>krb5cc_1000</filename> is 
	    composed of the prefix <filename>krb5cc_</filename> and the user
	    id (uid), which in this case is <filename>1000</filename>.
            You may need to add an entry into the 
	    <filename>/etc/hosts</filename> for the KDC so the client can
	    find the KDC.  For example:
            </para>
            
<programlisting>
192.168.0.1   kdc01.example.com       kdc01
</programlisting>

            <para>
            Replacing <emphasis>192.168.0.1</emphasis> with the IP address of your KDC.  
	    This usually happens when you have a Kerberos realm encompassing 
	    different networks separated by routers.
            </para>

          </step>
          <step>
          
            <para>
	    The best way to allow clients to automatically
            determine the KDC for the Realm is using DNS SRV records.  Add the following to 
            <filename>/etc/named/db.example.com</filename>:
            </para>

<programlisting>
_kerberos._udp.EXAMPLE.COM.     IN SRV 1  0 88  kdc01.example.com.
_kerberos._tcp.EXAMPLE.COM.     IN SRV 1  0 88  kdc01.example.com.
_kerberos._udp.EXAMPLE.COM.     IN SRV 10 0 88  kdc02.example.com. 
_kerberos._tcp.EXAMPLE.COM.     IN SRV 10 0 88  kdc02.example.com. 
_kerberos-adm._tcp.EXAMPLE.COM. IN SRV 1  0 749 kdc01.example.com.
_kpasswd._udp.EXAMPLE.COM.      IN SRV 1  0 464 kdc01.example.com.
</programlisting>

            <note>
              <para>
              Replace <emphasis>EXAMPLE.COM</emphasis>, <emphasis>kdc01</emphasis>, and <emphasis>kdc02</emphasis> with your 
              domain name, primary KDC, and secondary KDC.
              </para>
            </note>

            <para>
            See <xref linkend="dns"/> for detailed instructions on setting up DNS.
            </para>

          </step>
        </procedure>
       
        <para>
        Your new Kerberos Realm is now ready to authenticate clients.
        </para>

      </sect3>
    </sect2>
    <sect2 id="kerberos-secondary-kdc" status="review">
      <title>Secondary KDC</title>

      <para>
      Once you have one Key Distribution Center (KDC) on your network, it is good practice to have a Secondary KDC in case the
      primary becomes unavailable. 
      Also, if you have Kerberos clients that are in different networks 
      (possibly separated by routers using NAT), it is wise to place a 
      secondary KDC in each of those networks.
      </para> 
      
      <procedure>
        <step>
        
        <para>
        First, install the packages, and when asked for the Kerberos and Admin server names enter the name of the Primary KDC:        
        </para>

<screen>
<command>sudo apt-get install krb5-kdc krb5-admin-server</command>
</screen>

        </step>
        <step>

        <para>
        Once you have the packages installed, create the Secondary KDC's host principal.  From a terminal prompt, enter:
        </para>

<screen>
<command>kadmin -q "addprinc -randkey host/kdc02.example.com"</command>
</screen>
    
        <note>
          <para>
          After, issuing any <application>kadmin</application> commands you will be prompted for your 
          <emphasis>username/admin@EXAMPLE.COM</emphasis> principal password.
          </para>
        </note>
      
        </step>
        <step>

          <para>
          Extract the <emphasis>keytab</emphasis> file:
          </para>

<screen>
<command>kadmin -q "ktadd -norandkey -k keytab.kdc02 host/kdc02.example.com"</command>
</screen>

        </step>
        <step>

          <para>
          There should now be a <filename>keytab.kdc02</filename> in the current directory, move the file to 
          <filename>/etc/krb5.keytab</filename>:
          </para>

<screen>
<command>sudo mv keytab.kdc02 /etc/krb5.keytab</command>
</screen>

          <note>
            <para>
            If the path to the <filename>keytab.kdc02</filename> file is different adjust accordingly. 
            </para>
          </note>

          <para>
          Also, you can list the principals in a Keytab file, which can be useful when troubleshooting, using the 
          <application>klist</application> utility:
          </para>

<screen>
<command>sudo klist -k /etc/krb5.keytab</command>
</screen>

            <para>
            The <application>-k</application> option indicates the file is a keytab file.
            </para>

        </step>
        <step>

          <para>
          Next, there needs to be a <filename>kpropd.acl</filename> file on each KDC that lists all KDCs for the Realm.  For example, 
          on both primary and secondary KDC, create <filename>/etc/krb5kdc/kpropd.acl</filename>:
          </para>

<programlisting>
host/kdc01.example.com@EXAMPLE.COM
host/kdc02.example.com@EXAMPLE.COM
</programlisting>

        </step>
        <step>

          <para>
          Create an empty database on the <emphasis>Secondary KDC</emphasis>:
          </para>

<screen>
<command>sudo kdb5_util -s create</command>
</screen>

        </step>
        <step>

          <para>
          Now start the <application>kpropd</application> daemon, which listens for connections from the 
          <application>kprop</application> utility.  <application>kprop</application> is used to transfer 
          dump files:
          </para>

<screen>
<command>sudo kpropd -S</command>
</screen>
      
        </step>
        <step>

          <para>
          From a terminal on the <emphasis>Primary KDC</emphasis>, create a dump file of the principal database:
          </para>

<screen>
<command>sudo kdb5_util dump /var/lib/krb5kdc/dump</command>
</screen>

        </step>
        <step>

          <para>
          Extract the Primary KDC's <emphasis>keytab</emphasis> file and copy it to <filename>/etc/krb5.keytab</filename>:
          </para>

<screen>
<command>kadmin -q "ktadd -k keytab.kdc01 host/kdc01.example.com"</command>
<command>sudo mv keytab.kdc01 /etc/krb5.keytab</command>
</screen>

          <note>
            <para>
            Make sure there is a <emphasis>host</emphasis> for <emphasis>kdc01.example.com</emphasis> before extracting the Keytab.
            </para>
          </note>

        </step>
        <step>

          <para>
          Using the <application>kprop</application> utility push the database to the Secondary KDC:
          </para>

<screen>
<command>sudo kprop -r EXAMPLE.COM -f /var/lib/krb5kdc/dump kdc02.example.com</command>
</screen>

          <note>
            <para>
            There should be a <emphasis>SUCCEEDED</emphasis> message if the propagation worked.  If there is an error 
            message check <filename>/var/log/syslog</filename> on the secondary KDC for more information.
            </para>
          </note>
      
          <para>
          You may also want to create a <application>cron</application> job to periodically update the database on the Secondary KDC.  For 
          example, the following will push the database every hour (note the long line has been split to fit the format of this document):
          </para>

<programlisting>
# m h  dom mon dow   command
0 * * * * /usr/sbin/kdb5_util dump /var/lib/krb5kdc/dump &amp;&amp; 
/usr/sbin/kprop -r EXAMPLE.COM -f /var/lib/krb5kdc/dump kdc02.example.com
</programlisting>
  
        </step>
        <step>

          <para>
          Back on the <emphasis>Secondary KDC</emphasis>, create a <emphasis>stash</emphasis> file to hold the Kerberos 
          master key:
          </para>

<screen>
<command>sudo kdb5_util stash</command>
</screen>

        </step>
        <step>

          <para>
          Finally, start the <application>krb5-kdc</application> daemon on the Secondary KDC:
          </para>

<screen>
<command>sudo service krb5-kdc start</command>
</screen>

        </step>
      </procedure>

      <para>
      The <emphasis>Secondary KDC</emphasis> should now be able to issue tickets for the Realm.  You can test this by stopping 
      the <application>krb5-kdc</application> daemon on the Primary KDC, then 
      by using <application>kinit</application> to request a ticket.
      If all goes well you should receive a ticket from the Secondary KDC.
      Otherwise, check <filename>/var/log/syslog</filename> and
      <filename>/var/log/auth.log</filename> in the Secondary KDC.
      </para>

    </sect2>
    <sect2 id="kerberos-linux-client" status="review">
      <title>Kerberos Linux Client</title>    

      <para>
      This section covers configuring a Linux system as a <application>Kerberos</application> client.  This will allow access
      to any kerberized services once a user has successfully logged into the system.
      </para>

      <sect3 id="kerberos-client-installation" status="review">
        <title>Installation</title>

        <para>
        In order to authenticate to a Kerberos Realm, the <application>krb5-user</application> and <application>libpam-krb5</application>
        packages are needed, along with a few others that are not strictly necessary but make life easier.  To install the packages 
        enter the following in a terminal prompt:
        </para>

<screen>
<command>sudo apt-get install krb5-user libpam-krb5 libpam-ccreds auth-client-config</command>
</screen>

        <para>
        The <application>auth-client-config</application> package allows simple configuration of PAM for authentication from multiple 
        sources, and the <application>libpam-ccreds</application> will cache authentication credentials allowing you to login in case the 
        Key Distribution Center (KDC) is unavailable.  This package is also useful for laptops that may authenticate using Kerberos while 
        on the corporate network, but will need to be accessed off the network as well.
        </para>

      </sect3>
      <sect3 id="kerberos-client-configuration" status="review">
        <title>Configuration</title>

        <para>
        To configure the client in a terminal enter:
        </para>

<screen>
<command>sudo dpkg-reconfigure krb5-config</command>
</screen>

        <para>
        You will then be prompted to enter the name of the Kerberos Realm.  Also, if you don't have DNS configured with Kerberos 
        <emphasis>SRV</emphasis> records, the menu will prompt you for the hostname of the Key Distribution Center (KDC) and 
        Realm Administration server.
        </para>

        <para>
        The <application>dpkg-reconfigure</application> adds entries to the <filename>/etc/krb5.conf</filename> file for your Realm.
        You should have entries similar to the following:
        </para>

<programlisting>
[libdefaults]
        default_realm = EXAMPLE.COM
...
[realms]
        EXAMPLE.COM = {
                kdc = 192.168.0.1
                admin_server = 192.168.0.1
        }
</programlisting>

	<note>
	  <para>
	  If you set the uid of each of your network-authenticated users to 
	  start at 5000, as suggested in 
	  <xref linkend="kerberos-server-installation"/>, you 
	  can then tell pam to only try to authenticate using Kerberos 
	  users with uid > 5000:
	  </para>
<screen>
<command># Kerberos should only be applied to ldap/kerberos users, not local ones.
for i in common-auth common-session common-account common-password; do
 sudo sed -i -r \ 
 -e 's/pam_krb5.so minimum_uid=1000/pam_krb5.so minimum_uid=5000/' \ 
 /etc/pam.d/$i 
done </command>
</screen>
	  <para>
	  This will avoid being asked for the (non-existent) Kerberos 
	  password of a locally authenticated user when changing its 
	  password using <command>passwd</command>.
	  </para>
	</note>

        <para>
        You can test the configuration by requesting a ticket using the <application>kinit</application> utility.  For example:
        </para>

<screen>
<command>kinit steve@EXAMPLE.COM</command>
<computeroutput>Password for steve@EXAMPLE.COM:</computeroutput>
</screen>

        <para>
        When a ticket has been granted, the details can be viewed using <application>klist</application>:
        </para>

<screen>
<command>klist</command>
<computeroutput>Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: steve@EXAMPLE.COM

Valid starting     Expires            Service principal
07/24/08 05:18:56  07/24/08 15:18:56  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        renew until 07/25/08 05:18:57


Kerberos 4 ticket cache: /tmp/tkt1000
klist: You have no tickets cached</computeroutput>
</screen>

        <para>
        Next, use the <application>auth-client-config</application> to configure the <application>libpam-krb5</application> module
        to request a ticket during login:
        </para>

<screen>
<command>sudo auth-client-config -a -p kerberos_example</command>
</screen>

        <para>
        You will should now receive a ticket upon successful login authentication. 
        </para>

      </sect3>
    </sect2>
    <sect2 id="kerberos-resources" status="review">
      <title>Resources</title>

      <itemizedlist>
        <listitem>
          <para>
          For more information on MIT's version of Kerberos, see the <ulink url="http://web.mit.edu/Kerberos/">MIT Kerberos</ulink> site.
          </para>
        </listitem>
        <listitem>
          <para>
          The <ulink url="https://help.ubuntu.com/community/Kerberos">Ubuntu Wiki Kerberos</ulink> page has more details.
          </para>
        </listitem>
        <listitem>
          <para>
          O'Reilly's <ulink url="http://oreilly.com/catalog/9780596004033/">Kerberos: The Definitive Guide</ulink> is a great reference when
          setting up Kerberos.
          </para>
        </listitem>
        <listitem>
          <para>
          Also, feel free to stop by the <emphasis>#ubuntu-server</emphasis> 
	  and <emphasis>#kerberos</emphasis>
	  IRC channels on <ulink url="http://freenode.net/">Freenode</ulink>  
          if you have Kerberos questions.
          </para>
        </listitem>
      </itemizedlist>

    </sect2>
  </sect1>
  <sect1 id="kerberos-ldap" status="review">
    <title>Kerberos and LDAP</title>

    <para>
    Most people will not use Kerberos by itself; once an user is authenticated
    (Kerberos), we need to figure out what this user can do (authorization).
    And that would be the job of programs such as
    <application>LDAP</application>.
    </para>

    <para>
    Replicating a Kerberos principal database between two servers can be complicated, and adds an additional user
    database to your network.  Fortunately, MIT Kerberos can be configured to use an <application>LDAP</application>
    directory as a principal database.  This section covers configuring a primary and secondary kerberos server to use
    <application>OpenLDAP</application> for the principal database.
    </para>

    <note>
       <para>
       The examples presented here assume 
       <application>MIT Kerberos</application> and 
       <application>OpenLDAP</application>.
       </para>
    </note>

    <sect2 id="kerberos-ldap-openldap" status="review">
      <title>Configuring OpenLDAP</title>

      <para>
      First, the necessary <emphasis>schema</emphasis> needs to be loaded on an <application>OpenLDAP</application> server that has
      network connectivity to the Primary and Secondary KDCs.  The rest of this section assumes that you also have LDAP replication
      configured between at least two servers.  For information on setting up OpenLDAP see <xref linkend="openldap-server"/>.
      </para>

      <para>
      It is also required to configure OpenLDAP for TLS and SSL connections, so that traffic between the KDC and LDAP server is encrypted.
      See <xref linkend="openldap-tls"/> for details.
      </para>

      <note>
         <para>
         <filename>cn=admin,cn=config</filename> is a user we created with 
rights to edit the ldap database. Many times it is the RootDN. Change its 
value to reflect your setup.
         </para>
      </note>
      
      <itemizedlist>
        <listitem>
          <para>
          To load the schema into LDAP, on the LDAP server install the <application>krb5-kdc-ldap</application> package.
          From a terminal enter:
          </para>

<screen>
<command>sudo apt-get install krb5-kdc-ldap</command>
</screen>

        </listitem>
        <listitem>
          <para>
          Next, extract the <filename>kerberos.schema.gz</filename> file:
          </para>

<screen>
<command>sudo gzip -d /usr/share/doc/krb5-kdc-ldap/kerberos.schema.gz</command>
<command>sudo cp /usr/share/doc/krb5-kdc-ldap/kerberos.schema /etc/ldap/schema/</command>
</screen>

        </listitem>
        <listitem>

           <para>
           The <emphasis>kerberos</emphasis> schema needs to be added to the <emphasis>cn=config</emphasis> tree.
           The procedure to add a new schema to <application>slapd</application> is also detailed in 
           <xref linkend="openldap-configuration"/>.
           </para>

           <procedure>
              <step>
                <para>                  
                First, create a configuration file named <filename>schema_convert.conf</filename>, or a similar 
                descriptive name, 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/kerberos.schema
</programlisting>


                </step>
                <step>

                  <para>
                   Create a temporary directory to hold the LDIF files:
                  </para>
<screen>
<command>mkdir /tmp/ldif_output</command>
</screen>

                </step>
                <step>

                  <para>
                  Now use <application>slapcat</application> to convert the schema files: 
                  </para>

<screen>
<command>slapcat -f schema_convert.conf -F /tmp/ldif_output -n0 -s \
"cn={12}kerberos,cn=schema,cn=config" > /tmp/cn=kerberos.ldif</command>
</screen>

                  <para>
                  Change the above file and path names to match your own if they are different.
                  </para>
                
                </step>
                <step>

                  <para>
                  Edit the generated <filename>/tmp/cn\=kerberos.ldif</filename> file, changing the following attributes: 
                  </para>

<programlisting>
dn: cn=kerberos,cn=schema,cn=config
...
cn: kerberos
</programlisting>

                  <para>
                  And remove the following lines from the end of the file:
                  </para>

<programlisting>
structuralObjectClass: olcSchemaConfig
entryUUID: 18ccd010-746b-102d-9fbe-3760cca765dc
creatorsName: cn=config
createTimestamp: 20090111203515Z
entryCSN: 20090111203515.326445Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20090111203515Z
</programlisting>

                    <para>
                    The attribute values will vary, just be sure the attributes are removed. 
                    </para>

                </step>
                <step>

                  <para>
                  Load the new schema with <application>ldapadd</application>:
                  </para>

<screen>
<command>ldapadd -x -D cn=admin,cn=config -W -f /tmp/cn\=kerberos.ldif</command>
</screen>

                </step>
                <step>
        
                  <para>
                  Add an index for the <emphasis>krb5principalname</emphasis> attribute:
                  </para>

<screen>
<command>ldapmodify -x -D cn=admin,cn=config -W</command>
<computeroutput>Enter LDAP Password:
<userinput>dn: olcDatabase={1}hdb,cn=config
add: olcDbIndex
olcDbIndex: krbPrincipalName eq,pres,sub</userinput>

modifying entry "olcDatabase={1}hdb,cn=config"</computeroutput>
</screen>
      
                </step>
                <step>
        
                  <para>
                  Finally, update the Access Control Lists (ACL):
                  </para>

<screen>
<command>ldapmodify -x -D cn=admin,cn=config -W</command>
<computeroutput>Enter LDAP Password: 
<userinput>dn: olcDatabase={1}hdb,cn=config
replace: olcAccess
olcAccess: to attrs=userPassword,shadowLastChange,krbPrincipalKey by
 dn="cn=admin,dc=example,dc=com" write by anonymous auth by self write by * none
-
add: olcAccess
olcAccess: to dn.base="" by * read
-
add: olcAccess
olcAccess: to * by dn="cn=admin,dc=example,dc=com" write by * read</userinput>

modifying entry "olcDatabase={1}hdb,cn=config"
</computeroutput>
</screen>
      
                </step>
           </procedure>    
        </listitem>
      </itemizedlist>

      <para>
      That's it, your LDAP directory is now ready to serve as a Kerberos principal database.
      </para>

    </sect2>
    <sect2 id="kerberos-ldap-primary-kdc" status="review">
      <title>Primary KDC Configuration</title>

      <para>
      With <application>OpenLDAP</application> configured it is time to configure the KDC.
      </para>

      <itemizedlist>
        <listitem>
          <para>
          First, install the necessary packages, from a terminal enter:
          </para>

<screen>
<command>sudo apt-get install krb5-kdc krb5-admin-server krb5-kdc-ldap</command>
</screen>

        </listitem>
        <listitem>

          <para>
          Now edit <filename>/etc/krb5.conf</filename> adding the following options to under the appropriate sections:
          </para>

<programlisting>
[libdefaults]
        default_realm = EXAMPLE.COM

...

[realms]
        EXAMPLE.COM = {
                kdc = kdc01.example.com
                kdc = kdc02.example.com
                admin_server = kdc01.example.com
                admin_server = kdc02.example.com
                default_domain = example.com
                database_module = openldap_ldapconf
        }

...

[domain_realm]
        .example.com = EXAMPLE.COM


...

[dbdefaults]
        ldap_kerberos_container_dn = dc=example,dc=com

[dbmodules]
        openldap_ldapconf = {
                db_library = kldap
                ldap_kdc_dn = "cn=admin,dc=example,dc=com"

                # this object needs to have read rights on
                # the realm container, principal container and realm sub-trees
                ldap_kadmind_dn = "cn=admin,dc=example,dc=com"

                # this object needs to have read and write rights on
                # the realm container, principal container and realm sub-trees
                ldap_service_password_file = /etc/krb5kdc/service.keyfile
                ldap_servers = ldaps://ldap01.example.com ldaps://ldap02.example.com
                ldap_conns_per_server = 5
        }
</programlisting>

          <note>
            <para>
            Change <emphasis>example.com</emphasis>, <emphasis>dc=example,dc=com</emphasis>, <emphasis>cn=admin,dc=example,dc=com</emphasis>,
            and <emphasis>ldap01.example.com</emphasis> to the appropriate domain, LDAP object, and LDAP server for your network.
            </para>
          </note>

        </listitem>
        <listitem>
        
          <para>
          Next, use the <application>kdb5_ldap_util</application> utility to create the realm:
          </para>

<screen>
<command>sudo kdb5_ldap_util -D  cn=admin,dc=example,dc=com create -subtrees \
dc=example,dc=com -r EXAMPLE.COM -s -H ldap://ldap01.example.com</command>
</screen>
      
        </listitem>
        <listitem>
        
          <para>
          Create a stash of the password used to bind to the LDAP server.  This password is used by the <emphasis>ldap_kdc_dn</emphasis> and        
          <emphasis>ldap_kadmin_dn</emphasis> options in <filename>/etc/krb5.conf</filename>:
          </para>

<screen>
<command>sudo kdb5_ldap_util -D  cn=admin,dc=example,dc=com stashsrvpw -f \
/etc/krb5kdc/service.keyfile cn=admin,dc=example,dc=com</command>
</screen>
      
        </listitem>
        <listitem>
        
          <para>
          Copy the CA certificate from the LDAP server:
          </para>

<screen>
<command>scp ldap01:/etc/ssl/certs/cacert.pem .</command>
<command>sudo cp cacert.pem /etc/ssl/certs</command>
</screen>

          <para> 
          And edit <filename>/etc/ldap/ldap.conf</filename> to use the certificate:
          </para>

<programlisting>
TLS_CACERT /etc/ssl/certs/cacert.pem
</programlisting>

          <note>
            <para>
            The certificate will also need to be copied to the Secondary KDC, to allow the connection to the LDAP servers using
            LDAPS.
            </para>
          </note>
      
        </listitem>
      </itemizedlist>

      <para>
      You can now add Kerberos principals to the LDAP database, and they will be copied to any other LDAP servers configured for replication.
      To add a principal using the <application>kadmin.local</application> utility enter:
      </para>

<screen>
<command>sudo kadmin.local</command>
<computeroutput>Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local:  <userinput>addprinc -x dn="uid=steve,ou=people,dc=example,dc=com" steve</userinput>
WARNING: no policy specified for steve@EXAMPLE.COM; defaulting to no policy
Enter password for principal "steve@EXAMPLE.COM": 
Re-enter password for principal "steve@EXAMPLE.COM": 
Principal "steve@EXAMPLE.COM" created.</computeroutput>
</screen>

      <para>
      There should now be krbPrincipalName, krbPrincipalKey, krbLastPwdChange, and krbExtraData attributes added to the 
      <emphasis>uid=steve,ou=people,dc=example,dc=com</emphasis> user object.  Use the <application>kinit</application> and 
      <application>klist</application> utilities to test that the user is indeed issued a ticket.
      </para>

      <note>
        <para>
        If the user object is already created the <emphasis>-x dn="..."</emphasis> option is needed to add the Kerberos attributes.
        Otherwise a new <emphasis>principal</emphasis> object will be created in the realm subtree.
        </para>
      </note>

    </sect2>
    <sect2 id="kerberos-ldap-secondary-kdc" status="review">
      <title>Secondary KDC Configuration</title>

      <para>
      Configuring a Secondary KDC using the LDAP backend is similar to configuring one using the normal Kerberos database.
      </para>

      <procedure>
        <step>
          <para>
          First, install the necessary packages.  In a terminal enter:
          </para>

<screen>
<command>sudo apt-get install krb5-kdc krb5-admin-server krb5-kdc-ldap</command>
</screen>

        </step>
        <step>

          <para>
          Next, edit <filename>/etc/krb5.conf</filename> to use the LDAP backend:
          </para>

<programlisting>
[libdefaults]
        default_realm = EXAMPLE.COM

...

[realms]
        EXAMPLE.COM = {
                kdc = kdc01.example.com
                kdc = kdc02.example.com
                admin_server = kdc01.example.com
                admin_server = kdc02.example.com
                default_domain = example.com
                database_module = openldap_ldapconf
        }

...

[domain_realm]
        .example.com = EXAMPLE.COM

...

[dbdefaults]
        ldap_kerberos_container_dn = dc=example,dc=com

[dbmodules]
        openldap_ldapconf = {
                db_library = kldap
                ldap_kdc_dn = "cn=admin,dc=example,dc=com"

                # this object needs to have read rights on
                # the realm container, principal container and realm sub-trees
                ldap_kadmind_dn = "cn=admin,dc=example,dc=com"

                # this object needs to have read and write rights on
                # the realm container, principal container and realm sub-trees
                ldap_service_password_file = /etc/krb5kdc/service.keyfile
                ldap_servers = ldaps://ldap01.example.com ldaps://ldap02.example.com
                ldap_conns_per_server = 5
        }
</programlisting>


        </step>
        <step>
        
      <para>
      Create the stash for the LDAP bind password:
      </para>

<screen>
<command>sudo kdb5_ldap_util -D  cn=admin,dc=example,dc=com stashsrvpw -f \
/etc/krb5kdc/service.keyfile cn=admin,dc=example,dc=com</command>
</screen>
      
        </step>
        <step>

          <para>
          Now, on the <emphasis>Primary KDC</emphasis> copy the <filename>/etc/krb5kdc/.k5.EXAMPLE.COM</filename> 
          <emphasis>Master Key</emphasis> stash to the Secondary KDC.  Be sure to copy the file over an encrypted 
          connection such as <application>scp</application>, or on physical media.
          </para>

<screen>
<command>sudo scp /etc/krb5kdc/.k5.EXAMPLE.COM steve@kdc02.example.com:~</command>
<command>sudo mv .k5.EXAMPLE.COM /etc/krb5kdc/</command>
</screen>

        <note>
          <para>
          Again, replace <emphasis>EXAMPLE.COM</emphasis> with your actual realm.
          </para>
        </note>

        </step>
        <step>

          <para>
          Back on the <emphasis>Secondary KDC</emphasis>, (re)start the ldap
	  server only,
          </para>

<screen>
<command>sudo service slapd restart</command>
</screen>

        </step>
        <step>

          <para>
          Finally, start the <application>krb5-kdc</application> daemon:
          </para>

<screen>
<command>sudo service krb5-kdc start</command>
</screen>

        </step>
        <step>

          <para>
          Verify the two ldap servers (and kerberos by extension) are in sync.
          </para>

        </step>
      </procedure>

      <para>
      You now have redundant KDCs on your network, and with redundant LDAP servers you should be able to 
      continue to authenticate users if one LDAP server, one Kerberos server, or one LDAP and one Kerberos 
      server become unavailable. 
      </para>

    </sect2>
    <sect2 id="kerberos-ldap-resources" status="review">
      <title>Resources</title>

      <itemizedlist>
        <listitem>
          <para>
          The <ulink url="http://web.mit.edu/Kerberos/krb5-1.6/krb5-1.6.3/doc/krb5-admin.html#Configuring-Kerberos-with-OpenLDAP-back_002dend">
          Kerberos Admin Guide</ulink> has some additional details.
          </para>
        </listitem>
        <listitem>
          <para>
          For more information on <application>kdb5_ldap_util</application> see 
          <ulink url="http://web.mit.edu/Kerberos/krb5-1.6/krb5-1.6.3/doc/krb5-admin.html#Global-Operations-on-the-Kerberos-LDAP-Database">
          Section 5.6</ulink> and the 
          <ulink url="http://manpages.ubuntu.com/manpages/&distro-short-codename;/en/man8/kdb5_ldap_util.8.html">kdb5_ldap_util man page</ulink>.
          </para>
        </listitem>
        <listitem>
          <para>
          Another useful link is the <ulink url="http://manpages.ubuntu.com/manpages/&distro-short-codename;/en/man5/krb5.conf.5.html">krb5.conf man page</ulink>.
          </para>
        </listitem>
        <listitem>
          <para>
          Also, see the <ulink url="https://help.ubuntu.com/community/Kerberos#kerberos-ldap">Kerberos and LDAP</ulink> Ubuntu wiki page.
          </para>
        </listitem>
      </itemizedlist>

    </sect2>
  </sect1>
  <sect1 id="sssd-ad" status="review">
    <title>SSSD and Active Directory</title>
    <para>
    	This section describes the use of sssd to authenticate user logins against an Active Directory via using sssd's "ad" provider.  In previous versions of sssd, it was possible to authenticate using the "ldap" provider.  However, when authenticating against a Microsoft Windows AD Domain Controller, it was generally necessary to install the POSIX AD extensions on the Domain Controller.  The "ad" provider simplifies the configuration and requires no modifications to the AD structure.
    </para>
    <sect2 id="sssd-ad-requirements" status="review">
    	<title>Prerequisites, Assumptions, and Requirements</title>
      	<itemizedlist>
        	<listitem>
        		<para>This guide does not explain Active Directory, how it works, how to set one up, or how to maintain it.  It may not provide <quote>best practices</quote> for your environment.</para></listitem>
    		<listitem>
				<para>This guide assumes that a working Active Directory domain is already configured.</para></listitem>
    		<listitem>
				<para>The domain controller is acting as an authoritative DNS server for the domain.</para></listitem>
    		<listitem>
				<para>The domain controller is the primary DNS resolver as specified in  <filename>/etc/resolv.conf</filename>.</para>
			</listitem>
    		<listitem>
				<para>The appropriate <emphasis>_kerberos</emphasis>, <emphasis>_ldap</emphasis>, <emphasis>_kpasswd</emphasis>, etc. entries are configured in the DNS zone (see Resources section for external links).</para></listitem> 
    		<listitem>
				<para>System time is synchronized on the domain controller (necessary for Kerberos).</para></listitem>
    		<listitem>
				<para>The domain used in this example is <emphasis>myubuntu.example.com</emphasis> .</para></listitem>
		</itemizedlist>
	</sect2>
	<sect2 id="sssd-ad-installation" status="review">
		<title>Software Installation</title>
		<para>The following packages are needed: <emphasis>krb5-user</emphasis>, <emphasis>samba</emphasis>, <emphasis>sssd</emphasis>, and <emphasis>ntp</emphasis>.  Samba needs to be installed, even if the system is not exporting shares. The Kerberos realm and FQDN or IP of the domain controllers are needed for this step.</para>
		<para>Install these packages now.
		</para>
		<screen><command>sudo apt-get install krb5-user samba sssd ntp</command></screen>
		<para>See the next section for the answers to the questions asked by the <emphasis>krb5-user</emphasis> postinstall script.</para>
	</sect2>
	<sect2 id="sssd-ad-kerberos" status="review">
		<title>Kerberos Configuration</title>
		<para>The installation of <emphasis>krb5-user</emphasis> will prompt for the realm name (in ALL UPPERCASE), the kdc server (i.e. domain controller) and admin server (also the domain controller in this example.)  This will write the [realm] and [domain_realm] sections in <filename>/etc/krb5.conf</filename>.  These sections may not be necessary if domain autodiscovery is working.  If not, then both are needed.</para>
		<para>If the domain is <emphasis>myubuntu.example.com</emphasis>, enter the realm as <emphasis>MYUBUNTU.EXAMPLE.COM</emphasis>
		</para>

		<para>Optionally, edit <emphasis>/etc/krb5.conf</emphasis> with a few additional settings to specify Kerberos ticket lifetime (these values are safe to use as defaults):</para>
		<programlisting>
[libdefaults]

default_realm = MYUBUNTU.EXAMPLE.COM
ticket_lifetime = 24h #
renew_lifetime = 7d
		</programlisting>

		<para>If default_realm is not specified, it may be necessary to log in with <quote>username@domain</quote> instead of <quote>username</quote>.</para>

		<para>The system time on the Active Directory member needs to be consistent with that of the domain controller, or Kerberos authentication may fail.  Ideally, the domain controller server itself will provide the NTP service. Edit <filename>/etc/ntp.conf</filename>:</para>

<programlisting>
server dc.myubuntu.example.com
</programlisting>

	</sect2>
	<sect2 id="sssd-ad-samba" status="review">
	<title>Samba Configuration</title>
<para>Samba will be used to perform netbios/nmbd services related to Active Directory authentication, even if no file shares are exported.  Edit the file /etc/samba/smb.conf and add the following to the <emphasis>[global]</emphasis> section:</para>

<programlisting>
[global]

workgroup = MYUBUNTU
client signing = yes
client use spnego = yes
kerberos method = secrets and keytab
realm = MYUBUNTU.EXAMPLE.COM
security = ads
</programlisting>

<note><para>Some guides specify that "password server" should be specified and pointed to the domain controller.  This is only necessary if DNS is not properly set up to find the DC.  By default, Samba will display a warning if "password server" is specified with "security = ads".</para></note>

</sect2>

<sect2 id="sssd-ad-sssdconfig" status="review">
	<title>SSSD Configuration</title>

<para>There is no default/example config file for <filename>/etc/sssd/sssd.conf</filename> included in the sssd package.  It is necessary to create one.  This is a minimal working config file:</para>

<programlisting>
[sssd]
services = nss, pam
config_file_version = 2
domains = MYUBUNTU.EXAMPLE.COM

[domain/MYUBUNTU.EXAMPLE.COM]
id_provider = ad
access_provider = ad

# Use this if users are being logged in at /.
# This example specifies /home/DOMAIN-FQDN/user as $HOME.  Use with pam_mkhomedir.so
override_homedir = /home/%d/%u

# Uncomment if the client machine hostname doesn't match the computer object on the DC.
# ad_hostname = mymachine.myubuntu.example.com

# Uncomment if DNS SRV resolution is not working
# ad_server = dc.mydomain.example.com

# Uncomment if the AD domain is named differently than the Samba domain
# ad_domain = MYUBUNTU.EXAMPLE.COM

# Enumeration is discouraged for performance reasons.
# enumerate = true
</programlisting>

<para>After saving this file, set the ownership to root and the file permissions to 600:</para>
<screen><command>sudo chown root:root /etc/sssd/sssd.conf</command></screen>
<screen><command>sudo chmod 600 /etc/sssd/sssd.conf</command></screen>

<para>If the ownership or permissions are not correct, sssd will refuse to start.</para>
</sect2>

<sect2 id="sssd-ad-nsswitch" status="review">
	<title>Verify nsswitch.conf Configuration</title>
	<para>The post-install script for the sssd package makes some modifications to /etc/nsswitch.conf automatically.  It should look something like this:</para>

<programlisting>
passwd:         compat sss
group:          compat sss
...
netgroup:       nis sss
sudoers:        files sss
</programlisting>
</sect2>

<sect2 id="sssd-ad-hosts" status="review">
	<title>Modify /etc/hosts</title>
<para>Add an alias to the localhost entry in /etc/hosts specifying the FQDN.  For example:</para>
<programlisting>192.168.1.10 myserver myserver.myubuntu.example.com</programlisting>

<para>This is useful in conjunction with dynamic DNS updates.</para>
</sect2>

<sect2 id="sssd-ad-join" status="review">
	<title>Join the Active Directory</title>
<para>Now, restart ntp and samba and start sssd.</para>
<screen><command>sudo service ntp restart</command>
<command>sudo restart smbd</command> 
<command>sudo restart nmbd</command> 
<command>sudo start sssd</command></screen>

<para>Test the configuration by obtaining a Kerberos ticket:</para>

<screen><command>sudo kinit Administrator</command></screen>

<para>Verify the ticket with:</para>
<screen><command>sudo klist</command></screen>

<para>If there is a ticket with an expiration date listed, then it is time to join the domain:</para>

<screen><command>sudo net ads join -k</command></screen>

<para>A warning about "No DNS domain configured. Unable to perform DNS Update." probably means that there is no (correct) alias in <filename>/etc/hosts</filename>, and the system could not provide its own FQDN as part of the Active Directory update.  This is needed for dynamic DNS updates.  Verify the alias in <filename>/etc/hosts</filename> described in "Modify /etc/hosts" above.</para>

<para>(The message "NT_STATUS_UNSUCCESSFUL" indicates the domain join failed and something is incorrect.  Review the prior steps before proceeding).</para>

<para>Here are a couple of (optional) checks to verify that the domain join was successful. Note that if the domain was successfully joined but one or both of these steps fail, it may be necessary to wait 1-2 minutes and try again.  Some of the changes appear to be asynchronous.</para>

<para>Verification option #1:</para>
<para>Check the default Organizational Unit for computer accounts in the Active Directory to verify that the computer account was created.  (Organizational Units in Active Directory is a topic outside the scope of this guide).</para>

<para>Verification option #2</para>
<para>Execute this command for a specific AD user (e.g. administrator)</para>
<screen><command>getent passwd username</command></screen>

<note><para>If <emphasis>enumerate = true</emphasis> is set in <filename>sssd.conf</filename>, <emphasis>getent passwd</emphasis> with no username argument will list all domain users.  This may be useful for testing, but is slow and not recommended for production.</para></note>
</sect2>

<sect2 id="sssd-ad-test" status="review">
	<title>Test Authentication</title>
	<para>It should now be possible to authenticate using an Active Directory User's credentials:</para>

<screen><command>su - username</command></screen>

<para>If this works, then other login methods (getty, ssh) should also work.</para>

<para>If the computer account was created, indicating that the system was "joined" to the domain, but authentication is unsuccessful, it may be helpful to review <filename>/etc/pam.d</filename> and <filename>nssswitch.conf</filename> as well as the file changes described earlier in this guide.</para>
</sect2>

<sect2 id="sssd-ad-mkhomedir" status="review">
	<title>Home directories with pam_mkhomedir (optional)</title>
	<para>When logging in using an Active Directory user account, it is likely that user has no home directory.  This can be fixed with pam_mkdhomedir.so, which will create the user's home directory on login.  Edit <filename>/etc/pam.d/common-session</filename>, and add this line directly after <emphasis>session required pam_unix.so:</emphasis></para>
<programlisting>
session    required    pam_mkhomedir.so skel=/etc/skel/ umask=0022
</programlisting>

<note><para>This may also need <emphasis>override_homedir</emphasis> in <filename>sssd.conf</filename> to function correctly, so make sure that's set.</para></note>
</sect2>

<sect2 id="sssd-ad-desktop" status="review">
	<title>Desktop Ubuntu Authentication</title>
	<para>It is possible to also authenticate logins to Ubuntu Desktop using Active Directory accounts.  The AD accounts will not show up in the pick list with local users, so lightdm will need to be modified.  Edit the file <filename>/etc/lightdm/lightdm.conf.d/50-unity-greeter.conf</filename> and append the following two lines:</para>

<programlisting>
greeter-show-manual-login=true
greeter-hide-users=true
</programlisting>

<para>Reboot to restart lightdm.  It should now be possible to log in using a domain account using either <emphasis>username</emphasis> or <emphasis>username/username@domain</emphasis> format.</para>
</sect2>

<sect2 id="sssd-ad-resources" status="review">
	<title>Resources</title>
	     <itemizedlist>
        <listitem><para><ulink url="https://fedorahosted.org/sssd">SSSD Project</ulink></para></listitem>
<listitem><para><ulink url="http://www.ucs.cam.ac.uk/support/windows-support/winsuptech/activedir/dnsconfig">DNS Server Configuration guidelines</ulink></para></listitem>
<listitem><para><ulink url="https://technet.microsoft.com/en-us/library/cc759550%28v=ws.10%29.aspx">Active Directory DNS Zone Entries</ulink></para></listitem>
<listitem><para><ulink url="http://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html">Kerberos config options</ulink></para></listitem>
	     </itemizedlist>

</sect2>
</sect1>
</chapter>