Installing the agent

Requirements

The Following requirements should be observed:

  • Java JRE 1.8. Framework server GUI can be used to copy the JRE to the target automatically.
  • A location on the server should contain the following files: log4j.properties, midvision-deploy-orchestration.jar, midvision-remoting-server.xml. These files can be copied to the target automatically from the framework server GUI.
  • Optional: Add the server to a multicast group to make use of detection.

Basic Installation

The RapidDeploy web application (RapidDeploy UI) comes pre-installed with an internal agent which is started by default whenever RapidDeploy web application is started. There is therefore no need to install an agent on the framework server.

The agent is a stand-alone java application. Jobs may be invoked from the framework server GUI via SSH or by direct connection to the target server (also known as "Remoting").

The agent allows direct communication from the framework server using a bi-directional socket connection. This feature is particularly useful for implementations where the SSH transport cannot be used.

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.

Therefore the basic installation is to simply unzip the MidVision binary to a directory of your choosing. This will create a midvision directory structure.

e.g.

c:\midvision-agent
/usr/midvision-agent

This location is referred to as MV_AGENT_HOME

Starting The Agent

The Agent is shipped with a Java Runtime Environment for the target system. Supplied with the agent are startup scripts which can be modified to suit your preferences, for example, you may wish to use your own JRE which will require some modification of the script. To start the Agent exeucute the start-up script.

e.g.

start-remoting-server.bat (double click the icon on Windows)
./start-remoting-server.sh (execute as written on Unix)

Verifying Startup

By Default the agent listens on port 20000. In Windows a second command window s launched and for all platforms log files are generated at startup in the MV_AGENT_HOME/logs. Following a successful start up, the log (midvision-deploy-orchestration.log) shows a message at the bottom as follows:

Agent has been started, now listening.

In addition you will now be able to test the agent from within the framework server. Details for this can be found in the documentation.

Troubleshooting

The basic installation typically works straight out of the box. Logfiles should be investigated and some platform features should be noted

Logfiles are located in MV_AGENT_HOME/logs

AIX typically does not apply appropriate permissions to execute scripts and binaries for newly created files. In that instance when the agent package is unzipped the start-remoting-server.sh scripts are not executable.

Furthermore when the start script is run, if you are relying on the shipped Java Runtime Environment you may need to ensure that the Java executable is executable (this is extracted from a zip file the first time the start-web-app.sh is run. Therefore you may need to run a chmod command a number of times.

e.g.

chmod -R 755 MV_AGENT_HOME

Ports may already be in use. See advanced configurations for details about changing ports The default port for the agent is 20000

Advanced Configuration

Detection (Multicast) mode

The framework server 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 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 framework server hosting the application, and the target agent servers (Deployment Manager servers).

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

In the framework server configure rapiddeploy_default.properties:

multicast.address=<Address_of_Multicast_group>

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.

Point to Point Mode

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

                <resource type="port">20000</resource>

For SSL connection:

                <resource type="secure.port">20443</resource>

Remote Agent have a secondary listening port (Bind port) which as default is auto selected, but it could be manually set. This port should match the port set in the midvision-remoting-server.xml file on the agent as follows:

                <resource type="bind.ports">20100,20101,20102</resource>

For SSL connection:

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

Firewall considerations The framework server (client) talks to the agent (server) using a specific socket implementation. Currently supported are socket and bisocket. These are set on the client with remoting.socket.implementation and on the agent with transport properties.

If there is a firewall between framework server client and agent server, the callback mechanism used to stream logs back to the client, and stream deployment files from client to server will not work in socket mode as the callback opens a new port from server back to client in the ephemeral port range and this port is not known in advance.

Instead use the bisocket mode which allows callback from the server back to the client on the same connection made from the client to the server.

Starting/stopping the agent

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.

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

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

In addition to these settings, you have to configure your agent service to re spawn once it is killed, so the agent will stop itself when the above conditions have been met, and your OS has to start it again. You can make your services re spawn by configuring it in inittab (Unix/Linux), or on Recovery tab (Windows).

Example configuration to re spawn a service on Linux/Unix

First of all, configure RapidDeploy agent to be startable and stoppable as a service. Create a file called rdagent under init.d folder.

        cd /etc/init.d
        vi rdagent

Implement the start and stop functionality for the service by pasting the following content, replacing MV_HOME value with the current RD installation location. The agent will be started within the service start process, not started in another separate one. This is required in order to configure the agent to be restarted automatically.

        #!/bin/sh
        # service to start/stop RapidDeploy Remote Agent

        case $1 in
        start)

        export MV_HOME=/home/midvision/mv_home/midvision
        export REMOTING_XML="$MV_HOME/remoting/midvision-remoting-server.xml"
        export JRE_HOME="$MV_HOME/web-apps/jre"
        export JAVA_OPTS="-Xms1024m -Xmx1024m -XX:MaxPermSize=512m -Drapiddeploy.properties=$MV_HOME/bin/rapiddeploy.properties -DMV_HOME=$MV_HOME"
        CLASSPATH=
        for i in `/bin/ls "$MV_HOME"/lib/*.jar`; do
                if [ -f ${i} ]; then
                        CLASSPATH=${i}:${CLASSPATH}
                fi
        done
        for i in `/bin/ls "$MV_HOME"/ext-lib/*.jar`; do
                if [ -f ${i} ]; then
                        CLASSPATH=${i}:${CLASSPATH}
                fi
        done
        export CLASSPATH
        umask 022
        
        "$JRE_HOME"/bin/java -cp ${CLASSPATH} ${JAVA_OPTS} com.midvision.rapiddeploy.domain.task.core.JobRunner definition="$REMOTING_XML" name=midvision-remoting-server
        
        ;;
        stop)
        cd $MV_HOME/bin;./stop-remoting-server.sh
        esac

