Apache JMeter on AWS User Guide

Overview

Apache JMeter is the de-facto open-source tool for load and performance testing of web applications, APIs, databases and other services. The cloudimg image ships JMeter as a headless / server appliance: JMeter's GUI is a desktop Swing application and is not installed for interactive use here, so the product surface is non-GUI command-line test execution and the JMeter distributed-mode remote engine. The image installs Apache JMeter 5.6.3 from the official Apache binary distribution to /opt/jmeter, installs OpenJDK 17 as the runtime, runs the distributed-mode jmeter-server engine as a systemd service under a dedicated unprivileged jmeter user, ships a bundled sample test plan, and keeps test plans, results and HTML dashboard reports on a dedicated EBS data volume at /var/lib/jmeter. Backed by 24/7 cloudimg support.

What is included:

• Apache JMeter 5.6.3 (Apache-2.0) from the official Apache binary distribution at /opt/jmeter
• Headless (non-GUI) test execution: jmeter -n -t plan.jmx -l results.jtl
• The distributed-mode remote engine jmeter-server running as a systemd service (jmeter-server.service) under a dedicated unprivileged jmeter user
• OpenJDK 17 (Ubuntu 24.04 main) as the JVM runtime
• RMI registry on 127.0.0.1:1099 and the server engine port on 127.0.0.1:1100, both loopback-only, with RMI SSL enabled against a per-instance keystore generated on first boot
• A bundled sample test plan at /opt/jmeter/sample.jmx
• HTML dashboard report generation from .jtl results
• Test plans, results and reports on a dedicated 30 GiB EBS data volume at /var/lib/jmeter
• 24/7 cloudimg support

The distributed-mode engine listens on 127.0.0.1 only and the RMI ports are never opened to the internet. Run headless tests locally on the instance, or attach a remote JMeter controller over an SSH tunnel using the per-instance keystore as the trust boundary.

Prerequisites

An active AWS account, an EC2 key pair, and a VPC + subnet in the target region. m5.large (2 vCPU / 8 GiB RAM) is a good starting point for the JVM-based engine; use larger compute-optimized instances (c5/c6i) for high-concurrency or distributed load generation. Security group inbound: allow 22/tcp from your management network. No inbound application ports are needed because tests run locally on the instance or the remote engine is reached over the SSH tunnel.

Connecting to your instance

Connect over SSH on port 22 as the default login user for your AMI variant:

Step 1 - Deploy from the AWS Marketplace

Sign in to the AWS Marketplace, search for Apache JMeter by cloudimg, and choose Continue to Subscribe. Accept the terms, then Continue to Configuration, pick the region and AMI variant, and Continue to Launch. Under Launch this software choose your instance type (m5.large is a good start), your VPC/subnet, an EC2 key pair, and a security group that allows SSH (22) from your management network only. Then Launch.

Step 2 - Deploy from the AWS CLI

aws ec2 run-instances \
  --image-id <marketplace-ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <sg-allowing-22> \
  --subnet-id <your-subnet> \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=20,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=jmeter}]'

Step 3 - Connect to your instance

ssh ubuntu@<instance-public-ip>

Step 4 - Confirm JMeter is installed and the engine is running

Confirm the JMeter binaries, the running distributed-mode engine, and that the RMI ports are bound to loopback only:

sudo -u jmeter env JMETER_HOME=/opt/jmeter /opt/jmeter/bin/jmeter --version 2>/dev/null | tail -8
systemctl is-active jmeter-server.service
ss -tln | grep -E ':1099|:1100'
sudo nft list table inet jmeter_guard

You should see the JMeter 5.6.3 banner, active, both RMI ports listening on 127.0.0.1, and the nftables guard dropping any non-loopback ingress to 1099/1100:

                       ... 5.6.3
Copyright (c) 1999-2024 The Apache Software Foundation

active

LISTEN 0  50  [::ffff:127.0.0.1]:1100  *:*
LISTEN 0  50  [::ffff:127.0.0.1]:1099  *:*

iif "lo" accept
iifname != "lo" tcp dport { 1099, 1100 } drop

Step 5 - Review the per-instance endpoint notes

On first boot the image generates a fresh per-instance RMI SSL keystore and writes an endpoints notes file. Read it:

sudo cat /var/lib/cloudimg/apache-jmeter-endpoints.notes

The file records JMETER_HOME, the loopback RMI endpoint, the keystore path, the per-instance JMETER_RMI_KEYSTORE_PASSWORD, the public IP, and the SSH-tunnel guidance. Treat the keystore and its password as connection material - they are the trust boundary for distributed mode.

Step 6 - Review the bundled sample test plan

A sample test plan ships at /opt/jmeter/sample.jmx (a 5-thread x 20-loop thread group with a Summary Report listener). Confirm it is present:

ls -l /opt/jmeter/sample.jmx

Step 7 - Run a headless (non-GUI) test

Run the bundled sample plan headless with jmeter -n and write the results to a .jtl file. The run prints a live summary and an end-of-run line:

sudo -u jmeter /opt/jmeter/bin/jmeter -n -t /opt/jmeter/sample.jmx -l /var/lib/jmeter/results/run.jtl 2>/dev/null | grep -vE 'WARN Status' | tail -8

You should see the run reach ... end of run with 100 samples and zero errors:

Created the tree successfully using /opt/jmeter/sample.jmx
Starting standalone test @ 2026 Jul 21 11:20:04 UTC (1784632804996)
summary +      1 in 00:00:00 =    4.6/s Avg:   133 Min:   133 Max:   133 Err:     0 (0.00%) Active: 1 Started: 1 Finished: 0
summary +     99 in 00:00:04 =   27.0/s Avg:   141 Min:    11 Max:   261 Err:     0 (0.00%) Active: 0 Started: 5 Finished: 5
summary =    100 in 00:00:04 =   25.8/s Avg:   141 Min:    11 Max:   261 Err:     0 (0.00%)
Tidying up ...    @ 2026 Jul 21 11:20:09 UTC (1784632809023)
... end of run

Step 8 - Generate an HTML dashboard report

Generate a JMeter HTML dashboard report from the .jtl results with jmeter -g, then list the report directory:

sudo -u jmeter /opt/jmeter/bin/jmeter -g /var/lib/jmeter/results/run.jtl -o /var/lib/jmeter/reports/run 2>/dev/null | tail -2
ls -1 /var/lib/jmeter/reports/run

The report directory contains index.html, the content graphs, and statistics.json:

content
index.html
sbadmin2-1.0.7
statistics.json

Open index.html in a browser (copy the report directory off the instance, or serve it over an SSH tunnel) to see the APDEX score, the pass/fail requests summary, and the response-time, throughput and over-time dashboards:

Step 9 - Run your own test plan

Copy your own .jmx plan to the data volume and run it headless, writing results and generating a report:

# Copy your plan to the instance (from your workstation):
scp my-plan.jmx ubuntu@<instance-public-ip>:/tmp/my-plan.jmx

# On the instance:
sudo install -o jmeter -g jmeter -m 0644 /tmp/my-plan.jmx /var/lib/jmeter/test-plans/my-plan.jmx
sudo -u jmeter /opt/jmeter/bin/jmeter -n -t /var/lib/jmeter/test-plans/my-plan.jmx -l /var/lib/jmeter/results/my-run.jtl
sudo -u jmeter /opt/jmeter/bin/jmeter -g /var/lib/jmeter/results/my-run.jtl -o /var/lib/jmeter/reports/my-run

Step 10 - Drive this instance as a remote engine (distributed mode)

The jmeter-server engine is the remote half of JMeter's distributed (controller/worker) mode. The RMI endpoint listens on 127.0.0.1:1099 only and is secured with RMI SSL against the per-instance keystore at /var/lib/jmeter/rmi_keystore.jks. To drive this instance from a controller, open an SSH tunnel, copy the keystore to the controller, point the controller's jmeter.properties at it, and target the tunnelled endpoint:

# On your workstation:
ssh -L 1099:127.0.0.1:1099 ubuntu@<instance-public-ip>
sudo scp ubuntu@<instance-public-ip>:/var/lib/jmeter/rmi_keystore.jks ./rmi_keystore.jks

# Then on the controller (with the keystore + per-instance password configured):
jmeter -n -t my-plan.jmx -R 127.0.0.1:1099 -l results.jtl

Never expose 1099 or 1100 to the internet; the per-instance keystore and loopback binding are the security boundary. To generate distributed load at scale, launch a fleet of instances from this AMI and drive them all from a single controller.

Maintenance

• Data: test plans, .jtl results and HTML reports live on the dedicated EBS data volume at /var/lib/jmeter, so they survive reboots and the volume is independently resizable. Use EBS Snapshots to back it up.
• Engine: the distributed-mode remote engine runs as jmeter-server.service; restart it with sudo systemctl restart jmeter-server.service.
• Tuning: edit /opt/jmeter/bin/user.properties for engine and RMI tuning, then restart the service.
• Security patches: the OS continues to receive security updates; apply them with sudo apt-get update && sudo apt-get upgrade.
• Security boundary: the RMI registry and server engine ports bind to loopback only with RMI SSL against a per-instance keystore - keep 1099/1100 off the public internet and reach the remote engine over the SSH tunnel.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.

Apache JMeter and the Apache feather logo are trademarks of The Apache Software Foundation. This image is provided by cloudimg and is not affiliated with or endorsed by The Apache Software Foundation.