OpenLDAP Directory Administration Replication, Referrals, Searching, and SASL Explained

Table of Contents ● More Than One Copy Is “a Good Thing” ● Distributing the Directory ● Advanced Searching Options ● Determining a Server's Capabilities ● Creating Custom Schema Files for slapd ● SASL and OpenLDAP

Table of Contents ● More Than One Copy Is “a Good Thing” ● Distributing the Directory ● Advanced Searching Options ● Determining a Server's Capabilities ● Creating Custom Schema Files for slapd ● SASL and OpenLDAP

More Than One Copy Is “a Good Thing” ● Directory replication hasn't been standardized yet: vendor-specific ● Cross-vendor replication ? Only using tricks like parsing a change log ● When should I install a replica for all or for part of my directory ? Symptons: – If one application makes heavy use of the directory and slows things down – If one Directory server does not have enough CPU power – Group of clients located behind a slow network link – IF the directory cannot be taken offline for backups – If the directory is a critical part of the services provided by your network ● Next question is “How ?”

More Than One Copy Is “a Good Thing” (cont.) ● OpenLDAP uses a secondary daemon, slurpd, to process a change log written by slapd ● slurpd forwards the changes to the replica's local slapd instance using normal LDAP modify commands slapd Replica directory server Master directory server Changes are sent via LDAP operations such as modify,delete,add,etc. Replication logfile reads writes slapd slurpd

More Than One Copy Is “a Good Thing” (cont.) Building slurpd – Pass this to the./configure script: --enable-slurpd Replication in a Nutshell – You must have a working server – Stop slapd – Reconfigure slapd.conf to enable replication – copy database from master to replica – Configure replica's slapd.conf file – Start replica server's slapd process – Start master server's slapd process – Start master server's slurpd process

More Than One Copy Is “a Good Thing” (cont.) Configuring the Master Server – You can give slurpd its own configuration file (start it with the - f option), but this is generally not done – Add two directives to the database section of slapd.conf : replogfile/var/ldap/slapd.replog replicahost=replica1.plainjoe.org:398 suffix=”dc=plainjoe,dc=org” binddn=”cn=replica,dc=plainjoe,dc=org” credentials=MyPass bindmethod=simple tls=yes

More Than One Copy Is “a Good Thing” (cont.) Configuring the Replica Server – First step: initialize database ● Copy database ● OR: Export master database to LDIF format – Restrictions to keep in mind when simply copying: ● Both hosts must have same, compatible versions of DBM libraries ● Hosts must have same byte ordering (little-endian vs. big- endian) ● Some methods of copying files (cp) will fill in the holes, resulting in much larger files on the replica host – Hence, it's probably better to use LDIF format! ● On master: # slapcat -b “dc=plainjoe,dc=org” -l contents.ldif ● On replica: # slapadd -l contents.diff only needed if there is more than one “partition”

More Than One Copy Is “a Good Thing” (cont.) Configuring the Replica Server (cont.) – Time to update the slapd.conf file on the replica to accept updates from the master server – Global section will be identical (certain pieces like server certificate should be unique, though!) – Database: identical, except: ● Replication parameters: an updatedn (tells slave server who is authorized to make changes) and updateref (points slave to master server (single master model=clients are references to master when write access is required)) updatedn“cn=replica,dc=plainjoe,dc=org” updaterefldap://pogo.plainjoe.org ● Appropriate local rootdn and rootpw paramters rootdn“cn=replica,dc=plainjoe,dc=org” rootpw{SSHA}SMKnFP0435G+QstIzNGb4RGjTOKLz2TV (Note: the development version of OpenLDAP supports an experimental multi- master replication protocol)

