Setup is done. Workers are listening. Resources are deployed. Now it is time to actually run the test. JMeter gives you two flags for distributed execution, and choosing the right one depends on your situation.
The -r flag tells JMeter to distribute the test to every host listed in the remote_hosts property in jmeter.properties. This is the "fire everything" button.
# Run test on ALL remote hosts configured in jmeter.properties
# Prerequisite: remote_hosts=192.168.1.101,192.168.1.102,192.168.1.103
jmeter -n -t /tests/load_test.jmx -r -l /results/distributed_results.jtl
# Breakdown:
# -n = Non-GUI mode (mandatory for load tests)
# -t = Test plan file
# -r = Run on all remote_hosts
# -l = Log results to this file
# With additional reporting:
jmeter -n -t /tests/load_test.jmx -r -l /results/results.jtl \
-e -o /results/html_reportThe -R flag lets you specify exactly which workers to use, overriding whatever is in jmeter.properties. This is useful when you want to run a quick test on just two workers, or when one worker is down and you do not want to edit the properties file.
# Run on specific workers (overrides remote_hosts property)
jmeter -n -t /tests/load_test.jmx \
-R 192.168.1.101,192.168.1.102 \
-l /results/results.jtl
# Run on just one worker (useful for debugging)
jmeter -n -t /tests/load_test.jmx \
-R 192.168.1.101 \
-l /results/results.jtl
# With custom port (if workers are on non-default ports)
jmeter -n -t /tests/load_test.jmx \
-R 192.168.1.101:2099,192.168.1.102:2099 \
-l /results/results.jtl| Flag / Property | Purpose | Example |
|---|---|---|
| -Jthreads=500 | Pass a JMeter property to override thread count (use with __P() function in test plan) | jmeter -n -t test.jmx -r -Jthreads=500 |
| -Gduration=600 | Pass a global property to ALL workers (note: -G not -J) | jmeter -n -t test.jmx -r -Gduration=600 |
| -X | Exit remote workers after test ends (clean shutdown) | jmeter -n -t test.jmx -r -X -l results.jtl |
| -Djava.rmi.server.hostname=IP | Force RMI to use a specific network interface | jmeter -n -t test.jmx -r -Djava.rmi.server.hostname=10.0.0.1 |
| server.exitaftertest=true | Worker exits after test (set in jmeter.properties) | Set in properties file on each worker |
Here is a pro trick. Instead of hardcoding thread count in your test plan, use the __P() function and pass the value from the command line. This way, you can run the same JMX with different load levels without editing the file.
Thread Count: ${__P(threads,100)}
Ramp-up Period: ${__P(rampup,60)}
Loop Count: ${__P(loops,-1)}
Duration: ${__P(duration,300)}
# __P(propertyName,defaultValue)
# If the property is not passed, the default value is used
# -1 for loops means "infinite" (controlled by duration)# Smoke test: 10 users per worker for 60 seconds
jmeter -n -t test.jmx -r \
-Gthreads=10 -Grampup=10 -Gduration=60 \
-l smoke_results.jtl
# Full load: 500 users per worker for 30 minutes
jmeter -n -t test.jmx -r \
-Gthreads=500 -Grampup=120 -Gduration=1800 \
-l load_results.jtl
# Stress test: 1000 users per worker for 1 hour
jmeter -n -t test.jmx -r \
-Gthreads=1000 -Grampup=300 -Gduration=3600 \
-l stress_results.jtlUse -G (global) not -J (local) when passing properties in distributed mode. -J sets the property only on the master. -G sets it on ALL workers. Since workers run the threads, -G is what you need.
When you need to stop a distributed test mid-run, you have options. In non-GUI mode, you can use the JMeter Shutdown script or send a shutdown signal.
# Graceful shutdown (waits for current samples to finish)
./stoptest.sh
# Immediate shutdown (kills threads immediately)
./shutdown.sh
# If running in a terminal, Ctrl+C sends shutdown signal
# JMeter will try to gracefully stop all workers
# Nuclear option: if workers are not responding
# SSH into each worker and kill jmeter-server
for host in 192.168.1.101 192.168.1.102 192.168.1.103; do
ssh user@$host "pkill -f jmeter-server"
doneQ: What is the difference between -r and -R flags in JMeter distributed testing? When would you use -G instead of -J?
A: The -r flag runs the test on ALL remote hosts configured in the remote_hosts property of jmeter.properties. The -R flag overrides remote_hosts and lets you specify exactly which workers to use on the command line (e.g., -R 192.168.1.101,192.168.1.102). I use -r for full production test runs where all workers are stable, and -R for debugging, partial runs, or when a worker is temporarily down. Regarding -J vs -G: -J sets a JMeter property only on the local (master) machine, while -G sets a global property that is propagated to ALL remote workers. Since workers execute the threads, any property that affects test execution (thread count, ramp-up, duration) must use -G to reach the workers. -J is useful for master-only settings like result file paths.
Key Point: Use -r to run on all configured workers, -R to run on specific workers. Use -G (not -J) to pass properties to remote workers.