# 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:

1. 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.

2. 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.

## Exposing more Overthere properties in Deployit

Most of the Overthere connection properties defined in the Overthere documentation are available as regular properties or hidden properties on the `overthere.SshHost` and `overthere.CifsHost` types. If you need access to any additional properties, you can create a `type-modification` in the `ext/synthetic.xml` file like this:

    <type-modification type="overthere.SshHost">
        <property name="listFilesCommand" hidden="true" default="/bin/ls -a1 {0}" />
        <property name="getFileInfoCommand" hidden="true" default="/bin/ls -ld {0}" />
    </type-modification>

# 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] = WINDOWS
|  | Operating system the host runs
|  | password : STRING
|  | Password to use for authentication
|  | username : STRING
|  | Username to connect with
|  | cifsPort : INTEGER = 445
|  | Port on which the CIFS server runs
|  | 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 task | Parameter CI | Attributes | Description
--- | --- | --- | ---
checkConnection |  |  | Checks whether Deployit can transfer files to and execute commands on this host.

### 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 the host 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.

|  | 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 task | Parameter CI | Attributes | Description
--- | --- | --- | ---
checkConnection |  |  | Checks whether Deployit can transfer files to and execute commands on this host.

### 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
--- | --- | ---
|  | 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 task | Parameter CI | Attributes | Description
--- | --- | --- | ---
checkConnection |  |  | Checks whether Deployit can transfer files to and execute commands on this host.

### 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 the host 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.

|  | 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 task | Parameter CI | Attributes | Description
--- | --- | --- | ---
checkConnection |  |  | Checks whether Deployit can transfer files to and execute commands on this host.

### 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 the host runs
|  | 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 task | Parameter CI | Attributes | Description
--- | --- | --- | ---
checkConnection |  |  | Checks whether Deployit can transfer files to and execute commands on this host.

### 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 the host runs
|  | port : INTEGER = 22
|  | Port on which the SSH server runs
|  | username : STRING
|  | Username to connect with
|  | 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 task | Parameter CI | Attributes | Description
--- | --- | --- | ---
checkConnection |  |  | Checks whether Deployit can transfer files to and execute commands on this host.

### 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
|  | 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 task | Parameter CI | Attributes | Description
--- | --- | --- | ---
checkConnection |  |  | Checks whether Deployit can transfer files to and execute commands on this host.