Configuring Commands As Tasks

Certain command-line utilities can be used to schedule tasks to run within the directory server as well as to perform their functions locally. Tasks that can be scheduled support the options used to connect to the directory server to interact with the task back end.

Commands That Can Schedule Tasks

The following utilities can schedule tasks:

import-ldif
export-ldif
backup
restore
stop-ds
stop-ds --restart
rebuild-index
dsreplication purge-historical

For Oracle Unified Directory proxy, only the stop-ds command can be scheduled to run as a task.

Controlling Which Tasks Can Be Run

You can control the tasks that can be run by setting the allowed-tasks advanced global configuration property. By default, all tasks supported by the tasks back end are allowed. To prevent a task from being run, remove its value from the allowed-tasks property. For example, to prevent the server from being stopped using a task, run the following command:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
  set-global-configuration-prop \
  --remove allowed-task:org.opends.server.tasks.ShutdownTask

Scheduling and Configuring Tasks

The procedures in this section indicate how to schedule a task, how to configure task notification, and how to configure task dependencies. All of the examples in this section assume that the commands are being run on the local host, using the default administration port (4444), and the local certificate configuration. If you are running the commands remotely, you might need to specify the certificate parameters. For more information, see Managing Administration Traffic to the Server.

To Schedule a Task

To schedule a task, invoke the required utility with the options used to connect to the directory server, an optional start time, and any options that will be used as arguments for the task execution.

If the -t or --start option is provided, the utility exits immediately after scheduling the task. To schedule a task for immediate execution and have the utility exit immediately after scheduling the task, specify 0 as the value for the start time.

If the -t or --start option is omitted, the utility schedules the task for immediate execution and tracks the task's progress, printing log messages as they are available and exiting when the task has completed.

Schedule the export-ldif task to start at 12:15 on September 24th, 2009.

$ export-ldif -D "cn=directory manager" -w password \
  -l /ldif-files/example.ldif --start 20090924121500 -n userRoot

To Schedule a Recurring Task

To schedule a recurring task, invoke the required utility with the options used to connect to the directory server, specifying the recurring task schedule, and any options that will be used as arguments for the task execution. The following commands can be scheduled as recurring tasks:

import-ldif
export-ldif
backup
restore
rebuild-index
dsreplication purge-historical

The --recurringTask option specifies a recurring task schedule that is used by the task scheduler to determine when and how often a recurring task should run. The pattern used to specify the schedule is based on UNIX crontab(5) scheduling patterns and rules and includes the following five integer pattern fields, separated by blank spaces:

Minute [0,59]
Hour [0,23]
Day of the month [1,31]
Month of the year [1,12]
Day of the week [0,6] (with 0=Sunday)

Each of these patterns can be either an asterisk (meaning all valid values), an element, or a list of elements separated by commas. An element is either a number or two numbers separated by a dash (meaning an inclusive range).

The task scheduler spawns regular task iterations according to the specified schedule.

Schedule the task using the --recurringTask option.

The following command schedules a backup task to execute at the beginning of every hour.

$ backup -D "cn=directory manager" -w password --recurringTask \
  "00 * * * *" --backupDirectory /example/backup --backUpAll --backupID "Hourly Backup"

Example 2-1 Recurring Task Example

This example shows an export task that is scheduled to run every 15 minutes, every Sunday.

$ export-ldif -D "cn=directory manager" -w password --recurringTask \
  "0,15,30,45 * * * 0" -l PATH/export-recurring.ldif -n userRoot
Recurring Export task  ExportTask-a614e45d-6ba5-4c29-a8e1-d518c20e46ab scheduled
successfully

To Configure Task Notification

The task scheduling options of a utility enable you to notify an administrator when a task completes or if an error occurs during the task's execution. To use the notification facility, an SMTP server must be configured for the directory server.

