35-2 Oracle Fusion Middleware Administrators Guide for Oracle Internet Directory
Oracle Internet Directory, and is enabled by default. The entry for this plug-in is cn=plugin,cn=subconfigsubentry.
This plug-in has three triggers:
■
The DN of the plug-in trigger used to create a garbage collection job is: cn=Add PurgeConfig,cn=plugin,cn=subconfigsubentry.
■
The DN of the plug-in trigger used to modify a garbage collection job is: cn=Modify PurgeConfig,cn=plugin,cn=subconfigsubentry.
■
The DN of the plug-in trigger used to delete a garbage collection job is: cn=Delete PurgeConfig,cn=plugin,cn=subconfigsubentry.
Background Database Processes
The background database processes that are invoked by the garbage collection plug-in include garbage collectors and the Oracle Internet Directory statistics collector.
Garbage Collectors You can set and manage these behaviors of a garbage collector:
■
The time it starts
■
The age of the data you want it to purge
■
How often it runs
■
The type of data you want it to purge
■
The number of entries to purge at a time
Predefined Garbage Collectors A default installation of Oracle Internet Directory includes these predefined garbage collectors:
■
Change log garbage collector: Cleans up the consumed change log entries in the directory. The container for this garbage collector is
cn=changelog purgeconfig, cn=purgeconfig,cn=subconfigsubentry.
■
General statistics garbage collector: Cleans up obsolete entries created by Oracle Internet Directory Server Manageability for monitoring general statistics of the
directory. The container for this garbage collector is cn=general stats purgeconfig,
cn=purgeconfig,cn=subconfigsubentry.
■
Health statistics garbage collector: Cleans up obsolete entries created by Oracle Internet Directory Server Manageability for monitoring health statistics of the
directory. The container for this garbage collector is cn=health stats purgeconfig,
cn=purgeconfig,cn=subconfigsubentry.
■
Security and refresh events garbage collector: Cleans up obsolete entries created by Oracle Internet Directory Server Manageability for monitoring security and
refresh events of the directory. The container for this garbage collector is cn=secrefresh events purgeconfig,
cn=purgeconfig,cn=subconfigsubentry.
See Also: Oracle Internet Directory Configuration Schema
Elements in Oracle Fusion Middleware Reference for Oracle Identity Management for a list and descriptions of the attributes of the
garbage collection plug-in
Managing Garbage Collection 35-3
■
System resource events garbage collector: Cleans up obsolete entries created by Oracle Internet Directory Server Manageability for monitoring system resource
events of the directory. The container for this garbage collector is cn=sysresource events purgeconfig,
cn=purgeconfig,cn=subconfigsubentry.
■
Tombstone garbage collector: Cleans up obsolete entries marked as deleted in the directory. The container for this garbage collector is
cn=tombstone purgeconfig, cn=purgeconfig,cn=subconfigsubentry.
■
LDAP performance monitoring garbage collector: Cleans up LDAP server performance statistics data. The container for this garbage collector is cn=perf
stats purgeconfig,cn=purgeconfig,cn=subconfigsubentry.
■
LDAP bind performance monitoring garbage collector: Cleans up bind performance data gathered for security events tracking. The container for this
garbage collector is cn=bindsec stats purgeconfig,cn=purgeconfig, cn=subconfigsubentry.
■
LDAP compare performance monitoring garbage collector: Cleans up compare performance data gathered for security events tracking. The container for this
garbage collector is cn=comparesec stats purgeconfig, cn=purgeconfig,cn=subconfigsubentry.
■
LDAP compare failure performance monitoring garbage collector: Cleans up compare failure performance data gathered for security events tracking. The
container for this garbage collector is cn=comparefailure stats purgeconfig,cn=purgeconfig,cn=subconfigsubentry.
Oracle Internet Directory Statistics Collector You can set and manage these behaviors of the Oracle Internet Directory statistics collector:
■
The time it starts
■
How often it runs The Oracle Internet Directory statistics collector collects statistics about Oracle Internet
Directory. The container for this background database process is cn=oidstats_config,
cn=purgeconfig,cn=subconfigsubentry.
See Also:
■
Capabilities of Oracle Internet Directory Server Manageability on page 24-1
■
Oracle Internet Directory Configuration Schema Elements in Oracle Fusion Middleware Reference for Oracle Identity Management
Note: Oracle recommends that you not delete any of the predefined
garbage collectors. Deleting one or more of them can result in the proliferation of obsolete data, eventually exhausting all the available
disk space.
You may, however, modify predefined garbage collectors to customize their behavior.
35-4 Oracle Fusion Middleware Administrators Guide for Oracle Internet Directory
How Oracle Internet Directory Garbage Collection Works
Figure 35–1 shows an example of a garbage collector operation that purges change log
entries.
Figure 35–1 Example: Garbage Collection of Change Log Entries
As the example in Figure 35–1
on page 35-4 shows, the garbage collection process is as follows:
1. An LDAP client sends to the directory server a request for a particular garbage
collection operation. The operation could be, for example, to purge the entries of tombstone or, change logs.
2. The directory server passes the request to the garbage collection plug-in.
3. The garbage collection plug-in sends the request to the garbage collection engine
in the Oracle Internet Directory-designated database.
4. The garbage collection engine triggers the corresponding background database
process—in this case, the change log garbage collector. The background database process runs according to the parameters specified in its configuration.
Oracle Internet Directory Database 1
Directory Server
Garbage Collection
Plug-in Framework
Oracle Directory Server Instance
3 4
Garbage Collection
Engine Garbage Collector
Change Log Garbage Collector
General Statistics Garbage Collector
Health Statistics Garbage Collector
Security Refresh Events Garbage Collector
System Resource Events Garbage Collector
Tombstone Garbage Collector
Bind performance monitoring
Garbage Collector Compare performance
monitoring Garbage Collector
Compare failure performance monitoring
Statistics Collector
LDAP Client
2
Managing Garbage Collection 35-5
Garbage Collector Entries and the Oracle Internet Directory Statistics Collector Entry
Garbage collector entries, each with attributes specifying how it is to behave, are located in the entry cn=purgeconfig, which is located immediately below the entry
cn=subconfigsubentry.
The Oracle Internet Directory statistics collector entry, with its attributes, is also located in the entry cn=purgeconfig, immediately below the entry
cn=subconfigsubentry.
Figure 35–2 shows the location of these entries.
Figure 35–2 Garbage Collection Entries in the DIT
Change Log Purging
Both replication and Oracle Directory Integration Platform use change logs to propagate information from a supplier directory to a consumer directory. All change
logs are stored in the table ods_chg_log. In addition, replication change logs are stored in asr_chg_log. When the change log garbage collector runs, it purges change
logs that are no longer needed by any change log consumers. This prevents the change log store in the Oracle Internet Directory database from becoming too large.
The change log garbage collector uses the following two methods to determine which change logs to purge:
■
Change number-based purging Change number-based purging respects the change status of all change log
consumers. That is, it does not purge change logs unless they have been consumed by all consumers. When the change log garbage collector runs, it purges all change
logs that have been consumed by replication, Oracle Directory Integration Platform, and other consumers.
■
Time-based purging Time-based purging is a fall-back method designed to purge change logs of a
certain age. It ensures that old change logs are purged even if they have not been
See Also: Oracle Internet Directory Configuration Schema
Elements in Oracle Fusion Middleware Reference for Oracle Identity Management for a description of each garbage collector attribute
cn=purgeConfig cn=subconfigSubentry
Root
cn= healthStats PurgeConfig
cn= secRefresh Events PurgeConfig
cn= sysResource Events PurgeConfig
cn= tombstone PurgeConfig
cn= auditlog PurgeConfig
cn= oidstats_config
cn= changelog PurgeConfig
cn= generalStats PurgeConfig
cn= comparefailure stats PurgeConfig
cn= comparesec stats PurgeConfig
cn= bindsec stats PurgeConfig
cn= perf stats PurgeConfig
35-6 Oracle Fusion Middleware Administrators Guide for Oracle Internet Directory
consumed by all change log subscribers. Time-based purging respects the change status of replication, but not the change status of other consumers. The change log
garbage collector purges all change logs that are not needed by replication and that are at least orclpurgetargetage hours old. If orclpurgetargetage is
zero, the change log garbage collector does this immediately. If orclpurgetargetage is an invalid number or not defined, the default value is
240 hours 10 days. Change logs needed by replication are not purged until they have been consumed by replication.
If you have deployed Oracle Directory Integration Platform, and you want to enable time-based purging, be sure to set orclpurgetargetage to a large
enough value to allow change logs to be processed by Oracle Directory Integration Platform before they are purged. A value of 240 allows 10 days before change logs
are purged.
See Configuring Time-Based Change Log Purging
on page 35-9.
Set Oracle Database Time Zone for Garbage Collection
To ensure that the Oracle Internet Directory garbage collection logic works correctly, you must set the Oracle Database dbtimezone parameter to the appropriate
displacement from Coordinated Universal Time UTC. Proceed as follows:
1.
Invoke PLSQL: sqlplus nolog
SQL connect as sysdba
2.
Perform a query to get the value of dbtimezone: SQL select dbtimezone from dual;
3.
Perform a query to get the displacement from Coordinated Universal Time UTC: SQL select systimestamp from dual;
The output will look similar to this: SYSTIMESTAMP
--------------------------------------- 31-JAN-09 01.04.42.281000 PM -05:00
Get the last column of the systimestamp output. In the example, it is -05:00.
4.
If the dbtimezone parameter is equal to last column value of the systimestamp output, you do not need to perform the remaining steps. Otherwise, proceed to
Step 5.
5.
Stop all instances of Oracle Internet Directory that are using the Oracle Database, as described in
Chapter 8, Managing Oracle Internet Directory Instances.
6.
Set the dbtimezone parameter, using the value you got from the last column the systimestamp query:
SQL ALTER DATABASE SET TIME_ZONE = -05:00;
7.
Shut down the Oracle Database: SQL shutdown immediate
8.
Restart the Oracle Database: SQL startup
Managing Garbage Collection 35-7
9.
Restart Oracle Internet Directory as described in Chapter 8, Managing Oracle
Internet Directory Instances.
Modifying Oracle Internet Directory Garbage Collectors
This section contains these topics:
■
Modifying a Garbage Collector by Using Oracle Directory Services Manager
■
Modifying a Garbage Collector by Using Command-Line Tools
■
Modifying the Oracle Internet Directory Statistics Collector
Modifying a Garbage Collector by Using Oracle Directory Services Manager
To modify a garbage collector:
1. Invoke Oracle Directory Services Manager and connect to the Oracle Internet
Directory server as described in Invoking Oracle Directory Services Manager
on page 7-9.
2. From the task selection bar, select Advanced.
3. Expand Garbage Collection in the left pane, then select the garbage collector you
want to modify. The Garbage Collector Window appears in the right pane.
4. In the Garbage Collector window, enter the changes you want to make for this
garbage collector.
5. Choose Apply.
Modifying a Garbage Collector by Using Command-Line Tools
This section provides examples of how to modify garbage collectors by using command-line tools. The garbage collection attributes that you can modify are listed in
Oracle Internet Directory Configuration Schema Elements in Oracle Fusion Middleware Reference for Oracle Identity Management.
Example 1: Modifying a Garbage Collector
Suppose that you want the tombstone garbage collector to run immediately. The LDIF would look like this:
dn: cn=tombstone purgeconfig, cn=purge config, cn=subconfigsubentry changetype:modify
replace: orclpurgenow orclpurgenow: 1
Load this entry with ldapmodify. ldapmodify -D cn=orcladmin -q -h hostname -p port \
-D username -f file_name_of_defined_entry
Example 2: Disabling a Garbage Collector Change Log
Suppose that you want to disable changelog garbage collector.
See Also: Oracle OLAP DML Reference for more information about
the dbtimezone parameter.
35-8 Oracle Fusion Middleware Administrators Guide for Oracle Internet Directory
dn: cn=changelog purgeconfig, cn=purgeconfig, cn=subconfigsubentry changetype: modify
replace: orclpurgeenable orclpurgeenable: 0
Load this entry with ldapmodify. ldapmodify -D cn=orcladmin -q -h hostname -p port \
-D username -f file_name_of_defined_entry
Modifying the Oracle Internet Directory Statistics Collector
You modify the Oracle Internet Directory statistics collector in the same way as the garbage collectors, but there are only three modifiable fields.
Managing Logging for Oracle Internet Directory Garbage Collectors
This section contains these topics:
■
Enabling Logging for Oracle Internet Directory Garbage Collectors
■
Disabling Logging for Oracle Internet Directory Garbage Collectors
■
Monitoring Garbage Collection Logging
Enabling Logging for Oracle Internet Directory Garbage Collectors
If you enable logging for garbage collectors, then the directory server writes the information into a file in the file system. This information includes:
■
The job identifier
■
A job description of the garbage collector
■
The number of entries purged
■
The operation status
■
The time stamp
■
Any errors caught To enable logging of garbage collection information:
1.
Set the orclpurgedebug attribute to 1if needed. When orclpurgedebug is set to 1, extra debugging detail information is logged. This is useful for troubleshooting
garbage collection problems.
2.
Set the orclpurgefilename attribute to a valid file name for the log file, for example: oidgc001.log.
3.
Set the orclpurgefileloc attribute to the path name of the directory in which the log file is located, for example: privateqzhouoracleldaplog.
4.
Enable PLSQL IO access to the directory specified in step 3. To do this, include the following in the database:
UTL_FILE_DIR=PATH_NAME where PATH_NAME is the path you specified in Step 3.
See Also: The section on the UTL_FILE_DIR parameter type in
the Oracle Database Reference
Managing Garbage Collection 35-9
5.
Shut down the replication server, then the Oracle Internet Directory server.
6.
Restart the database.
7.
Start the Oracle Internet Directory server, then the replication server.
Disabling Logging for Oracle Internet Directory Garbage Collectors
To disable logging of garbage collection information, set the orclpurgedebug attribute to 0.
Monitoring Garbage Collection Logging
The information in the garbage collection log can be useful for monitoring and troubleshooting garbage collection. You determine the location of the log by setting
attributes when enabling logging. For example, if you configured:
orclpurgefilename = oidgc001.log orclpurgefileloc = privateqzhouoracleldaplog
when you enabled logging, then you can monitor change log garbage collection activities by reading the file
privateqzhouoracleldaplogoidgc001.log.
The following is an example of the information logged when an administrator modified the orclpurgenow attribute of the change log garbage collection
configuration entry:
Running Garbage Collector: cn=changelog purgeconfig Starting time: 20050324 11:03:23
PurgeConfig object located, Eid= 936 purge_ODSChglog: Nothing to be purgedno_work_to_do
purge_ODSChglog: 107 chglogs successfully purged purge_ASRChglog: Nothing to be purgedno_work_to_do
purge_ASRChglog: 0 chglogs successfully purged purge_ASRChglog: 0 chglogs successfully purged
Modifying Garbage Collector for at 20050324 11:03:23 Garbage Collector DN recognized, rdn=cn=changelog purgeconfig
orclPurgeNow successfully retrieved. Garbage Collector job found: jobno=21
Garbage Collector has been run Garbage collector is updated successfully
Modifying orclpurgenow forces the change log garbage collector to run immediately. As shown in the first paragraph, 107 change logs were purged from the ods_chg_log
table and 0 change logs were purged from the asr_chg_log table. Also, the information in the second paragraph indicates successful modification of
orclpurgenow attribute.
Configuring Time-Based Change Log Purging
Change log purging was described in Change Log Purging
on page 35-5. You configure time-based purging by modifying the orclpurgetargetage attribute of
Note: Even when orclpurgedebug is set to 0, minimal information
about garbage collector operation is still logged to indicate the garbage collectors acitivites.
35-10 Oracle Fusion Middleware Administrators Guide for Oracle Internet Directory
the changelog purging configuration entry. This example configures time-based purging for 120 hours 5 days. Use an LDIF file similar to this:
dn: cn=changelog purgeconfig,cn=purgeconfig,cn=subconfigsubentry changetype:modify
replace: orclpurgetargetage orclpurgetargetage: 120
To apply the ldif file mod.ldif, type: ldapmodify -D cn=orcladmin -q -p port -h host -D dn -q -f mod.ldif
Note: The container for the change log garbage collector is
cn=changelog purgeconfig, cn=purgeconfig,cn=subconfigsubentry.
See Also: Oracle Internet Directory Configuration Schema
Elements in Oracle Fusion Middleware Reference for Oracle Identity Management
