Changes between Initial Version and Version 1 of ALL__add_attribute

Timestamp:

11/13/14 15:50:38 (10 years ago)

Author:

lttoth@…

Comment:

--

ALL__add_attribute

@@ +1 @@
+= 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)