Specify an SMTP server by setting the smtp-server global configuration property.
The following command configures the SMTP server named mailserver.example.com:
```
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
  set-global-configuration-prop \
  --set smtp-server:mailserver.example.com
```
Use the completionNotify and errorNotify options to specify the email address to which the task notification should be sent.
The following command schedules a backup task and specifies that admin@example.com should be notified when the task completes, or when an error occurs:
```
$ backup -D "cn=directory manager" -w password -a -d /tmp/backups \
  --start 20080924121500 --completionNotify admin@example.com \
  --errorNotify admin@example.com
Backup task 20080924121500 scheduled to start Sep 24, 2008 12:15:00 PM SAST
```

To Configure Task Dependencies

Certain tasks might require that another task be completed before the task begins. The task dependency options of a utility enable you to specify that the task depends on another task, and what the task should do should the other task fail.

Schedule the task and specify the dependency and failedDependencyAction.

The following example schedules a backup task that depends on another task, and specifies that the backup should be canceled should the other task fail:

$ backup -D "cn=directory manager" -w password -a -d /tmp/backups \
  --start 2008102914530410 --dependency 20080924121500 \
  --failedDependencyAction cancel
Backup task 2008102914530410 scheduled to start Oct 29, 2008 14:53:04 PM SAST

Managing and Monitoring Scheduled Tasks

The manage-tasks utility can be used to obtain a list of scheduled tasks, to display task status, and to cancel scheduled tasks. The following procedures provide examples of managing scheduled tasks. For more information, see manage-tasks in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory.

To Obtain Information About Scheduled Tasks

Display a summary of all scheduled tasks.

$ manage-tasks -D "cn=directory manager" -w password -n -s
ID                Type    Status
------------------------------------------------
2008100912550010  Backup  Completed successfully
2008100912554710  Backup  Completed successfully
2008100912560510  Backup  Waiting on start time
2008100912561410  Backup  Waiting on start time

Display additional information on a particular task, specified by its task ID.

$ manage-tasks -D "cn=directory manager" -w password -n -i 2008100912550010

Task Details
------------------------------------------------------
ID                        2008100912550010
Type                      Backup
Status                    Completed successfully
Scheduled Start Time      Immediate execution
Actual Start Time         Oct 9, 2008 12:55:00 PM SAST
Completion Time           Oct 9, 2008 12:55:01 PM SAST
Dependencies              None
Failed Dependency Action  None
Email Upon Completion     None Specified
Email Upon Error          None Specified

Backup Options
----------------------------
Backup All        true
Backup Directory  ../backups

Last Log Message
------------------------------------------------------------------------------
[09/Oct/2008:12:55:01 +0200] severity="NOTICE" msgCount=4 msgID=10944795
message="The backup process completed successfully"

To Cancel a Scheduled Task

Run the manage-tasks utility with the -c or --cancel option.
The following command cancels a particular task, specified by its task ID:
```
$ manage-tasks -D "cn=directory manager" -w password -n -c 2008100912561410
```

To Cancel a Recurring Task

You can cancel an entire recurring task, in which case both the recurring task and its next scheduled iteration are canceled. Alternatively, you can cancel only the next scheduled task iteration, in which case future recurring task iterations will be spawned by the task scheduler.

Use the manage-tasks command to display the summary of scheduled tasks.

$ manage-tasks -D "cn=directory manager" -w password -n -s

 ID                                             Type    Status
 
----------------------------------------------------------------------------
 Hourly Backup                                  Backup  Recurring
 Hourly Backup - Wed Jan 14 13:00:00 SAST 2009  Backup  Waiting on start time

Run the manage-tasks utility with the -c or --cancel option.

Cancel the entire recurring task by specifying its task ID.

$ manage-tasks -D "cn=directory manager" -w password -n -c "Hourly Backup"
Task Hourly Backup canceled

Cancel the next scheduled task by specifying its task ID.

$ manage-tasks -D "cn=directory manager" -w password -n \
  -c "Hourly Backup - Wed Jan 14 13:00:00 SAST 2009 "
Task Hourly Backup - Wed Jan 14 13:00:00 SAST 2009  canceled

Skip Navigation Links
Exit Print View
	Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1)