Referential integrity plug-in

IBM Tivoli Directory Server, Version 6.3

Referential integrity plug-in

The referential integrity plug-in sample code contains pre-operation and post-operation referential integrity plug-ins. The pre-operation plug-in, libprerefint, performs referential integrity checks when performing ldapadd and ldapmodify operations. The post-operation plug-in, libpostrefint, performs referential integrity checks when performing ldapdelete and ldapmodrdn operations.

Building from source files

All the necessary files to build the plug-in library files on the Windows NT® systems are available in the <TDS_INSTALL_ROOT>\examples\plug-in directory, and for AIX®, Linux®, and Solaris systems are available in the <TDS_INSTALL_ROOT>/examples/plug-in directory. The example source code files for the referential integrity plug-in are also available in the directory.

To build the source files on a particular operating system, run the following commands:

For Windows NT systems: nmake -f makefile.plugin
For AIX, Solaris, and Linux systems: make -f makefile.plugin
Note:

On Solaris, you might need the -KPIC compiler flag to create position independent code.

Note:

The makefile may require changes based on the differences in individual machine configurations.

An example makefile to build the library files on a Linux system:

#####################################################################
##  Linux Makefile
#####################################################################
#DEFINES=-D LINUX -D LDAP_STATIC_LINK -DLOCAL_LDAP_CACHE

IDS_LDAP_HOME=/opt/ibm/ldap/V6.3
IDS_LDAP_INCLUDES= -I$(IDS_LDAP_HOME)/include

#********************************************
# ------ Options for building 32-bit targets
#********************************************
IDS_LDAP_LIBS = $(IDS_LDAP_HOME)/lib
OS_LIBS = /usr/lib
COMPILER_TARGET_FLAG =

#********************************************
# ------ Options for building 64-bit targets
#********************************************
#IDS_LDAP_LIBS = $(IDS_LDAP_HOME)/lib64
#OS_LIBS = /usr/lib64
#COMPILER_TARGET_FLAG = -m64

DEBUG=-g
OPTIMIZED=-O2
OPT=${DEBUG}

CC_ARGS=$(DEFINES) $(IDS_LDAP_INCLUDES) $(CFLAGS)

CC=/usr/bin/gcc -g -DSTRINGS $(COMPILER_TARGET_FLAG)
LD=/usr/bin/gcc -g -shared $(COMPILER_TARGET_FLAG)

#To work with 64-bit compiler use the -fPIC flag
#CC=/usr/bin/gcc -g -DSTRINGS $(COMPILER_TARGET_FLAG) -fPIC
#LD=/usr/bin/gcc -g -shared $(COMPILER_TARGET_FLAG)

API_LIB_DIR=./lib
API_OBJ_DIR=./obj

API_I_POSTFILE=libpostrefint.so
API_I_POST=${API_LIB_DIR}/${API_I_POSTFILE}
API_I_PREFILE=libprerefint.so
API_I_PRE=${API_LIB_DIR}/${API_I_PREFILE}

LDAPLIB=-lslapi -lldap -lpthread -L$(OS_LIBS) -L$(IDS_LDAP_LIBS)

TAR_FILE=${API_OBJ_DIR}/libdelref.tar
TAR_SOURCE=$(API_E)

API_OBJS_POST= \
   ${API_OBJ_DIR}/DeleteReference.o \
   ${API_OBJ_DIR}/ModRdnReference.o \
   ${API_OBJ_DIR}/ReferenceUtils.o \
   ${API_OBJ_DIR}/PostReferenceUtils.o

API_OBJS_PRE= \
   ${API_OBJ_DIR}/AddReference.o \
   ${API_OBJ_DIR}/ReferenceUtils.o \
   ${API_OBJ_DIR}/ModReference.o \
   ${API_OBJ_DIR}/PreReferenceUtils.o

all: debug

debug:
        @OPT="${DEBUG}" make -f makefile.plugin -e build

optimized:
        @OPT="${OPTIMIZED}" make -e build

