How to Modify the EDIR Schema

Original Author - Beth Mercer 20081028

20081028 sxelm How to Modify the EDIR Schema ==========================================================================================

EDIR is comprised of an iPlanet Directory, Oracle Registry and web gateway. EDIR schema changes require that each of those components be modified in some manner.

NOTE: Schema definitions are unique to a directory instance; they are not replicated between directory instances. Changes to attribute values under dc=alaska,dc=edu records, however, are replicated and the absence of an attribute definition in a target directory can cause problems. Therefore, always complete schema changes in all directory instances before making ACI, gateway and registry changes that allow the update of new attributes.

+++++++++++++++++ iPlanet Directory +++++++++++++++++

An iPlanet directory instance is where the EDIR Web Gateway gets the information it displays and where (in addition to the registry) data changes are stored. The directory schema governs what attributes may be stored in EDIR. Directory ACIs govern who has access to what information.

iPlanet schema (attribute and object) information is stored in text files that are read during instance startup. The file names are prefixed by a number; those prefixes other than 98 represent schema files provided by Sun, while 98-series files represent UA-specific schema information. While schema changes can be made via the iPlanet Console, do not do so for the EDIR project. Schema changes made via the console are written to iPlanet's configuration files where they are mixed up with other, non-EDIR, schema information. All EDIR related schema changes have been carefully placed in a separate configuration file. Edit that file to modify the EDIR schema.

To modify the iPlanet EDIR schema:

# ssh to iplanet account on edgar or elias # move to schema directory for particular directory instance cd /e01/iplanet/servers/slap-[edgar|elias][Test|Prep]/config/schema/

# list existing EDIR schema versions # making sure the current copy of 98uaSchemaAdditions.ldif has a datestamped backup ls -lrt 98uaSchemaAdditions*

# copy 98uaSchemaAdditions.ldif to a new backup with today's date cp -p 98uaSchemaAdditions.ldif 98uaSchemaAdditions.ldif.$(date +'%Y%m%d')

# edit the backup copy vi 98uaSchemaAdditions.ldif.$(date +'%Y%m%d')

# diff the current and new schemas sdiff -s 98uaSchemaAdditions.ldif.$(date +'%Y%m%d') 98uaSchemaAdditions.ldif

# if diff shows what is expected, overwrite current version with new version cp -p 98uaSchemaAdditions.ldif.$(date +'%Y%m%d') 98uaSchemaAdditions.ldif

# bounce the directory instance pbrun [Prep|Test]stop-slapd pbrun [Prep|Test]start-slapd

If after making schema changes, the directory instance should fail to start, restore the backup copy of 98uaSchemaAdditions.ldif and start directory.

To modify the iPlanet EDIR ACIs:

# ssh to iplanet account on edgar or elias # move to the directory containing ACI source cd local/ldap/schema

# list existing EDIR ACI versions # making sure the current ACI file has a datestamped backup ls -lrt aci*

# set up variables used in remaining syntax examples HOST=$(hostname) INST=Test # (null), Test or Prep PORT=13238 # 389, 13238 or 15462 FILENAME=aci.with_user_update.$(date +'%Y%m%d') # glean from other ACI file names echo ${HOST} ${INST} ${PORT} ${FILENAME}

# make a date stamped copy of the most recent applicable ACI file # e.g. cp -p <applicable_file> ${FILENAME}

# edit new copy of ACI file vi ${FILENAME}

# count number of add: and delete: statements in file # that count should be matched when you next apply the ACIs egrep 'add:|delete:' ${FILENAME}|wc -l

# apply ACIs to applicable directory instance (ldapmodify -p ${PORT} -h ${HOST}.alaska.edu -D "cn=Directory Manager" \

-j $HOME/.DirectoryManager?${INST}.pass -c -v -f ${FILENAME}) | grep 'modify complete'|wc -l

If your ACI changes include a NEW delete statement, the count of of "modify complete" statements will not match the count of add: and delete: statements (can't delete what didn't exist). Apply the ACI file a second time and check the counts.

If the count of "modify complete" statements still does not match the count of add: and delete: statements, then reapply the prior version of the ACI file.

+++++++++++++++ Oracle Registry +++++++++++++++

EDIR gateway updates are processed in the Oracle Registry before they are processed in the iPlanet Directory. The registry table LDAP_CLASS_ATTRIBS governs what attributes can be processed. The registry EDIR procedure enforces edit rules and performs the registry update.

To modify the registry LDAP_CLASS_ATTRIBS table:

# ssh to sxldap account on registry host, toklat or summit as appropriate. # connect to EDIR instance . ua_oracle rptt|q|s env sqlplus /

# list current attributes set pages 2000 lines 132 column class format a30 column attributes format a30 column source format a30 select * from LDAP_CLASS_ATTRIBS order by attribute;

# review list and determine appropriate change

# delete an attribute delete LDAP_CLASS_ATTRIBS where attribute = '&case_sensitive_attrib_name';

# add an attribute (see NOTES) insert into LDAP_CLASS_ATTRIBS values ( '&case_sensitive_class_name', '&case_sensitive_attrib_name', '&privileged_flag_Y_N', '&selfserve_flag_Y_N', '&static_flag_Y_N', '&case_sensitive_source_name', '&isunique_flag_Y_N' );

