Built by Maven

Remoting Transport plugin

This plugin allows the framework server to connect to remote targets via remote agent.

Remoting allows direct connection to an agent running on a target server. This agent is simply a running version of the midvision-deployment-orchestration.jar, started as a windows service or via a unix shell script running as a daemon.

This transport plugin for RapidDeploy enables RapidDeploy to connect to a target using a remote agent.

The remote agent is a java based agent that requires just one jar file to run. Specific agent settings are configured in a simple xml file. The agent supports point-to-point and multicasting. It also supports SSL encryption and a security mechanism that controls which framework servers or other clients can communicate with this agent.

There is also support for auto-update of agent files and auto-restart of the agent after files have been updated - settable in the agent xml file. This means that you can choose, on an agent by agent basis, t o have updates to the agent or any plugins on the framework server automatically pushed out to the registered agents.

Agents can communicate with each other such that via an orchestration jobs can hop from one agent to another downstream one to perform actions on servers one or more steps removed from the framework server. This is useful where, for example, a target server has no direct line of sight from the framework server.

Prerequisites

The remote agent should be deployed to the remote target and must be online in order to run jobs on the selected target.

Download the agent from our website.

Install by unzipping the downloaded zip file into a folder of your choice.

Server side requirements

The agent requires Java 1.8. This will be installed under the midvision-agent folder when you run the start-remoting-server script.

Remoting transport plugin parameters:

List and description of all user interface plugin parameters.

Configuring remote agent logging.

Starting the agent

Unix Linux

If you have an Ssh connection to the target, you can start a deployed agent from the server panel.

Alternatively you can start the agent on remote server. The remote agent is managed from the agent package bin directory using the following scripts:

        ./start-remoting-server.sh
        ./stop-remoting-server.sh

Windows

You can run the agent as a windows service, or start it manually as for Unix/Linux.

Protocols

Detection (Multicast) mode

The RapidDeploy GUI application can perform a detection function allowing it to detect when each agent comes online or goes offline. In this mode it is not necessary to configure the target port for each RapidDeploy target deployment manager servers agent on the servers panel, as detection will automatically determining the locator of the target agent.

In order to use this mode, multicasting must be enabled between the RapidDeploy server hosting the Rapiddeploy application, and the remote agent servers.

You should configure a multicast group in which all the servers participating in RapidDeploy deployments are members.

On each of the agents configure midvision-remoting-server.xml:

<resource type="multicast.address">Address_of_Multicast_group</resource>

You can also configure the UDP port for detection via the multicast.port property on both the client and the server in the same files as above. If the multicast.port property is left unset, then multicasting will be disabled and the agents multicast detector will not be started.

Disabling multicasting on the framework server.

In the rapiddeploy_default.properties file, unset the multicast.port property. Multicasting is now disabled for the framework server.

Point to Point Mode

Connection Port Settings

In this case, on the RapidDeploy GUI, simply go to the server panel for the server running the agent you want to connect to and make sure the Agent port and Secure port are set. These ports should match the ports set in the midvision-remoting-server.xml file on the agent as follows:

<resource type="port">20000</resource>
<resource type="secure.port">20443</resource>
Secondary Bind Port (Optional)

There are some optional ports which can be set both in RapidDeploy GUI and in the midvision-remoting-server.xml. They are for the secondary binding connection. These ports are automatically defined if they are not set before hand. 

<resource type="bind.ports">20100,20101,20102</resource>
<resource type="secure.bind.ports">20500,20501,20502</resource>

Firewall considerations

The RapidDeploy client talks to the agent using a specific socket implementation. Currently supported are bisocket and sslbisocket.

Bisocket implementation is based on two socket binding connection via primary and secondary ports. Additionally callback mechanism is used to stream logs back to the client and stream deployment files from client to server. This means that there will be at least four ports, primary bind port, secondary port, callback primary bind port and callback secondary bind port, opened during the communication between client and server. SSS connection implementation is optional and if it is required it will require two additional ports for secure connection.