build: libpost libpre

${API_LIB_DIR}:
        mkdir -p ${API_LIB_DIR}

${API_OBJ_DIR}:
        mkdir -p ${API_OBJ_DIR}

libpost: ${API_LIB_DIR} ${API_OBJ_DIR} $(API_I_POST)

libpre: ${API_LIB_DIR} ${API_OBJ_DIR} $(API_I_PRE)

$(API_I_POST): $(API_OBJS_POST)
        rm -f $(API_I_POST)
        $(LD) -o ${API_I_POST} $(API_OBJS_POST) $(LDAPLIB)

$(API_I_PRE): $(API_OBJS_PRE)
        rm -f $(API_I_PRE)
        $(LD) -o ${API_I_PRE} $(API_OBJS_PRE) $(LDAPLIB)

$(TAR_FILE).tar.Z: ${TAR_SOURCE}
        rm -f ${TAR_FILE}.*
        tar cvf $(TAR_FILE).tar $(TAR_SOURCE)
        compress $(TAR_FILE).tar

${API_OBJ_DIR}/DeleteReference.o: DeleteReference.c
        ${CC} -c ${CC_ARGS} DeleteReference.c -o $@

${API_OBJ_DIR}/ModRdnReference.o: ModRdnReference.c
        ${CC} -c ${CC_ARGS} ModRdnReference.c -o $@

${API_OBJ_DIR}/ReferenceUtils.o:ReferenceUtils.c
        ${CC} -c ${CC_ARGS} ReferenceUtils.c -o $@

${API_OBJ_DIR}/PostReferenceUtils.o:PostReferenceUtils.c
        ${CC} -c ${CC_ARGS} PostReferenceUtils.c -o $@

${API_OBJ_DIR}/AddReference.o: AddReference.c
        ${CC} -c ${CC_ARGS} AddReference.c -o $@

${API_OBJ_DIR}/ModReference.o: ModReference.c
        ${CC} -c ${CC_ARGS} ModReference.c -o $@

${API_OBJ_DIR}/PreReferenceUtils.o:PreReferenceUtils.c
        ${CC} -c ${CC_ARGS} PreReferenceUtils.c -o $@

clean:
        rm -rf ${API_OBJ_DIR} ${API_LIB_DIR}

Output directory of the library files

The referential integrity plug-in library files generated as a result of build are stored in the <TDS_INSTALL_ROOT>/examples/plug-in/lib directory on AIX, Linux, and Solaris systems and in the <TDS_INSTALL_ROOT>\examples\plug-in\lib directory on the Windows NT system. On Windows NT system, the library files will be libprerefint.dll and libpostrefint.dll. On AIX, Linux, and Solaris systems, the library files will be libprerefint.so and libpostrefint.so.

Input and log files of referential integrity plug-in

Input file

The referential integrity plug-in is initialized by reading referential integrity constraint information from the file specified by <input-file-path> , which is a requirement for using the plug-in. Here in the examples, the refIntegInput file is used. You can use any input file that has constraint in the following format:

at=<DN-style-attribute><\n>
dn=<search-base-DN><\n>

The input file can contain multiple DN style attribute, and search base DN entry in any order. The plug-in treats each entry as it is and therefore white space before and after the specification is not allowed and might lead to undesirable results.

On a Linux system an example input file, refIntegInput, is provided in the <TDS_INSTALL_ROOT>/examples/plug-in/input directory, and an example ldif file, add.ldif, in the <TDS_INSTALL_ROOT>/examples/plug-in/ldif directory. A copy of example input file, refIntegInput, is used that is stored in the <instance_home>/ idsslapd-myinst1/etc directory. In the example input file, the constraints is checked against the following format:

at=seeAlso
dn=o=ibm,c=us

Here, the attribute "seeAlso" will be checked for referential integrity constraints for entries falling under the DN "o=ibm, c=us".

Log file

