Table of Contents |
---|
Introduction
This document describes the functionality of the JobSchedulerSSHJob and the parameters to configure the Job properly. Additionaly Additionally this document provides a minimal example for a of an SSH Job configuration.
Mode Of Operation
Unix based operating systems provide an SSH client, while MS Windows operating systems do not.
Parameters
The JobSchedulerSSHJob allows the execution of shell commands and scripts on a remote host running an SSH server without requiring a local SSH client to be installed.
For a minimal SSH job only a limited number of parameters has to be configured as shown in the example below.
Example
A minimal SSH Job configuration
Excerpt | |||||||||
---|---|---|---|---|---|---|---|---|---|
|
Parameters
...
- Required Parameters
- Parameters which are required to have to be set in the job configuration to properly run the Jobjob
- Example: To connect to a remote host, the '
host
' parameter is Thehost
parameter is always required to run the Job properlya job that connects to a remote host.
- Example: To connect to a remote host, the '
- Parameters which are required to have to be set in the job configuration to properly run the Jobjob
- Optional Parameters
- Parameters which depend on other parameters
- Example: Depending on the value of the '
auth_method
' parameter ('password' or 'publickey') one of the conditional parameters, the 'password
' parameter or the 'publickey
' parameter, has to be set.
- Example: Depending on the value of the '
- are not required or parameters which are technically required but are instantiated through a default value and therefore do not have to be set in the job configuration
- Example 1: technically required, but instantiated with default value
- To connect to a remote host, the
port
parameter is required. The parameter is instantiated with the default value22
therefore theport
parameter does not have to be set in the job configuration.
- To connect to a remote host, the
- Example 2: not required
- The
proxy_host
parameter is only used if the jobs
- The
- Example 1: technically required, but instantiated with default value
- Parameters which are not required, but depend on specific conditions
- Example: To connect with a remote host only a '
host
' parameter is required. If the- connection has to be instantiated over a proxy,
proxy_host
' is required.
- Example: To connect with a remote host only a '
- Parameters which depend on other parameters
Note |
---|
Some parameters are technically required to build a connection, but are not shown in the 'Required Parameters' section of this document. This is because some of those parameters are configured with a default value and therefore there is no need to configure them explicitly. |
- otherwise it is not needed at all
Required Parameters
host
- default value:
- empty
- description:
- This parameter specifies the hostname or IP address of the SSH server to which a connection is to be made.
port
- default value:
- 22
- description:
- This parameter specifies the port number of the SSH server.
user
- default value:
- empty
- description:
- This parameter specifies the user account to be used when connecting to the SSH server.
...
Optional Parameters
port
- default value:
- %%22
- description:
- Command delimiter characters are specified using this parameter. These delimiters can then used in the command parameter to seperate multiple commands. These commands are then excecuted in a separate SSH session.
Conditional Parameters
- This parameter specifies the port number of the SSH server.
auth_method
- default value:
- publickey
- description:
- This parameter specifies the authorization method for the SSH server - the publickey and password methods are supported. When the publickey authorization method is used, then the The path name of the private key file must be set in the
auth_file
parameter . Should when the publickey authorization method is used. If the private key file be is secured by a password then this must be specified with thepassword
parameter. For the password authorization method the password The password for each user account using password authorization must be specified using thepassword
parameter. The authorization methods which are enabled depend on the SSH server configuration. Not all SSH server configurations support the password authorization method.
- This parameter specifies the authorization method for the SSH server - the publickey and password methods are supported. When the publickey authorization method is used, then the The path name of the private key file must be set in the
password
- default value:
- empty
- description:
- This parameter specifies the user account password for authorization by the SSH server and must be specified if the password authorization method is specified in the
auth_method
parameter.
Alternatively, this parameter may is used specify the secret key passphrase if the publickey authorization method has been set in theauth_method
parameter.
- This parameter specifies the user account password for authorization by the SSH server and must be specified if the password authorization method is specified in the
...
auth_file
- default value:
- empty
- description:
- This parameter specifies the path and name of a user's private key file used for registeration registration on an SSH server. This parameter must be specified if the publickey authorization method has been specified in the
auth_method
parameter.
If the private key file is secured with a passphrase, thepassword
parameter the passphrase parameter hat to be set with the passphrase.
- This parameter specifies the path and name of a user's private key file used for registeration registration on an SSH server. This parameter must be specified if the publickey authorization method has been specified in the
command_delimiter
- default value:
- %%
- description:
- Command delimiter characters are specified using this parameter. These delimiters are used in command parameters to separate multiple commands. These commands can then executed in separate SSH sessions.
command
- default value:
- empltyempty
- description:
- This parameter specifies a command that is to be executed on the SSH server. Multiple commands can be separated by the command delimiter that is specified using the
command_delimiter
parameter.
- This parameter specifies a command that is to be executed on the SSH server. Multiple commands can be separated by the command delimiter that is specified using the
command_script
- default value:
- empty
- description:
- This parameter can be used as an alternative to
command
,command_delimiter
andcommand_script_file
. It contains scriptcode script code which will be saved to a temporary (script-)file on the remote host and executed there. The script can access task and order parameters by environment variables. The Environment variable names are written in upper case and have "SCHEDULER_PARAM_" as a prefix. Order parameters with the same name overwrite task parameters.
- This parameter can be used as an alternative to
command_script_file
- default value:
- empty
- description:
This parameter can be used as an alternative to
Thecommand
,command_delimiter
andcommand_script
. It contains the name of a local (script-)file, which will be transferred to the remote host and executed there. The script can access task and order parameters by environment variables.Environment variable names are written in upper case and have "SCHEDULER_PARAM_" as a prefix. Order parameters with the same name overwrite task parameters.
...
Note The SSH Job is only able to transfer a command script file to the remote machine if SFTP is allowed on the remote SSH Server.
proxy_host
- default value:
- empty
- description
- The value of this parameter is the host name or the IP address of a proxy used to create the connection to the SSH server. The use of a proxy is optional.
proxy_port
- default value:
- empty
- description
- This parameter specifies the port number of the proxy , should if a proxy be is used to create the connection to the SSH server.
proxy_user
- default value:
- empty
- description
- The value of this parameter specifies the user account for authorization by the proxy server should if a proxy be is used to connect to the SSH server.
proxy_password
- default value:
- empty
- description
- This parameter specifies the password for the proxy server user account , should if a proxy be is used to connect to the SSH server.
command_script_param
- default value:
- empty
- description
- This parameter contains a parameterstring, parameter string which will be appended when calling the a
command_script
or thecommand_script_file
is called.
- This parameter contains a parameterstring, parameter string which will be appended when calling the a
ignore_error
- default value:
- false
- description
- If the value true is set,
- value of this parameter is set to true then execution errors caused by commands on the SSH server are
- will be ignored. Otherwise such execution errors for jobs and orders are reported by the Job Scheduler.
ignore_exit_code
- default value:
- empty
- description
- This parameter configures is used to specify one or more exit codes which will not be treated as errors. Multiple exit codes can be defined using comma seperated separated values or using ranges.
- examples:
- 255
- 2,3,4,100
- 4,50-60,210-220
ignore_signal
- default value:
- false
- description
- If the value true is set, then value of this parameter is set to true then all signals on Unix systems all signals will be ignored that terminate the execution of a command on the SSH server server will be ignored - if for example a command is terminated using kill.
Note that by default the Job Scheduler reports errors for commands that are terminated by signals.
- If the value true is set, then value of this parameter is set to true then all signals on Unix systems all signals will be ignored that terminate the execution of a command on the SSH server server will be ignored - if for example a command is terminated using kill.
ignore_stderr
- default value:
- false
- description
- This job checks if any output to
stderr
has been created by a command that is being executed on the SSH server and reports this as an error.
If the value true is set, value is set to true then output tostderr
will not be reported as an error by the Job Scheduler.
- This job checks if any output to
simulate_shell
- default value:
- false
- description
- If the value true is set, this value is set to true then a login to a shell is simulated to execute commands. Some scripts may cause problems if no a shell is not present.
simulate_shell_prompt_trigger
- default value:
- empty
- description
- The expected command line prompt. Using this prompt the job tries to find out if commands may be entered or have been carried out. If no prompt can be configured, timeout parameters have to be used.
simulate_shell_login_timeout
- default value:
- empty
- description
- If no new characters are written to
stdout
orstderr
after the within a given number of milliseconds, the job assumes that that the login has been carried out and the shell is waiting for commands.
- If no new characters are written to
simulate_shell_inactivity_timeout
- default value:
- empty
- description
- If no new characters are written to stdout or stderr after the given number of milliseconds, the job assumes that this parameter is set the job will assume that the command has been carried out and the shell is waiting for commands .
Example
Example 1: A minimal SSH Job configuration
Excerpt | |||||||||
---|---|---|---|---|---|---|---|---|---|
|
...
- if no new characters are written to
stdout
orstderr
after the given number of milliseconds.
- if no new characters are written to