Operation

This chapter describes how to operate DirX Directory in the CSP environment, including how to:

  • Administer DSA and LDAP server auditing

  • Use SNMP traps

  • Check database consistency

  • Back up the database

  • Manage DirX Directory patches

Managing Auditing

The DirX Directory DSA and LDAP server processes can be configured to write audit trails containing all key arguments of each protocol operation.The audit files are written in binary format and should be evaluated before archiving them.

In the context of a CSP, the analysis of audits can help to detect issues like performance problems or security breaches.As a result, we recommend enabling the audit feature for both processes with the maximum degree of detail.

This section describes how to enable DSA and LDAP server audit and how to process them for archiving.

Enabling DSA Audit

The following dirxadm command enables the DSA’s audit facility.After writing 50,000 records in the current audit trail file, the file is moved by appending a timestamp to its filename.The audit detail is set to the maximum the level attrval (attributes and values are recorded).The settings are made persistent in the DirX Directory database so that after a process restart, audit writing is continued:

dirxadm> audit modify -status on -level attrval -overflow move

Enabling LDAP Audit

The following dirxcp command creates a new LDAP audit subentry that stores the audit settings for the LDAP server persistently in the DirX Directory database. After a process restart, audit writing is continued:

dirxcp> create CN=CommonldapAudit,O=My-Company \
    –attr {objectClass=ldapAudit;subentry} \
    {subtreeSpecification;binary=MIAAAA==} \
    ldapAuditOn=TRUE ldapAuditSizeLimit=100000 \
    ldapAuditOverFlow=moveFile ldapAuditLevel=max \
    ldapAuditValueLimit=256 ldapAuditOpSelection=all \
    ldapAuditEncryption=none

This LDAP audit subentry is relevant for the entire subtree due to its subtreeSpecification attribute.

The subentry configures the LDAP audit facility to move the file after writing 100,000 audit records with the maximum degree of detail.All LDAP operations are subject to auditing.The attribute values from the LDAP requests are written up to the first 256 characters, which is sufficient because the certificates and CRLs are handled as binary attributes in LDAP and thus cannot be written in clear text in the audit records.

Archiving Audit Files

The DirX Directory server processes write audit records in a binary format into the audit files.These files need to be processed off-line using dirxauddecode command.Note that the binary format of the audit files may change with a new DirX Directory version.It is therefore necessary to archive the processed audit file rather than the binary-formatted files.

The dirxauddecode command supports a number of options to filter the output.

As a preferable choice for the LDAP audits, dirxauddecode can be used to produce a comma-separated list of values for each audit record, which makes the audit records easy to parse by programs.Use the LDAP audit configuration file to configure the type of the values reported for a single operation.The dirxauddecode command uses this configuration file to customize the output file when evaluating LDAP audit log files.

Using SNMP Traps

All DirX Directory server processes and the watchdog process can be configured to send out SNMPv2 traps.According to the SNMP specification, the traps are transmitted using UDP/IP and can be trapped by a trap receiver application which is by default listening on port 162. An environment variable controls whether or not SNMP traps are enabled.The different types of traps can be configured individually in a configuration file.

DirX Directory can generate about 40 different traps that can be categorized as follows:

  1. Traps that indicate normal state change of the service; for example, starting a process, completing the DBAM cache preload phase and so on.

  2. Traps that indicate security-relevant issues; for example, password policy-driven account locking due to multiple incorrect password inputs.

  3. Traps that indicate a critical operation status; for example, resource shortage, operation response times exceeding a configurable threshold or unexpected restarts of processes.

In the context of a CSP operation, we recommend activating at least the SNMP trap facility for categories 2 and 3. The install_path/conf/snmptraps.cfg configuration file is a template for SNMP settings, with all traps commented out. The following sections provide a short discussion of the traps and the trap parameters that a CSP can use.

The DirX Directory SNMP trap facility must generally be enabled by exporting the environment variable

DIRX_SNMP=1

in the configuration file:

install_path/conf/dirxenv.ini.

Security-related Traps

trap   dirxUnauthorizedAdminAccess     0      0

This trap is sent each time a user tries to bind with the administrative client application dirxadm without being configured as the administrator in the dirxAdminstrators (DADM) attribute of the root DSE.

trap   dirxAccountLocked               0      0

This trap is sent each time a user account is locked due to the password policy settings. In the example above, this is the case if a user sends an incorrect password in the bind operation three times within two minutes. (See section 3.3.4 " Configuring Password Policy" for information about password policy settings.) The administrator must unlock such a user account explicitly.

trap   dirxDsaBindProblem              0      0

This trap is sent each time a DSA-to-DSA bind operation (DSP or DISP) fails. This may be the case because of a configuration error (individual passwords of DSAs do not match in the respective DSA policy attributes of the root DSEs) or because the host clocks are not synchronous.

trap   dirxPduDecodeError              0      0

This trap is sent each time the DirX Directory servers cannot decode an operation request. This may be the case because a client application intentionally sends invalid PDUs. In the context of CSP operation, it may result from the attempt to load invalid encoded userCertificates.

Critical State-related Traps

trap  dirxServiceStartFailure#     0   0

This trap is sent if the DirX Directory watchdog process is unable to start the service processes. This is a fatal situation. Further investigation in the DirX Directory exception files and the system log files is required.

trap  dirxProcessCrash        0   0

This trap is sent if the DirX Directory watchdog detects the crash of one of its supervised server processes. Although the crashed process is restarted automatically, multiple occurrences of such traps need further investigation in the DirX Directory exception files.