These are set on the client side (RapidDeploy) via the remoting transport plugin form and on the server side (Remote Agent) via configuration file midvision-remoting-server.xml. Secondary bind port can be one or a set of ports separated by commas.

For example, the minimal configuration ports for bisocket with secure connection enabled:

On server side (Remote Agent), in the configuration file midvision-remoting-server.xml:

        <resource type="port">20000</resource>
        <resource type="secure.port">20443</resource>
        <resource type="bind.ports">20001</resource>
        <resource type="secure.bind.ports">20444</resource>

On client side (RapidDeploy), in the remoting transport plugin form:

        Agent Port: 20000:
        Agent Bind Ports: 20001
        Secure Agent Port: 20443:
        Secure Agent Bind Ports: 20444
        Callback Port: 20500
        Callback Bind Ports: 20501
Troubleshooting

To diagnose network/firewall issues look out for attempts to connect back to the framework server by the agent

  • If the target server where the agent is running cannot identify the framework server by the name the framework server sends to the target server, it will fail
  • If it is a firewall issue on the target server, you can run: 
    netstat -an | grep SYN
  • if there are any SYN_SENT or SYN_REC entries on the relevant ports (or ANY occurences of those states really) then there is an issue connecting to or from the agent server.

Starting the agent as a service

Navigate to the directory where the agent is installed.

On Unix: run rdagent stop or rdagent start to stop or start the agent.
On Unix: Add the rdagent command to /etc/rc.d/rc2.d directory and /etc/init.d directories as required.
On Unix: Add the rdagent script to the /etc/inittab as a respawned process as required.
On Windows: Add the agent as a service.

Updating/Restarting the agent.

This feature is only supported on Unix systems.

Set the following parameters in the midvision-remoting-server.xml

Configure the following parameters:

<resource type="agent.auto.update">true</resource>
<resource type="agent.auto.restart">true</resource>

Setting agent.auto.update to true causes any changes to the agent software stored on the client to be copied to the server. A change means a change to the checksum of any of the defined files on the server. Setting agent.auto.restart to true causes the agent to be restarted when all of the following conditions are met:

  • agent.auto.update is true;
  • An update to a core agent file is detected;
  • No deployments are currently in progress.

Backward Compatibility

Set the following parameters in the midvision-remoting-server.xml

Configure the following parameters:

        <resource type="backward.compatibility">true</resource>

Setting backward.compatibility to true enables the agent to support RapidDeploy versions 2.X and 3.X . If is not defined or set in false, the agent will supports only version 3.X by default.

Secure connection

The remote agent supports secure connection between remoting clients (RapidDeploy web application) and servers (Remote Agent instance).

The default security values are defined in rapiddeploy.properties file within both contexts, in RapidDeploy web application and Remote Agent instances as it is explained below. But the default values can be overridden in RapidDeploy web application for each target server context via transport plugin form located in server details page.

In other words, all Remote Agent instances can have particular and common security values. So, in RapidDeploy web application, the default values can be configured in order to match the common security values defined in all the Remote Agent instances and also it can be configured particular security values for each server in the transport plugin form. it will override the default values defined in the rapiddeploy.properties file.

The security implemented in the remote agent consist in KeyStores and TrustStores for each end point, and asymmetric encryption.

The KeyStores contains the private key (RSA or DSA) and the CA root and intermediate certificates. (Certificates chain)

The TrustStores only contains the CA root and intermediate certificates. (Certificates chain)

KeyStores are for private use and information decryption.

TrustStore are for store public Certificates for asymmetric encryption.

Both the client (RapidDeploy web application) and the server (Remote Agent instance installed) has their KeyStores and TrustStores located by default in MV_HOME/remoting/ssl and MV_AGENT_HOME/remoting/ssl.

There are 4 cryptographic credentials modes for management and distribution:

Auto Mode: is the default mode in which credentials are automatically generated and distributed and exchanged between both ends, providing an encrypted communication channel to ensure a secure connection between clients and servers.

On Server side Remote Agent KeyStore and TrustStore are created automatically if they don't exist or are invalid:

  • MV_AGENT_HOME/remoting/ssl/.remoting-keystore (Default Server KeyStore)
  • MV_AGENT_HOME/remoting/ssl/.remoting-truststore (Default Server TrustStore for client)

