Installing the Host Agent on Windows

Windows installer

This is an automatic installation.

  1. Sign in to Instana, click More -> Agents -> Instana agent installation -> Windows.
  2. From the Technology list, select Windows Installer.
  3. Download Windows installer exe via the download button.

    A GUI guides you through the process of installing the agent and takes care of installing the pre-requisites (.NET Framework 4.5 and a JVM). The installer will also register the agent as a service, set it to start automatically, and start it right after the installation.

    If you prefer the installation to happen without interaction, pass the following parameters to the installer.

    Parameter Description
    INSTANA_AGENT_ENDPOINT Your host agent endpoint
    INSTANA_AGENT_ENDPOINT_PORT The TCP port used for communication, normally 443 (https) (see Agent Communication)
    INSTANA_AGENT_KEY The agent key
    INSTANA_AGENT_MODE Optional setting that lets you set the agent mode the agent is running in.

In addition to these parameters, you can pass in the /quiet switch, which will prevent the GUI from coming up and thus run the installation-process silently without any user interaction.

To run the agent installer silently, run the following command:

AgentBootstrap.exe INSTANA_AGENT_ENDPOINT=<your-host> INSTANA_AGENT_ENDPOINT_PORT=<your-port> INSTANA_AGENT_KEY=<your-key> INSTANA_AGENT_MODE=<apm | infrastructure | off> /quiet

Zip archives

The zip-based installation is a manual. The zip file contains the agent files, but not a JVM, and as such, it is not self-contained.

Prerequisites

  • .net Framework 4.5
  • a Java 8 JVM

Supported JDKs

At the moment, the following JVMs are supported for running the agent:

It is important that the JVM is executable for any user on the system. We recommend using the latest available patch release of the Java distribution of your choice. Be advised that depending on your OS distribution, the packages provided by the OS distributor might not contain strong encryption support due to export control. Using such a package will result in errors like "java.lang.RuntimeException: Could not generate DH key pair."

Install the JDK

We recommend ont of the two following options to install the JDK so that the host agent can be run with it:

  • (easiest) place the JDK under <instana-agent-install-dir>/jvm, ensuring that <instana-agent-install-dir>/jvm/bin/java exists
  • install the JDK under a folder of your choice, and set its path to the environment variable JAVA_HOME; the JAVA_HOME environment variable can be also set to the agent via instana-agent-install-dir>/bin/setenv.bat.

Download the ZIP archive

  1. Sign in to Instana, click More -> Agents -> Instana agent installation -> Windows.
  2. From the Technology list, select Zip Archives.
  3. Select the archive matching your system architecture; 64bit static, 64bit, or 32bit, and then click Download.

    It is automatically preconfigured with your account settings, so you just need to extract and start the agent.

Start the agent

<instana-agent-install-dir>\bin\start.bat

Stop the agent

<instana-agent-install-dir>\bin\stop.bat

Check the status of the agent

<instana-agent-install-dir>\bin\status.bat

As a Service

Installing the agent as a Windows service requires no manual start and you are not required to be signed in.

Service Wrapper Download

A service wrapper is recommended for installation to be as easy as possible. We suggest using WinSW.

Please position the executable file, winsw-VERSION-bin.exe, in the Instana agent folder (a folder of your choice, referred to as <instana-agent-install-dir>) and name it instana-agent.exe. In order to start the agent, Windows will call this wrapper. Details can be found in the configuration file instana-agent.xml in the same directory.

Service Wrapper Configuration File

The following is an example config file for the service wrapper. It should be located in the Instana agent folder with the same name as the wrapper executable, except with the extension .xml (i.e instana-agent.xml).

<service>
 <id>instana-agent</id>
 <name>Instana Agent</name>
 <description>Instana Agent</description>
 <!-- start -->
 <executable>"<instana-agent-install-dir>\bin\karaf.bat"</executable>
 <startargument>daemon</startargument>
 <!-- stop -->
 <stopexecutable>"<instana-agent-install-dir>\bin\karaf.bat"</stopexecutable>
 <stopargument>stop</stopargument>
 <stoptimeout>10sec</stoptimeout>
 <!-- logging -->
 <logpath><instana-agent-install-dir>\data\log</logpath>
 <log mode="roll-by-time">
   <pattern>yyyyMMdd</pattern>
 </log>
</service>

Installing the Wrapper as a Service

Now that the wrapper has been configured and named, the .exe and .xml files with the same name can be run by simply running the following command in the Instana agent directory:

instana-agent.exe install

This installs the wrapper as a service. In order to start it, use:

net start instana-agent-service