# Preface

This document describes the functionality provided by the Remoting plugin.

See the Deployit Reference Manual for background information on Deployit and deployment concepts.

# Overview

The Remoting plugin is a Deployit plugin that allows Deployit to manipulate files and execute commands on remote hosts. It does so by using the Overthere framework. Overthere is a Java library to manipulate files and execute processes on remote hosts, i.e. do stuff "over there". See the Overthere repository for more information.

## Features

- Define remote host CIs to use as deployment targets.

- Define jump stations to connect to remote hosts.

# Requirements

- Deployit requirements
  - Deployit: version 3.5+
  - Other Deployit Plugins: None

# Examples

## Connecting through a tunnel

When Deployit cannot reach a Host directly, but that Host can only be reached through an SSH tunnel, you need to create a so-called Jumpstation Host. This can be set up as follows.

Two Infrastructure items need to be created, ie. the target 'overthere.Host' and the 'overthere.SshJumpstation' that will actually be used to connect to the target machine. Once these are created, they can be hooked up to eachother, by pointing the 'jumpstation' property of the target machine to the created 'overthere.Jumpstation'.

Once Deployit starts a deployment to the target host, it will see that it needs to connect through the jumpstation, and will first open a connection to that machine, and then setup a dynamic ssh tunnel to the target machine.

# CI Reference

## Configuration Item Overview

### Containers

### Other Configuration Items

## Configuration Item Details

### overthere.CifsHost

Type Hierarchy | overthere.RemoteHost >> overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that can be connected to using either WinRM or Telnet and can perform file manipulation via the CIFS protocol

|  | Public Properties
--- | --- | ---
|  | address : STRING
|  | Address of the host
|  | connectionType : ENUM [TELNET, WINRM, WINRM_HTTP, WINRM_HTTPS] = WINRM
|  | Connection Type
|  | os : ENUM [WINDOWS, UNIX]
|  | Operating system
|  | password : STRING
|  | Password to use for authentication
|  | username : STRING
|  | Username to connect with
|  | cifsPort : INTEGER = 445
|  | Port on which the CIFS server runs
|  | deploymentGroup : INTEGER
|  | If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
|  | jumpstation : CI<overthere.Jumpstation >
|  | Jumpstation that should be used to reach this host
|  | pathShareMappings : MAP_STRING_STRING
|  | Mapping from Windows paths to Windows share names, e.g. C:\IBM\WebSphere -> WebSphereShare
|  | port : INTEGER
|  | Port on which the Telnet or WinRM server runs
|  | tags : SET_OF_STRING
|  | If set, only deployables with the same tag will be automatically mapped to this container.
|  | temporaryDirectoryPath : STRING
|  | Directory into which temporary files are stored. Will be cleaned up when the connection is closed.
|  | winrmEnableHttps : BOOLEAN = false
|  | Enable SSL communication to the WinRM server

|  | Hidden Properties
--- | --- | ---
|  | connectionTimeoutMillis : INTEGER = 1200000
|  | Number of milliseconds Overthere waits for a connection to a remote host to be established
|  | protocol : STRING = cifs
|  | Protocol
|  | tmpFileCreationRetries : INTEGER = 1000
|  | Number of times Overthere attempts to create a temporary file with a unique name
|  | winrmContext : STRING = /wsman
|  | Context used by the WinRM server
|  | winrmEnvelopSize : INTEGER = 153600
|  | Envelop size for WinRM messages
|  | winrmHttpsCertificateTrustStrategy : ENUM [STRICT, SELF_SIGNED, ALLOW_ALL] = STRICT
|  | HTTPS certifiacte trust strategy for WinRM over HTTPS
|  | winrmHttpsHostnameVerificationStrategy : ENUM [STRICT, BROWSER_COMPATIBLE, ALLOW_ALL] = STRICT
|  | HTTPS host name verification strategy for WinRM over HTTPS
|  | winrmLocale : STRING = en-US
|  | Locale to use for WinRM messages
|  | winrmTimeout : STRING = PT60.000S
|  | Timeout to use for WinRM messages in XML schema duration format
|  | tmpDeleteOnDisconnect : BOOLEAN = true
|  | Whether to delete the temporary connection directory when the connection is closed
|  | winrmKerberosAddPortToSpn : BOOLEAN = false
|  | Add the port number (e.g. 5985) to the service principal name (SPN) for which a Kerberos ticket is requested
|  | winrmKerberosDebug : BOOLEAN = false
|  | Enable Kerberos debug messages
|  | winrmKerberosUseHttpSpn : BOOLEAN = false
|  | Use the HTTP protocol in the service principal name (SPN) for which a Kerberos ticket is requested, instead of the default WSMAN protocol

Control Tasks
| checkConnection | Check connection

### overthere.Host

Virtual Type
Type Hierarchy | udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that runs middleware, on which scripts can be executed, etc.