More Than One Copy Is “a Good Thing” (cont.) slurpd's replogfile – Replication log uses a format similar to LDIF – After reading replogfile, slurpd copies the entry to its own replay log ( slurpd.replog, -t command-line option) – Entry in replogfile generated by address change: replica: pogo.plainjoe.org time: dn: cn=jerry carter,ou=people,dc=plainjoe,dc=org changetype: modify replace: mail mail: - replace: entryCSN entryCSN: :55:49Z#0x0001#0# replace: modifiersName modifiersName: cn=Manager,dc=plainjoe,dc=org - replace: modifyTimestamp modifyTimestamp: Z - replica: pogo.plainjoe.org time: dn: cn=jerry carter,ou=people,dc=plainjoe,dc=org changetype: modify replace: mail mail: - replace: entryCSN entryCSN: :55:49Z#0x0001#0# replace: modifiersName modifiersName: cn=Manager,dc=plainjoe,dc=org - replace: modifyTimestamp modifyTimestamp: Z - one attribute value change results in four replication log entries!

More Than One Copy Is “a Good Thing” (cont.) slurpd's replogfile – modifiersName, modifyTimestamp, and entryCSN are maintained by the LDAP server and cannot be modified by clients – replica directive defines the host to which the change should be propagated (there can be more than one line) – time parameter defines epoch; slurpd maintains state information (in a file slurpd.status ) that prevents it from reparsing entries that have already been processed – If slurpd cannot propagete the change to the other server, slurpd writes the entry and reason for the failure to a rejext logfile.rej – Certain errors (eg. nework errors) cause slurpd to requeue a modification >< entry in a.rej file (requires manual intervention on case-by-case basis) – slurpd can run as a daemon, or can be run in “one-shot” mode to process a single log and exit

More Than One Copy Is “a Good Thing” (cont.) slurpd's replogfile – Command-line options for slurpd : – Start slurpd on the master server; slurpd will check for updates every 3 seconds – Backing up the slave/replica server ? Stop slurpd on the master first, restart after the backup

Table of Contents ● More Than One Copy Is “a Good Thing” ● Distributing the Directory ● Advanced Searching Options ● Determining a Server's Capabilities ● Creating Custom Schema Files for slapd ● SASL and OpenLDAP

