Messaging & Event Streaming
ActiveMQ Classic 6: Installation, activemq.xml and Transport Configuration
Intermediate9 min readUpdated
ActiveMQ Classic is the long-standing JMS broker of the Apache ActiveMQ project. This guide takes you from a downloaded archive to a broker you understand: the directory layout, the sections of activemq.xml that matter, transport connectors and protocols, system usage limits and producer flow control, client failover URLs, embedded brokers and networks of brokers — with notes on where ActiveMQ Artemis differs.
What you will learn
- Install and run ActiveMQ Classic 6 as a service on Linux and as a container
- Read and edit the main sections of conf/activemq.xml with confidence
- Configure transport connectors for OpenWire, AMQP, STOMP, MQTT and WebSocket clients
- Set memory, store and temp limits and understand producer flow control
- Write failover connection URLs and tune prefetch for clients
- Connect brokers into a network and know when Artemis is the better choice
Apache ActiveMQ Classic is a mature JMS broker written in Java: download it, start it, and a few seconds later you have queues, topics, a web console and listeners for five protocols. The simplicity is real, but production use depends on a handful of configuration decisions in conf/activemq.xml that the defaults do not make for you. This guide covers the 6.x line, which requires Java 17 and uses the jakarta.jms API, and points out where ActiveMQ Artemis — the project's other broker — does things differently.
Installing the broker
ActiveMQ ships as a single archive containing the broker, its libraries and a web console. There is no installer and no database to prepare.
Install a JDK 17 or later. On Debian or Ubuntu, sudo apt install openjdk-17-jre-headless; on RHEL-family systems, sudo dnf install java-17-openjdk-headless. Confirm with java -version.
Create a service user. Run the broker under an unprivileged account: sudo useradd --system --home /opt/activemq --shell /usr/sbin/nologin activemq.
Download and unpack. Fetch the binary tarball from the Apache download page, verify its signature or checksum, then unpack it under /opt and keep a version-independent symlink so that upgrades are a symlink change:
curl -LO https://archive.apache.org/dist/activemq/6.1.6/apache-activemq-6.1.6-bin.tar.gz
sudo tar -xzf apache-activemq-6.1.6-bin.tar.gz -C /opt
sudo ln -sfn /opt/apache-activemq-6.1.6 /opt/activemq
sudo chown -R activemq:activemq /opt/apache-activemq-6.1.6
Start it once in the foreground. /opt/activemq/bin/activemq console runs the broker attached to your terminal so you can read the startup log. You should see lines announcing the KahaDB store, each transport connector (tcp://0.0.0.0:61616, amqp://..., and so on) and the web console at http://0.0.0.0:8161/. Stop it with Ctrl+C.
Run it as a systemd service. Create /etc/systemd/system/activemq.service, then sudo systemctl daemon-reload && sudo systemctl enable --now activemq.
[Unit]
Description=Apache ActiveMQ Classic
After=network-online.target
Wants=network-online.target
[Service]
Type=forking
User=activemq
Group=activemq
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
ExecStart=/opt/activemq/bin/activemq start
ExecStop=/opt/activemq/bin/activemq stop
PIDFile=/opt/activemq/data/activemq.pid
Restart=on-failure
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
For containers, the project publishes an official image; a one-liner gives you a broker with the same defaults as the tarball:
docker run -d --name activemq \
-p 61616:61616 -p 8161:8161 -p 5672:5672 \
-v activemq-data:/opt/apache-activemq/data \
apache/activemq-classic:6.1.6
Mount /opt/apache-activemq/conf as well if you want to supply your own activemq.xml, and always mount the data directory: without a volume, every persistent message is lost when the container is removed.
What is in the distribution
Knowing the layout saves time when something goes wrong.
| Directory | Contents |
|---|---|
bin/ | The activemq launcher script (Linux/macOS) and activemq.bat; env holds JVM options such as heap size |
conf/ | activemq.xml (broker), jetty.xml and jetty-realm.properties (web console), login.config, users.properties, groups.properties (JAAS security), log4j2.properties |
data/ | KahaDB store, activemq.log, the PID file; the directory to back up and to put on fast disk |
lib/ | Broker and client jars; activemq-all-*.jar bundles everything for quick client tests |
webapps/ | The admin web console and the Jolokia REST endpoint |
examples/ | Sample producers and consumers for each protocol |
The launcher script has more subcommands than start and stop. bin/activemq status reports whether the broker is running; bin/activemq bstat prints broker statistics; dstat lists destinations with their queue size, enqueue and dequeue counts; browse --amqurl tcp://localhost:61616 orders.placed prints the messages in a queue without consuming them; purge empties one; producer and consumer generate and consume test traffic. These commands talk to the broker over JMX or JMS, so they work against remote brokers too.
Heap size lives in bin/env as ACTIVEMQ_OPTS_MEMORY="-Xms64M -Xmx1G". Raise the maximum for real workloads, and keep in mind that the broker's own memoryUsage limit (below) is a fraction of that heap.
Reading activemq.xml
The configuration file is a Spring XML application context, which is why it can define data sources and other beans alongside the broker. The broker itself is the <broker> element; its children are the sections you will edit.
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://activemq.apache.org/schema/core
http://activemq.apache.org/schema/core/activemq-core.xsd">
<broker xmlns="http://activemq.apache.org/schema/core"
brokerName="orders-broker"
dataDirectory="${activemq.data}"
useJmx="true"
advisorySupport="false"> <!-- advisory topics cost CPU; enable only if you use them -->
<destinationPolicy>
<policyMap>
<policyEntries>
<!-- ">" matches every queue; "orders.>" would match orders.placed, orders.paid ... -->
<policyEntry queue=">" producerFlowControl="true" memoryLimit="64mb">
<deadLetterStrategy>
<individualDeadLetterStrategy queuePrefix="DLQ." useQueueForQueueMessages="true"/>
</deadLetterStrategy>
</policyEntry>
<policyEntry topic=">" producerFlowControl="true">
<pendingMessageLimitStrategy>
<constantPendingMessageLimitStrategy limit="1000"/>
</pendingMessageLimitStrategy>
</policyEntry>
</policyEntries>
</policyMap>
</destinationPolicy>
<persistenceAdapter>
<kahaDB directory="${activemq.data}/kahadb"/>
</persistenceAdapter>
<systemUsage>
<systemUsage sendFailIfNoSpace="true">
<memoryUsage><memoryUsage percentOfJvmHeap="70"/></memoryUsage>
<storeUsage><storeUsage limit="20 gb"/></storeUsage>
<tempUsage><tempUsage limit="5 gb"/></tempUsage>
</systemUsage>
</systemUsage>
<transportConnectors>
<transportConnector name="openwire" uri="tcp://0.0.0.0:61616?maximumConnections=1000&wireFormat.maxFrameSize=104857600"/>
<transportConnector name="amqp" uri="amqp://0.0.0.0:5672?maximumConnections=1000"/>
<transportConnector name="stomp" uri="stomp://0.0.0.0:61613?maximumConnections=1000"/>
<transportConnector name="mqtt" uri="mqtt://0.0.0.0:1883?maximumConnections=1000"/>
<transportConnector name="ws" uri="ws://0.0.0.0:61614?maximumConnections=1000"/>
</transportConnectors>
</broker>
<import resource="jetty.xml"/> <!-- web console on 8161 -->
</beans>
Three attributes on <broker> matter early. brokerName identifies the broker in JMX, in logs and in networks of brokers — give every broker a unique one. dataDirectory is where the store, the scheduler and the lock file live. advisorySupport controls advisory messages, internal topics on which the broker publishes events such as "consumer connected" or "message expired"; they are useful for tooling but add overhead, and many teams turn them off.
Destination policies
<destinationPolicy> applies per-destination settings by name pattern. The wildcard > matches everything below a prefix and * matches one name segment, so orders.* covers orders.placed but not orders.eu.placed. Policies can set memory limits, dead-letter strategies, dispatch behaviour and, for topics, how many messages a slow non-durable subscriber may have pending before old ones are discarded — the pendingMessageLimitStrategy above, which stops one stuck subscriber from exhausting broker memory.
The individualDeadLetterStrategy shown replaces the single shared ActiveMQ.DLQ with one dead-letter queue per source queue (DLQ.orders.placed), which makes poison messages far easier to trace back to their origin.
System usage and producer flow control
<systemUsage> sets three ceilings: memory for messages held in RAM, store for the persistent store on disk, and temp for non-persistent messages spilled to disk. When a destination or the broker reaches a ceiling, producer flow control kicks in: the broker stops acknowledging sends on the affected destinations, and synchronous producers block until consumers free space. This protects the broker from running out of memory, but it looks to the sending application like a hang. sendFailIfNoSpace="true" turns the hang into a ResourceAllocationException the producer can handle; producerFlowControl="false" on a policy disables the mechanism for that destination and lets messages spill to the store instead, which is the usual choice for queues that are expected to build backlog.
Transport connectors and protocols
Each <transportConnector> opens a listening socket for one protocol. The URI scheme selects the protocol and the query string tunes it.
| Scheme | Protocol | Typical clients | Notes |
|---|---|---|---|
tcp:// | OpenWire, ActiveMQ's native binary protocol | Java (activemq-client), .NET (NMS), C++ (CMS) | Fastest for JMS; one thread per connection |
nio:// | OpenWire over Java NIO | Same | Fewer threads for many connections; prefer it at scale |
ssl://, nio+ssl:// | OpenWire over TLS | Same | Configure a keystore in <sslContext> |
amqp:// | AMQP 1.0 | Qpid JMS, Apache Qpid Proton, .NET, Go | Standards-based interoperability |
stomp:// | STOMP | Scripting languages, quick tests | Text protocol; stomp+nio for scale |
mqtt:// | MQTT 3.1.1 | IoT devices, mobile | QoS 0/1/2 map onto delivery modes |
ws://, wss:// | STOMP or MQTT over WebSocket | Browsers | Pair with a JavaScript STOMP client |
vm:// | In-JVM | Tests, embedded use | No socket; broker starts on first connection |
Useful query options include maximumConnections (refuse new connections beyond a limit rather than exhausting threads), wireFormat.maxFrameSize (reject oversized messages before they reach memory; 100 MB is the default), transport.soTimeout and transport.keepAlive. Bind to 0.0.0.0 only when the broker must be reachable from other hosts, and put the listeners behind a firewall — a broker with the default credentials exposed to the internet is a well-known incident pattern.
Client-side URLs: failover and prefetch
Clients configure a lot through the connection URL, and two options belong in every production URL.
The failover transport wraps one or more broker addresses and reconnects transparently when the connection drops, replaying unacknowledged sends and re-establishing consumers:
ConnectionFactory factory = new ActiveMQConnectionFactory(
"failover:(tcp://broker-a:61616,tcp://broker-b:61616)"
+ "?randomize=false" // try broker-a first, broker-b as backup
+ "&initialReconnectDelay=100"
+ "&maxReconnectDelay=10000" // back off to at most 10 s between attempts
+ "&maxReconnectAttempts=-1" // keep trying forever (the default)
+ "&timeout=3000"); // fail a send after 3 s without a broker instead of blocking
Even with a single broker, failover:(tcp://broker:61616) is worth using: without it, a restart of the broker leaves every client with a dead connection and an exception it has to handle itself.
Prefetch is the number of messages the broker pushes to a consumer ahead of acknowledgement. The default of 1000 for queues maximises throughput for fast consumers but is wrong for slow ones: one consumer hoards a thousand messages while its nine peers sit idle, and a crash leaves those thousand to be redelivered. Set it per connection, tcp://broker:61616?jms.prefetchPolicy.queuePrefetch=10, or per destination, orders.placed?consumer.prefetchSize=1. A prefetch of 1 gives strict fairness at the cost of a round trip per message; 10 to 50 is a common compromise for work that takes tens of milliseconds.
Embedded brokers for tests
The vm:// transport starts a broker inside the JVM of the first client that connects, which makes integration tests self-contained:
// Fully in-memory: no KahaDB directory, no ports, gone when the JVM exits
ConnectionFactory factory =
new ActiveMQConnectionFactory("vm://test?broker.persistent=false&broker.useJmx=false");
Spring Boot's spring-boot-starter-activemq used to embed a broker automatically; since Boot 3.x the embedded-broker support is gone, so point spring.activemq.broker-url at a vm:// URL for tests or, better, at a container started by Testcontainers so that tests exercise the real network path.
Networks of brokers
A network of brokers connects several brokers so that a message produced on one can be consumed from another. Each broker keeps its own store and clients; a <networkConnector> forwards messages to a peer only when that peer has a consumer for the destination, so the network reacts to demand rather than replicating everything.
<networkConnectors>
<!-- On broker-a: forward to broker-b when broker-b has interested consumers.
duplex="true" carries traffic both ways over this single connector. -->
<networkConnector name="a-to-b"
uri="static:(tcp://broker-b:61616)"
duplex="true"
networkTTL="1"
decreaseNetworkConsumerPriority="true">
<excludedDestinations>
<queue physicalName="internal.>"/>
</excludedDestinations>
</networkConnector>
</networkConnectors>
Networks scale out consumers and connect sites, but they are not high availability: a message stored on broker-a is unavailable while broker-a is down. High availability in Classic comes from a shared store (KahaDB on shared storage or a JDBC store) with one active broker and standby brokers waiting for the lock, which the persistence guide covers. decreaseNetworkConsumerPriority="true" keeps messages local when a local consumer exists, and networkTTL limits how many hops a message may travel — leave it at 1 unless you have a deliberate multi-hop topology, because messages that bounce between brokers are painful to debug.
Where Artemis differs
If you are starting a new deployment, evaluate ActiveMQ Artemis before defaulting to Classic. The differences that affect setup are:
- Configuration is
etc/broker.xml, withartemis creategenerating a broker instance directory separate from the installation. - The address model has addresses, queues and routing types (anycast for point-to-point, multicast for pub-sub) instead of JMS destinations mapped directly onto queues and topics.
- Persistence is a purpose-built append-only journal (with an NIO or Linux AIO backend) rather than KahaDB.
- High availability is built in: replicated or shared-store live/backup pairs, and connection routers.
- AMQP 1.0 is a first-class protocol with its own broker-to-broker federation and mirroring.
- Throughput is generally higher, and WildFly and Red Hat's AMQ broker are based on it.
Classic remains the right answer when your operations tooling, activemq.xml policies, OpenWire clients or JMX dashboards already exist, or when you rely on Classic-only features such as virtual topics and composite destinations. Both are actively maintained.
Common mistakes
- Leaving
admin/adminon the web console. Changeconf/jetty-realm.propertiesbefore the broker is reachable from anything but localhost, and restrict port 8161 to an operations network. - Running with the default heap on a real workload. The 1 GB
-Xmxinbin/envcombined withpercentOfJvmHeap="70"leaves little room; size the heap deliberately and monitor memory percent usage. - No failover URL on clients. A broker restart becomes an application incident. Wrap every URL in
failover:( ). - Prefetch 1000 with slow consumers. Symptoms are one busy consumer and idle peers, and large redelivery bursts after a crash. Lower the prefetch.
- Disabling producer flow control without limits. With flow control off and no store limit, a producer can fill the disk. Keep
storeUsageand alert on it. - Treating a network of brokers as replication. It is routing, not redundancy. Use a shared store for failover.
Key takeaways
- ActiveMQ Classic 6 needs Java 17, speaks OpenWire, AMQP 1.0, STOMP, MQTT and WebSocket, and runs from a tarball, a systemd unit or the official container image.
conf/activemq.xmlis a Spring XML file; the parts that matter are<destinationPolicy>,<persistenceAdapter>,<systemUsage>and<transportConnectors>.- Memory, store and temp limits trigger producer flow control; decide per destination whether producers should block, fail or spill to disk.
- Clients get resilience from
failover:( )URLs and fairness from a sensible prefetch, not from broker settings. - A network of brokers routes messages between brokers on demand; high availability needs a shared store.
- Artemis is the project's other broker, with a different configuration and address model; prefer it for new high-throughput or clustered deployments, Classic where existing tooling and features keep you there.
Sources and further reading
Frequently asked questions
- Which Java version does ActiveMQ Classic 6 need?
- Java 17 or later. The 6.x line moved to the jakarta.jms namespace and Java 17 at the same time, so it pairs with Jakarta EE 10 servers and Spring Boot 3.2+. If you are stuck on Java 8 or 11 or on javax.jms clients, stay on the 5.18 line, which is still maintained but is a dead end for new features.
- What is the difference between ActiveMQ Classic and ActiveMQ Artemis?
- They are two brokers under one Apache project. Classic is the original code base with activemq.xml, KahaDB and OpenWire. Artemis descends from HornetQ, uses a different address model, its own journal, a broker.xml configuration and supports AMQP 1.0 as a first-class protocol; WildFly embeds it. Both implement JMS. Classic is the safe choice when you have existing configuration and tooling; Artemis is the better platform for new, high-throughput or clustered deployments.
- Why does my producer hang and never return from send()?
- Almost always producer flow control. The destination or the broker reached its memory, store or temp limit and the broker stopped acknowledging sends, so a synchronous producer blocks. Check the web console for destinations with high memory percent usage, add consumers or raise limits, and set sendFailIfNoSpace if you prefer an exception to a hang.
- Can I run ActiveMQ inside my application instead of as a separate server?
- Yes. The vm:// transport starts an embedded broker inside the JVM on first connection; add ?broker.persistent=false for a pure in-memory broker. It is ideal for integration tests and small single-node tools, but a shared production broker should run as its own process with its own lifecycle and monitoring.