Install and Configure Insight Agent

This section describes how to:

  1. Install the Insight Agent using the downloadable agent installer or an RPM package, following the instructions in Install Agent from insight-agent.jar or RHEL Only: Install Agent RPM.

  2. Configure SSL for the agent as described in Configure SSL for Agent, as appropriate.

    Use of SSL for dashboard-agent communication is optional. Note that if you the agent installer you download from the Insight Dashboard will be pre-configured with the dashboard's connection and SSL configuration. So, if you use that installer, and configure SSL for the dashboard prior to downloading the it, you should not need to explicitly configure the agent for SSL.

Prerequisites

Install Agent from insight-agent.jar

This section has instructions for downloading the Insight Agent installer from the dashboard and installing it.

The agent installer is insight-agent.jar. The instructions below describe how to provide agent configuration data interactively. Alternatively, you can provide the configuration values at the command line when your run the installer. All command options are defined in Agent Installer Command Options. If you did not configure the Insight Dashboard's keystore prior to downloading the agent installer, you can manually configure the SSL keystore and trust store for an Insight Agent. See Set Up SSL for Insight Agents.

Perform the following procedure on each machine with application you want to monitor with Insight..

Prerequisites

Procedure

Perform this procedure on each machine that hosts applications you want to monitor.

  1. On the machine that hosts applications you wish to monitor, open the Insight Dashboard in a web browser. For example:

    http://support.apps.home.com:8080/insight.

  2. Click the Administration tab in the dashboard user interface.

  3. On the Administration page, click the Download Agent option in the Support Tools section.

  4. On the agent download page, click the Download Agent button.

    The insight-agent.jar is downloaded.

  5. Copy insight-agent.jar from your downloads directory into the server instance directory where the target applications run.

    For example, in a terminal window, enter the following command on one line:

    prompt$ cp insight-agent.jar /opt/vmware/vfabric-tc-server-standard-2.7.0.RELEASE/myRuntime
  6. Change directory to the server instance directory.

    For example:

    prompt$ cd /opt/vmware/vfabric-tc-server-standard-2.7.0.RELEASE/myRuntime
  7. Run the agent installer.

    prompt$ java -jar insight-agent.jar --install

  8. The installer detects supported containers on the platform and prompts you to approve the target server.

    For example:

    prompt$ Would you like to install Insight agent in the current directory? (/opt/vmware/vfabric-tc-server-standard-2.7.0.RELEASE/myRuntime) [Yn]:

  9. Press return to install the agent into the directory.

  10. You are prompted enter the address of the Insight Dashboard; by default, the IP address of the platform where the Dashboard runs is presented.

    prompt$ Please enter Insight IP address or host name [Default:10.140.104.206]: 
  11. Press return to accept the IP address presented.

  12. You are prompted to enter the user name the agent should use to connect to the Dashboard:

    prompt$ Please enter Insight user name [Default:agent]:
            
  13. You are prompted to enter the password the user should use to connect to the Dashboard:

    prompt$ Please enter Insight password [Default:insight]:
            
  14. Press return to accept the default password.

Agent Installer Command Options

The table below defines the options supported by the insight-agent.jar installer.

Table 2. Agent Installer Command Options

OptionDescription
--catalina_base PATH(Only applicable for agent installed in a Tomcat instance, not for tcServer or JBoss environments.) Use this option to specify the full path to the directory specified by the CATALINA_BASE environment variable for the Tomcat installation.

Default:

If not specified, the value of the path option is used.

--helpDisplays help for installer.
--installInstalls a new agent.
--ip IpAddressSupplies the hostname or IP address of the platform where the Insight Dashboard runs.

Default:

The IP address of the dashboard from which the agent was downloaded.
--jboss_profile profileWhen you install the agent to a Jboss instance, specifies the JBoss configuration profile for the instance to which the Insight Agent is being deployed.

Allowable values include:

  • all

  • default

  • jbossweb-standalone

  • minimal

  • standard

Default:

default
--keystore pathSupplies the path to a keystore you have configured on the agent host, in which case you should also define --keystorepass password.

If you download the agent installer from the dashboard after configuring the dashboard keystore, it is not necessary to set up and configure the agent keystore; agent keystore is automatically set up and configured.

--keystorepass passwordSupplies the password to a keystore you have configured on the agent host, in which case you should also define --keystore path/.

If you download the agent installer from the dashboard after configuring the dashboard keystore, it is not necessary to set up and configure the agent keystore; agent keystore will be automatically set up and configured.

-n

or

--no-questions

Runs the agent installer with default options, instead of interactively.

The installer does not query for user input; it uses the default values for configuration options.

Defaults for --ip, --keystore, --keystorepass, --truststore and the transport protocol option are derived from the configuration of the Dashboard at the time you downloaded the agent installer.

The installer runs an auto-discovery process to find the runtime in which to install the agent. It looks for one of the following supported installations: Tomcat 6 and 7; jboss 5.0.1, 5.1.0, 6.0.0 and 6.1.0; tcServer 2.1, 2.5, 2.6 and 2.7

nioSpecifies plain NIO (not NIO over SSL) for agent-dashboard communication.

Default:

n/a

niosslSpecifies NIO over SSL for agent-dashboard communication.

Default:

n/a

--password passwordSupplies the password the agent will use to connect to the dashboard.

If you do not supply the password at the command line, the installer prompts for it interactively.

Default:

insight

--path password

Supplies the path to the runtime instance where you want to deploy the agent.

This directory contains the runtime's standard subdirectories: /conf, /logs, /webapps, /work, and /temp.

Default:

current directory

--reinstallReinstalls the agent. The installer removes the existing agent installation.
--service TomcatServiceNameIf you are installing the agent to a Tomcat instance that runs on Windows, provides the service name of the Tomcat instance.