The plug-in perform referential integrity checks for the ldap operations that it is designed for and logs the report to the ibmslapd.log file. If the debug version of the plug-in initialization function are used the log status becomes more verbose and can be used to trace execution.

Registering the referential integrity plug-in

To use referential integrity plug-in libraries, they must be registered with IBM® Tivoli® Directory Server. To register the plug-in, first you must add an entry for the plug-in the configuration file, ibmslapd.conf. This is done by adding "ibm-slapdPlugin" specifications to the "ibmslapd.conf" file. You can add an entry to the configuration file using the ldapmodify command, provided you must have the required permissions. The plug-in initialization functions that are used in the <init-function> specification are "preReferenceInit" and "postReferenceInit". For debugging purposes, the "preReferenceInitDebug", and "postReferenceInitDebug" can be substituted in the <init-function> specification, to get more verbose logging. To add entries, issue the idsldapmodify command of the following format:

# idsldapmodify -p 3389 -D cn=root -w root -f <filename>

where, <filename> contains:

dn: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
changetype: modify
add: ibm-slapdPlugin
ibm-slapdPlugin: preoperation /opt/ibm/ldap/V6.3/examples/plug-in/lib/libprerefint.so  
 preReferenceInit /home/myinst1/idsslapd-myinst1/etc/refIntegInput
-
add: ibm-slapdPlugin
ibm-slapdPlugin: postoperation /opt/ibm/ldap/V6.3/examples/plug-in/lib/libpostrefint.so 
 postReferenceInit /home/myinst1/idsslapd-myinst1/etc/refIntegInput

To verify that the entries got added under the specified entry DN, issue the idsldapsearch command of the following format:

# idsldapsearch -D cn=root -w root -p 3389 -s sub -b \
 "cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration" \
 -L objectclass=*

dn: cn=Directory, cn=RDBM Backends, cn=IBM Directory, cn=Schemas, cn=Configuration
cn: Directory
ibm-slapdDbAlias: ldapdb2b
ibm-slapdDbConnections: 15
ibm-slapdDbInstance: myinst1
ibm-slapdDbLocation: /home/myinst1
ibm-slapdDbName: myinst1
ibm-slapdDbUserID: myinst1
ibm-slapdDbUserPW: {AES256}hCUF8fpN7J0gVcFaZau8jw==
ibm-slapdEnableRemotePWPExOps: TRUE
ibm-slapdGroupMembersCacheBypassLimit: 25000
ibm-slapdGroupMembersCacheSize: 25
ibm-slapdLanguageTagsEnabled: FALSE
ibm-slapdNumRetry: 5
ibm-slapdPagedResAllowNonAdmin: TRUE
ibm-slapdPagedResLmt: 3
ibm-slapdPlugin: database    libback-rdbm.so rdbm_backend_init
ibm-slapdPlugin: replication libldaprepl.so  replInit
ibm-slapdPlugin: preoperation /opt/ibm/ldap/V6.3/examples/plug-in/lib/libprerefint.so 
preReferenceInit /home/myinst1/idsslapd-myinst1/etc/refIntegInput
ibm-slapdPlugin: postoperation /opt/ibm/ldap/V6.3/examples/plug-in/lib/libpostrefint.so 
postReferenceInit /home/myinst1/idsslapd-myinst1/etc/refIntegInput
ibm-slapdReadOnly: FALSE
ibm-slapdSortKeyLimit: 3
ibm-slapdSortSrchAllowNonAdmin: TRUE
ibm-slapdSuffix: cn=localhost
ibm-slapdSuffix: cn=ibmpolicies
ibm-slapdSuffix: cn=Deleted Objects
ibm-slapdSuffix: o=ibm, c=us
ibm-slapdTombstoneEnabled: FALSE
ibm-slapdTombstoneLifetime: 168
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdRdbmBackend

After adding the referential integrity plug-in entries in the configuration file, you must restart IBM Tivoli Directory Server for the registration and loading of the library files to take effect.

An example excerpt of the messages that the IBM Tivoli Directory Server generates at starting the instance:

# ibmslapd -I myinst1 -n -c

GLPSRV041I Server starting.
GLPCTL113I Largest core file size creation limit for the process 
           (in bytes): '0'(Soft limit) and '-1'(Hard limit).
GLPCTL119I Maximum Data Segment(Kbytes) soft ulimit for the process 
           is -1 and the prescribed minimum is 262144.
GLPCTL119I Maximum File Size(512 bytes block) soft ulimit for the process 
           is -1 and the prescribed minimum is 2097152.
GLPCTL122I Maximum Open Files soft ulimit for the process is 1024 and the 
           prescribed minimum is 500.
GLPCTL119I Maximum Stack Size(Kbytes) soft ulimit for the process is -1 
           and the prescribed minimum is 10240.
GLPCTL119I Maximum Virtual Memory(Kbytes) soft ulimit for the process is -1 
           and the prescribed minimum is 1048576.
GLPCOM024I The extended Operation plugin is successfully loaded from libevent.so.
GLPCOM024I The extended Operation plugin is successfully loaded from libtranext.so.
GLPCOM024I The extended Operation plugin is successfully loaded from libldaprepl.so.
GLPSRV155I The DIGEST-MD5 SASL Bind mechanism is enabled in the configuration file.
...
GLPCOM024I The extended Operation plugin is successfully loaded from libpsearch.so.
GLPCOM022I The database plugin is successfully loaded from libback-rdbm.so.
GLPCOM010I Replication plugin is successfully loaded from libldaprepl.so.
GLPCOM021I The preoperation plugin is successfully loaded from
/opt/ibm/ldap/V6.3/examples/plug-in/lib/libprerefint.so.
GLPCOM023I The postoperation plugin is successfully loaded from
/opt/ibm/ldap/V6.3/examples/plug-in/lib/libpostrefint.so.
GLPSRV189I Virtual list view support is enabled.
GLPCOM021I The preoperation plugin is successfully loaded from libpta.so.
...
GLPSRV180I Pass-through authentication is disabled.
GLPCOM003I Non-SSL port initialized to 3389.
GLPRPL137I Restricted Access to the replication topology is set to false.
GLPSRV009I 6.3.0.0      server started.
GLPRPL136I Replication conflict resolution mode is set to true.
GLPSRV048I Started 15 worker threads to handle client requests.

Examples

Examples to verify the working of referential integrity plug-in

After creating and configuring a directory server instance, add data to directory server instance from the example ldif file, add.ldif, available in the <TDS_INSTALL_ROOT>/examples/plug-in/ldif directory on a Linux system. An example of the idsldapadd command with its output:

#idsldapadd -p 3389 -D cn=root -w root -f add.ldif
Operation 0 adding new entry o=ibm, c=us
Operation 1 adding new entry cn=sullyBoss,o=ibm,c=us
Operation 2 adding new entry cn=sullyEmp,o=ibm,c=us
Operation 3 adding new entry cn=sully1,o=IBM,c=US

To search for the newly added entries, run the idsldapsearch command. An example of the idsldapsearch command with its output:

#idsldapsearch -p 3389 -s sub -b "o=ibm, c=us" objectclass=*
o=ibm,c=us
objectclass=organization
objectclass=top
o=ibm

cn=sullyBoss,o=ibm,c=us
objectclass=inetOrgPerson
objectclass=organizationalPerson
objectclass=person
objectclass=top
objectclass=ePerson
sn=sullyEmpSN
cn=sullyEmp
cn=sullyBoss

cn=sullyEmp,o=ibm,c=us
objectclass=inetOrgPerson
objectclass=organizationalPerson
objectclass=person
objectclass=top
objectclass=ePerson
sn=sullyEmpSN
cn=sullyEmp
seealso=cn=sullyBoss,o=ibm,c=us