On Client side RapidDeploy KeyStore and TrustStore are created automatically if they don't exist or are invalid. >>

  • MV_HOME/remoting/ssl/.rapiddeploy-keystore
  • MV_HOME/remoting/ssl/.rapiddeploy-truststore

Manual Mode: custom generation, distribution and configuration of SSL credentials. There is no management of credentials which means that credentials are read, verified based on configuration and used on SSL communication. This mode include certificate path validation including certificate valid date.

Two-way mode: custom generation and configuration, automatically distributed and exchanged between both ends credentials managed via two-way SSL handshake in which certificates are exchanged. This mode include certificate path validation including certificate valid date.

Two-way-strict mode: Same as two-way mode but including hostname validation between both ends. The hostname are verified against the common name (CN) in the subject DN value defined from last intermediate certificate. This mode include certificate path validation including certificate valid date.

Self-signed certificate example: 

Owner: CN=Hostname, OU=RapidDeploy, O=MidVision, L=City of London, ST=London, C=UK
Issuer: CN=Hostname, OU=RapidDeploy, O=MidVision, L=City of London, ST=London, C=UK
Serial number: 51f29105
Valid from: Fri Jul 26 12:08:53 ART 2013 until: Mon Jul 21 12:08:53 ART 2014
Certificate fingerprints:
         MD5:  AB:BD:B4:DA:76:0C:D5:A2:1F:7E:B6:44:DE:1F:46:CE
         SHA1: 1A:91:80:9C:40:93:55:2F:05:E7:92:3F:A7:AA:74:22:78:75:D4:2E
         Signature algorithm name: SHA1withRSA
         Version: 3


Default Security Properties

This configuration file is usually located in MV_AGENT_HOME/bin/rapiddeploy.properties (Remote Agent)

