Configuring Alerts and Account Status Notification Handlers

Oracle Unified Directory provides mechanisms for transmitting alert and account status notifications by means of JMX extensions or SMTP extensions. You can configure the directory server to send alert notifications when an event occurs during processing. Typical server events include server starts and shut downs, or problems that are detected by the server, such as an attempt to write to the configuration file.

You can also receive account status notifications when an event occurs during password policy processing, such as when accounts are locked out, accounts expire, passwords expire, and so on.

Alerts and account status notification handlers are configured by using the dsconfig command. For more information, see Managing the Server Configuration With dsconfig.

For additional information about the topics in this section, see Chapter 11, Managing Password Policies and The Alert Handler Configuration.

Managing Alert Handlers

Oracle Unified Directory supports the following alert handlers:

• JMX alert handler for JMX notifications

• SMTP alert handler for email notifications.

• Custom alert handlers

To View All Configured Alert Handlers

Oracle Unified Directory stores alert handlers information in the configuration file under the cn=Alert Handlers,cn=config subtree. You can access the information using the dsconfig command.

• To display a list of alert handlers, run the following dsconfig command:

  $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
   list-alert-handlers
  
  Alert Handler     : Type : enabled
  ------------------:------:--------
  JMX Alert Handler : jmx  : false

To Enable an Alert Handler

The JMX alert handler is disabled by default. Before you begin, you must configure JMX on the server. For more information, see Monitoring the Server With JConsole.

1. To list the alert handler's properties, use the dsconfig command as follows.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     get-alert-handler-prop \
     --handler-name "JMX Alert Handler"
   
   Property            : Value(s)
   --------------------:---------------------------------------------
   disabled-alert-type : -
   enabled             : false
   enabled-alert-type  : -

2. To enable the alert handler, use dsconfig as follows.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     set-alert-handler-prop \
     --handler-name "JMX Alert Handler" --set enabled:true

3. (Optional) Verify the change by using dsconfig.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     get-alert-handler-prop \
     --handler-name "JMX Alert Handler"
   
   Property            : Value(s)
   --------------------:---------------------------------------------
   disabled-alert-type : -
   enabled             : true
   enabled-alert-type  : -

To Configure an Alert Handler

You can create a new alert handler by using dsconfig. This example configures a new SMTP handler. Before starting this procedure, ensure that you have configured an SMTP server for your server.

1. To create an alert handler run dsconfig with the create-alert-handler subcommand.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     create-alert-handler \
     --handler-name "my SMTP Handler" --type smtp --set enabled:true \
     --set message-body:"Alert Type: %%alert-type%%\n\nAlert ID: \
     %%alert-id%%\n\nAlert Message: %%alert-message%%" \
     --set message-subject:"Alert Message" \
     --set recipient-address:directorymanager@example.com \
     --set sender-address:OUD-Alerts@directory.example.com

2. (Optional) View the list of alert handlers by using dsconfig.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
    list-alert-handlers

Supported Alert Types

The server sends out message alerts when an alert type event occurs in the system. The supported alert types are defined in the following table.

To Delete an Alert Handler

The following example removes an alert handler from the directory server.

• To delete an alert handler use the following dsconfig command.

  $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
    delete-alert-handler \
    --handler-name "JMX Alert Handler"

To Disable an Alert Type

By default, all alert types are allowed. If you specify a value for the enabled-alert-type property, only alerts with one of those types are allowed. If you specify a value for the disabled-alert-type property, all alert types except for the values in that property are allowed. Alert types are specified by their Java class, as shown in this example.

• To disable an alert type, specify its Java class as a value of the disabled-alert-type property.

  This command disables the startup alert from the JMX Alert Handler.

  $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
    set-alert-handler-prop \
    --handler-name "JMX Alert Handler" \
    --set disabled-alert-type:org.opends.server.DirectoryServerStarted

Managing Account Status Notification Handlers

Account status notification handlers provide alerts on events during password policy processing. By default, the Error Log Account Status Notification handler is set to enabled upon initial configuration. The server writes a message to the server error log when one of the following events has been configured in the password policy and occurs during the course of password policy processing:

• account-temporarily-locked

• account-permanently-locked

• account-unlocked

• account-idle-locked

• account-reset-locked

• account-disabled

• account-expired

• password-expired

• password expiring

• password-reset

• password-changed

The error log is located at install-dir/logs/errors.

To View the Configured Account Status Notification Handlers

• Use dsconfig with the list-account-status-notification-handlers subcommand.

  $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
    list-account-status-notification-handlers
  
  Account Status Notification Handler : Type      : enabled
  ------------------------------------:-----------:--------
  Error Log Handler                   : error-log : true
  SMTP Handler                        : smtp      : false

To Enable Account Status Notification Handlers

You can enable an existing account status notification handler using the dsconfig command. By default, the directory server enables the Error Log Handler when the server is initially configured. This example enables the SMTP notification handler.

1. To view the enabled property use dsconfig with the get-account-status-notification-handler-prop subcommand.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     get-account-status-notification-handler-prop --handler-name "SMTP Handler" \
   --property enabled
   
   Property : Value(s)
   ---------:---------
   enabled  : false

2. To enable the notification handler use dsconfig with the set-account-status-notification-handler-prop subcommand.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     set-account-status-notification-handler-prop --handler-name "SMTP Handler" \
     --set property:enabled

To Create a New Account Status Notification Handler

1. Use dsconfig with the create-account-status-notification-handler subcommand to create the handler.

   When you specify the type, you can use either error-log or generic (default).

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     create-account-status-notification-handler \
     --handler-name "My Password Reset Logger" --type error-log --set enabled:true \
     --set account-status-notification-type:password-reset

2. (Optional) Use dsconfig to view the list of account status notification handlers.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     list-account-status-notification-handlers
   
   Account Status Notification Handler : Type      : enabled
   ------------------------------------:-----------:--------
   Error Log Handler                   : error-log : true
   my Password Reset Logger            : error-log : true
   SMTP Handler                        : smtp      : false

To Delete an Account Status Notification Handler

You can disable an account status notification handler instead of deleting it. In this case, the alert handler is available if you need to enable it again in the future.

You can remove an account status notification handler entirely by using dsconfig.

• Use dsconfig with the delete-account-status-notification-handler subcommand.

  $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
    delete-account-status-notification-handler --handler-name "My Password Reset Logger"