cn=sully1,o=IBM,c=US
objectclass=person
objectclass=organizationalPerson
objectclass=top
cn=sully1
sn=sullivan
telephonenumber=1-812-855-8541
internationalisdnnumber=755-8541
title=Mechanical Ana. Thermal
seealso=cn=sullyBoss,o=ibm,c=us
postalcode=4502

Checking the plug-in for pre-operation referential integrity

To check for pre-operation referential integrity when adding wrong data. An example of the idsldapadd command with its output:

#idsldapadd -p 3389 -D cn=root -w root
cn=sully2,o=ibm,c=us
objectclass=person
objectclass=organizationalPerson
objectclass=top
cn=sully2
sn=bob
seealso=cn=sully1, o=sample
Operation 0 adding new entry cn=sully2,o=ibm,c=us
ldap_add: Unknown error
ldap_add: additional info: plugin function failed

To check for pre-operation referential integrity when modifying an existing entry. An example of the idsldapmodify command with its output:

#idsldapmodify -p 3389 -D cn=root -w root
dn: cn=sully1,o=IBM,c=US
changetype: modify
replace: seealso
seealso:
Operation 0 modifying entry cn=sully1,o=IBM,c=US
ldap_modify: Unknown error
ldap_modify: additional info: plugin function failed

Checking the plug-in for post-operation referential integrity

To check for post-operation referential integrity by modifying the RDN. An example of the idsldapmodrdn command with its output:

# idsldapmodrdn -p 3389 -D cn=root -w root cn=sullyBoss,o=ibm,\
   c=us cn=sullyManager
copying cn=sullyBoss,o=ibm,c=us to cn=sullyManager

Verifying the data in the directory server:

# idsldapsearch -p 3389 -s sub -b "o=ibm, c=us" objectclass=*
o=ibm,c=us
objectclass=organization
objectclass=top
o=ibm

cn=sullyManager,o=ibm,c=us
objectclass=inetOrgPerson
objectclass=organizationalPerson
objectclass=person
objectclass=top
objectclass=ePerson
sn=sullyEmpSN
cn=sullyEmp
cn=sullyBoss
cn=sullyManager

cn=sullyEmp,o=ibm,c=us
objectclass=inetOrgPerson
objectclass=organizationalPerson
objectclass=person
objectclass=top
objectclass=ePerson
sn=sullyEmpSN
cn=sullyEmp
seeAlso=cn=sullyManager,o=ibm,c=us

cn=sully1,o=IBM,c=US
objectclass=person
objectclass=organizationalPerson
objectclass=top
cn=sully1
sn=sullivan
telephonenumber=1-812-855-8541
internationalisdnnumber=755-8541
title=Mechanical Ana. Thermal
postalcode=4502
seeAlso=cn=sullyManager,o=ibm,c=us

Notice the changes made to the values of the seeAlso attribute in other entries.

To check for post-operation referential integrity by deleting an entry that is referred to by the seeAlso attribute. An example of the idsldapdelete command with its output:

#idsldapdelete -p 3389 -D cn=root -w root cn=sullyManager,\
   o=ibm,c=us
Deleting entry cn=sullyManager,o=ibm,c=us

Verifying the data in the directory server:

# idsldapsearch -p 3389 -s sub -b "o=ibm, c=us" objectclass=*
o=ibm,c=us
objectclass=organization
objectclass=top
o=ibm

cn=sullyEmp,o=ibm,c=us
objectclass=inetOrgPerson
objectclass=organizationalPerson
objectclass=person
objectclass=top
objectclass=ePerson
sn=sullyEmpSN
cn=sullyEmp

cn=sully1,o=IBM,c=US
objectclass=person
objectclass=organizationalPerson
objectclass=top
cn=sully1
sn=sullivan
telephonenumber=1-812-855-8541
internationalisdnnumber=755-8541
title=Mechanical Ana. Thermal
postalcode=4502

Notice that the references to the value, “cn=sullyManager,o=ibm,c=us", in the seeAlso attribute has been removed along with the deletion of the entry “cn=sullyManager,o=ibm,c=us".

[ Top of Page | Previous Page | Next Page ]