|  | Public Properties
--- | --- | ---
|  | os : ENUM [WINDOWS, UNIX]
|  | Operating system
|  | deploymentGroup : INTEGER
|  | If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
|  | tags : SET_OF_STRING
|  | If set, only deployables with the same tag will be automatically mapped to this container.
|  | temporaryDirectoryPath : STRING
|  | Directory into which temporary files are stored. Will be cleaned up when the connection is closed.

|  | Hidden Properties
--- | --- | ---
|  | protocol : STRING
|  | Protocol to use when connecting to this host
|  | tmpFileCreationRetries : INTEGER = 1000
|  | Number of times Overthere attempts to create a temporary file with a unique name
|  | tmpDeleteOnDisconnect : BOOLEAN = true
|  | Whether to delete the temporary connection directory when the connection is closed

Control Tasks
| checkConnection | Check connection

### overthere.Jumpstation

Virtual Type
Type Hierarchy | overthere.RemoteHost >> overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Base class for jumpstations

|  | Public Properties
--- | --- | ---
|  | deploymentGroup : INTEGER
|  | If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
|  | jumpstation : CI<overthere.Jumpstation >
|  | Jumpstation that should be used to reach this host
|  | tags : SET_OF_STRING
|  | If set, only deployables with the same tag will be automatically mapped to this container.

|  | Hidden Properties
--- | --- | ---
|  | connectionTimeoutMillis : INTEGER = 1200000
|  | Number of milliseconds Overthere waits for a connection to a remote host to be established
|  | os : ENUM [WINDOWS, UNIX] = UNIX
|  | Os
|  | protocol : STRING
|  | Protocol to use when connecting to this host
|  | tmpFileCreationRetries : INTEGER = 1000
|  | Number of times Overthere attempts to create a temporary file with a unique name
|  | temporaryDirectoryPath : STRING
|  | The default platform value (/tmp) suffices as no temporary files will be placed on the jumpstation
|  | tmpDeleteOnDisconnect : BOOLEAN = true
|  | Whether to delete the temporary connection directory when the connection is closed

Control Tasks
| checkConnection | Check connection

### overthere.LocalHost

Type Hierarchy | overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine on which the Deployit Server is running

|  | Public Properties
--- | --- | ---
|  | os : ENUM [WINDOWS, UNIX]
|  | Operating system
|  | deploymentGroup : INTEGER
|  | If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
|  | tags : SET_OF_STRING
|  | If set, only deployables with the same tag will be automatically mapped to this container.
|  | temporaryDirectoryPath : STRING
|  | Directory into which temporary files are stored. Will be cleaned up when the connection is closed.

|  | Hidden Properties
--- | --- | ---
|  | protocol : STRING = local
|  | Protocol
|  | tmpFileCreationRetries : INTEGER = 1000
|  | Number of times Overthere attempts to create a temporary file with a unique name
|  | tmpDeleteOnDisconnect : BOOLEAN = true
|  | Whether to delete the temporary connection directory when the connection is closed

Control Tasks
| checkConnection | Check connection

### overthere.RemoteHost

Virtual Type
Type Hierarchy | overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Description unavailable

|  | Public Properties
--- | --- | ---
|  | os : ENUM [WINDOWS, UNIX]
|  | Operating system
|  | deploymentGroup : INTEGER
|  | If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
|  | jumpstation : CI<overthere.Jumpstation >
|  | Jumpstation that should be used to reach this host
|  | tags : SET_OF_STRING
|  | If set, only deployables with the same tag will be automatically mapped to this container.
|  | temporaryDirectoryPath : STRING
|  | Directory into which temporary files are stored. Will be cleaned up when the connection is closed.

|  | Hidden Properties
--- | --- | ---
|  | connectionTimeoutMillis : INTEGER = 1200000
|  | Number of milliseconds Overthere waits for a connection to a remote host to be established
|  | protocol : STRING
|  | Protocol to use when connecting to this host
|  | tmpFileCreationRetries : INTEGER = 1000
|  | Number of times Overthere attempts to create a temporary file with a unique name
|  | tmpDeleteOnDisconnect : BOOLEAN = true
|  | Whether to delete the temporary connection directory when the connection is closed

Control Tasks
| checkConnection | Check connection

### overthere.SshHost

Type Hierarchy | overthere.RemoteHost >> overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that can be connected to using SSH

|  | Public Properties
--- | --- | ---
|  | address : STRING
|  | Address of the host
|  | connectionType : ENUM [SFTP, SFTP_CYGWIN, SFTP_WINSSHD, SCP, SUDO, INTERACTIVE_SUDO, TUNNEL] = SFTP
|  | Type of SSH connection to create
|  | os : ENUM [WINDOWS, UNIX]
|  | Operating system
|  | port : INTEGER = 22
|  | Port on which the SSH server runs
|  | username : STRING
|  | Username to connect with
|  | deploymentGroup : INTEGER
|  | If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
|  | jumpstation : CI<overthere.Jumpstation >
|  | Jumpstation that should be used to reach this host
|  | passphrase : STRING
|  | Optional passphrase for the private key in the private key file
|  | password : STRING
|  | Password to use for authentication
|  | privateKeyFile : STRING
|  | Private key file to use for authentication
|  | sudoUsername : STRING
|  | Username to sudo to when accessing files or executing commands
|  | tags : SET_OF_STRING
|  | If set, only deployables with the same tag will be automatically mapped to this container.
|  | temporaryDirectoryPath : STRING
|  | Directory into which temporary files are stored. Will be cleaned up when the connection is closed.