dirxThreadLimitReached         5   60

This trap is sent—at most five times within one minute—if one of the DirX Directory processes exceeds its configured thread limit. The DSA rejects all subsequent protocol operations. Multiple occurrences of such traps need further investigation in the DirX Directory exception files.

trap   dirxThreadPoolExhausted         1        1

This trap is sent—at most once per second—if the DirX Directory LDAP server process has no more free operation threads that are able to perform an operation. In this case, the operation is queued in the operation stack. Although the ThreadPoolSize can be increased in the LDAP configuration subentry, multiple occurrences of such traps need further investigation in the DirX Directory exception files.

trap   dirxOpStackLimitReached         1      1

This trap is sent—at most once per second—if the operation stack of the DirX Directory LDAP server process has no more free slots to queue an incoming LDAP operation. In this case, the LDAP operation is rejected with the error code “server reject”. Multiple occurrences of such traps need further investigation in the DirX Directory exception files.

trap   dirxCtxLimitExceeded            5      60
trap   dirxCtxULimitExceeded           5      60

These traps are sent—at most five times per minute—if the configured maximum main memory assigned to one operation (CtxLimit) or to all operations (CtxULimit) is exhausted. Possible reasons include search results that are too large or too many in-parallel paged search operations that are not completed by the client application in time. Although the respective limits can be increased by increasing the values of specific environment variables, multiple occurrences of such traps need further investigation in the DirX Directory exception files.

trap   dirxDispAgreementDisabled       0      0
trap   dirxDispAgreementTerminated     0      0

These traps are sent every time the DirX Directory DSA disables or terminates a shadowing agreement due to some internal problem. The problem is described in more detail in the DSA exception file. A disabled shadowing agreement may be enabled manually after resolving the problem. A terminated shadowing agreement must be re-established.

trap        dirxOpTimeWatch                 0      0
trapparam   dirxLdapOpTimeWatchDuration            20
trapparam   dirxLdapOpTimeWatchFreq                3

This trap provides a monitoring of the LDAP operation runtime. In this example, the trap is initiated if an active LDAP operation has been running for longer than 20 seconds. The trap handler checks for such operations every three seconds. Such long-running operations may be observed due to missing attribute indexes. Check the LDAP audit files for the attribute index settings and the long-running operations.

trap   dirxDBAMDeviceNearLimit         1      60

This trap is sent—at most once per minute—if any of the DBAM devices exceeds a ratio of more than 90%.If the database has not already exceeded its final size, a re-sizing of the DBAM devices using the dbamconfig command is required.This step involves a save and restore of the database.

trap   dirxDBAMAvidxNearClusterLimit   1   60

This trap is sent—at most once per minute—if the attribute indexes require more than 90% of the available index cluster space in the DBAM device.Either an attribute index reorganization (using the dirxadm db attrconfig -build operation) or resizing of the DBAM devices (using the dbamconfig command) is required.

Checking Database Consistency

You can use the dbamverify command-line tool on a regular basis to check the consistency of the DirX Directory DBAM database.The dbamverify command can check:

  • The referential integrity of all attribute value blocks and tree blocks

  • The consistency of all directory-specific entries (DSEs)—each DSE is read in the context of this check and is verified with respect to DBAM level consistency, linkage of the entry in the tree, and ASN.1 encoding, schema and index consistency of its attributes

  • Attribute value index bit strings

  • Subordinate index bit strings

Specifying no option directs dbamverify to perform all consistency tests.The command returns an exit code of 0 on success or a 1 if it encountered an error.The text of the error message is displayed on stderr.

Because dbamverify locks the database for update operations while it runs, we recommend that you take a backup of the database with dirxbackup and then run dbamverify on this archive off-line.The section “Managing Backups” provides an example of this approach.

For details on dbamverify and dirxbackup command-line syntax, see the Administration Reference.

Managing Backups

Saving backups of the directory’s database is one of the most important tasks of CSP operation.

You must use the dirxbackup command to save and restore a database or verify the consistency of a database archive that you created with dirxbackup.Saving a directory database does NOT require setting the directory in read-only mode, so it does not interfere with normal CSP operation.

The dirxbackup command supports both full and delta backups.To restore a saved database, first restore the full backup archive and then restore all delta backups in the correct sequence.For details on dirxbackup command-line syntax, see the Administration Reference.

Do not use a non-DirX backup tool to save DBAM database files or devices.It can produce inconsistencies in the database and / or in the dirxbackup archive file.

Here is a sample backup and database consistency-checking scenario that can be used in the context of CSP operations:

  • Create a full backup every 24 hours—for example, at 12:00 pm—by creating a scheduled job that performs the following dirxbackup command:

dirxbackup –S dirxDB.date_Time

  • Create delta backups every n hours; for example, every four hours. The actual frequency of delta backups depends on your requirements. To achieve this, create a scheduled job that performs the following dirxbackup command:

dirxbackup –Sd dirxDB.date_Time.delta.number

  • Check the archives for internal integrity and completeness by performing:

dirxbackup –T dirxDB.date_Time dirxDB.date_Time.number

  • If the checks on the archives perform successfully, perform the DBAM database consistency check on the archives with the dbamverify command. Specify the full backup archive first, followed by the delta backup archives in sequence, for example:

dbamverify dirxDB.date_Time dirxDB.date_Time.1 \
    dirxDB.date_Time.2 …

Managing Patches

The operators responsible for the CSP service must ensure that the productive directory service always uses the latest released patch of the DirX Directory software.