JMeter distributed testing runs one test plan on several machines at once: a controller sends the .jmx to worker machines running jmeter-server, each worker generates load, and the results come back to the controller. You need the same JMeter and Java versions everywhere, an RMI keystore (or SSL switched off), open RMI ports, and the test data copied to every worker. Then run jmeter -n -t plan.jmx -R worker1,worker2 -l results.jtl.
Key takeaways
- Each worker runs the whole test plan. 1,000 threads on 6 workers is 6,000 threads, so divide the thread count yourself.
- JMeter does not copy CSV or other data files to the workers. Put them at the same path on every machine.
- RMI needs the registry port (1099 by default) plus the server and client ports, and it does not cross subnets without a proxy. Keep the controller and workers on one private network.
- Running independent CLI instances and merging the result files is a valid alternative, and avoids RMI altogether.
What is distributed testing in JMeter?
Distributed testing is JMeter’s remote mode: one controller node starts and stops the test on several worker nodes and collects their results. JMeter’s manual also calls them client and servers, and older guides say master and slaves. You use it when one machine cannot produce the load you need, because its CPU, heap or network runs out before the target server does.
| Role | What runs there | What it does |
|---|---|---|
| Controller (client, master) | jmeter in CLI or GUI mode | Sends the test plan, starts and stops the test, writes the results file |
| Worker (server, slave) | jmeter-server | Runs the full test plan and sends sample results back |
| Target | Your application | Receives the load from every worker |
The controller does not split the load between workers. Each worker runs every Thread Group in the plan at the size the plan says, so the total load is the plan’s thread count multiplied by the number of workers. The JMeter manual’s own example: 1,000 threads on 6 servers injects 6,000 threads.
When do you need distributed JMeter testing?
You need it when a single load generator becomes the bottleneck. The signs are a generator at or near 100% CPU, garbage collection pauses in jmeter.log, a saturated network link, or response times that rise while the server under test still has spare capacity. JMeter’s step-by-step guide puts a single client on a recent 2-3 GHz CPU at 1,000 to 2,000 threads, depending on the test.
Measure your own limit before planning workers: run the plan from one machine at increasing thread counts and watch the generator, not only the results. How many threads JMeter can run from one machine covers how. If one machine is enough, stay on one machine: distributed mode adds network traffic and setup without making the numbers any better.
How to set up JMeter distributed testing, step by step
The steps below follow the JMeter remote testing guide. They assume Linux or macOS workers; on Windows use the .bat versions of each script.
Step 1: Prepare every node the same way
Install exactly the same JMeter version on the controller and all workers, and the same Java version where you can (the manual says different Java versions “may work but is discouraged”). Install the same plugins everywhere too, because a worker that lacks a plugin your plan uses fails to load the test.
Copy every data file the plan reads, such as CSV Data Set files, to each worker at the path the plan expects. The controller sends the .jmx, not its data. If each user needs unique data (logins, order ids), give each worker its own slice of the file.
Step 2: Create the RMI keystore, or switch SSL off
Since JMeter 4.0, the RMI connection between controller and workers uses SSL by default. Run bin/create-rmi-keystore.sh once, then copy the generated rmi_keystore.jks into the bin folder of every node. The key it creates is valid for seven days, so regenerate it for a later test.
On an isolated private network you can instead set server.rmi.ssl.disable=true in user.properties on every node. Do not do that on a network other people share.
Step 3: Fix the ports and open the firewall
RMI uses the registry port (1099 by default) and, unless you fix them, random high ports in both directions: the server engine on each worker and a reverse connection from the controller that carries results back. Pin them, then open exactly those:
# user.properties on each worker (the registry stays on 1099)
server.rmi.localport=50000
# user.properties on the controller
client.rmi.localport=60000Open 1099 and 50000 on the workers, and the controller’s ports from 60000 up (JMeter opens up to three, starting at the base number) to the workers. In a cloud account that means a security group or firewall rule that allows these ports between the instances only.
RMI does not cross subnets without a proxy, so put the controller and the workers in the same private network and use private IP addresses. If a worker registers itself under the wrong address, which can happen on machines with several network interfaces, the remote testing guide shows how to set java.rmi.server.hostname in the jmeter-server start script.
Step 4: Start jmeter-server on each worker
cd apache-jmeter-5.6.3/bin
./jmeter-serverOnly one jmeter-server can run on a machine unless you give each a different RMI port. Check jmeter-server.log for a “Created remote object” line; if it is missing, the server did not start. Add -Jserver.exitaftertest=true if you want a worker to stop after one test.
Step 5: Run the test from the controller
Start the test in CLI mode, listing the workers with -R:
jmeter -n -t checkout.jmx -R 10.0.1.11,10.0.1.12,10.0.1.13 -Gthreads=200 -l results.jtl -e -o report/ -X-Rlists the workers for this run (or put them inremote_hostsinjmeter.propertiesand use-r).-Gthreads=200sets a property on every worker; with${__P(threads,10)}in the Thread Group, each worker runs 200 threads, 600 in total here.-l,-e -owrite the combined results file and the HTML report on the controller.-Xstops the workers when the test ends.
You can also start the workers from the GUI with Run > Remote Start All, which is useful to check the setup with one thread before the real run. Run the real load from the command line, as with any JMeter test.
How results are collected, and what slows the controller down
Workers send their sample results back to the controller while the test runs. Since JMeter 2.9 the default sending mode is StrippedBatch, which batches results and strips the response data to save network traffic. Even so, many workers can overload the controller or its network link, and the manual notes that remote mode uses more resources than running the same number of CLI tests independently.
Keep the controller on a machine of its own, avoid listeners in the plan (the -l file is enough), and watch its CPU and network during the run. If the controller becomes the bottleneck, the alternative is to drop remote mode: start an independent jmeter -n -t plan.jmx -l results-N.jtl on each generator at the same time, then concatenate the result files (keep one header line) and build the report with jmeter -g all-results.jtl -o report/.
Common JMeter distributed testing problems
| Symptom | Likely cause | Fix |
|---|---|---|
| Controller cannot connect to a worker | Firewall, wrong IP, or RMI across subnets | Open 1099 and the fixed RMI ports; use private IPs on one network |
| SSL or keystore error on start | Missing or expired rmi_keystore.jks | Regenerate it and copy it to every node, or disable SSL on a private network |
| Worker fails to load the plan | Missing plugin or different JMeter version | Install identical JMeter and plugins on every node |
| CSV Data Set errors on workers | Data file only on the controller | Copy it to the same path on each worker |
| Load is several times higher than planned | Every worker runs the full thread count | Divide threads by the number of workers, or pass them with -G |
| Results arrive late or the controller slows down | Too many workers for one controller | Fewer listeners, a bigger controller, or independent CLI instances |
Running distributed JMeter in the cloud without managing workers
Self-hosted distributed testing in the cloud means launching the instances, installing identical JMeter and plugin versions, distributing the keystore and data files, opening the ports, and terminating everything when you are done. That gives you full control of the network and the data, and it is a fair amount of work to repeat for every test.
A managed service does the worker side for you. On LoadFocus you upload the .jmx with its CSV files and set the total virtual users, duration and ramp-up in the browser; LoadFocus starts the cloud machines for the run, spreads the threads across them and shuts them down when the test ends. Unlike JMeter’s remote mode, the number you set is the total, not a per-worker count. You can run from several of its 25 cloud regions in one test and compare results region by region. For the basics before you scale, see our JMeter load testing tutorial.
Frequently Asked Questions
What is distributed testing in JMeter?
It is JMeter’s remote mode: a controller sends one test plan to several worker machines running jmeter-server, each worker runs the full plan against the target, and the controller collects all the results into one file. It exists because a single machine runs out of CPU, memory or network before a large target does.
Does JMeter split the threads between workers?
No. Every worker runs the full thread count in the plan, so 100 threads on 5 workers is 500 threads. Set the per-worker count yourself, for example with a property in the Thread Group and -Gthreads=100 on the command line.
Do the workers need the CSV files?
Yes. The controller sends the test plan but not its data files, so each worker needs a copy at the path the plan uses. Give each worker a different slice if every virtual user needs unique data.
Which ports does JMeter distributed testing use?
The RMI registry port, 1099 by default, plus the server engine port on each worker and a reverse connection from the controller for results. Fix them with server.rmi.localport and client.rmi.localport and open those in the firewall.
Can I run JMeter distributed testing with Docker?
Yes, as long as each container runs the same JMeter version, the RMI ports are published or the containers share a network, and the keystore and data files are inside each container. The same RMI rules apply as on separate machines.
Sources
- Remote Testing, JMeter user manual: node requirements, RMI over SSL and the keystore script, ports,
-R,-G,-X, sample sending modes, each server runs the full plan (jmeter.apache.org, October 2026). - Apache JMeter Distributed Testing Step-by-step: terminology, starting workers, subnet limitation, threads per client (jmeter.apache.org, October 2026).
- Best Practices, JMeter user manual: independent CLI instances as an alternative (jmeter.apache.org, October 2026).
- JMeter properties reference:
server.rmi.ssl.disable(jmeter.apache.org, October 2026).