rapiddeploy.security.remoting.client.alias=remoting
rapiddeploy.security.remoting.client.privatekey.password={_MV@ENC#_}+JAFX60oYq4=
rapiddeploy.security.remoting.client.keystore.file.path=${MV_HOME}/remoting/ssl/.rapiddeploy-keystore
rapiddeploy.security.remoting.client.keystore.password={_MV@ENC#_}/Pd0rZPtkz3VCLTV9ICZ8A==
rapiddeploy.security.remoting.client.keystore.type=JCEKS
rapiddeploy.security.remoting.client.truststore.file.path=${MV_HOME}/remoting/ssl/.rapiddeploy-truststore
rapiddeploy.security.remoting.client.truststore.password={_MV@ENC#_}/Pd0rZPtkz3VCLTV9ICZ8A==
rapiddeploy.security.remoting.client.truststore.type=JCEKS
rapiddeploy.security.remoting.client.credentials.mode=auto

rapiddeploy.security.remoting.server.alias=remoting
rapiddeploy.security.remoting.server.privatekey.password={_MV@ENC#_}+LaMt7eX99M=
rapiddeploy.security.remoting.server.keystore.file.path=${MV_HOME}/remoting/ssl/.remoting-keystore
rapiddeploy.security.remoting.server.keystore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.server.keystore.type=JCEKS
rapiddeploy.security.remoting.server.truststore.file.path=${MV_HOME}/remoting/ssl/.remoting-truststore
rapiddeploy.security.remoting.server.truststore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.server.truststore.type=JCEKS
rapiddeploy.security.remoting.server.credentials.mode=auto

Where:

  • rapiddeploy.security.remoting.client.alias is the alias key used on client (RapidDeploy) KeyStore and TrustStore.
  • rapiddeploy.security.remoting.client.privatekey.password is the secret password value for private key + CA Certificates chain protection on client (RapidDeploy) KeyStore
  • rapiddeploy.security.remoting.client.keystore.file.path is the file path of the client (RapidDeploy) KeyStore
  • rapiddeploy.security.remoting.client.keystore.password is the secret password value for client (RapidDeploy) KeyStore protection
  • rapiddeploy.security.remoting.client.keystore.type is the client KeyStore type. e.g JKS, JCEKS, PKCS12
  • rapiddeploy.security.remoting.client.truststore.file.path is the file path of the client (RapidDeploy) TrustStore
  • rapiddeploy.security.remoting.client.truststore.password is the secret password value for client (RapidDeploy) TrustStore protection
  • rapiddeploy.security.remoting.client.truststore.type is the the client TrustStore type. e.g JKS, JCEKS, PKCS12
  • rapiddeploy.security.remoting.credentials.mode is the credentials handling mode, available modes are "auto", "manual", "two-way" and "two-way-strict".
  • rapiddeploy.security.remoting.server.alias is the alias of the stored private key + CA Certificates chain in the server (Remote Agent) KeyStore.
  • rapiddeploy.security.remoting.server.privatekey.password is the secret password value for protection of the stored private key + CA Certificates chain in the server (Remote Agent) KeyStore.
  • rapiddeploy.security.remoting.server.keystore.file.path is the file path of the server (Remote Agent) KeyStore.
  • rapiddeploy.security.remoting.server.keystore.password is the secret password value for server (Remote Agent) KeyStore protection
  • rapiddeploy.security.remoting.server.keystore.type is the server KeyStore type. e.g JKS, JCEKS, PKCS12
  • rapiddeploy.security.remoting.server.truststore.file.path is the file path of the server (Remote Agent) TrustStore
  • rapiddeploy.security.remoting.server.truststore.password is the secret password value for server (Remote Agent) TrustStore protection
  • rapiddeploy.security.remoting.server.truststore.type is the server TrustStore type. e.g JKS, JCEKS, PKCS12
  • rapiddeploy.security.remoting.server.credentials.mode is the credentials handling mode, available modes are "auto", "manual", "two-way" and "two-way-strict".

Password values can be set in plain text or encrypted by Property Encryption tool. Through this tool, enter the server or client alias value as property key and the password as property value, then copy and paste the output value.


Using Manual Secure Credentials Mode:

  1. Shutdown the server side (Remote Agent Instance) via MV_AGENT_HOME/bin/stop-remoting-server script (or just close the console where it is running)
  2. Setup remoting security configuration as it is explained above in both server (Remote Agent) and client (RapidDeploy) instances.

    On server side you need to configure:

    rapiddeploy.security.remoting.server.alias=remoting
rapiddeploy.security.remoting.server.privatekey.password={_MV@ENC#_}+LaMt7eX99M=
rapiddeploy.security.remoting.server.keystore.file.path=${MV_HOME}/remoting/ssl/.remoting-keystore
rapiddeploy.security.remoting.server.keystore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.server.keystore.type=JCEKS
rapiddeploy.security.remoting.server.truststore.file.path=${MV_HOME}/remoting/ssl/.remoting-truststore
rapiddeploy.security.remoting.server.truststore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.server.truststore.type=JCEKS
rapiddeploy.security.remoting.server.credentials.mode=manual

    On client side you need to configure (Default values):

    rapiddeploy.security.remoting.client.alias=remoting
rapiddeploy.security.remoting.client.privatekey.password={_MV@ENC#_}+LaMt7eX99M=
rapiddeploy.security.remoting.client.keystore.file.path=${MV_HOME}/remoting/ssl/.remoting-keystore
rapiddeploy.security.remoting.client.keystore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.client.keystore.type=JCEKS
rapiddeploy.security.remoting.client.truststore.file.path=${MV_HOME}/remoting/ssl/.remoting-truststore
rapiddeploy.security.remoting.client.truststore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.client.truststore.type=JCEKS
rapiddeploy.security.remoting.client.credentials.mode=manual

    OPTIONAL: on client side you can override the remoting transport plugin for each server, please read help text on each plugin field to configure it properly.

  3. Replace or add KeyStores and TrustStores files by custom client (RapidDeploy) and/or server (Remote Agent) ones based on the remoting security configurations. By default they are ".remoting-keystore" and ".remoting-truststore" located on MV_AGENT_HOME/remoting/ssl, ".rapiddeploy-keystore" and ".rapiddeploy-truststore" located on MV_HOME/remoting/ssl.
  4. Start the server side (Remote Agent Instance) via MV_AGENT_HOME/bin/start-remoting-server script


Using Two-way and Two-way-strict Secure Credentials Modes:

  1. Shutdown the server side (Remote Agent Instance) via MV_AGENT_HOME/bin/stop-remoting-server script (or just close the console where it is running)
  2. Setup remoting security configuration as it is explained above in both server (Remote Agent) and client (RapidDeploy) instances.

    On server side you need to configure:

    rapiddeploy.security.remoting.server.alias=remoting
rapiddeploy.security.remoting.server.privatekey.password={_MV@ENC#_}+LaMt7eX99M=
rapiddeploy.security.remoting.server.keystore.file.path=${MV_HOME}/remoting/ssl/server/my_server_keystore.jks
rapiddeploy.security.remoting.server.keystore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.server.keystore.type=JKS
rapiddeploy.security.remoting.server.truststore.file.path=${MV_HOME}/remoting/ssl/server/my_server_truststore.jks
rapiddeploy.security.remoting.server.truststore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.server.truststore.type=JKS
rapiddeploy.security.remoting.server.credentials.mode=two-way-strict

    On client side you need to configure (Default values):

    rapiddeploy.security.remoting.client.alias=remoting
rapiddeploy.security.remoting.client.privatekey.password={_MV@ENC#_}+LaMt7eX99M=
rapiddeploy.security.remoting.client.keystore.file.path=${MV_HOME}/remoting/ssl/.remoting-keystore
rapiddeploy.security.remoting.client.keystore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.client.keystore.type=JKS
rapiddeploy.security.remoting.client.truststore.file.path=${MV_HOME}/remoting/ssl/.remoting-truststore
rapiddeploy.security.remoting.client.truststore.password={_MV@ENC#_}/Pd0rZPtkz2K6sCr24MxSA==
rapiddeploy.security.remoting.client.truststore.type=JKS
rapiddeploy.security.remoting.client.credentials.mode=two-way-strict

    OPTIONAL: on client side you can override the remoting transport plugin for each server, please read help text on each plugin field to configure it properly.

  3. Replace or add KeyStores files in the client path (RapidDeploy) and/or server (Remote Agent) path based on the remoting security configurations.
  4. Start the server side (Remote Agent Instance) via MV_AGENT_HOME/bin/start-remoting-server script
  5. Once the client establishes a new secure connection, the new credentials will be distributed automatically in both sides stored in the TrustStores which will be automatically created if they do not exist.

Connection Authorisation

You can also configure which RapidDeploy or other agent clients can communicate with this agent by setting the following parameters in the midvision-remoting-server.xml:

<resource type="auth.servers">gui@localhost,gui@mv.cloud.002,rduser/{_MV@ENC#_}myqZ6/6EPDYI+TquGwfXIw==@mv.cloud.003,rdadmin@mv.cloud.005,mv.cloud.001</resource>

This is a comma separated list of [username[/password]@]hostname entries that are allowed to communicate with this agent.

If this resource is not set, everyone can communicate with this agent.

If the username is omitted, any user from the hostname may have access

The special entry gui@hostname, means the connection is restricted to RapidDeploy framework servers on that hostname and no other connection is permitted.

If the password is set, which is optional, the username must be set. Password value can in plain text or encrypted by Property Encryption tool. Through this tool, enter the user name value as property key and password as property value and copy and paste the output value.

Please, be sure of setting up the password value in both places, RapidDeploy property file (%MV_HOME%/bin/rapiddeploy.properties) and Remote Agent settings file (%MV_AGENT_HOME/remoting/midvision-remoting-server.xml). Optionally this can overridden via the remoting transport plugin for each server, please read help text on each plugin field to configure it properly. 

rapiddeploy.security.remoting.username=mvadmin
rapiddeploy.security.remoting.password={_MV@ENC#_}WG/1f5S+yZQ=

Further reading