Distributing the Directory ● So far, scenarios have assumed that the entire directory consists of only one partition; seldom the case in reality ● Definition for the ou=hosts partition is very similar to the database section we have been using so far – Main changes are suffix served by the backend ( ou=hosts,dc=plainjoe,dc=org ) and directory in which BerkeleyDB files are stored ( /var/ldap/hosts/ ) – rootdn must also be updated (must exists within partition's context) dc=plainjoe,dc=org ou=hosts,dc=plainjoe,dc=org

Distributing the Directory (cont.) ● Configuration: ## Partition on second server holding ou=hosts databasebdb # Root suffix suffix“ou=hosts,dc=plainjoe,dc=org” # Root DN & password rootdn“cn=Manager,ou=hosts,dc=plainjoe,dc=org” rootpw{SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy # Directory containing the database files directory/var/ldap/hosts # Files should be created “rw” for the owner *only* mode0600 # Indexes to maintain indexobjectClasseq indexcnpres,eq cachesize2000 Simple ACL granting read access to the world access to * by * read ## Partition on second server holding ou=hosts databasebdb # Root suffix suffix“ou=hosts,dc=plainjoe,dc=org” # Root DN & password rootdn“cn=Manager,ou=hosts,dc=plainjoe,dc=org” rootpw{SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy # Directory containing the database files directory/var/ldap/hosts # Files should be created “rw” for the owner *only* mode0600 # Indexes to maintain indexobjectClasseq indexcnpres,eq cachesize2000 Simple ACL granting read access to the world access to * by * read

Distributing the Directory (cont.) ● Superior knowledge references (referrals) point from the root of a subtree to the server of the larger directory ● Subordinate knowledge references (references) point from a node to the larger dicrectory to the subtree/partition to which it should be attached ● Client can now start a search at any node in the directory and containue down through the directory tree (search reference URI is returned to client – he can choose to continues the search on the other server) dc=plainjoe,dc=org ou=hosts,dc=plainjoe,dc=org superior knowlede reference subordinate knowledge reference

Distributing the Directory (cont.) ● slapd.conf for server holding ou=hosts tree possesses a global section indentical to existing server, with one exception: – OpenLDAP uses referral global parameter to define an LDAP URI for the server's superior knowledge reference – This is a global, server-wide parameter as opposed to a database-specific directive – Why ? Because it points to knowledge that the server receiving the request doesn't have ## slapd.conf for ou=hosts (ldap2.plainjoe.org)... # Define the URL (only host:port) for the host that clients # should contact in the event that you cannot service their # requests referralldap://master.plainjoe.org:398/ ## slapd.conf for ou=hosts (ldap2.plainjoe.org)... # Define the URL (only host:port) for the host that clients # should contact in the event that you cannot service their # requests referralldap://master.plainjoe.org:398/

Distributing the Directory (cont.) ● Subordinate knowledge references are implemented as entries within the directory itself ● These entries use referral structural object class (RFC 3296), contains a single required attribute, ref, which loads the LDAP URI for the root of the subtree ● Command to create this entry: $ ldapadd -H ldap://localhost/ -D “cn=Manager,dc=plainjoe,dc=org” \ > -w secret -x <<EOR > dn: ou=hosts,dc=plainjoe,dc=org > ou: hosts > objectClass: extensibleObject > objectClass: referral > ref: ldap://ldap2.plainjoe.org/ou=hosts,dc=plainjoe,dc=org > EOR Adding new entry “ou=hosts,dc=plainjoe,dc=org” $ ldapadd -H ldap://localhost/ -D “cn=Manager,dc=plainjoe,dc=org” \ > -w secret -x <<EOR > dn: ou=hosts,dc=plainjoe,dc=org > ou: hosts > objectClass: extensibleObject > objectClass: referral > ref: ldap://ldap2.plainjoe.org/ou=hosts,dc=plainjoe,dc=org > EOR Adding new entry “ou=hosts,dc=plainjoe,dc=org”

Distributing the Directory (cont.) ● Creating a sample in the ou=hosts tree ldap2.plainjoe.org for later use: $ ldapadd -H ldap://ldap2.plainjoe.org/ \ > -D “cn=Manager,ou=hosts,dc=plainjoe,dc=org” \ > -w secret -x <<EOR > dn: ou=hosts,dc=plainjoe,dc=org > objectClass: organizationalUnit > ou: hosts > description: Container for host info in plainjoe.org domain > EOR Adding new entry “ou=hosts,dc=plainjoe,dc=org” $ ldapadd -H ldap://ldap2.plainjoe.org/ \ > -D “cn=Manager,ou=hosts,dc=plainjoe,dc=org” \ > -w secret -x <<EOR > dn: ou=hosts,dc=plainjoe,dc=org > objectClass: organizationalUnit > ou: hosts > description: Container for host info in plainjoe.org domain > EOR Adding new entry “ou=hosts,dc=plainjoe,dc=org”

Table of Contents ● More Than One Copy Is “a Good Thing” ● Distributing the Directory ● Advanced Searching Options ● Determining a Server's Capabilities ● Creating Custom Schema Files for slapd ● SASL and OpenLDAP

Advanced Searching Options ● More thorough look at the topic of filters ● Commonly used form – syntax: ( attribute filterOperator value ) ● The attribute is the name of the actual attribute type ● The filterOperator is one of: =for equality matches ~=for approximate matches <=for less than comparisons >=for greater than comparisons ● The value can be an absolute value or a pattern using the asterisk (*) as a wildcard, eg. (cn=*carter) (telephoneNumber=555*)

Advanced Searching Options (cont.) ● Boolean operators to combine single filters: & logical AND | logical OR ! logical NOT ● LDAP search filters use prefix notation! (|(sn=smith)(sn=jones)) (&(|(sn=smith)(sn=jones))(cn=john*)) ● sn attribute uses a case insensitive matching rule ● See RFC 2254 for more information on matching

Advanced Searching Options (cont.) Following Referrals with ldapsearch – By default ldapsearch only prints information about referral objects but doesn't automatically follow them $ ldapsearch -H ldap://localhost/ -LL -x \ > -b “dc=plainjoe,dc=org” “ou=*” ou # plainjoe.org dn: dc=plainjoe,dc=org ou: Plainjoe Dot Org # people, plainjoe.org dn: ou=people,dc=plainjoe,dc=org ou: people # Search reference # refldap://ldap2.plainjoe.org/ou=hosts,dc=plainjoe,dc=org??sub $ ldapsearch -H ldap://localhost/ -LL -x \ > -b “dc=plainjoe,dc=org” “ou=*” ou # plainjoe.org dn: dc=plainjoe,dc=org ou: Plainjoe Dot Org # people, plainjoe.org dn: ou=people,dc=plainjoe,dc=org ou: people # Search reference # refldap://ldap2.plainjoe.org/ou=hosts,dc=plainjoe,dc=org??sub

Advanced Searching Options (cont.) Following Referrals with ldapsearch (cont.) – Add the -C option (“chase referrals”): $ ldapsearch -H ldap://localhost/ -LL -x -C \ > -b “dc=plainjoe,dc=org” “ou=*” ou # plainjoe.org dn: dc=plainjoe,dc=org ou: Plainjoe Dot Org # people, plainjoe.org dn: ou=people,dc=plainjoe,dc=org ou: people # hosts, plainjoe.org dc: ou=hosts,dc=plainjoe,dc=org ou: hosts $ ldapsearch -H ldap://localhost/ -LL -x -C \ > -b “dc=plainjoe,dc=org” “ou=*” ou # plainjoe.org dn: dc=plainjoe,dc=org ou: Plainjoe Dot Org # people, plainjoe.org dn: ou=people,dc=plainjoe,dc=org ou: people # hosts, plainjoe.org dc: ou=hosts,dc=plainjoe,dc=org ou: hosts

Advanced Searching Options (cont.) Limiting Your Searches – Wildcard searching can put a strain on a server with thousands of entries: ldapsearch allows you to define limits for both client and server – ldapsearch command-line parameters: – Limits on the server, in slapd.conf :

Table of Contents ● More Than One Copy Is “a Good Thing” ● Distributing the Directory ● Advanced Searching Options ● Determining a Server's Capabilities ● Creating Custom Schema Files for slapd ● SASL and OpenLDAP

Determining a Server's Capabilities ● Two new LDAPv3 features: subschemaSubentry and rootDSE objects: allow client to find out about a previously unknown directory server – rootDSE object: contains info about features such as servernaming context, implemented SASL mechanisms, supported LDAP extensions and controls ● LDAPv3 requires that rootDSE has an empty DN – subschemaSubentry attribute specifies the base search suffix for querying the schema supported by the server ● Means that clients can verify that server supports a given matching rule, attribute type, or object class prior to performing an operation that depends on a certain characteristic

Determining a Server's Capabilities (cont.) ● rootDSE example: $ ldapsearch -x -s base -b “” “(objectClass=*)” + dn: structuralObjectClass: OpenLDAProotDSE namingContexts: dc=plainjoe,dc=org supportedControl: supportedControl: supportedControl: supportedExtension: supportedExtension: supportedExtension: supportedFeatures: supportedFeatures: supportedFeatures: supportedFeatures: supportedFeatures: supportedLDAPVersion: 3 supportedSASLMechanisms: GSSAPI supportedSASLMechanisms: DIGEST-MD5 supportedSASLMechanisms: CRAM-MD5 subschemaSubentry: cn=Subschema $ ldapsearch -x -s base -b “” “(objectClass=*)” + dn: structuralObjectClass: OpenLDAProotDSE namingContexts: dc=plainjoe,dc=org supportedControl: supportedControl: supportedControl: supportedExtension: supportedExtension: supportedExtension: supportedFeatures: supportedFeatures: supportedFeatures: supportedFeatures: supportedFeatures: supportedLDAPVersion: 3 supportedSASLMechanisms: GSSAPI supportedSASLMechanisms: DIGEST-MD5 supportedSASLMechanisms: CRAM-MD5 subschemaSubentry: cn=Subschema StartTLS option ManageDsaIT control

Determining a Server's Capabilities (cont.) ● subschemaSubentry example: $ ldapsearch -D “cn=Manager,dc=plainjoe,dc=org” \ > -w secret -x -s base -b “cn=SubSchema” \ > “(objectclass=*)” + ldapSyntaxes: ( DESC 'IA5 String' )... matchingRules: ( NAME 'caseIgnoreMatch' SYNTAX )... attributeTypes: ( NAME ( 'pager' 'pagerTelephoneNumber' ) EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX )... objectClasses: ( NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn ) MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) )... $ ldapsearch -D “cn=Manager,dc=plainjoe,dc=org” \ > -w secret -x -s base -b “cn=SubSchema” \ > “(objectclass=*)” + ldapSyntaxes: ( DESC 'IA5 String' )... matchingRules: ( NAME 'caseIgnoreMatch' SYNTAX )... attributeTypes: ( NAME ( 'pager' 'pagerTelephoneNumber' ) EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX )... objectClasses: ( NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn ) MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) )...

Table of Contents ● More Than One Copy Is “a Good Thing” ● Distributing the Directory ● Advanced Searching Options ● Determining a Server's Capabilities ● Creating Custom Schema Files for slapd ● SASL and OpenLDAP

Creating Custom Schema Files for slapd ● What when standard schema files distributed with you LDAP server don't meet the needs of your applications ? – Create a custom schema file for OpenLDAP ● How ? – Assign unique OID for all new attribute types and object classes – Create schema file and include it in slapd.conf ● It's also possible to create alternate schema syntaxes and matching rules (typically require implementing a plug-in for the directory server or modifying the server's source code) ● Obtain private enterprise numbers from IANA: see and RFC

Creating Custom Schema Files for slapd (cont.) ● Example: suppose LDAP client application requires a new object class based on person. New object should contain all of the attributes possessed by the person object, with addition of userPassword and mail attributes – Allocated OID arc of for the new object classes: iso(1) org(3) dod(6) internet(1) private(4) enterprise(1) SAMBA.org(7165) plainjoe.org(1) O'Reilly LDAP Book(1) iso(1) org(3) dod(6) internet(1) private(4) enterprise(1) SAMBA.org(7165) plainjoe.org(1) O'Reilly LDAP Book(1)

Creating Custom Schema Files for slapd (cont.) ● Chose to allocate to ldap object classes created and for new attributes: ● Add following definition to schema file plainjoe.schema : ● LDAP's inheritance: you need to add only the new required attributes; if new attributes are used, must be defined prior to use in plainjoePerson object SAMBA.org(7165) plainjoe.org(1) O'Reilly LDAP Book(1) |-- objectClasses (1) |-- attributeTypes (2) SAMBA.org(7165) plainjoe.org(1) O'Reilly LDAP Book(1) |-- objectClasses (1) |-- attributeTypes (2) ## objectclass definition for 'plainjoePerson' depends on ## core.scheme objectclass ( NAME 'plainjoePerson' SUB person STRUCTURAL MUST (userPassword $ mail) ) ## objectclass definition for 'plainjoePerson' depends on ## core.scheme objectclass ( NAME 'plainjoePerson' SUB person STRUCTURAL MUST (userPassword $ mail) ) Because it's derived from a STRUCTURAL class

Creating Custom Schema Files for slapd (cont.) ● Defining new attributes: same way, RFC 2252 ● eg. new attribute plainjoePath to store a single, case- sensitive pathname, add this to plainjoe.schema : (other LDAP implementations may use different syntax) ● Include line in slapd.conf : ## Store a case-sensitive path to a directory attributetype( NAME 'plainjoePath' DESC 'A directory on disk' SUBSTR caseExactIA5SubstringsMatch EQUALITY caseExactIA5Match SYNTAX SINGLE-VALUE ) ## Store a case-sensitive path to a directory attributetype( NAME 'plainjoePath' DESC 'A directory on disk' SUBSTR caseExactIA5SubstringsMatch EQUALITY caseExactIA5Match SYNTAX SINGLE-VALUE ) # Global section include/usr/local/etc/openldap/schema/core.schema # NEW include/usr/local/etc/openldap/schema/plainjoe.schema # Global section include/usr/local/etc/openldap/schema/core.schema # NEW include/usr/local/etc/openldap/schema/plainjoe.schema

Table of Contents ● More Than One Copy Is “a Good Thing” ● Distributing the Directory ● Advanced Searching Options ● Determining a Server's Capabilities ● Creating Custom Schema Files for slapd ● SASL and OpenLDAP

SASL and OpenLDAP ● How to replace the simple authentication used with SASL mechanisms ● We will use the GSSAPI mechanisms for Kerberos 5 authentication (RFCs 1510, 2743, and 2478) ● Asumptions: Kerberos realm is named PLAINJOE.ORG and a service principal ldapadmin has already been created – Need more info on Kerberos ? ● In OpenLDAP 2.1, an SASL ID can be converted to a distinguished name and used for authentication or authorization wherever a normal DN would be appropriate – Exception: Don't use SASL ID as the DN of an entry in the directory

SASL and OpenLDAP ● SASL ID, converted to a DN: uid=name[,realm=realm],cn=mechanism,cn=auth ● Example: replace rootdn in slapd.conf rootdn“uid=ldapadmin,cn=gssapi,cn=auth” ● rootpw entry can be deleted: SASL GSSAPI mechanism will take care of authentication ● OpenLDAP server must possess a valid keytab file containing the key for decrypting tickets transmitted with client requests (man kadmin). Moreover, server must use the default realm of PLAINJOE.ORG ● Restart slapd ● Test OpenLDAP by adding an entry using LDIF (ldapadd) dn: cn=test user,ou=people,dc=plainjoe,dc=org cn: test user sn: test objectClass: person dn: cn=test user,ou=people,dc=plainjoe,dc=org cn: test user sn: test objectClass: person

SASL and OpenLDAP ● Add this entry to the directory: ● If SASL fails, use -Y option to specify SASL mechanisms $ kinit Password for password $ klist Ticket cache: FILE:/tmp/krb5cc_780 Default principal: Valid startingExpiresService principal 11/28/02 19:20:1511/29/02 $ ldapmodify -a -H ldap://master.plainjoe.org/ \ > -f testuser.ldif SASL/GSSAPI authentication started SASL username: SASL SSL: 56 SASL installing layers adding new entry “cn=test user,ou=people,dc=plainjoe,dc=org” $ klist Ticket cache: FILE:/tmp/krb5cc_780 Default principal: Valid startingExpiresService principal 11/28/02 19:20:1511/29/02 11/28/02 19:23:3411/29/02 $ kinit Password for password $ klist Ticket cache: FILE:/tmp/krb5cc_780 Default principal: Valid startingExpiresService principal 11/28/02 19:20:1511/29/02 $ ldapmodify -a -H ldap://master.plainjoe.org/ \ > -f testuser.ldif SASL/GSSAPI authentication started SASL username: SASL SSL: 56 SASL installing layers adding new entry “cn=test user,ou=people,dc=plainjoe,dc=org” $ klist Ticket cache: FILE:/tmp/krb5cc_780 Default principal: Valid startingExpiresService principal 11/28/02 19:20:1511/29/02 11/28/02 19:23:3411/29/02

SASL and OpenLDAP ● Client can obtain list of supported mechanisms by querrying server's rootDSE and viewing supportedSASLMechanisms attribute ● Example definition in slapd.conf that allows principal jerry to edit the mail attribute for all users in the people organizational unit: access to dn=”.*,ou=people,dc=plainjoe,dc=org” attrs=mail by “uid=jerry,cn=gssapi,cn=auth” write