PingAuthorize Server Documentation Index
Command-Line Tool Reference Home

schedule-exec-task

Description
Examples
Arguments

Description

Schedule an exec task to run a specified command in the server. To run an exec task, a number of conditions must be satisfied: the server's global configuration must have been updated to include 'com.unboundid.directory.server.tasks.ExecTask' in the set of allowed-task values, the requester must have the 'exec-task' privilege, and the command to execute must be listed in the 'exec-command-whitelist.txt' file in the server's config directory. The absolute path (on the server system) of the command to execute must be specified as the first unnamed trailing argument to this program, and the arguments to provide to that command (if any) should be specified as the remaining trailing arguments. The server root is used as the command's working directory, so any arguments that represent relative paths are interpreted as relative to that directory.

Examples

Schedules an exec task to invoke the verify-index tool to ensure that all cn attribute values are properly indexed in the backend with base DN 'dc=example,dc=com':
schedule-exec-task --hostname directory.example.com --port 389 \
     --bindDN uid=admin,dc=example,dc=com --promptForBindPassword \
     --waitForCompletion --logCommandOutput /ds/bin/verify-index \
     --baseDN dc=example,dc=com --index cn

Arguments

-V
--version

Description Display PingAuthorize Server version information

-H
--help

Description Display general usage information

--help-debug

Description Display help for using debug options
Advanced Yes

-h {host}
--hostname {host}

Description The IP address or resolvable name to use to connect to the directory server. If this is not provided, then a default value of 'localhost' will be used.
Default Value localhost
Required Yes
Multi-Valued No

-p {port}
--port {port}

Description The port to use to connect to the directory server. If this is not provided, then a default value of 389 will be used.
Default Value 389
Required Yes
Multi-Valued No

-D {dn}
--bindDN {dn}

Description The DN to use to bind to the directory server when performing simple authentication.
Required No
Multi-Valued No

-w {password}
--bindPassword {password}

Description The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

-j {path}
--bindPasswordFile {path}

Description The path to the file containing the password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

--promptForBindPassword

Description Indicates that the tool should interactively prompt the user for the bind password.

-Z
--useSSL

Description Use SSL when communicating with the directory server.

-q
--useStartTLS

Description Use StartTLS when communicating with the directory server.

--defaultTrust

Description Use the JVM's default trust store, the server's default trust store, the server's topology registry, and optionally an additional trust store specified using the --trustStorePath argument to non-interactively determine whether to trust any certificate chain presented during TLS negotiation. If the chain cannot be trusted based on any of those sources, then negotiation will fail without prompting about whether to trust it.

-X
--trustAll

Description Trust any certificate presented by the directory server.

-K {path}
--keyStorePath {path}

Description The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
Required No
Multi-Valued No

-W {password}
--keyStorePassword {password}

Description The password to use to access the key store contents.
Required No
Multi-Valued No

-u {path}
--keyStorePasswordFile {path}

Description The path to the file containing the password to use to access the key store contents.
Required No
Multi-Valued No

--promptForKeyStorePassword

Description Indicates that the tool should interactively prompt the user for the password to use to access the key store contents.

--keyStoreFormat {format}

Description The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
Required No
Multi-Valued No

-P {path}
--trustStorePath {path}

Description The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
Required No
Multi-Valued No

-T {password}
--trustStorePassword {password}

Description The password to use to access the trust store contents.
Required No
Multi-Valued No

-U {path}
--trustStorePasswordFile {path}

Description The path to the file containing the password to use to access the trust store contents.
Required No
Multi-Valued No

--promptForTrustStorePassword

Description Indicates that the tool should interactively prompt the user for the password to use to access the trust store contents.

--trustStoreFormat {format}

Description The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
Required No
Multi-Valued No

-N {nickname}
--certNickname {nickname}

Description The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
Required No
Multi-Valued No

-o {name=value}
--saslOption {name=value}

Description A name-value pair providing information to use when performing SASL authentication.
Required No
Multi-Valued Yes

--useSASLExternal

Description Use the SASL EXTERNAL mechanism to authenticate.

--helpSASL

Description Provide information about the supported SASL mechanisms, including the properties available for use with each.

--taskID {id}

