On-Premise Agent configuration

An Agent is a small Docker container running on a physical machine. It provides the following features:

  • Monitor your system: monitor various parts of your system,
  • Load Generator: start / stop / remove JMeter containers to run your load tests.

The Agents table shows the following information:

Column Description
State Green when connected to the server, else Red
IP IP address of the computer running the agent
Last Update  When the agent has been updated for the last time
Provider Provider Name associated to this agent
Region Region Name associated to this agent
Name  Agent name
Version Docker version and Operating System
Free Memory The server memory information (total and available for load tests).
Containers Number of Docker containers running on this machine


For best efficiency, always use the same hardware configuration for all your agents.


OctoPerf On-Premise agents have the following installation requirements:

  • CPU: At least 4 cores, Intel Core I7 or Xeon recommended,
  • RAM: At least 4GB RAM, 8GB recommended,
  • Operating system: Linux, Ubuntu 16.04LTS, 18.04LTS or greater is recommended. Any Distribution which supports the latest Docker versions. (See Docker Install Docs for more info)
  • Server: both physical and virtual machines are supported,
  • Software: Docker must be installed. Docker 17.09CE or newer is recommended.


RHEL distributions are not supported by Docker. Prefer Ubuntu or CentOS.


The machines used as load generators must:

  • Have a constant access over HTTPS to,
  • Have enough Free RAM Memory (see table below),

You may also use at least quad-cores processor machines, with 10GB free hard-disk space.

The table below gives an overview of the amount of virtual users you can run depending on the instance memory and using the default configuration:

  • 128MB allocated to start JMeter,
  • 5MB additional for each virtual user,
  • 70% of the machine memory dedicated to the load tests.
Memory (MB) Number of virtual users
4096 547
8192 1121
16384 2242


Bare-metal Linux machines are strongly recommended for running the load tests. You can use multiple machines to simulate higher loads.


We suggest to use no more than 70% of available RAM to prevent any performance issue. Some memory must be left for the operating system and filesystem cache.


We recommend to use small (8Go) to medium (16Go) sized machines instead of big ones as JMeter may not behave correctly with very high memory allocation.


The following procedure explains how to launch an on-premise load generator:

  1. Create an On-Premise Provider with a region on our platform, and select it,
  2. In Agents table, click on Create Agent button,
  3. Select the Region where the agent will be running,
  4. Select the Operating System (Windows or Linux),
  5. Follow the instructions related to the OS.

Windows installation

Host install Windows

Host installation on Windows requires Vagrant, a free and open-source software for creating and configuring virtual development environments. It can be considered a wrapper around virtualization software like VirtualBox.

So you need to download and install both software:

  1. Click on the Download VirtualBox button,
  2. Download and install VirtualBox for your Operating System,
  3. Click on the Download Vagrant button,
  4. Select you Operating System (you may also use Vagrant on Linux/Mac),
  5. Download and install Vagrant,
  6. Download the Vagrantfile (it is generated for the selected Provider and Region name, so you must re-download it to install an agent for another Provider / Region),
  7. Execute the command vagrant up in the folder that contains the downloaded Vagrantfile.

The Host should appear in the list in a couple of minutes.

Linux installation

Host install Linux

Host installation on Linux requires Docker. So the first command line installs it - you can skip it if you already have docker on your Linux injector.

The second command line installs the on-premise agent.

  1. Click on the Copy to Clipboard button at the right of the wget command,
  2. Paste it on your terminal to install Docker,
  3. Click on the Copy to Clipboard button at the right of the command. It should look like (do not actually use this one): sudo docker run -d -restart=unless-stopped --name flawed_gentleman -v /var/run/docker.sock:/var/run/docker.sock -e AGENT_TOKEN='...' -e SERVER_URL='' octoperf/docker-agent:...
  4. Execute the command on the target computer.

The Agent should appear in the list in a couple of minutes.


The agent can be configured using environement variables. You can specify an environement variable within the agent docker command using --env or -e parameter. See Docker Run for more information.

The agent supports the following environment variables:

  • AGENT_TOKEN: required. unique token generated by the server, used by the agent to authenticate itself when registering on the server,
  • SERVER_URL: required. Location of the OctoPerf server,
  • optional. Default to true. Whenever the agent should upgrade itself when a new version is available.

