Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Distributed Testing

Setting Up Remote Agents and Running a Distributed Test

Configure JMeter agents step by step: jmeter-server, remote_hosts, the -r and -R flags, RMI keystore, ports, Docker and Kubernetes options, and troubleshooting.

Setting up distributed testing is mostly networking and consistency. The steps are always the same: make every machine identical, start the agent service, tell the controller where the agents are, and run. This lesson lists the real commands and files. JMeter and its servers cannot run on this site, so the code you can run here is a Python stand-in that checks a configuration for the usual mistakes.

Step 1: make the machines identical

All machines need the same JMeter version and the same Java version (use a current LTS JDK). Mismatched versions cause serialization errors or silent differences. Also copy:

  • the same lib/ext plugins and lib libraries (for example the JDBC driver or plugins for extra listeners),
  • test data files at the same relative path (for CSV Data Set Config use a path relative to the .jmx, or the same absolute path everywhere),
  • the RMI keystore (see below).

The cleanest way is a Docker image or a virtual machine image that already contains all of this, so agents are copies of each other.

Step 2: create the RMI keystore

From the bin folder of the controller:

Terminal
./create-rmi-keystore.sh

It asks for a name and password and writes rmi_keystore.jks. Copy that file into the bin folder of every agent and keep it identical. If the keystore is missing, agents fail to start with an SSL error.

Step 3: configure and start the agents

On each agent, set in bin/jmeter.properties (or user.properties):

PROPERTIES
server_port=1099
server.rmi.localport=4000
java.rmi.server.hostname=10.0.0.11

java.rmi.server.hostname is the address the controller uses to reach this agent. It is essential in cloud and NAT setups. Then start the service:

Terminal
./jmeter-server

Leave it running (or install it as a service). The log line Created remote object shows it is ready. If the agent has several network cards, tell Java which one with -Djava.rmi.server.hostname=....

Step 4: tell the controller about the agents

In the controller's bin/jmeter.properties:

PROPERTIES
remote_hosts=10.0.0.11,10.0.0.12,10.0.0.13
client.rmi.localport=4001

You can also choose agents on the command line with -R. In the GUI, use Run > Remote Start (one agent) or Remote Start All.

Step 5: run from the command line

Terminal
# Run on all hosts listed in remote_hosts
jmeter -n -t plan.jmx -r -l results.jtl -e -o report/

# Run on selected hosts only
jmeter -n -t plan.jmx -R 10.0.0.11,10.0.0.12 -l results.jtl

# Pass properties to the agents as well
jmeter -n -t plan.jmx -r -Gthreads=250 -Ghost=staging.shop.test -l results.jtl
  • -n runs without the GUI (non-GUI mode), -t names the test plan.
  • -r starts all remote_hosts; -R starts only the hosts you list.
  • -G sets a property on the agents; -J sets one on the controller only. The distinction trips many people up: use -G for values that the test plan reads with __P.
  • -l writes results; the controller merges what the agents send.
  • -X (exit) tells the agents to shut down at the end, which is handy in pipelines.

A distributed run needs the whole test plan to be valid on each agent. Anything the plan reads from the controller's disk (certificates, large payload files, scripts) must exist at the same path on the agents.

Docker and Kubernetes

A popular approach is one container image used as both controller and agent, with jmeter-server as the agent command. Compose or a Kubernetes StatefulSet gives agents stable names; the controller lists them in remote_hosts. The important details are the same as above: a pinned RMI port, java.rmi.server.hostname set to the pod address, and the keystore mounted as a secret. Many teams skip RMI and run several independent Jobs, each with a different slice of the data, then merge the .jtl files.

A configuration checker (stand-in)

Typical mistakes can be found before a run starts. This stand-in checks a dictionary that represents the settings of each machine.

Python Stand-in: validate a distributed setup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Troubleshooting

Symptom Likely cause
Connection refused to host: 127.0.0.1 java.rmi.server.hostname is missing or loopback
SSLHandshakeException missing or different rmi_keystore.jks
Test starts, but an agent reports no samples data files missing, or plan error visible only in jmeter-server.log
Controller freezes at high load too many samples sent back; reduce listeners, use -G for properties, or use independent instances
NoSuchObjectException an agent restarted during the run

Always check jmeter-server.log on the agent and jmeter.log on the controller. On shutdown, if agents keep running, stop them with shutdown (graceful) or stoptest messages through the GUI's Remote Shutdown, or from a script with -X.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which flag starts the test on every host listed in remote_hosts?

    -r uses remote_hosts; -R takes an explicit list; -G sets properties on agents; -X exits the agents.
  2. 2. You pass -Jthreads=100 but agents still use their default. What should you use?

    -J applies to the controller only; -G sends the property to the agents.
  3. 3. What is java.rmi.server.hostname for?

    Without a reachable address, the agent can advertise 127.0.0.1 and the controller fails to connect.
  4. 4. Which file must be identical on all machines for RMI over SSL?

    All parties must trust the same keystore, otherwise the SSL handshake fails.

Summary

  • Use identical JMeter and Java versions, plugins, data files and keystore on every machine.
  • Agents run jmeter-server; the controller lists them in remote_hosts or -R.
  • -r runs on all agents, -G sets agent properties, -X shuts agents down.
  • Pin RMI ports and set java.rmi.server.hostname.
  • Containers and independent instances are modern alternatives to RMI.

Next: Sizing and Tuning Load Generators