Description The unique identifier that should be assigned to the task. If this is not provided, then a unique identifier will be automatically generated
Required No
Multi-Valued No

-t {YYYYMMDDhhmmss}
--startTime {YYYYMMDDhhmmss}

Description The time that the command should be scheduled to start running. If this is provided, then the value must be specified in a valid generalized time format, or in a generalized time format without a time zone indicator to indicate that the time should be interpreted in the local time zone. If this is not provided, then the command will be scheduled to start immediately
Required No
Multi-Valued No

--alertOnStart

Description Indicates that the server should generate an alert notification when the task starts running

--alertOnSuccess

Description Indicates that the server should generate an alert notification when the task completes successfully

--alertOnError

Description Indicates that the server should generate an alert notification when the task fails to complete successfully

--emailOnStart {emailAddress}

Description An email address to which a message should be sent when the task starts running. This argument may be used multiple times to provide multiple email addresses
Required No
Multi-Valued Yes

--emailOnSuccess {emailAddress}

Description An email address to which a message should be sent when the task completes successfully. This argument may be used multiple times to provide multiple email addresses
Required No
Multi-Valued Yes

--emailOnError {emailAddress}

Description An email address to which a message should be sent when the task fails to complete successfully. This argument may be used multiple times to provide multiple email addresses
Required No
Multi-Valued Yes

--dependsOnTask {id}

Description The task ID of a task that must complete before the created exec task will be eligible to start running. This argument may be used multiple times to specify multiple dependencies
Required No
Multi-Valued Yes

--failedDependencyAction {process|cancel|disable}

Description The behavior that the server should exhibit if any of the task's dependencies fails to complete successfully. If this is provided, the value must be one of 'process' (to indicate that the exec task should still be processed), 'cancel' (to indicate that th exec task should be canceled), or 'disable' (to indicate that the exec task should be disabled so that it will not be eligible to start until it is manually re-enabled). This argument can only be provided if one or more dependencies are configured. If this argument is not provided, then a default behavior of 'process' will be used
Default Value process
Required No
Multi-Valued No

--waitForCompletion

Description Indicates that the tool should wait for the exec task, and the command that it invokes, to complete. By default, this tool will exit as soon as the exec task is scheduled. This argument cannot be used in conjunction with the --startTime argument

--outputFile {path}

Description The path to a file (on the server filesystem) to which the command's output (both standard output and standard error) should be written. The path may be relative or absolute, with relative paths interpreted as relative to the server root. If this is provided, then the specified file will be overwritten if it already exists, and if the output file does not exist, then the parent directory must already exist. If this argument is not provided, then the command's output will not be written to any file
Required No
Multi-Valued No

--logCommandOutput

Description Indicates that the command's output (both standard output and standard error) should be recorded in the server's error log, which will also cause it to be preserved in the task entry. This argument is not recommended for use with commands that may produce non-text output, or for commands that may produce text-based output with extremely long lines

--taskCompletionStateForNonZeroExitCode {stopped-by-error|completed-with-errors|completed-successfully}

Description The task state that should be used if the command completes with a nonzero exit code. If this is provided, then the value must be one of 'stopped-by-error' (to indicate that the task completely failed, and that any dependent tasks should behave as if it failed), 'completed-with-errors' (to indicate that the task was not completely successful but that any dependent tasks should behave as if it had been successful), or 'completed-successfully' (to indicate that the task was completely successful). If this is not provided, a default value of 'stopped-by-error' will be used
Default Value stopped_by_error
Required No
Multi-Valued No

--workingDirectory {path}

Description The path to a directory (on the server filesystem) where the command should be executed. The path must be absolute and the directory must already exist. If this argument is not provided, then the command will be executed from the server root directory
Required No
Multi-Valued No

--interactive

Description Launch the tool in interactive mode.

--propertiesFilePath {path}

Description The path to a properties file used to specify default values for arguments not supplied on the command line.
Required No
Multi-Valued No

--generatePropertiesFile {path}

Description Write an empty properties file that may be used to specify default values for arguments.
Required No
Multi-Valued No

--noPropertiesFile

Description Do not obtain any argument values from a properties file.

--suppressPropertiesFileComment

Description Suppress output listing the arguments obtained from a properties file.