To determine the service name, select Run from the Windows Start menu, enter services.msc, and click OK.

Default:

n/a

--sslSpecifies SSL for communication between the agent and the dashboard.

Default:

The default value is the value set for transport protocol that was defined for the dashboard at the time the agent installer was downloaded.
--tmpSpecifies the path to the temp directory for the runtime instance to which you are installing the agent.

Default:

Defaults to the temp directory of the runtime instance to which you are installing the agent. For example, if you are installing the agent in a tc Server instance named AgentInstance, the default temp directory is: tcServerHome/AgentInstance/tmp
--truststore path 
--uninstallUninstalls the agent.

n/a

Default:

n/a

--updateReconfigures the location of the dashboard, credentials for connecting to the agent, and the transport protocol to use for communicating with the dashboard. The installer prompts for updated connection information.

Default:

n/a

--username UserNameSupplies the username the agent uses to connect to the dashboard.

Default:

agent


RHEL Only: Install Agent RPM

This section has instructions for installing the Insight Agent from VMware's RPM repository to a tc Server Standard installation running in an RHEL VM.

VMware recommends the use of yum for RPM installations.

Prerequisites

Install the repository RPMs as described in Install vFabric Repository RPMs.

On each RHEL VM with a tc Server Standard instance running application you want to monitor with Insight:

  1. Log in as the root user (or as another user with sudo privileges) to the target RHEL machine, and start a terminal.

  2. Use the yum to install the agent RPM

    prompt# yum install vfabric-insight-agent

    yum resolves dependencies and displays the packages it plans to install.

  3. Enter y at the prompt to begin the installation. If you have not already accepted the VMware license terms you are prompted to, and you must do so to continue.

    If the installation is successful, you will see a Complete! message at the end.

    The yum command installs the insight-agent template in the /opt/vmware/vfabric-tc-server-standard/templates directory.

  4. Create the Insight Agent:

    For information about thetcruntime-instance command and supported command options, see the tcruntime-instance.sh reference information in Getting Started with tc Server.

Create and Start Insight Agent

This section has instructions for creating an Insight Agent from the insight-agent template (rather than using the insight-agent.jar installer).

Follow the steps in this section if you installed the agent template from an RPM, as described in the previous section.

You do not need to perform this procedure if you installed the agent using the insight-agent.jar installer.

  1. In a terminal window, change to the tc Server home directory, for example:

    /opt/vmware/vfabric-tc-server-standard-2.7.0.RELEASE/

  2. Create a tc Server instance with tcruntime-instance.sh, using the insight-agent template. For example, to create an instance named "myAgent":

    ./tcruntime-instance.sh create myAgent -t insight-agent
  3. Start the Spring Insight Agent with the tcruntime-ctl.sh or tcruntime-ctl.bat command.

    • On Unix systems:

      ./tcruntime-ctl.sh myAgent start

    • On a Windows system, install a Windows Service for the instance before you start it the first time. (After that, you can control the service from the Windows services control panel.) Enter these commands to install and start the service:

      tcruntime-ctl.bat myAgent install

      tcruntime-ctl.bat myAgent start

    (For information about thetcruntime-ctl command and supported command options, see the tcruntime-ctl Command Reference section in Getting Started with tc Server. )

Set Up SSL for Insight Agents

This section has instructions for manually configuring the SSL keystore and trust store for an Insight Agent.

Note

If you configured the Insight Dashboard's keystoreprior to downloading the agent installer, the agent installer automatically generates SSL keystore and truststore, so you do not need to perform the steps below.

The instructions assume you have already performed the steps in Configure SSL for Insight Dashboard.

Procedure

  1. Copy the dashboard_cert certificate file you exported from the dashboard's keystore onto the each Agent host computer, or make it available on a network drive or a thumb drive.

  2. Change to the directory where you want to create the Insight Agent keystore and truststore files, for example, CATALINA_BASE/conf.

  3. Create a keystore for the agent, if one does not already exist.

    keytool -genkey -alias agent -keyalg RSA -keystore agent.keystore
  4. When prompted, enter the requested information.

    The identification information is encoded into the Agent's certificate. Make a note of the keystore password you create for later steps. The command creates the agent.keystore file in the current directory.

  5. Create a truststore and import the dashboard public certificate.

    keytool -import -alias dashboard -keystore agent.truststore -f /full/path/to/dashboard_cert
  6. Edit CATALINA_BASE/insight/insight.properties and change the dashboard.jms.connect.uri property to use the SSL scheme.

    dashboard.jms.connect.uri: ssl://dashboardHost:20234
  7. Set the Java system properties to specify the location of the agent.keystore file, the location of the agent.truststore file, and the keystore password.

    It is easiest to do this in the CATALINA_BASE/bin/setenv.sh script. Edit the setenv.sh script and add the following lines before the JAVA_OPTS=... line.

    SSL_KEYSTORE="/full/path/to/agent.keystore" # e.g. "$CATALINA_BASE/conf/agent.keystore"
    SSL_TRUSTSTORE="/full/path/to/agent.trustore" # e.g. "$CATALINA_BASE/conf/agent.truststore"
    SSL_KEYSTORE_PW="keystore_password"
    SSL_OPTS="-Djavax.net.ssl.keystore=$SSL_KEYSTORE -Djavax.net.ssl.truststore=$SSL_TRUSTSTORE \
        -Djavax.net.ssl.keystorePassword=$SSL_KEYSTORE_PW"
  8. Add the SSL_OPTS environment variable to the JAVA_OPTS variable.

    JAVA_OPTS="$JVM_OPTS $AGENT_PATHS $JAVA_AGENTS $JAVA_LIBARARY_PATH $SSL_OPTS"
  9. To enable these changes, restart the tc Runtime instance.