The agent has the following volume mappings:

  • /var/run/docker.sock:/var/run/docker.sock: optional. Gives access to the docker service on the host machine. It's used to start / stop JMeter containers on the host.


The docker.sock volume mapping can be safely removed when the agent is being used for monitoring only.


The agent must be upgraded manually when the docker.sock volume mapping is not present.

Agent Containers

Agent Containers

By clicking on the magnifier next to an agent, the Inspect Agent panel appears. It provides various information including:

  • Agent Information: docker version, operating system, name, last time the agent has been seen etc,
  • Containers Table: displays the containers currently running on this machine.

When selecting a container, container logs are displayed. Those information are mostly provided for debugging purpose.


Backend servers are usually protected behind firewalls to protect them from outer attacks. The agent doesn't require any port opening on firewall: it performs only outgoing HTTP requests to OctoPerf.

When using:

  • OctoPerf Saas: Firewall outgoing rules must allow the agent to send http requests to,
  • OctoPerf Enterprise Edition: it depends if a Firewall is placed between your OctoPerf server and your agents.


If a direct internet access is not an option, note that it is possible to direct all traffic from docker through a proxy. The procedure is detailed in docker documentation.


The computer running OctoPerf agent must have a direct access to the application under test. Make sure the proxy is only required to access internet, not the application.

The Agent itself can be configured to use a proxy to communicate with OctoPerf server ( when using OctoPerf Saas) via environment properties when running the agent. The agent is a Java Program

  • -e HTTP_PROXY='hostname': the host name of the proxy server (HTTP),
  • -e HTTPS_PROXY='hostname': the host name of the proxy server (HTTPS),
  • -e NO_PROXY='': a list of hosts that should be reached directly, bypassing the proxy.

If your proxy is SSL-Secured, use https instead of http. For a more complete documentation, see Configuring Proxies documentation.

Stop and Removal

To stop an agent on Linux:

  • Connect on the machine running the container through a Terminal (Linux);
  • Find the container within the list of running containers by running docker ps command,
  • Copy the containerId and run the command docker stop containerId.

The agent should be marked as DOWN within a few minutes.


Agents down for a while (>= 1 Hour) are automatically removed.


Restarting a removed agent will make it reappear on the server again in UP state.


My agent does not appear in the agents list.

Make sure you have successfully installed Docker and launched the agent on the machine. You can inspect the Docker container logs by using the command docker logs -f <container id>. Feel free to contact us if you still experience some issues.

The vagrant up command hangs on Windows 7.

This is a known vagrant issue:

You simply need to download and install the latest PowerShell on windows 7.

The agent upgrade somehow failed. How can I restart a new agent?

Delete the existing agent by running the following commands: docker ps -a | grep docker-agent docker rm -f <containerId>

Then proceed to re-install it.

My Agent stays in DOWN state. How can I find the root cause?

Display the Agent Logs

Connect via a linux terminal on the host machine and inspect the containers using the command docker ps -a | grep docker-agent. Find the monitoring-agent container and copy its id. Then run docker logs <containerId> where is the id of the container.

The agent logs should show you if it's a connectivity issue (no internet connection?) or something else. Contact our support team in case you are unable to find out.

Switching Logs to Debug

In case the default logs do not give enough information you may start a new agent with this environment variable added: -e JAVA_OPTS="-Dorg.slf4j.simpleLogger.defaultLogLevel=debug".

This will activate DEBUG logs and may help you find out what is going on.

Try to Connect to the REST API

You should be able to retrieve the list of Workspaces from the machine hosting the OctoPerf docker agent. Calling the REST API ensures that the Agent is able to communicate with the backend.

Run the following command:

curl --header "Authorization: Bearer API_KEY" -v

You API key can be found in the OctoPerf application profile section.

You may also run this command from the inside of the agent Docker container:

docker exec -it <containerId> /bin/bash

Once connected to the container shell:

apt-get -qq update
apt-get -qq -y install curl
curl --header "Authorization: Bearer API_KEY" -v