|  | Hidden Properties
--- | --- | ---
|  | connectionTimeoutMillis : INTEGER = 1200000
|  | Number of milliseconds Overthere waits for a connection to a remote host to be established
|  | interactiveKeyboardAuthRegex : STRING = .*Password:[ ]?
|  | Regular expression to look for in keyboard-interactive authentication before sending the password
|  | protocol : STRING = ssh
|  | Protocol
|  | sudoCommandPrefix : STRING = sudo -u {0}
|  | Sudo command to prefix to the original command. The placeholder {0} is replaced with the sudoUsername
|  | sudoPasswordPromptRegex : STRING = .*[Pp]assword.*:
|  | Regular expression to look for in interactive sudo before sending the password
|  | tmpFileCreationRetries : INTEGER = 1000
|  | Number of times Overthere attempts to create a temporary file with a unique name
|  | allocateDefaultPty : BOOLEAN = false
|  | If true, a default PTY (dummy:80:24:0:0) is allocated when executing a command
|  | allocatePty : STRING
|  | Specification for the PTY to be allocated when executing a command. The format is TERM:COLS:ROWS:WIDTH:HEIGHT, e.g. xterm:80:24:0:0
|  | sudoOverrideUmask : BOOLEAN = true
|  | If true, permissions are explicitly changed with chmod -R go+rX after uploading a file or directory
|  | sudoPreserveAttributesOnCopyFromTempFile : BOOLEAN = true
|  | If true, files are copied from the connection temporary directory using the -p flag to the cp command
|  | sudoPreserveAttributesOnCopyToTempFile : BOOLEAN = true
|  | If true, files are copied to the connection temporary directory using the -p flag to the cp command
|  | sudoQuoteCommand : BOOLEAN = false
|  | If true, the original command is quoted when it is prefixed with sudoCommandPrefix
|  | tmpDeleteOnDisconnect : BOOLEAN = true
|  | Whether to delete the temporary connection directory when the connection is closed

Control Tasks
| checkConnection | Check connection

### overthere.SshJumpstation

Type Hierarchy | overthere.Jumpstation >> overthere.RemoteHost >> overthere.Host >> udm.BaseContainer >> udm.BaseConfigurationItem
Interfaces | udm.Taggable, udm.ConfigurationItem, udm.Container, overthere.HostContainer

Machine that can be used to create a tunneled connection to a destination host

|  | Public Properties
--- | --- | ---
|  | address : STRING
|  | Address of the host
|  | port : INTEGER = 22
|  | Port on which the SSH server runs
|  | username : STRING
|  | Username to connect with
|  | deploymentGroup : INTEGER
|  | If the group-orchestrator is enabled, all containers with the same deployment group number will be deployed to at the same time. The groups are ordered by this number.
|  | jumpstation : CI<overthere.Jumpstation >
|  | Jumpstation that should be used to reach this host
|  | passphrase : STRING
|  | Optional passphrase for the private key in the private key file
|  | password : STRING
|  | Password to use for authentication
|  | privateKeyFile : STRING
|  | Private key file to use for authentication
|  | tags : SET_OF_STRING
|  | If set, only deployables with the same tag will be automatically mapped to this container.

|  | Hidden Properties
--- | --- | ---
|  | connectionTimeoutMillis : INTEGER = 1200000
|  | Number of milliseconds Overthere waits for a connection to a remote host to be established
|  | connectionType : ENUM [SFTP, SFTP_CYGWIN, SFTP_WINSSHD, SCP, SUDO, INTERACTIVE_SUDO, TUNNEL] = TUNNEL
|  | Connection Type
|  | interactiveKeyboardAuthRegex : STRING = .*Password:[ ]?
|  | Regular expression to look for in keyboard-interactive authentication before sending the password
|  | os : ENUM [WINDOWS, UNIX] = UNIX
|  | Os
|  | portAllocationRangeStart : INTEGER = 1025
|  | Port from where to start looking for freely available ports to use as the local part of an SSH port forward
|  | protocol : STRING = ssh
|  | Protocol
|  | tmpFileCreationRetries : INTEGER = 1000
|  | Number of times Overthere attempts to create a temporary file with a unique name
|  | temporaryDirectoryPath : STRING
|  | The default platform value (/tmp) suffices as no temporary files will be placed on the jumpstation
|  | tmpDeleteOnDisconnect : BOOLEAN = true
|  | Whether to delete the temporary connection directory when the connection is closed

Control Tasks
| checkConnection | Check connection