Introduction
The JITL SSHJob implements an SSH client (Secure Shell) and allows to execute shell code, scripts and programs on a remote host without a JS7 Agent being installed on that host. As a prerequisite the remote host has to operate an SSH server.
The SSHJob allows execution on Unix and Windows systems.
- Unix based operating systems generally provide an SSH client, while Windows operating systems by default do not.
- The beauty of SSH is its simplicity. It allows public/private key authentication and is well suited to execute programs for specific accounts.
- The JITL SSHJob allows shell scripts to add return values to orders.
- One of the restrictions of SSH connections is that there is limited control of child processes on the remote host.
- If a number of child processes are spawned by a program during an SSH session and that session is aborted then child processes will continue to run.
- The SSHJob provides a means to control the behavior with output to stderr and exit codes of shell commands.
- For Windows operating systems hardly any products with decent SSH server capabilities are available, therefore use of JS7 Agents for Windows is preferable.
Usage
When defining the job consider
- to invoke the Wizard that is available from the job properties tab in the Configuration view and to select the JITL SSHJob and respective arguments from the Wizard
or
- to specify the
com.sos.jitl.jobs.ssh.SSHJob
Java class name, then add arguments as explained from the below documentation.
Example
Download (upload .json): jdSSHPublicKeyAuthentication.json
An SSHJob configuration can look like this:
The SSHJob arguments can look like this:
Documentation
Job Documentation including the full list of arguments: https://www.sos-berlin.com/doc/JS7-JITL/SSHJob.xml
Find below an extract of most commonly used arguments.
- Required Arguments
- Arguments that have to be specified with the job configuration.
- Example: The
host
argument is required to run a job that connects to a remote host.
- Example: The
- Arguments that have to be specified with the job configuration.
- Optional Arguments
- Arguments that are not required or arguments that are technically required but are available from default values.
- Example 1: technically required, but available from default value
- To connect to a remote host, the
port
argument is required. The argument is available from the default value22
, therefore theport
argument is not required.
- To connect to a remote host, the
- Example 2: not required
- The
proxy_host
argument is used only if the job's connection makes use of a proxy.
- The
- Example 1: technically required, but available from default value
- Arguments that are not required or arguments that are technically required but are available from default values.
The com.sos.jitl.jobs.ssh.SSHJJob
class accepts the following arguments:
Name | Required | Default Value | Purpose | Example |
---|---|---|---|---|
host | yes | This argument specifies the hostname or IP address of the SSH server to which a connection is to be made. | ||
| yes | This argument specifies the user account to be used when connecting to the SSH server. | ||
port | no | 22 | This argument specifies the port number of the SSH server. | |
auth_method | no | publickey | This argument specifies the authentication method for the SSH server - the publickey and password methods are supported. The path name of the private key file is specified with the | |
password | no | This argument specifies the user account's password for authentication by the SSH server and has to be specified if the password authentication method is specified with the | ||
auth_file | no | This argument specifies the path and name of a private key file used for authentication with an SSH server. This argument has to be specified if the publickey authentication method is specified with the | ||
command_delimiter | no | %% | Command delimiter characters can be specified using this argument. The delimiters are used in command arguments to separate multiple commands. The commands can be executed in separate SSH sessions. | |
command | no | This argument specifies a command that should be executed on the SSH server. Multiple commands can be separated by the command delimiter that is specified using the | ||
command_script | no | This argument can be used as an alternative to | ||
command_script_file | no | This argument can be used as an alternative to The SSH Job can transfer a command script file to the remote host only if SFTP is allowed on the remote SSH Server. | ||
create_env_vars | Populates the remote shell with JS7_* environment variables of the current task, for a full list see JS7 - Job Environment Variables, chapter: Environment Variables that are automatically available to Shell Jobs | |||
proxy_host | no | The value of this argument is the host name or the IP address of a proxy used to establish the connection to the SSH server. Use of a proxy is optional. | ||
proxy_port | no | This argument specifies the port number of a proxy that is used to establish the connection to the SSH server. | ||
proxy_user | no | The value of this argument specifies the user account for authentication with the proxy server that is used to connect to the SSH server. | ||
proxy_password | no | This argument specifies the password for the proxy server user account if a proxy is used to connect to the SSH server. | ||
ignore_error | no | false | If the value of this argument is set to | |
exit_codes_to_ignore | no | This argument is used to specify one or more exit codes that will not be considered as errors. Multiple exit codes can be defined using comma separated values. |
| |
ignore_stderr | no | This job checks if any output to stderr has been created by a command that is executed on the SSH server and reports such output as an error. | ||
simulate_shell | no | If this value is set to | ||
credential_store_file | no | Location of a credential store database (*.kdbx) | ./config/private/jobs.kdbx | |
credential_store_key | no | Location of a credential store key file (*.key) | ./config/private/jobs.key |
The SSHJob can be used with a credential store to hold sensitive arguments. For use of the credential_store_*
arguments see JS7 - Use of Credential Store with JITL Jobs.