Remote Script Tasks

This topic covers Remote Script tasks in Digital.ai Release, which use the Overthere framework to execute commands on remote hosts. The Overthere framework is a Java library designed for managing files and processes on remote systems.

Choosing a Host Type and Connection Type

The remoting functionality in Deploy and Release uses the Overthere framework to manipulate files and execute commands on remote hosts. For more information, see Overthere framework.

This section describes how to choose a host and connection type for your remote scripts.

If the remote host is the Deploy or Release server

Create a local host (overthere.LocalHost) configuration item (CI).

If the remote host is a Unix host

Create an SSH host (overthere.SshHost) CI, set the os property to UNIX, and depending on your needs, select an option below:

• If you need to connect to the target system with the user that has the privileges to manipulate the files and execute the commands required: Use the SCP connection type.
• If you need to log in as one user and then use sudo, or a similar command like sx, but not su, to execute commands and manipulate files as a different user: Use the SUDO connection type. If you do not need this functionality, use the INTERACTIVE_SUDO connection type.
• If you need to log in as one user and then use su to execute commands and manipulate files as a different user: Use the SU connection type.

If the remote host is a Microsoft Windows host

• If you configured WinRM on the remote host: Create an SMB host (overthere.SmbHost) CI.
• If Deploy or Release server is running on a Windows host: Use the WINRM_NATIVE connection type. If Deploy or Release server is not running on Windows: Use the WINRM_INTERNAL connection type.

If WinSSHD is installed on the remote host:

1. Create an SSH host (overthere.SshHost) CI,
2. Set the os property to WINDOWS, and use the SFTP_WINSSHD connection type.

If OpenSSH (Cygwin or Copssh) is installed on the remote host:

1. Create an SSH host (overthere.SshHost) CI.
2. Set the os property to WINDOWS, and use the SFTP_CYGWIN connection type.

If Telnet is installed on the remote host: Create an SMB host (overthere.SmbHost) CI and use the TELNET connection type.

note

The SMB protocol is supported in Deploy. SMB is not supported in Release.

If the remote host is a z/OS host

1. Create an SSH (overthere.SshHost) CI.
2. Set the os property to ZOS, and use the SFTP connection type.

You can use Remote Script tasks to:

• Execute shell scripts on Unix, z/OS, or Microsoft Windows (using Cygwin or WinSSHD) hosts.
• Execute batch scripts on Microsoft Windows hosts. Note: All scripts will be interpreted as batch files. PowerShell is currently not supported.

The following Remote Script task types are available:

• Remote Script: Unix: Execute a shell script on a Unix host using SSH
• Remote Script: Windows: Execute a batch script on a Microsoft Windows host using WinRM
• Remote Script: Windows (SSH): Execute a shell script on a Microsoft Windows host using SFTP
• Remote Script: z/OS: Execute a shell script on z/OS

In the release flow editor, Remote Script tasks are marked with a blue border.

Common Properties

The following properties are common to all Remote Script task types.

Remote Script Execution Details

Property	Description
Script	The shell script to execute on the remote host (required)
Remote Path	The path on the remote host where the script should be executed (required)
Temporary Directory Path	Where to store temporary files. This directory will be removed on connection close.

Remote Host Connection

• UNIX: SCP, SFTP, SU, SUDO, INTERACTIVE_SUDO, SFTP_CYGWIN, or SFTP_WINSSHD
• Windows: TELNET, WINRM_INTERNAL, or WINRM_NATIVE
• Windows (SSH): SFTP_CYGWIN, or SFTP_WINSSHD
• z/OS: This option is not present, and SFTP will be used (unless overridden in the remoteScript.Zos.connectionType setting in the deployit-defaults.properties file)

Note: To connect to a Windows host, use the WINRM_INTERNAL connection type.

Property	Description
Jumpstation	The SSH jumpstation or HTTP proxy to use
Address and Port	Address and SSH port (or Telnet or WinRM port for Windows) of the remote host (required)
Connection type	The SSH connection type to use:

Command Output

The following output properties are available:

Property	Description
Output	The variable in which the standard output will be stored
Err	The variable in which the error output will be stored

important

You must exit your script with Exit 0 to populate task variables. If your script exits with anything other than Exit 0, then the task fails, and the release gets halted. However, if something fails in the script, you can redirect the script with 1>&2 that controls the Err task output. This is an alternative to checking scripts when the task fail and using the XLR failure handling on the task for the appropriate action.

note

The output of the remote script task is in Markdown format. See Using Markdown in Release for more information.

Unix Remote Script

The following properties are available in the Remote Script: Unix, Remote Script: Windows (SSH), and Remote Script: z/OS task types.

Credentials

Property	Description
Username	The Unix host user login ID (required)
Password	The Unix host user password
Private key	The private key to use (verbatim) for authentication
Private key file and Passphrase	The file containing a private key, and an optional passphrase for the key it contains

You can use a password, a private key, or a private key file and passphrase.

Privilege Elevation

Property	Description
SUDO username	Access files and commands after sudo'ing to this user
SU username and SU password	Access files and commands after su'ing to this user

Windows Remote Script

The following properties are available in the Remote Script: Windows task type.

Credentials

Property	Description
Username and Password	The Windows host user login ID and password
Allow credential delegation	If checked, allow the user's credentials to be used to access. Example: remote shares (only on WINRM_NATIVE connection type).

Connectivity

Property	Description
CIFS Port	The port on which the CIFS (SMB) server runs
Windows path to Windows share mappings	Mapping from Windows paths to Windows share names. Example: C:\IBM\WebSphere → WebSphereShare
Timeout	The WinRM timeout in XML schema duration format. The default value is PT60.000S
Enable HTTPS for WinRM	Check this if the remote Windows host supports encrypted connections

Using Advanced Overthere Functionality

Release uses the Overthere framework, which includes several connection options. While most common options are available in the Release GUI, you can use other options as described in the Overthere documentation.

You can change the default values of options that are not exposed in the GUI in the XL_RELEASE_SERVER_HOME/conf/deployit-defaults.properties file.

To use a different setting for a particular option per task, you can create a type modification in the XL_RELEASE_SERVER_HOME/conf/synthetic.xml file for the task types. In the modification, you can add the desired Overthere connection option as a property on the task. These task properties will automatically be used as connection options for Overthere if the name matches.

Example: To make the connection timeout configurable on each task, add this to synthetic.xml:

<type-modification type="remoteScript.WindowsSsh">
    <property name="connectionTimeoutMillis" category="input" kind="integer" default="120000"
              description="Number of milliseconds Overthere waits for a connection to a remote host to be established"/>
</type-modification>