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: 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.
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 value 22, therefore the port argument is not required.
  - Example 2: not required
    - The proxy_host argument is used only if the job's connection makes use of a proxy.

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.
`user`	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 `auth_file` argument when the publickey authentication method is used. If the private key file is secured by a password then this has to be specified with the `password` argument. Available authentication methods depend on the SSH server configuration. Not all SSH server configurations support the password authentication method.
`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_method` argument. Alternatively, this argument is used to specify the passphrase for a private key if the publickey authentication method is used with the `auth_method` argument.
`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 `auth_method` argument. If the private key file is secured with a passphrase then the passphrase has to be specified with the `password` argument.
`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_delimiter` argument.
`command_script`	no		This argument can be used as an alternative to `command`, `command_delimiter` and `command_script_file`. It contains script code that will be stored to a temporary file on the remote host and will be executed. The script can access task and order arguments by environment variables. Environment variable names are written in upper case letter. Order arguments with the same name overwrite a job's arguments.
`command_script_file`	no		This argument can be used as an alternative to `command`, `command_delimiter` and `command_script`. It contains the name of a local file, that will be transferred to the remote host and will be executed. The script can access task and order arguments by environment variables. Environment variable names are written in upper case letters. Order arguments with the same name overwrite the job's arguments. The SSH Job can transfer a command script file to the remote host only if SFTP is allowed on the remote SSH Server.
`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 `true` then execution errors caused by commands on the SSH server will be ignored. Otherwise such execution errors are reported by the Agent.
`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.	`2,3,4,100`
`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. If the value is set to `true` then output to stderr will not be reported as an error by the Agent.
`simulate_shell`	no		If this value is set to `true` then a login to a shell is simulated to execute commands. Some scripts may cause problems if no shell is present.
`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.

Space shortcuts

Page tree

Introduction

Usage

Example

Documentation

Further Resources

Space shortcuts

Page tree

JS7 - JITL SSHJob

Introduction

Usage

Example

Documentation

Further Resources