Introduction

  • The JITL SSHJob implements an SSH client (Secure Shell) and allows execution of 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 a standard-compliant SSH server.

  • The SSHJob allows execution of commands, scripts, executables on remote 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 execution of 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.
  • For Windows operating systems hardly any products are available with decent SSH server capabilities and therefore the use of JS7 Agents for Windows is preferable.

Usage

When defining the job consider:

  • invoking the Wizard that is available from the job properties tab in the Configuration view and selecting the JITL SSHJob and relevant arguments from the Wizard

or 

  • specifing the com.sos.jitl.jobs.ssh.SSHJob Java class name and then adding arguments as explained in the documentation below.

Example

Download (upload .json): jdSSHPublicKeyAuthentication.json

An SSHJob configuration can look like this:


The SSHJob arguments can look like this:


Explanation:

  • The workflow implements two jobs:
    • Job: execute-ssh
      • Argument: command
        • The value of the argument is a number of shell commands:

          echo "printing environment variables"
          printenv
          echo "adding hostname $HOSTNAME to variable remote_hostname"
          echo "remote_hostname=$HOSTNAME" >> $JS7_RETURN_VALUES

          The last line appends a key=value pair to a temporary file that is made available from the JS7_RETURN_VALUES environment variable. The name being remote_hostname and the value being provided from the HOSTNAME environment variable.
          This creates an order variable with the name remote_hostname that is available to subsequent jobs and instructions in a workflow.

      • Argument: create_env_vars
        • The argument is assigned the value true that specifies that for any order variables the job will create environment variables in the remote session.
          • For example, an order variable with the name date will be made available from the environment variable JS7_VAR_DATE.
        • For details see chapter Variables.
      • For the full list of available arguments see next chapter.
    • Job: display-result
      • Argument: no arguments
      • Environment Variables
        • The job is assigned an environment variable with the name REMOTE_HOSTNAME and the value $remote_hostname which is a reference to the order variable created by the previous job.
      • Script
        • The job script looks like this:

          echo "using workflow: $JS7_WORKFLOW_NAME"
          echo "running job: $JS7_JOB_NAME"
          
          echo "remote hostname: $REMOTE_HOSTNAME"

          The job script makes use of the REMOTE_HOSTNAME environment variable that is populated from the order variable created by the previous job.

Documentation

The Job Documentation including the full list of arguments can be found under: https://www.sos-berlin.com/doc/JS7-JITL/SSHJob.xml

The most commonly used arguments are listed in the table below.

  • 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 must not be provided 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:


NameRequiredDefault ValuePurposeExample
hostyes

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.


portno22

This argument specifies the port number of the SSH server.


auth_methodnopublickey

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.


passwordno

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_fileno

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_delimiterno%%

Command delimiter characters can be specified using this argument. These delimiters are used in command arguments to separate multiple commands. The commands can be executed in separate SSH sessions.


commandno

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_scriptno

This argument can be used as an alternative to commandcommand_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. Order arguments overwrite a job's arguments of the same name.


command_script_fileno

This argument can be used as an alternative to 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 order variables from environment variables. Environment variable names are written in upper case.

The SSH Job can transfer a command script file to the remote host only if SFTP is allowed on the remote SSH Server.


command_script_paramno

If the command_script or command_script_file argument is used then this argument can hold an argument string that is passed on when executing the command script file on the remote host.


create_env_varsno
Populates the remote shell with the JS7_* environment variables of the current job, for a full list see JS7 - Job Environment Variables, chapter: Environment Variables that are automatically available to Shell Jobs
filter_regexno.*

This argument specifies a regular expression to filter variables that should be propagated to the remote shell as environment variables.

Names of environment variables on the remote host are prefixed with JS7_VAR_ and the variable name is spelled in upper case letters, for example myVariable => JS7_VAR_MYVARIABLE

If no regular expression is specified then all variables are propagated.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.3.0


proxy_hostno

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_portno

This argument specifies the port number of a proxy that is used to establish the connection to the SSH server.