# modify an attribute # either delete then add, # or write appropriate SQL update statement

To modify the registry EDIR procedure, if special handling of the new attribute by EDIR is necessary:

# ssh to sxldap account on summit	
# change to registry source code directory
	cd local/ldap/registry

# list source files for EDIR procedure making sure the current copy
# of create_package_edir.sql has a datestamped backup
	ls -lrt create_package_edir.sql*

# copy create_package_edir.sql to a new backup with today's date
	cp -p create_package_edir.sql create_package_edir.sql.$(date +'%Y%m%d')

# edit the backup copy
	vi create_package_edir.sql.$(date +'%Y%m%d')

# diff the current and new versions
	sdiff -s create_package_edir.sql.$(date +'%Y%m%d') create_package_edir.sql

# if diff shows what is expected, overwrite current version with new version
	cp -p create_package_edir.sql.$(date +'%Y%m%d') create_package_edir.sql

# connect to EDIR instance and compile procedure - RPTQ before RPTS
	rpt[t|q|s]
	sqlplus /
		@create_package_edir.sql

If the EDIR procedure should fail to compile, restore the backup copy of create_package_edir.sql and execute that version of the source script.

+++++++++++ Web Gateway +++++++++++

The EDIR Web Gateway utilizes attribute information stored in the CGI script ldap_lib.pm to control what attributes are displayed to what types of individuals. If a new attribute is not added to ldap_lib.pm, the attribute won't be displayed by the gateway.

To modify the gateway ldap_lib.pm CGI script:

# ssh to ldapgw account on an e-box host
# move to EDIRTEST gateway directory
	cd EDIRTEST/cgi-bin

# list existing ldap_lib.pm versions
# making sure the current copy has a datestamped backup
	ls -lrt ldap_lib.pm

# copy ldap_lib.pm to a new backup with today's date
	cp -p ldap_lib.pm ldap_lib.pm.$(date +'%Y%m%d')

# edit the backup copy
	vi ldap_lib.pm.$(date +'%Y%m%d')

	# find getAttributes() function
	# add/delete/modify in ATTRIBUTES hash
	# N.B. a placeholder entry for an attribute which is not expected to be visible or
	# updated might look like this:
	# 'attribute name'  =>  [99,'n','S','N','N','Displayable Attribute Name','','','',''],

	# diff the current and new schemas
	sdiff -s ldap_lib.pm.$(date +'%Y%m%d') ldap_lib.pm

	# if diff shows what is expected, overwrite current version with new version
	cp -p ldap_lib.pm.$(date +'%Y%m%d') ldap_lib.pm

If the Web Gateway does not function after making changes to ldap_lib.pm, restore the prior datestamped backup.

Note: EDIRTEST/cgi-bin changes are subsequently copied to the PREP and PROD cgi-bin directories on the e-box hosts.

####################### NOTES

1. It appears that if an attribute is added to the directory but not to the registry, the update back end will continue to function normally. This is not intended to suggest that adding attributes to the directory but not the registry is a good idea.

2. It appears that the only code in which this table is referenced is the stored procedures in create_package_edir.sql (i.e. the "registry EDIR procedure"), and the CLASS, ISUNIQUE and ATTRIBUTE columns are the only ones currently referenced. This is not to suggest that it is a good idea to omit fully documenting attributes by adding entries for them to this table.

3. It appears that each row of the LDAP_CLASS_ATTRIBS table describes one directory attribute. The column definitions of the LDAP_CLASS_ATTRIBS table are something like:

CLASS - the object class to which the attribute belongs, e.g. eduPersonAffiliation belongs

to the eduPerson object class.

ATTRIBUTE - attribute name, e.g. eduPersonAffiliation PRIVILEGED - don't know exactly what this column means, but it is Y for these attributes:

userPassword defaultPassword uakSecQuestion uakSecResponse

and NULL otherwise.

SELFSERVE - this appears to be Y for attributes which can be changed via self-service and

NULL otherwise.

STATIC - this column appears to be Y for attributes which normally do not change over the

lifetime of the entry, currently:

c(ountry) o(rganization) uid ou

and NULL otherwise.

SOURCE - this column seems to contain an abbreviation representing from where in Banner the

datum was drawn:

bgen (Banner General?) bhr (Banner HR?) bfac (Banner ?) bstu (Banner ?)

it is always NULL when SELFSERV = Y.

ISUNIQUE - this column appears to be Y (or in one case T) for attributes intended to be single-

valued. This intent is generally not enforced in the directory, and there are attributes defined as single-valued in the directory which are not defined as such in this table.

DEFAULT_VALUE - this column appears to be the default for this attribute or else NULL.

4. It appears that every directory attribute except objectClass has a row in LDAP_CLASS_ATTRIBS. objectClass has a column (CLASS) in this table. Recall that the objectClass attributes in a directory entry list the object classes to which the entry belongs, and the attributes of the entry belong to one of the object classes. So the object class information is more appropriately stored in a column rather than a row.

####################### DOCUMENT CHANGE HISTORY

20081028 elm Added clarifying statements about need to remove directories from

Equalizer mix before making schema changes and to make schema changes in all directory instances before enabling updates to new attributes.

20090622 mpa Added NOTES and miscellaneous small corrections.

========================================================================================== (eof)