Instances of the Purge Expired Data Plugin use a dedicated background thread within the Directory Server to periodically search for and then delete expired entries or JSON attribute values. This provides an automatic way to remove expired data, but since there is some delay between the data expiration and it being removed from the server, clients must still check to see if the data they receive in search results is still considered valid.
Data that should be deleted is identified by the datetime-attribute property and optionally the datetime-json-field property. The values stored in the attribute or field can either represent an expiration time or a creation time with the expiration-offset property defining how long before the data expires.
This plugin exposes an entry under "cn=Purge Expired Data Plugin: {PLUGIN NAME},cn=monitor" with an objectclass of ds-purge-expired-data-plugin-monitor-entry.
The following Purge Expired Data Plugin are available in the server :
These Purge Expired Data Plugin inherit from the properties described below.
The Purge Expired Data Plugin component inherits from the Plugin
The properties supported by this managed object are as follows:
| Description | A description for this Plugin |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the plug-in is enabled for use. |
| Default Value | None |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | The LDAP attribute that determines when data should be deleted. This could store the expiration time, or it could store the creation time and the expiration-offset property specifies the duration before data is deleted. If datetime-attribute stores only a date value (i.e., it is not a JSON attribute), then this attribute must be indexed for "ordering" to allow efficient searches. If the expiration is tracked in a JSON field within this attribute, the datetime-json-field property must be set, and the server must be configured with a JSON Attribute Constraint for this attribute along with a JSON Field Constraint for the configured datetime-json-field with index-values=true. |
| Default Value | None |
| Allowed Values | The name or OID of an attribute type defined in the server schema. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | The top-level JSON field within the configured datetime-attribute that determines when data should be deleted. This could store the expiration time, or it could store the creation time and the expiration-offset property specifies the duration before data is deleted. The server must be configured with a JSON Attribute Constraint for the datetime-attribute along with a JSON Field Constraint for the datetime-json-field, which includes index-values=true to allow efficient searches. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the format of the datetime stored within the entry that determines when data should be purged. |
| Default Value | generalized-time |
| Allowed Values | generalized-time - The datetime value is specified in Generalized Time format (e.g., 20071217170000Z). This is the standard time format within LDAP, and is used by attributes such as createTimestamp. Attributes configured with generalizedTimeOrderingMatch can be stored with any time zone offset. For dates stored in attributes with a string matching rule or stored in JSON fields, the time zone must be UTC. java-system-time-millis - The datetime value is consistent with what is returned by java.lang.System.currentTimeMillis(). custom - The format of the datetime value is specified using the custom-datetime-format field. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | When the datetime-format property is configured with a value of "custom", this specifies the format (using a string compatible with the java.text.SimpleDateFormat class) that will be used to search for expired data. Since the plugin uses range searches to search for expired data, the lexicographical ordering of two formatted date values must be consistent with their actual order. For instance, the ISO 8601 format, "yyyy-MM-dd'T'HH:mm:ssZ", meets this requirement, but a format that puts the day of the month first, "dd/MM/yyyy HH:mm:ssZ", does not. |
| Default Value | None |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the time zone to use when generating a date string using the configured custom-datetime-format value. The provided value must be accepted by java.util.TimeZone.getTimeZone. |
| Default Value | GMT |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | The duration to wait after the value specified in datetime-attribute (and optionally datetime-json-field) before purging the data. For example, if the configured datetime-attribute stores an expiration time, then specifying a value here of "5m" will purge the data at the next polling interval that occurs five minutes after the data expires. If the configured datetime-attribute stores a creation time (e.g., createTimestamp), then expiration-offset should store the duration of time before the data should be purged. |
| Default Value | None |
| Allowed Values | A duration. Lower limit is 0 milliseconds. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies whether to delete expired entries or attribute values. By default entries are deleted. |
| Default Value | None |
| Allowed Values | delete-entries - Matched entries are expired and should be deleted. A subtree where all entries are expired will be deleted. However, expired entries will not be deleted if there are any non-expired entries beneath them in the LDAP hierarchy. subtree-delete-entries - Matched entries and the subtrees beneath them in the LDAP hierarchy are expired and should be deleted. Subtrees must be smaller than the configured value of subtree-delete-size-limit on the Local DB Backend, which has a default of 5000. delete-json-attribute-values - Only matched attribute values are expired and should be deleted. This only applies to attributes with the JSONObject syntax and requires that datetime-json-field is also configured. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Only entries located within the subtree specified by this base DN are eligible for purging. In servers configured with multiple Local DB Backends and only one backend with data that should be purged, this property can be set to reduce what data is searched. This can make the plugin execute more efficiently, and it reduces the indexing requirements in the other backends. |
| Default Value | Entries in all Local DB Backends are eligible for purging. |
| Allowed Values | A valid DN. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Only entries that match this LDAP filter will be eligible for having data purged. By default this plugin searches for entries with expired data based only on the datetime-attribute and datetime-json-field if one is specified. However, setting this filter property can restrict that to only a subset of entries. For example, if OAuth token entries should be deleted one day after they were created, then this plugin could be configured with datetime-attribute=createTimestamp, expiration-offset=1d, and filter=(objectclass=oauthToken). |
| Default Value | Entries of all types are eligible for purging. |
| Allowed Values | A valid LDAP search filter |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | This specifies how often the plugin should check for expired data. It also controls the offset of peer servers (see the peer-server-priority-index for more information). When the filter property is configured so that only certain entries are purged, then the search to find expired data might be expensive because many entries might match the datetime-attribute (e.g., createTimestamp) portion of the search filter. In this situation, configuring a larger polling interval here can reduce the overall impact on the server. |
| Default Value | 5m |
| Allowed Values | A duration. Lower limit is 1000 milliseconds. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | This setting smooths out the performance impact on the server by throttling the purging to the specified maximum number of updates per second. To avoid a large backlog, this value should be set comfortably above the average rate that expired data is generated. When purge-behavior is set to subtree-delete-entries, then deletion of the entire subtree is considered a single update for the purposes of throttling. |
| Default Value | 100 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | The number of threads used to delete expired entries. By default, expired entries will be deleted in a single thread, and this is the recommended configuration for most deployments. However, multiple threads may be needed if expired entries accumulate faster than a single thread can delete them. |
| Default Value | 1 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
peer-server-priority-index (Advanced Property)
| Description | In a replicated environment, this determines the order in which peer servers should attempt to purge data. In replicated environments, this plugin should be configured on multiple servers to provide a highly-available configuration. That is, if one server is offline, then the data will still be purged by another server. However, having multiple servers purging data at the same time leads to increased replication overhead and warnings about missing entries that could not be deleted. To avoid concurrent purging, the plugins will automatically determine their relative order based on their replication server IDs. A server with a higher priority index will wait at least one polling-interval more than a server with a lower priority index before attempting to purge data, giving the other server a chance to delete data first. However, the relative priority of servers can be controlled by setting this property. Setting the value to 1 will cause the instance of this plugin running on the local server to wait one additional polling-interval before attempting to purge data, setting it to 2 will cause it to wait two additional polling-intervals, etc. Unique values should be chosen for all servers, but this is not enforced. |
| Default Value | Peer servers will automatically determine their relative priority. |
| Allowed Values | An integer value. Lower limit is 0. Upper limit is 1000 . |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured Plugins:
dsconfig list-plugins
[--property {propertyName}] ...
To view the configuration for an existing Plugin:
dsconfig get-plugin-prop
--plugin-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing Plugin:
dsconfig set-plugin-prop
--plugin-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new Purge Expired Data Plugin:
dsconfig create-plugin
--plugin-name {name}
--type purge-expired-data
--set enabled:{propertyValue}
--set datetime-attribute:{propertyValue}
--set expiration-offset:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Plugin:
dsconfig delete-plugin
--plugin-name {name}