proxy_userno

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_passwordno

This argument specifies the password for the proxy server user account if a proxy is used to connect to the SSH server.


ignore_errornofalse

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_ignoreno

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 semicolon separated values.

The semicolon delimiter is part of the JITL JobArgument implementation and is used in all JobArguments of the type List. It is independent from the command_delimiter argument, which is only available with the JITL SSHJob to separate a number of commands on the remote side.

2;3;4;100

ignore_stderrno

This job checks if any output to stderr has been created by a command that is executed on the SSH server. It reports such output as an error and fails the current order.
If the value is set to true then output to stderr will be reported as an error by the Agent but will not fail the current order.


simulate_shellno

If this value is set to true then a pseudo-terminal similar to a shell is used to execute commands. Some scripts may cause problems if no shell is present. In addition, this argument can be required by older SSH daemons to detect whether the SSHJob has closed the connection and terminated running child processes.


credential_store_fileno
Location of a credential store database (*.kdbx)./config/private/jobs.kdbx
credential_store_keyno
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.

Variables

FEATURE AVAILABILITY STARTING FROM RELEASE 2.3.0

Forwarding Variables

The SSHJob has access to variables from the following sources:

  • Global Variables
  • Specific Variables
    • Sources
      • Order variables that are added when planning or submitting an order.
      • Workflow variables that are added dynamically during execution of the workflow.
      • Job Resource variables that are added from JS7 - Job Resources at workflow level and at job level.
    • Mapping
      • Specific variables use names within the scope of the JS7 - Object Naming Rules and are mapped to environment variables in the remote SSH session:
      • Environment variables use the prefix JS7_VAR_.
      • If the same variable names are used in a number of sources then the following precedence applies:
        • order variables, workflow variables, job resource variables.
        • for job resource variables account is taken of the order of assignment of the job resource: a variable with the same name used by a previously assigned job resource will not be overwritten by a later job resource. Job resources assigned at workflow level take priority over job resources assigned at job level.

Examples:

  • The global variable JS7_AGENT_TZ is available with the remote SSH session and indicates the JS7 Agent's local time zone.
  • A specific variable $dbName is mapped to the environment variable JS7_VAR_DBNAME in the remote SSH session.
  • A specific variable $ScriptDir is specified by a job resource with a value /usr/scripts and is declared with a workflow using the default value /var/scripts. The resulting environment variable JS7_VAR_SCRIPTDIR will hold the value /var/scripts unless a different value is specified by the order that is added to the workflow.

Passing back Variables

The command script or commands of the SSHJob executed on the remote host can pass back variables to the workflow. To this purpose the command script or commands append any number of key=value pairs to a temporary file that will be picked up by the SSHJob. Each key=value pair is passed back to the workflow and becomes an order variable.

Example:

The command 

echo MYPARAM=myTestValue >> $JS7_RETURN_VALUES

appends MYPARAM=myTestValue to the temporary file defined by the environment variable JS7_RETURN_VALUES. For Unix the environment variable is specified using $JS7_RETURN_VALUES, for Windows the syntax is %JS7_RETURN_VALUES%.

The JS7_RETURN_VALUES environment variable is made available by the SSHJob during job execution. When the SSHJob completes it will read the key=value pairs from the temporary file and will add them as order variables to the job's outcome. The order variable MYPARAM  can be used in subsequent jobs. When calling up the variable the syntax $MYPARAM is used for Unix and Windows. Users should consider case-sensitive spelling of order variables.

Cancellation

The following operations are available:

  • The cancel operation is applied to the order, not to the SSHJob. In case of cancellation the job will continue until completion and the order will be put in the failed state.
  • The cancel/force operation is applied to the order and to the job. The SSHJob will be forcibly terminated, similarly child processes in the remote SSH session will be terminated. The order will be set to the failed state.
    • For older SSH servers, for example OpenSSH before version 7.5, to terminate child processes in the remote SSH session the simulate_shell job attribute has to be used.

Further Resources


  • No labels