Managing Garbage Collection

37.1 Understanding Garbage Collection Management

A garbage collector is a background database process that removes unwanted data from the directory.

The Oracle Internet Directory garbage collection framework provides a default set of garbage collectors, and enables you to modify them. The Oracle Internet Directory statistics collector also uses the Oracle Internet Directory garbage collection framework.

This introduction contains these topics:

37.1.1 Understanding the Components of the Garbage Collection Framework

The following topics describe the components that make up the Oracle Internet Directory garbage collection framework, namely, the garbage collection plug-in and the background database processes.

37.1.1.1 About Garbage Collection Plug-in

Garbage collection in Oracle Internet Directory relies on a garbage collection plug-in that receives requests to manage garbage collectors. This plug-in is installed with 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.

See Also:

Oracle Internet Directory Configuration Schema Elements in Reference for Oracle Identity Management for a list and descriptions of the attributes of the garbage collection plug-in

37.1.1.2 Understanding the Background Database Processes

The following topics describe the background database processes that are invoked by the garbage collection plug-in, which include the garbage collectors and the Oracle Internet Directory statistics collector:

37.1.1.2.1 About 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

37.1.1.2.2 About 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.
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.

37.1.1.2.3 About 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.

37.1.2 How Oracle Internet Directory Garbage Collection Works

This section depicts an example of a garbage collector operation that purges change log entries.

Figure 37-1 shows an example of a garbage collector operation that purges change log entries.

Figure 37-1 Example: Garbage Collection of Change Log Entries

This illustration is described in the text.

As the example in Figure 37-1 shows, the garbage collection process is as follows:

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.
The directory server passes the request to the garbage collection plug-in.
The garbage collection plug-in sends the request to the garbage collection engine in the Oracle Internet Directory-designated database.
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.

37.1.3 About Garbage Collector Entries and 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.

37.1.4 Overview of 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 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.

37.2 Setting 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).

Perform the following steps:

Invoke PL/SQL:

$ sqlplus /nolog   
SQL> connect / as sysdba

Perform a query to get the value of dbtimezone:
```
SQL> select dbtimezone from dual;
```
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.
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.
Stop all instances of Oracle Internet Directory that are using the Oracle Database, as described in Managing Oracle Internet Directory Instances.
Set the dbtimezone parameter, using the value you got from the last column the systimestamp query:
```
SQL> ALTER DATABASE SET TIME_ZONE = '-05:00'; 
```
Shut down the Oracle Database:
```
SQL> shutdown immediate
```
Restart the Oracle Database:
```
SQL> startup
```
Restart Oracle Internet Directory as described in Managing Oracle Internet Directory Instances.

Note:

Oracle OLAP DML Reference for more information about the dbtimezone parameter.

37.3 Modifying the Oracle Internet Directory Garbage Collectors

The following topics describe how to modify the Oracle Internet Directory Garbage collector and the Oracle Internet Directory Statistics Collector:

This section has the following topics:

37.3.1 Modifying a Garbage Collector by Using Oracle Directory Services Manager

Using Oracle Directory Services Manager, you can modify a garbage collector.

To modify a garbage collector:

Invoke Oracle Directory Services Manager and connect to the Oracle Internet Directory server as described in Invoking Oracle Directory Services Manager.
From the task selection bar, select Advanced.
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.
In the Garbage Collector window, enter the changes you want to make for this garbage collector.
Choose Apply.

37.3.2 Modifying a Garbage Collector by Using Command-Line Tools

Using examples understand how to modify garbage collectors by using command-line tools.

This section contains the following topics:

The garbage collection attributes that you can modify are listed in Oracle Internet Directory Configuration Schema Elements in Reference for Oracle Identity Management.

37.3.2.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=purgeconfig, 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

37.3.2.2 Disabling a Garbage Collector Change Log

Suppose that you want to disable changelog garbage collector.

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

37.3.3 Modifying the Oracle Internet Directory Statistics Collector

You modify 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.

37.4 Managing Oracle Internet Directory Garbage Collectors Logging

The following topics describe how to enable, disable and monitor the Oracle Internet Directory Garbage Collectors logging:

This section has the following topics:

37.4.1 Enabling the Oracle Internet Directory Garbage Collectors Logging

If you enable logging for garbage collectors, then the directory server writes the information into a file in the file system.

The information that are written to file 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:

Set the orclpurgedebug attribute to 1, if needed. When orclpurgedebug is set to 1, extra debugging detail information is logged, which can be useful for troubleshooting garbage collection problems.
Set the orclpurgefilename attribute to a valid file name for the log file, for example: oidgc001.log.
Set the orclpurgefileloc attribute to the path name of the directory in which the log file is located, for example: /private/mydir/oracle/ldap/log.
Enable PL/SQL I/O access to the directory specified earlier. To do this, include the following in the database:
```
UTL_FILE_DIR=PATH_NAME
```
where PATH_NAME is the path you specified earlier.

See Also:

The section on the UTL_FILE_DIR parameter type in the Oracle Database Reference
Shut down the replication server, then the Oracle Internet Directory server.
Restart the database.
Start the Oracle Internet Directory server, then the replication server.

37.4.2 Disabling the Oracle Internet Directory Garbage Collectors Logging

To disable logging of garbage collection information, set the orclpurgedebug attribute to 0.

Note:

Even when orclpurgedebug is set to 0, minimal information about garbage collector operation is still logged to indicate the garbage collector's acitivites.

37.4.3 Monitoring the Oracle Internet Directory 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     = /private/mydir/oracle/ldap/log

when you enabled logging, then you can monitor change log garbage collection activities by reading the file /private/mydir/oracle/ldap/log/oidgc001.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: 2005/03/24 11:03:23
PurgeConfig object located, Eid= 936
purge_ODSChglog: Nothing to be purged(no_work_to_do)
purge_ODSChglog: 107 chglogs successfully purged
purge_ASRChglog: Nothing to be purged(no_work_to_do)
purge_ASRChglog: 0 chglogs successfully purged
purge_ASRChglog: 0 chglogs successfully purged

Modifying Garbage Collector for at "2005/03/24 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.

37.5 Configuring Time-Based Change Log Purging

You can configure time-based purging by modifying the orclpurgetargetage attribute of the changelog purging configuration entry.

Change log purging was described in Overview of Change Log Purging. 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 -f mod.ldif

Note:

The container for the change log garbage collector is cn=changelog purgeconfig, cn=purgeconfig,cn=subconfigsubentry.