Make rdagent file executable.

        chmod 755 rdagent

Create a configuration file for the service in init folder.

        cd /etc/init    
        vi rdagent.conf

Paste the following content to configure the re spawn settings. Change the last line to refine the restart conditions.

        #!upstart
        description "rdagent"
        
        exec su -l midvision -c 'service rdagent start'
        
        respawn
        
        #stop the agent 3 times in 60 seconds to give up respawn
        respawn limit 3 60

In order to start the agent with re spawn, run the following command:

        start rdagent

To stop the agent from re spawn, run

        stop rdagent

IPv6 Support

If you want to use the agent for IPv6, you will need to amend the RapidDeploy MV_HOME/bin/start-remoting-server.sh or bat file. Amend the following line to remove the -Djava.net.preferIPv4Stack=true

Change:

export JAVA_OPTS="-Dcom.sun.xml.bind.v2.bytecode.ClassTailor.noOptimize=true -Xms1024m -Xmx1024m -XX:NewSize=512m -XX:MaxNewSize=512m -XX:MetaspaceSize=100m -XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC -XX:+CMSParallelRemarkEnabled -XX:+UseCMSInitiatingOccupancyOnly -XX:CMSInitiatingOccupancyFraction=70 -XX:+ScavengeBeforeFullGC -XX:+CMSScavengeBeforeRemark -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=$MV_HOME/logs/midvisionhd1.hprof -Drapiddeploy.properties=$MV_HOME/bin/rapiddeploy.properties -DMV_HOME=$MV_HOME -Djava.net.preferIPv4Stack=true"

To:

export JAVA_OPTS="-Dcom.sun.xml.bind.v2.bytecode.ClassTailor.noOptimize=true -Xms1024m -Xmx1024m -XX:NewSize=512m -XX:MaxNewSize=512m -XX:MetaspaceSize=100m -XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC -XX:+CMSParallelRemarkEnabled -XX:+UseCMSInitiatingOccupancyOnly -XX:CMSInitiatingOccupancyFraction=70 -XX:+ScavengeBeforeFullGC -XX:+CMSScavengeBeforeRemark -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=$MV_HOME/logs/midvisionhd1.hprof -Drapiddeploy.properties=$MV_HOME/bin/rapiddeploy.properties -DMV_HOME=$MV_HOME"