Amazon MQ DG

Amazon MQ
Developer Guide
Amazon MQ Developer Guide
Amazon MQ: Developer Guide

Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
Table of Contents
What is Amazon MQ? ......................................................................................................................... 1
What Are the Main Benefits of Amazon MQ? ................................................................................. 1
How Is Amazon MQ Different from Amazon SQS or Amazon SNS? .................................................... 1
How Can I Get Started with Amazon MQ? ..................................................................................... 2
We Want to Hear from You ......................................................................................................... 2
Frequently Viewed Topics .................................................................................................................... 3
Setting Up ........................................................................................................................................ 4
Step 1: Create an AWS Account and an IAM Administrator User ........................................................ 4
Step 2: Create an IAM User and Get Your AWS Credentials .............................................................. 4
Step 3: Get Ready to Use the Example Code ................................................................................. 5
Next Steps ................................................................................................................................ 5
Getting Started .................................................................................................................................. 6
Prerequisites .............................................................................................................................. 6
Step 1: Create an ActiveMQ Broker .............................................................................................. 6
Step 2: Connect a Java Application to Your Broker ......................................................................... 7
Prerequisites ...................................................................................................................... 7
Create a Message Producer and Send a Message .................................................................... 8
Create a Message Consumer and Receive the Message ............................................................ 9
Step 3: Delete Your Broker ........................................................................................................ 10
Next Steps ............................................................................................................................... 10
Tutorials .......................................................................................................................................... 12
Creating and Configuring a Broker .............................................................................................. 12
Step 1: Configure Basic Broker Settings ............................................................................... 12
Step 2: (Optional) Configure Advanced Broker Settings ......................................................... 13
Step 3: Finish Creating the Broker ...................................................................................... 14
Accessing the ActiveMQ Web Console of a Broker without Public Accessibility ........................... 15
Creating and Configuring a Network of Brokers ............................................................................ 16
Prerequisites .................................................................................................................... 17
Step 1: Allow Traffic between Brokers ................................................................................. 17
Step 2: Configure Network Connectors for Your Broker ......................................................... 18
Next Steps ....................................................................................................................... 19
Editing Broker Preferences ......................................................................................................... 20
To Edit Broker Engine Version, CloudWatch Logs, and Maintenance Preferences ........................ 20
Creating and Applying Configurations ......................................................................................... 21
Step 1: Create a Configuration from Scratch ........................................................................ 21
Step 2: Create a New Configuration Revision ....................................................................... 21
Step 3: Apply a Configuration Revision to Your Broker .......................................................... 22
Editing Configurations and Managing Configuration Revisions ........................................................ 23
To View a Previous Configuration Revision ........................................................................... 23
To Edit the Current Configuration Revision .......................................................................... 20
To Apply a Configuration Revision to Your Broker ................................................................. 25
To Roll Back Your Broker to the Last Configuration Revision ................................................... 25
Connecting a Java Application to Your Broker .............................................................................. 26
Prerequisites .................................................................................................................... 26
To Create a Message Producer and Send a Message .............................................................. 27
To Create a Message Consumer and Receive the Message ...................................................... 28
Listing Brokers and Viewing Broker Details .................................................................................. 29
To List Brokers and View Broker Details .............................................................................. 29
Creating and Managing Broker Users .......................................................................................... 30
To Create a New User ....................................................................................................... 31
To edit an existing user ..................................................................................................... 31
To Delete an Existing User ................................................................................................. 32
Rebooting a Broker ................................................................................................................... 32
To Reboot an Amazon MQ Broker ...................................................................................... 32
iii
Deleting a Broker ..................................................................................................................... 33

To Delete an Amazon MQ Broker ....................................................................................... 33
Accessing CloudWatch Metrics .................................................................................................... 33
AWS Management Console ................................................................................................ 34
AWS Command Line Interface ............................................................................................ 35
Amazon CloudWatch API ................................................................................................... 35
How Amazon MQ Works ................................................................................................................... 36
Basic Elements ......................................................................................................................... 36
Broker ............................................................................................................................. 36
Configuration ................................................................................................................... 41
Engine ............................................................................................................................ 42
User ................................................................................................................................ 43
Broker Architecture ................................................................................................................... 43
Single-Instance Broker ...................................................................................................... 44
Active/Standby Broker for High Availability ......................................................................... 45
Network of Brokers .......................................................................................................... 46
Broker Configuration Lifecycle ........................................................................................... 54
Broker Configuration Parameters ................................................................................................ 54
Working with Spring XML Configuration Files ....................................................................... 55
Permitted Elements .......................................................................................................... 55
Permitted Attributes ......................................................................................................... 57
Permitted Collections ........................................................................................................ 65
Working Java Examples ............................................................................................................. 70
Prerequisites .................................................................................................................... 71
AmazonMQExample.java ................................................................................................... 73
Tagging resources ..................................................................................................................... 78
Tagging for Cost Allocation ............................................................................................... 78
Managing Tags in the Amazon MQ Console ......................................................................... 78
Managing Using Amazon MQ API Actions ............................................................................ 79
Migrating to Amazon MQ .................................................................................................................. 80
Without Service Interruption ...................................................................................................... 80
To migrate to Amazon MQ without service interruption ........................................................ 81
With Service Interruption .......................................................................................................... 82
To migrate to Amazon MQ with service interruption ............................................................. 83
Best Practices .................................................................................................................................. 85
Using Amazon MQ Securely ....................................................................................................... 85
Prefer Brokers without Public Accessibility ........................................................................... 85
Always Use Client-Side Encryption as a Complement to TLS .................................................. 85
Always Configure an Authorization Map .............................................................................. 86
Always Configure a System Group ...................................................................................... 86
Block Unnecessary Protocols .............................................................................................. 86
Connecting to Amazon MQ ....................................................................................................... 86
Never Modify or Delete the Amazon MQ Elastic Network Interface .......................................... 87
Always Use Connection Pooling ......................................................................................... 87
Always Use the Failover Transport to Connect to Multiple Broker Endpoints ............................. 88
Avoid Using Message Selectors .......................................................................................... 88
Prefer Virtual Destinations to Durable Subscriptions ............................................................. 88
Ensuring Effective Amazon MQ Performance ............................................................................... 88
Disable Concurrent Store and Dispatch for Queues with Slow Consumers ................................. 89
Choose the Correct Broker Instance Type for the Best Throughput .......................................... 89
Configure Your Network of Brokers Correctly ....................................................................... 90
Avoid Slow Restarts by Recovering Prepared XA Transactions ......................................................... 90
Limits ............................................................................................................................................. 92
Brokers .................................................................................................................................... 92
Configurations ......................................................................................................................... 92
Users ...................................................................................................................................... 93
Data Storage ........................................................................................................................... 93
iv
API Throttling .......................................................................................................................... 93

Monitoring and Logging .................................................................................................................... 95
Monitoring Brokers Using CloudWatch ........................................................................................ 95
Broker Metrics .................................................................................................................. 95
Destination (Queue and Topic) Metrics ................................................................................ 97
Logging API Calls Using CloudTrail ............................................................................................. 99
Amazon MQ Information in CloudTrail ................................................................................ 99
Example Amazon MQ Log File Entry ................................................................................. 100
Configuring Amazon MQ to Publish Logs to CloudWatch Logs ...................................................... 101
Understanding the Structure of Logging in CloudWatch Logs ............................................... 102
Add the CreateLogGroup Permission to Your Amazon MQ User ............................................. 102
Configure a Resource-Based Policy for Amazon MQ ............................................................ 103
Troubleshooting CloudWatch Logs Configuration ................................................................ 104
Security ......................................................................................................................................... 105
Tag-based Policies .................................................................................................................. 105
Authentication ....................................................................................................................... 105
API Authentication and Authorization ....................................................................................... 107
IAM Permissions Required to Create an Amazon MQ Broker .................................................. 107
REST API Permissions Reference ....................................................................................... 108
Supported Resource-Level Permissions .............................................................................. 109
Messaging Authentication and Authorization .............................................................................. 109
Related Resources ........................................................................................................................... 111
Amazon MQ Resources ............................................................................................................ 111
Apache ActiveMQ Resources .................................................................................................... 111
Release Notes ................................................................................................................................ 113
Document History .................................................................................................................. 118
AWS Glossary ................................................................................................................................. 127
v
What Are the Main Benefits of Amazon MQ?
What Is Amazon MQ?

Amazon MQ is a managed message broker service for Apache ActiveMQ that makes it easy to migrate
to a message broker in the cloud. A message broker allows software applications and components
to communicate using various programming languages, operating systems, and formal messaging
protocols.
Amazon MQ works with your existing applications and services without the need to manage, operate, or
maintain your own messaging system.
Topics
• What Are the Main Benefits of Amazon MQ? (p. 1)
• How Is Amazon MQ Different from Amazon SQS or Amazon SNS? (p. 1)
• How Can I Get Started with Amazon MQ? (p. 2)
• We Want to Hear from You (p. 2)
What Are the Main Benefits of Amazon MQ?

• Security – You control who can create and modify brokers (p. 107) and who can send messages to
and receive messages from (p. 109) an ActiveMQ broker. Amazon MQ encrypts messages at rest and
in transit using encryption keys that it manages and stores securely.
• Durability – To ensure the safety of your messages, Amazon MQ stores them on redundant shared
storage (p. 43).
• Availability – You can create a single-instance broker (p. 44) (comprised of one broker in one
Availability Zone), or an active/standby broker for high availability (p. 45) (comprised of two brokers
in two different Availability Zones). For either broker type, Amazon MQ automatically provisions
infrastructure for high durability.
• Compatibility – Amazon MQ supports industry-standard APIs and protocols so you can migrate from
your existing message broker (p. 80) without rewriting application code (p. 70).
• Operation offloading – You can configure many aspects of your ActiveMQ broker (p. 54), such
as predefined destinations, destination policies, authorization policies, and plugins. Amazon MQ
controls some of these configuration elements, such as network transports and storage, simplifying
the maintenance and administration of your messaging system in the cloud.
How Is Amazon MQ Different from Amazon SQS or

Amazon SNS?
Amazon MQ is a managed message broker service that provides compatibility with many popular
message brokers. We recommend Amazon MQ for migrating applications from existing message brokers
that rely on compatibility with APIs such as JMS or protocols such as AMQP, MQTT, OpenWire, and
STOMP.
Amazon SQS and Amazon SNS are queue and topic services that are highly scalable, simple to use, and
don't require you to set up message brokers. We recommend these services for new applications that can
benefit from nearly unlimited scalability and simple APIs.
1
How Can I Get Started with Amazon MQ?
How Can I Get Started with Amazon MQ?

• To create your first broker with Amazon MQ, see Getting Started with Amazon MQ (p. 6).
• To discover the functionality and architecture of Amazon MQ, see How Amazon MQ Works (p. 36).
• To find out the guidelines and caveats that will help you make the most of Amazon MQ, see Best
Practices for Amazon MQ (p. 85).
• To learn about Amazon MQ REST APIs, see the Amazon MQ REST API Reference.
• To learn about Amazon MQ AWS CLI commands, see Amazon MQ in the AWS CLI Command Reference.
We Want to Hear from You

We welcome your feedback. To contact us, visit the Amazon MQ Discussion Forum.
2
Frequently Viewed Amazon MQ

Topics
Latest update: October 8, 2018
Amazon MQ Developer Guide Amazon MQ REST API Reference
1. Working Java Example (p. 70) 1. Broker

2. Connecting a Java Application to Your 2. Configuration
Broker (p. 26) 3. User
3. Getting Started with Amazon MQ (p. 6) 4. Resources
4. Creating and Configuring a Broker (p. 12) 5. Brokers
5. Amazon MQ Broker Configuration 6. Broker Reboot
Parameters (p. 54)
7. Configurations
6. Connecting to Amazon MQ (p. 86)
8. Users
7. Limits in Amazon MQ (p. 92)
9. Configuration Revision
8. Using Amazon MQ Securely (p. 85)
10.Configuration Revisions
9. Amazon MQ Broker Architecture (p. 43)
10.Amazon MQ Active/Standby Broker for High
Availability (p. 45)
3
Step 1: Create an AWS Account
and an IAM Administrator User
Setting Up Amazon MQ
Before you can use Amazon MQ, you must complete the following steps.
Topics
• Step 1: Create an AWS Account and an IAM Administrator User (p. 4)
• Step 2: Create an IAM User and Get Your AWS Credentials (p. 4)
• Step 3: Get Ready to Use the Example Code (p. 5)
• Next Steps (p. 5)
Step 1: Create an AWS Account and an IAM

Administrator User
To access any AWS service, you must first create an AWS account. This is an Amazon account that can
use AWS products. You can use your AWS account to view your activity and usage reports and to manage
authentication and access.
1. Navigate to the AWS home page, and then choose Create an AWS Account.
2. Follow the instructions.
Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone
keypad.
3. When you finish creating your AWS account, follow the instructions in the IAM User Guide to create
your first IAM administrator user and group.
Step 2: Create an IAM User and Get Your AWS

Credentials
To avoid using your IAM administrator user for Amazon MQ operations, it is a best practice to create an
IAM user for each person who needs administrative access to Amazon MQ.
To work with Amazon MQ, you need the AmazonMQFullAccess policy and AWS credentials that are
associated with your IAM user. These credentials are comprised of an access key ID and a secret access
key. For more information, see What Is IAM? in the IAM User Guide and AWS Security Credentials in the
AWS General Reference.
1. Sign in to the AWS Identity and Access Management console.

2. Choose Users, Add user.
3. Type a User name, such as AmazonMQAdmin.
4. Select Programmatic access and AWS Management Console access.
5. Set a Console password and then choose Next: Permissions.
6. On the Set permissions for AmazonMQAdmin page, choose Attach existing policies directly.
7. Type AmazonMQ into the filter, choose AmazonMQFullAccess, and then choose Next: Review.
8. On the Review page, choose Create user.
4
Step 3: Get Ready to Use the Example Code
The IAM user is created and the Access key ID is displayed, for example:
AKIAIOSFODNN7EXAMPLE
9. To display your Secret access key, choose Show, for example:
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Important
You can view or download your secret access key only when you create your credentials
(however, you can create new credentials at any time).
10. To download your credentials, choose Download .csv. Keep this file in a secure location.
Step 3: Get Ready to Use the Example Code

The following tutorials show how you can work with Amazon MQ and ActiveMQ using the AWS
Management Console and Java. To use the example code, you must install the Java Standard Edition
Development Kit and make some changes to the code.
You can also create and manage brokers programmatically using Amazon MQ REST API and AWS SDKs.
Next Steps
Now that you're prepared to work with Amazon MQ, get started by creating a broker (p. 6) and then
connecting a Java application (p. 26) to your broker.
You can also try the more advanced Amazon MQ tutorials (p. 12).
For more information on configuring a network of brokers, see Network of Brokers (p. 46).
5
Prerequisites
Getting Started with Amazon MQ

This section will help you become more familiar with Amazon MQ by showing you how to create a broker
and how to connect your application to it.
The following 3-minute video provides a preview of creating and using an Amazon MQ broker.
Topics
• Prerequisites (p. 6)
• Step 1: Create an ActiveMQ Broker (p. 6)
• Step 2: Connect a Java Application to Your Broker (p. 7)
• Step 3: Delete Your Broker (p. 10)
Prerequisites
Before you begin, complete the steps in Setting Up Amazon MQ (p. 4).
Step 1: Create an ActiveMQ Broker

A broker is a message broker environment running on Amazon MQ. It is the basic building block of
Amazon MQ. The combined description of the broker instance class (m5, t2) and size (large, micro) is a
broker instance type (for example, mq.m5.large). For more information, see Broker (p. 36).
The first and most common Amazon MQ task is creating a broker. The following example shows how you
can use the AWS Management Console to create a basic broker.
1. Sign in to the Amazon MQ console.

2. Do one of the following:
• If this is your first time using Amazon MQ, in the Create a broker section, type MyBroker for
Broker name and then choose Next step.
• If you have created a broker before, on the Create a broker page, in the Broker details section,
type MyBroker for Broker name.
3. In the Broker details section, choose a Broker instance type (for example, mq.m5.large). For more
information, see Broker Instance Types (p. 38).
4. Choose a Deployment mode. In this example, Single-instance broker is selected.
• A Single-instance broker is comprised of one broker in one Availability Zone. The broker
communicates with your application and with an AWS storage location. For more information, see
Amazon MQ Single-Instance Broker (p. 44).
• An Active/standby broker for high availability is comprised of two brokers in two different
Availability Zones, configured in a redundant pair. These brokers communicate synchronously
with your application, and with a shared storage location. For more information, see Amazon MQ
Active/Standby Broker for High Availability (p. 45).
5. Choose a Broker engine version.
Note
Currently, Amazon MQ supports only ActiveMQ broker engine versions 5.15.8, 5.15.6
and 5.15.0.
6
Step 2: Connect a Java Application to Your Broker
6. In the ActiveMQ Web Console access section, type a Username and Password.
7. Choose Create broker.
While Amazon MQ creates your broker, it displays the Creation in progress status.
Creating the broker takes about 15 minutes.
When your broker is created successfully, Amazon MQ displays the Running status.
8. Choose MyBroker.
On the MyBroker page, in the Connect section, note your broker's ActiveMQ Web Console URL, for
example:
https://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:8162
Also, note your broker's wire-level protocol Endpoints. The following is an example of an OpenWire
endpoint:
ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617
Step 2: Connect a Java Application to Your Broker

After you create an Amazon MQ broker, you can connect your application to it. The following examples
show how you can use the Java Message Service (JMS) to create a connection to the broker, create a
queue, and send a message. For a complete, working Java example, see Working Java Example (p. 70).
You can connect to ActiveMQ brokers using various ActiveMQ clients. We recommend using the
ActiveMQ Client.
Prerequisites
Enable VPC Attributes
To ensure that your broker is accessible within your VPC, you must enable the enableDnsHostnames
and enableDnsSupport VPC attributes. For more information, see DNS Support in your VPC in the
Amazon VPC User Guide.
Enable Inbound Connections

2. From the broker list, choose the name of your broker (for example, MyBroker).
3. On the MyBroker page, in the Connections section, note the addresses and ports of the broker's
ActiveMQ Web Console URL and wire-level protocols.
4. In the Details section, under Security and network, choose the name of your security group or .
The Security Groups page of the EC2 Dashboard is displayed.

5. From the security group list, choose your security group.
6. At the bottom of the page, choose Inbound, and then choose Edit.
7
Create a Message Producer and Send a Message
7. In the Edit inbound rules dialog box, add a rule for every URL or endpoint that you want to be
publicly accessible (the following example shows how to do this for an ActiveMQ Web Console).
a. Choose Add Rule.

b. For Type, select Custom TCP.
c. For Port Range, type the ActiveMQ Web Console port (8162).
d. For Source, leave Custom selected and then type the IP address of the system that you want to
be able to access the ActiveMQ Web Console (for example, 192.0.2.1).
e. Choose Save.
Your broker can now accept inbound connections.
Add Java Dependencies

Add the activemq-client.jar and activemq-pool.jar packages to your Java class path. The
following example shows these dependencies in a Maven project pom.xml file.
<dependencies>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-client</artifactId>
<version>5.15.8</version>
</dependency>
<dependency>
<artifactId>activemq-pool</artifactId>
</dependency>
</dependencies>
For more information about activemq-client.jar, see Initial Configuration in the Apache ActiveMQ
documentation.
Important
In the following example code, producers and consumers run in a single thread. For production
systems (or to test broker instance failover), make sure that your producers and consumers run
on separate hosts or threads.
Create a Message Producer and Send a Message

1. Create a JMS pooled connection factory for the message producer using your broker's endpoint and
then call the createConnection method against the factory.
Note
For an active/standby broker, Amazon MQ provides two ActiveMQ Web Console URLs,
but only one URL is active at a time. Likewise, Amazon MQ provides two endpoints for
each wire-level protocol, but only one endpoint is active in each pair at a time. The -1
and -2 suffixes denote a redundant pair. For more information, see Amazon MQ Broker
Architecture (p. 43)).
For wire-level protocol endpoints, you can allow your application to connect to either
endpoint by using the Failover Transport.
// Create a connection factory.

final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);
// Pass the username and password.
8
Create a Message Consumer and Receive the Message
connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);
// Create a pooled connection factory.

final PooledConnectionFactory pooledConnectionFactory = new PooledConnectionFactory();
pooledConnectionFactory.setConnectionFactory(connectionFactory);
pooledConnectionFactory.setMaxConnections(10);
// Establish a connection for the producer.

final Connection producerConnection = pooledConnectionFactory.createConnection();
producerConnection.start();
Note
Message producers should always use the PooledConnectionFactory class. For more
information, see Always Use Connection Pooling (p. 87).
2. Create a session, a queue named MyQueue, and a message producer.
// Create a session.
final Session producerSession = producerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);
// Create a queue named "MyQueue".

final Destination producerDestination = producerSession.createQueue("MyQueue");
// Create a producer from the session to the queue.

final MessageProducer producer = producerSession.createProducer(producerDestination);
producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
3. Create the message string "Hello from Amazon MQ!" and then send the message.
// Create a message.
final String text = "Hello from Amazon MQ!";
TextMessage producerMessage = producerSession.createTextMessage(text);
// Send the message.

producer.send(producerMessage);
System.out.println("Message sent.");
4. Clean up the producer.
producer.close();
producerSession.close();
producerConnection.close();
Create a Message Consumer and Receive the Message

1. Create a JMS connection factory for the message producer using your broker's endpoint and then
call the createConnection method against the factory.


// Establish a connection for the consumer.

final Connection consumerConnection = connectionFactory.createConnection();
9
Step 3: Delete Your Broker
consumerConnection.start();
Note
Message consumers should never use the PooledConnectionFactory class. For more
2. Create a session, a queue named MyQueue, and a message consumer.
final Session consumerSession = consumerConnection.createSession(false,

final Destination consumerDestination = consumerSession.createQueue("MyQueue");
// Create a message consumer from the session to the queue.

final MessageConsumer consumer = consumerSession.createConsumer(consumerDestination);
3. Begin to wait for messages and receive the message when it arrives.
// Begin to wait for messages.

final Message consumerMessage = consumer.receive(1000);
// Receive the message when it arrives.

final TextMessage consumerTextMessage = (TextMessage) consumerMessage;
System.out.println("Message received: " + consumerTextMessage.getText());
Note
Unlike AWS messaging services (such as Amazon SQS), the consumer is constantly
connected to the broker.
4. Close the consumer, session, and connection.
consumer.close();
consumerSession.close();
consumerConnection.close();
pooledConnectionFactory.stop();
Step 3: Delete Your Broker

If you don't use an Amazon MQ broker (and don't foresee using it in the near future), it is a best practice
to delete it from Amazon MQ to reduce your AWS costs.
The following example shows how you can delete a broker using the AWS Management Console.

2. From the broker list, select your broker (for example, MyBroker) and then choose Delete.
3. In the Delete MyBroker? dialog box, type delete and then choose Delete.
Deleting a broker takes about 5 minutes.
Next Steps
Now that you have created a broker, connected an application to it, and sent and received a message,
you might want to try the following:
10
Next Steps
• Creating and Configuring a Broker (p. 12) (Advanced Settings)

• Editing Broker Engine Version, CloudWatch Logs, and Maintenance Preferences (p. 20)
• Creating and Applying Broker Configurations (p. 21)
• Editing and Managing Broker Configurations (p. 23)
• Listing Brokers and Viewing Broker Details (p. 29)
• Creating and Managing Amazon MQ Broker Users (p. 30)
• Rebooting a Broker (p. 32)
• Accessing CloudWatch Metrics for Amazon MQ (p. 33)
You can also begin to dive deep into Amazon MQ best practices (p. 85) and Amazon MQ REST APIs,
and then plan to migrate to Amazon MQ (p. 80).
11
Creating and Configuring a Broker
Amazon MQ Tutorials
The following tutorials show how you can work with Amazon MQ and ActiveMQ using the AWS
Management Console and Java. To use the example code, you must install the Java Standard Edition
Development Kit and make some changes to the code.
Topics
• Tutorial: Creating and Configuring an Amazon MQ Broker (p. 12)
• Tutorial: Creating and Configuring an Amazon MQ Network of Brokers (p. 16)
• Tutorial: Editing Broker Engine Version, CloudWatch Logs, and Maintenance Preferences (p. 20)
• Tutorial: Creating and Applying Amazon MQ Broker Configurations (p. 21)
• Tutorial: Editing Amazon MQ Broker Configurations and Managing Configuration Revisions (p. 23)
• Tutorial: Connecting a Java Application to Your Amazon MQ Broker (p. 26)
• Tutorial: Listing Amazon MQ Brokers and Viewing Broker Details (p. 29)
• Tutorial: Creating and Managing Amazon MQ Broker Users (p. 30)
• Tutorial: Rebooting an Amazon MQ Broker (p. 32)
• Tutorial: Deleting an Amazon MQ Broker (p. 33)
• Tutorial: Accessing CloudWatch Metrics for Amazon MQ (p. 33)
Tutorial: Creating and Configuring an Amazon MQ

Broker
Amazon MQ. The combined description of the broker instance class (m5, t2) and size (large, micro) is a
broker instance type (for example, mq.m5.large). For more information, see Broker (p. 36).
The first and most common Amazon MQ task is creating a broker. The following example shows how you
can use the AWS Management Console to create and configure a broker using the AWS Management
Console.
Topics
• Step 1: Configure Basic Broker Settings (p. 12)
• Step 2: (Optional) Configure Advanced Broker Settings (p. 13)
• Step 3: Finish Creating the Broker (p. 14)
• Accessing the ActiveMQ Web Console of a Broker without Public Accessibility (p. 15)
Step 1: Configure Basic Broker Settings

2. Do one of the following:
12
Step 2: (Optional) Configure Advanced Broker Settings
• If this is your first time using Amazon MQ, in the Create a broker section, type MyBroker for
Broker name and then choose Next step.
• If you have created a broker before, on the Create a broker page, in the Broker details section,
type MyBroker for Broker name.
3. In the Broker details section, choose a Broker instance type (for example, mq.m5.large). For more
information, see Broker Instance Types (p. 38).
4. Choose a Deployment mode:
• A Single-instance broker is comprised of one broker in one Availability Zone. The broker
communicates with your application and with an AWS storage location. For more information, see
Amazon MQ Single-Instance Broker (p. 44).
• An Active/standby broker for high availability is comprised of two brokers in two different
Availability Zones, configured in a redundant pair. These brokers communicate synchronously
with your application, and with a shared storage location. For more information, see Amazon MQ
Active/Standby Broker for High Availability (p. 45).
• For more information on the sample blueprints for a network of brokers, see Sample
Blueprints (p. 48).
Note
and 5.15.0.
5. Choose a Broker engine version.
Note
and 5.15.0.
6. In the ActiveMQ Web Console access section, type a Username and Password.
Step 2: (Optional) Configure Advanced Broker

Settings
Important
• Subnet(s) – A single-instance broker requires one subnet (for example, the default subnet). An
active/standby broker requires two subnets.
• Security group(s) – Both single-instance brokers and active/standby brokers require at least
one security group (for example, the default security group).
• VPC – A broker's subnet(s) and security group(s) must be in the same VPC. EC2-Classic
resources aren't supported. Amazon MQ only supports default VPC tenancy, and does not
support dedicated VPC tenancy.
• Public accessibility – Disabling public accessibility makes the broker accessible only within
your VPC. For more information, see Prefer Brokers without Public Accessibility (p. 85) and
Accessing the ActiveMQ Web Console of a Broker without Public Accessibility (p. 15).
1. Expand the Advanced settings section.

2. In the Configuration section, choose Create a new configuration with default values or Select an
existing configuration. For more information, see Configuration (p. 41) and Amazon MQ Broker
Configuration Parameters (p. 54).
3. In the Logs section, choose whether to publish General logs and Audit logs to Amazon CloudWatch
Logs. For more information, see Configuring Amazon MQ to Publish Logs to Amazon CloudWatch
Logs (p. 101).
13
Step 3: Finish Creating the Broker
Important
If you don't add the CreateLogGroup permission to your Amazon MQ user (p. 102)
before the user creates or reboots the broker, Amazon MQ doesn't create the log group.
If you don't configure a resource-based policy for Amazon MQ (p. 103), the broker can't
publish the logs to CloudWatch Logs.
4. In the Network and security section, configure your broker's connectivity:
a. Do one of the following:
• Choose Use the default VPC, subnet(s), and security group(s).

• Choose Select existing VPC, subnet(s), and security group(s).
1. If you choose this option, you can create a new Virtual Private Cloud (VPC) on the Amazon
VPC console, select an existing VPC, or select the default VPC. For more information, see
What is Amazon VPC? in the Amazon VPC User Guide.
2. After you create or select a VPC, you can create new Subnet(s) on the Amazon VPC console
or select existing ones. For more information, see VPCs and Subnets in the Amazon VPC
User Guide.
3. After you create or select subnets, you can select the Security group(s).
b. Choose the Public accessibility of your broker.
5. In the Maintenance section, configure your broker's maintenance schedule:
a. To upgrade the broker to new versions as Apache releases them, choose Enable automatic
minor version upgrades. Automatic upgrades occur during the maintenance window defined by
the day of the week, the time of day (in 24-hour format), and the time zone (UTC by default).
Note
For an active/standby broker, if one of the broker instances undergoes maintenance,
it takes Amazon MQ a short while to take the inactive instance out of service, allowing
the healthy standby instance to become active and to begin accepting incoming
communications.
b. Do one of the following:
• To allow Amazon MQ to select the maintenance window automatically, choose No

preference.
• To set a custom maintenance window, choose Select maintenance window and then specify
the Start day and Start time of the upgrades.
Step 3: Finish Creating the Broker

1. Choose Create broker.
While Amazon MQ creates your broker, it displays the Creation in progress status.
Creating the broker takes about 15 minutes.
When your broker is created successfully, Amazon MQ displays the Running status.
2. Choose MyBroker.
On the MyBroker page, in the Connect section, note your broker's ActiveMQ Web Console URL, for
example:
14
Accessing the ActiveMQ Web Console
of a Broker without Public Accessibility
https://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:8162
Also, note your broker's wire-level protocol Endpoints. The following is an example of an OpenWire
endpoint:
Note
For an active/standby broker, Amazon MQ provides two ActiveMQ Web Console URLs, but only
one URL is active at a time. Likewise, Amazon MQ provides two endpoints for each wire-level
protocol, but only one endpoint is active in each pair at a time. The -1 and -2 suffixes denote a
redundant pair. For more information, see Amazon MQ Broker Architecture (p. 43)).
For wire-level protocol endpoints, you can allow your application to connect to either endpoint
by using the Failover Transport.
Accessing the ActiveMQ Web Console of a Broker

without Public Accessibility
If you disable public accessibility for your broker, you must perform the following steps to be able to
access your broker's ActiveMQ Web Console.
Note
The names of the VPCs and security groups are specific to the following example.
Prerequisites
To perform the following steps, you must configure the following:
• VPCs
• The VPC without an internet gateway, to which the Amazon MQ broker is attached, named
private-vpc.
• A second VPC, with an internet gateway, named public-vpc.
• Both VPCs must be connected (for example, using VPC peering) so that the Amazon EC2 instances in
the public VPC can communicate with the EC2 instances in the private VPC.
• If you use VPC peering, the route tables for both VPCs must be configured for the peering
connection.
• Security Groups
• The security group used to create the Amazon MQ broker, named private-sg.
• A second security group used for the EC2 instance in the public-vpc VPC, named public-sg.
• private-sg must allow inbound connections from public-sg. We recommend restricting this
security group to port 8162.
• public-sg must allow inbound connections from your machine on port 22.
To Access the ActiveMQ Web Console of a Broker without Public

Accessibility
1. Create a Linux EC2 instance in public-vpc (with a public IP, if necessary).
2. To verify that your VPC is configured correctly, establish an ssh connection to the EC2 instance and
use the curl command with the URI of your broker.
15
Creating and Configuring a Network of Brokers
3. From your machine, create an ssh tunnel to the EC2 instance using the path to your private key file
and the IP address of your broker instance. For example:
ssh -i ~/.ssh/id_rsa -N -C -q -f -D 8080 ec2-user@203.0.113.0
A forward proxy server is started on your machine.

4. Install a proxy client such as FoxyProxy on your machine.
5. Configure your proxy client using the following settings:
• For proxy type, specify SOCKS5.

• For IP address, DNS name, and server name, specify localhost.
• For port, specify 8080.
• Remove any existing URL patterns.
• For the URL pattern, specify *.mq.*.amazonaws.com*
• For the connection type, specify HTTP(S).
When you enable your proxy client, you can access the ActiveMQ Web Console on your machine.
Tutorial: Creating and Configuring an Amazon MQ

Network of Brokers
A network of brokers is comprised of multiple simultaneously active single-instance brokers (p. 44)
or active/standby brokers (p. 45). You can configure networks of brokers in a variety of
topologies (p. 48) (for example, concentrator, hub-and-spokes, tree, or mesh), depending on your
application's needs, such as high availability and scalability. For instance, a hub and spoke (p. 50)
network of brokers can increase resiliency, preserving messages if one broker is not reachable. A network
of brokers with a concentrator (p. 51) topology can collect messages from a larger number of brokers
accepting incoming messages, and concentrate them to more central brokers, to better handle the load
of many incoming messages. In this tutorial, you learn how to create a two-broker network of brokers
with a source and sink topology.
For a conceptual overview and detailed configuration information, see the following:
• Amazon MQ Network of Brokers (p. 46)

• Configure Your Network of Brokers Correctly (p. 90)
• networkConnector (p. 68)
• networkConnectionStartAsync (p. 64)
• Networks of Brokers in the ActiveMQ documentation
You can use the Amazon MQ console to create an Amazon MQ network of brokers. Because you can start
the creation of the two brokers in parallel, this process takes approximately 15 minutes.
Topics
• Step 1: Allow Traffic between Brokers (p. 17)
• Step 2: Configure Network Connectors for Your Broker (p. 18)
16
Prerequisites
Prerequisites
To create a network of brokers, you must have the following:
• Two or more simultaneously active brokers (named MyBroker1 and MyBroker2 in this tutorial). For
more information about creating brokers, see Creating and Configuring a Broker (p. 12).
• The two brokers must be in the same VPC or in peered VPCs. For more information about VPCs, see
What is Amazon VPC? in the Amazon VPC User Guide and What is VPC Peering? in the Amazon VPC
Peering Guide.
Important
If you don't have a default VPC, subnet(s), or security group, you must create them first. For
more information, see the following in the Amazon VPC User Guide:
• Creating a Default VPC
• Creating a Default Subnet
• Creating a Security Group
• Two users with identical usernames and passwords for both brokers. For more information about
creating users, see Creating and Managing Amazon MQ Broker Users (p. 30).
The following example uses two single-instance brokers (p. 44). However, you can create networks of
brokers using active/standby brokers (p. 45) or a combination of broker deployment modes.
Step 1: Allow Traffic between Brokers

After you create your brokers, you must allow traffic between them.
1. On the Amazon MQ console, on the MyBroker2 page, in the Details section, under Security and
network, choose the name of your security group or .

4. In the Edit inbound rules dialog box, add a rule for the OpenWire endpoint.
a. Choose Add Rule.

c. For Port Range, type the OpenWire port (61617).
d. Do one of the following:
• If you want to restrict access to a particular IP address, for Source, leave Custom selected, and
then enter the IP address of MyBroker1, followed by /32. (This converts the IP address to a
valid CIDR record). For more information see Elastic Network Interfaces.
Tip
To retrieve the IP address of MyBroker1, on the Amazon MQ console, choose the
name of the broker and navigate to the Details section.
• If all the brokers are private and belong to the same VPC, for Source, leave Custom selected
and then type the ID of the security group you are editing.
Note
For public brokers, you must restrict access using IP addresses.
e. Choose Save.
17
Step 2: Configure Network Connectors for Your Broker
Step 2: Configure Network Connectors for Your

Broker
After you allow traffic between your brokers, you must configure network connectors for one of them.
1. Edit the configuration revision for broker MyBroker1.
a. On the MyBroker1 page, choose Edit.

b. On the Edit MyBroker1 page, in the Configuration section, choose View.
The broker engine type and version that the configuration uses (for example, Apache ActiveMQ
5.15.0) are displayed.
c. On the Configuration details tab, the configuration revision number, description, and broker
configuration in XML format are displayed.
d. Choose Edit configuration.
e. At the bottom of the configuration file, uncomment the <networkConnectors> section and
include the following information:
• The name for the network connector.

• The ActiveMQ Web Console username (p. 17) that is common to both brokers.
• Enable duplex connections.
• Do one of the following:
• If you are connecting the broker to a single-instance broker, use the static: prefix and the
OpenWire endpoint uri for MyBroker2. For example:
<networkConnectors>
<networkConnector name="connector_1_to_2" userName="myCommonUser"
duplex="true"
uri="static:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617)"/>
</networkConnectors>
• If you are connecting the broker to an active/standby broker, use the masterslave: prefix
and the OpenWire endpoint uri for both brokers. For example:
<networkConnectors>
<networkConnector name="connector_1_to_2" userName="myCommonUser"
duplex="true"
uri="masterslave:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617,
ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-2.mq.us-
Note
Don't include the password for the ActiveMQ user.
f. Choose Save.
g. In the Save revision dialog box, type Add network of brokers connector for
MyBroker2.
h. Choose Save to save the new revision of the configuration.
2. Edit MyBroker1 to set the latest configuration revision to apply immediately.
a. On the MyBroker1 page, choose Edit.

b. On the Edit MyBroker1 page, in the Configuration section, choose Schedule Modifications.
18
Next Steps
c. In the Schedule broker modifications section, choose to apply modifications Immediately.

d. Choose Apply.
MyBroker1 is rebooted and your configuration revision is applied.
The network of brokers is created.
Next Steps
After you configure your network of brokers, you can test it by producing and consuming messages.
Important
Make sure that you enable inbound connections (p. 71) from your local machine for broker
MyBroker1 on port 8162 (for the ActiveMQ Web Console) and port 6167 (for the OpenWire
endpoint).
You might also need to adjust your security group(s) settings to allow the producer and
consumer to connect to the network of brokers.
1. On the Amazon MQ console, navigate to the Connections section and note the ActiveMQ Web
Console endpoint for broker MyBroker1.
2. Navigate to the ActiveMQ Web Console for broker MyBroker1.
3. To verify that the network bridge is connected, choose Network.
In the Network Bridges section, the name and the address of MyBroker2 are listed in the Remote
Broker and Remote Address columns.
4. From any machine that has access to broker MyBroker2, create a consumer. For example:
activemq consumer --brokerUrl "ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-

east-2.amazonaws.com:61617" \
--user commonUser \
--password myPassword456 \
--destination queue://MyQueue
The consumer connects to the OpenWire endpoint of MyBroker1 and begins to consume messages
from queue MyQueue.
5. From any machine that has access to broker MyBroker1, create a producer and send some
messages. For example:
activemq producer --brokerUrl "ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-1.mq.us-

east-2.amazonaws.com:61617" \
--user commonUser \
--password myPassword456 \
--destination queue://MyQueue \
--persistent true \
--messageSize 1000 \
--messageCount 10000
The producer connects to the OpenWire endpoint of MyBroker1 and begins to produce persistent
messages to queue MyQueue.
19
Editing Broker Preferences
Tutorial: Editing Broker Engine Version,

CloudWatch Logs, and Maintenance Preferences
In addition to editing broker configurations and managing configuration revisions (p. 23), you can
configure preferences specific to the broker.
Note
All preferences except for those for automatic minor version upgrades require you to schedule
modifications. For more information, see Amazon MQ Broker Configuration Lifecycle (p. 54).
The following example shows how you can edit Amazon MQ broker preferences using the AWS
Management Console.
To Edit Broker Engine Version, CloudWatch Logs, and

Maintenance Preferences
2. From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3. On the Edit MyBroker page, in the Specifications section, select a Broker engine version.
4. In the Configuration section, select the configuration and revision for your broker. For more
information, see Editing and Managing Broker Configurations (p. 23).
5. In the CloudWatch Logs section, choose whether to publish General logs and Audit logs to Amazon
CloudWatch Logs. For more information, see Configuring Amazon MQ to Publish Logs to Amazon
CloudWatch Logs (p. 101).
Important
If you don't add the CreateLogGroup permission to your Amazon MQ user (p. 102)
before the user creates or reboots the broker, Amazon MQ doesn't create the log group.
If you don't configure a resource-based policy for Amazon MQ (p. 103), the broker can't
publish the logs to CloudWatch Logs.
6. In the Maintenance section, configure your broker's maintenance schedule:
To upgrade the broker to new versions as AWS releases them, choose Enable automatic minor
version upgrades. Automatic upgrades occur during the maintenance window defined by the day of
the week, the time of day (in 24-hour format), and the time zone (UTC by default).
Note
For an active/standby broker, if one of the broker instances undergoes maintenance, it takes
Amazon MQ a short while to take the inactive instance out of service, allowing the healthy
standby instance to become active and to begin accepting incoming communications.
7. Choose Schedule modifications.
Note
If you choose only Enable automatic minor version upgrades, the button changes to Save
because no broker reboot is necessary.
Your preferences are applied to your broker at the specified time.
20
Creating and Applying Configurations
Tutorial: Creating and Applying Amazon MQ

Broker Configurations
A configuration contains all of the settings for your ActiveMQ broker, in XML format (similar to
ActiveMQ's activemq.xml file). You can create a configuration before creating any brokers. You can
then apply the configuration to one or more brokers. You can apply a configuration immediately or
during a maintenance window.
Note
For more information, see the following:
• Configuration (p. 41)

• Amazon MQ Broker Configuration Lifecycle (p. 54)
• Amazon MQ Broker Configuration Parameters (p. 54)
The following example shows how you can create and apply an Amazon MQ broker configuration using
the AWS Management Console.
Topics
• Step 1: Create a Configuration from Scratch (p. 21)
• Step 2: Create a New Configuration Revision (p. 21)
• Step 3: Apply a Configuration Revision to Your Broker (p. 22)
Step 1: Create a Configuration from Scratch

2. On the left, expand the navigation panel and choose Configurations.
3. On the Configurations page, choose Create configuration.

4. On the Create configuration page, in the Details section, type the Configuration name (for
example, MyConfiguration) and select a Broker engine version.
Note
and 5.15.0.
5. Choose Create configuration.
Step 2: Create a New Configuration Revision

1. From the configuration list, choose MyConfiguration.
21
Step 3: Apply a Configuration Revision to Your Broker
Note
The first configuration revision is always created for you when Amazon MQ creates the
configuration.
On the MyConfiguration page, the broker engine type and version that your new configuration
revision uses (for example, Apache ActiveMQ 5.15.8) are displayed.
2. On the Configuration details tab, the configuration revision number, description, and broker
Note
Editing the current configuration creates a new configuration revision.
3. Choose Edit configuration and make changes to the XML configuration.

4. Choose Save.
The Save revision dialog box is displayed.

5. (Optional) Type A description of the changes in this revision.
6. Choose Save.
The new revision of the configuration is saved.

Important
The Amazon MQ console automatically sanitizes invalid and prohibited configuration
parameters according to a schema. For more information and a full list of permitted XML
parameters, see Amazon MQ Broker Configuration Parameters (p. 54).
Making changes to a configuration does not apply the changes to the broker immediately.
To apply your changes, you must wait for the next maintenance window (p. 25) or
reboot the broker (p. 32). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 54).
Currently, you can't delete a configuration.
Step 3: Apply a Configuration Revision to Your Broker

1. On the left, expand the navigation panel and choose Brokers.
22
Editing Configurations and
Managing Configuration Revisions
3. On the Edit MyBroker page, in the Configuration section, select a Configuration and a Revision
and then choose Schedule Modifications.
4. In the Schedule broker modifications section, choose whether to apply modifications During the
next scheduled maintenance window or Immediately.
Important
Your broker will be offline while it is being rebooted.
5. Choose Apply.
Your configuration revision is applied to your broker at the specified time.
Tutorial: Editing Amazon MQ Broker

Configurations and Managing Configuration
Revisions
ActiveMQ's activemq.xml file). You can apply a configuration immediately or during a maintenance
window.
Note
To keep track of the changes you make to your configuration, you can create configuration revisions.
For more information, see the following:

The following examples show how you can edit Amazon MQ broker configurations and manage broker
configuration revisions using the AWS Management Console.
Topics
• To View a Previous Configuration Revision (p. 23)
• To Edit the Current Configuration Revision (p. 20)
• To Apply a Configuration Revision to Your Broker (p. 25)
• To Roll Back Your Broker to the Last Configuration Revision (p. 25)
To View a Previous Configuration Revision

and then choose Edit.
23
To Edit the Current Configuration Revision
Note
Unless you select a configuration when you create a broker, the first configuration revision
is always created for you when Amazon MQ creates the broker.
On the MyBroker page, the broker engine type and version that the configuration uses (for
example, Apache ActiveMQ 5.15.8) are displayed.
4. Choose Revision history.
5. The configuration Revision number, Revision date, and Description are displayed for each revision.
6. Select a revision and choose View details.
The broker configuration in XML format is displayed.
To Edit the Current Configuration Revision

3. On the MyBroker page, choose Edit.
and then choose Edit.
Note
Unless you select a configuration when you create a broker, the first configuration revision
is always created for you when Amazon MQ creates the broker.
On the MyBroker page, the broker engine type and version that the configuration uses (for
example, Apache ActiveMQ 5.15.8) are displayed.
5. On the Configuration details tab, the configuration revision number, description, and broker
Note
Editing the current configuration creates a new configuration revision.
6. Choose Edit configuration and make changes to the XML configuration.

7. Choose Save.
The Save revision dialog box is displayed.

8. (Optional) Type A description of the changes in this revision.
9. Choose Save.
The new revision of the configuration is saved.
24
To Apply a Configuration Revision to Your Broker
Important
The Amazon MQ console automatically sanitizes invalid and prohibited configuration
parameters according to a schema. For more information and a full list of permitted XML
parameters, see Amazon MQ Broker Configuration Parameters (p. 54).
Making changes to a configuration does not apply the changes to the broker immediately.
To apply your changes, you must wait for the next maintenance window (p. 25) or
reboot the broker (p. 32). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 54).
To Apply a Configuration Revision to Your Broker

and then choose Schedule Modifications.
Important
5. Choose Apply.
To Roll Back Your Broker to the Last Configuration

Revision
3. On the MyBroker page, choose Actions, Roll back to last configuration.
4. (Optional) To review the Current configuration or the Last configuration, on the Roll back to the
last configuration page, in the Summary section, choose Edit for either configuration.
Important
6. Choose Apply.
25
Connecting a Java Application to Your Broker
Tutorial: Connecting a Java Application to Your

Amazon MQ Broker
After you create an Amazon MQ broker, you can connect your application to it. The following examples
show how you can use the Java Message Service (JMS) to create a connection to the broker, create a
queue, and send a message. For a complete, working Java example, see Working Java Example (p. 70).
You can connect to ActiveMQ brokers using various ActiveMQ clients. We recommend using the
ActiveMQ Client.
Topics
• To Create a Message Producer and Send a Message (p. 27)
• To Create a Message Consumer and Receive the Message (p. 28)
Prerequisites


a. Choose Add Rule.

e. Choose Save.

26
To Create a Message Producer and Send a Message
<dependencies>
<dependency>
</dependency>
<dependency>
</dependency>
</dependencies>
For more information about activemq-client.jar, see Initial Configuration in the Apache ActiveMQ
documentation.
Important
To Create a Message Producer and Send a Message

1. Create a JMS pooled connection factory for the message producer using your broker's endpoint and
then call the createConnection method against the factory.
Note
For an active/standby broker, Amazon MQ provides two ActiveMQ Web Console URLs,
but only one URL is active at a time. Likewise, Amazon MQ provides two endpoints for
each wire-level protocol, but only one endpoint is active in each pair at a time. The -1
and -2 suffixes denote a redundant pair. For more information, see Amazon MQ Broker
Architecture (p. 43)).
For wire-level protocol endpoints, you can allow your application to connect to either
endpoint by using the Failover Transport.




Note
Message producers should always use the PooledConnectionFactory class. For more
2. Create a session, a queue named MyQueue, and a message producer.
final Session producerSession = producerConnection.createSession(false,
27
To Create a Message Consumer and Receive the Message

final Destination producerDestination = producerSession.createQueue("MyQueue");

final MessageProducer producer = producerSession.createProducer(producerDestination);
3. Create the message string "Hello from Amazon MQ!" and then send the message.
TextMessage producerMessage = producerSession.createTextMessage(text);

4. Clean up the producer.
producer.close();
To Create a Message Consumer and Receive the

Message
1. Create a JMS connection factory for the message producer using your broker's endpoint and then
call the createConnection method against the factory.



Note
Message consumers should never use the PooledConnectionFactory class. For more
2. Create a session, a queue named MyQueue, and a message consumer.
final Session consumerSession = consumerConnection.createSession(false,

final Destination consumerDestination = consumerSession.createQueue("MyQueue");

final MessageConsumer consumer = consumerSession.createConsumer(consumerDestination);
28
Listing Brokers and Viewing Broker Details
3. Begin to wait for messages and receive the message when it arrives.


Note
Unlike AWS messaging services (such as Amazon SQS), the consumer is constantly
connected to the broker.
4. Close the consumer, session, and connection.
consumer.close();
Tutorial: Listing Amazon MQ Brokers and Viewing

Broker Details
When you request that Amazon MQ create a broker, the creation process can take about 15 minutes..
The following example shows how you can confirm your broker's existence by listing your brokers in the
current region using the AWS Management Console.
To List Brokers and View Broker Details

Your brokers in the current region are listed.
The following information is displayed for each broker:
• Name
• Creation date
• Status (p. 41)
• Deployment mode (p. 43)
• Instance type (p. 38)
2. Choose your broker's name (for example, MyBroker).
On the MyBroker page, the configured (p. 41) Details are displayed for your broker:
29
Creating and Managing Broker Users
Below the Details section, the following information is displayed:
• In the Connections section, the ActiveMQ Web Console URL and the wire-level protocol endpoints
• In the Users section, the users (p. 43) associated with the broker
Tutorial: Creating and Managing Amazon MQ

Broker Users
An ActiveMQ user is a person or an application that can access the queues and topics of an ActiveMQ
broker. You can configure users to have specific permissions. For example, you can allow some users to
access the ActiveMQ Web Console.
A group is a semantic label. You can assign a group to a user and configure permissions for groups to
send to, receive from, and administer specific queues and topics.
Note
You can't configure groups independently of users. A group label is created when you add at
least one user to it and deleted when you remove all users from it.
30
To Create a New User
The following examples show how you can create, edit, and delete Amazon MQ broker users using the
AWS Management Console.
Topics
• To Create a New User (p. 31)
• To edit an existing user (p. 31)
• To Delete an Existing User (p. 32)
To Create a New User

2. From the broker list, choose the name of your broker (for example, MyBroker) and then choose Edit.
On the MyBroker page, in the Users section, all the users for this broker are listed.
3. Choose Create user.

4. In the Create user dialog box, type a Username and Password.
5. (Optional) Type the names of groups to which the user belongs, separated by commas (for example:
Devs, Admins).
6. (Optional) To enable the user to access the ActiveMQ Web Console, choose ActiveMQ Web Console.
7. Choose Create user.
Important
Making changes to a user does not apply the changes to the user immediately. To apply
your changes, you must wait for the next maintenance window (p. 25) or reboot
the broker (p. 32). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 54).
To edit an existing user

3. Select a username and choose Edit.
The Edit user dialog box is displayed.

4. (Optional) Type a new Password.
5. (Optional) Add or remove the names of groups to which the user belongs, separated by commas (for
example: Managers, Admins).
31
To Delete an Existing User
6. (Optional) To enable the user to access the ActiveMQ Web Console, choose ActiveMQ Web Console.
7. To save the changes to the user, choose Done.
Important
Lifecycle (p. 54).
To Delete an Existing User

3. Select a username (for example, MyUser) and then choose Delete.

4. To confirm deleting the user, in the Delete MyUser? dialog box, choose Delete.
Important
Lifecycle (p. 54).
Tutorial: Rebooting an Amazon MQ Broker

To apply a new configuration to a broker, you can reboot the broker. In addition, if your broker becomes
unresponsive, you can reboot it to recover from a faulty state.
The following example shows how you can reboot an Amazon MQ broker using the AWS Management
Console.
To Reboot an Amazon MQ Broker

3. On the MyBroker page, choose Actions, Reboot broker.
Important
32
Deleting a Broker
4. In the Reboot broker dialog box, choose Reboot.
Rebooting the broker takes about 5 minutes.
Tutorial: Deleting an Amazon MQ Broker

If you don't use an Amazon MQ broker (and don't foresee using it in the near future), it is a best practice
to delete it from Amazon MQ to reduce your AWS costs.
The following example shows how you can delete a broker using the AWS Management Console.
To Delete an Amazon MQ Broker

2. From the broker list, select your broker (for example, MyBroker) and then choose Delete.
3. In the Delete MyBroker? dialog box, type delete and then choose Delete.
Deleting a broker takes about 5 minutes.
Tutorial: Accessing CloudWatch Metrics for

Amazon MQ
Amazon MQ and Amazon CloudWatch are integrated so you can use CloudWatch to view and analyze
metrics for your ActiveMQ broker and the broker's destinations (queues and topics). You can view and
analyze your Amazon MQ metrics from the CloudWatch console, the AWS CLI, or the CloudWatch CLI.
CloudWatch metrics for Amazon MQ are automatically polled from the broker and then pushed to
CloudWatch every minute.
For a full list of Amazon MQ metrics, see Monitoring Amazon MQ Using CloudWatch (p. 95).
For information about creating a CloudWatch alarm for a metrics, see Create or Edit a CloudWatch Alarm
in the Amazon CloudWatch User Guide.
Note
There is no charge for the Amazon MQ metrics reported in CloudWatch. These metrics are
provided as part of the Amazon MQ service.
CloudWatch monitors only the first 200 destinations.
Topics
• AWS Management Console (p. 34)
• AWS Command Line Interface (p. 35)
• Amazon CloudWatch API (p. 35)
33
AWS Management Console
AWS Management Console

The following example shows you how to access CloudWatch metrics for Amazon MQ using the AWS
Management Console.
Note
If you're already signed into the Amazon MQ console, on the broker Details page, choose
Actions, View CloudWatch metrics.
1. Sign in to the CloudWatch console.

2. On the navigation panel, choose Metrics.
3. Select the AmazonMQ metric namespace.
4. Select one of the following metric dimensions:
• Broker Metrics
• Queue Metrics by Broker
• Topic Metrics by Broker
In this example, Broker Metrics is selected.
5. You can now examine your Amazon MQ metrics:
• To sort the metrics, use the column heading.
34
AWS Command Line Interface
• To graph the metric, select the check box next to the metric.
• To filter by metric, choose the metric name and then choose Add to search.
AWS Command Line Interface

To access Amazon MQ metrics using the AWS CLI, use the get-metric-statistics command.
For more information, see Get Statistics for a Metric in the Amazon CloudWatch User Guide.
Amazon CloudWatch API

To access Amazon MQ metrics using the CloudWatch API, use the GetMetricStatistics action.
For more information, see Get Statistics for a Metric in the Amazon CloudWatch User Guide.
35
Basic Elements
How Amazon MQ Works

Amazon MQ makes it easy to create a message broker with the computing and storage resources that fit
your needs. You can create, manage, and delete brokers using the AWS Management Console, Amazon
MQ REST API, or the AWS Command Line Interface.
This section describes the basic elements of a message broker, lists available Amazon MQ broker instance
types and their statuses, provides an overview of broker architecture, explains broker configuration
parameters and offers a working example of using Java Message Service (JMS) with an ActiveMQ broker.
To learn about Amazon MQ REST APIs, see the Amazon MQ REST API Reference.
Topics
• Amazon MQ Basic Elements (p. 36)
• Amazon MQ Broker Architecture (p. 43)
• Working Examples of Using Java Message Service (JMS) with ActiveMQ (p. 70)
• Tagging resources (p. 78)
Amazon MQ Basic Elements

This section introduces key concepts essential to understanding Amazon MQ.
Topics
• Broker (p. 36)
• Engine (p. 42)
• User (p. 43)
Broker
Amazon MQ. The combined description of the broker instance class (m5, t2) and size (large, micro)
is a broker instance type (for example, mq.m5.large). For more information, see Broker Instance
Types (p. 38).
• A single-instance broker is comprised of one broker in one Availability Zone. The broker communicates
with your application and with an AWS storage location.
• An active/standby broker is comprised of two brokers in two different Availability Zones, configured in
a redundant pair. These brokers communicate synchronously with your application, and with a shared
storage location.
For more information, see Amazon MQ Broker Architecture (p. 43).
You can enable automatic minor version upgrades to new minor versions of the broker engine, as Apache
releases new versions. Automatic upgrades occur during the maintenance window defined by the day of
the week, the time of day (in 24-hour format), and the time zone (UTC by default).
For information about creating and managing brokers, see the following:
• Creating and Configuring a Broker (p. 12)
36
Broker
• Limits Related to Brokers (p. 92)

• Broker Statuses (p. 41)
Supported Wire-level Protocols

You can access your brokers by using any programming language that ActiveMQ supports and by
enabling TLS explicitly for the following protocols:
• AMQP
• MQTT
• MQTT over WebSocket
• OpenWire
• STOMP
• STOMP over WebSocket
Attributes
A broker has several attributes, for example:
• A name (MyBroker)
• An ID (b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9)
• An Amazon Resource Name (ARN) (arn:aws:mq:us-
east-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9)
• An ActiveMQ Web Console URL (https://
b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:8162)
For more information, see Web Console in the Apache ActiveMQ documentation.
Important
If you specify an authorization map which doesn't include the activemq-webconsole group,
you can't use the ActiveMQ Web Console because the group isn't authorized to send messages
to, or receive messages from, the Amazon MQ broker.
• Wire-level protocol endpoints:
• amqp+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:5671
• mqtt+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
• ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
Note
This is an OpenWire endpoint.
• stomp+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
• wss://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
For more information, see Configuring Transports in the Apache ActiveMQ documentation.
Note
For an active/standby broker, Amazon MQ provides two ActiveMQ Web Console URLs, but only
one URL is active at a time. Likewise, Amazon MQ provides two endpoints for each wire-level
37
Broker
protocol, but only one endpoint is active in each pair at a time. The -1 and -2 suffixes denote a
redundant pair.
For a full list of broker attributes, see the following in the Amazon MQ REST API Reference:
• REST Operation ID: Broker

• REST Operation ID: Brokers
• REST Operation ID: Broker Reboot
Instance Types
The combined description of the broker instance class (m5, t2) and size (large, micro) is a broker
instance type (for example, mq.m5.large). The following table lists the available Amazon MQ broker
instance types.
Instance Type vCPU Memory (GiB) Network Notes

Performance
mq.t2.micro 1 1 Low Use the

mq.t2.micro
instance type for
basic evaluation
of Amazon MQ.
This instance type
(single-instance
brokers only)
qualifies for the
AWS Free Tier.
Note
Using the
mq.t2.micro
instance
type is
subject
to CPU
credits
and
baseline
performance—
with the
ability
to burst
above the
baseline
level (for
more
information,
see the
CpuCreditBalance (p. 95)
metric).
If your
application
requires
fixed
performance,
38
Broker

Performance
consider
using an
mq.m5.large
instance
type.
mq.m5.large 2 8 High Use the

mq.m5.large
instance
for regular
development,
testing, and
production
workloads.
39
Broker

Performance
mq.m5.xlarge 4 16 High Use the

mq.m5.xlarge,
mq.m5.2xlarge 8 32 High mq.m5.2xlarge,
and
mq.m5.4xlarge 16 64 High
mq.m5.4xlarge
instance types
for regular
development,
testing and
production
workloads that
require high
throughput.
Note
When
your
system
uses
persistent
messages,
its
throughput
depends
on how
quickly
messages
are
consumed.
If
messages
aren't
consumed
immediately,
using
larger
instance
types
with
persistent
messages
might not
improve
system
throughput.
In this
case, we
recommend
setting
the
concurrentStoreAndDisp
attribute
to false.
For more
40
Configuration

Performance
information,
see
Disable
Concurrent
Store and
Dispatch
for
Queues
with Slow
Consumers (p. 89).
mq.m4.large 2 8 Moderate Use the

mq.m4.large
instance type for
compatibility with
existing broker
deployments.
We recommend
using an mq.m5.*
instance for new
brokers.
For more information about throughput considerations, see Choose the Correct Broker Instance Type for
the Best Throughput (p. 89).
Statuses
A broker's current condition is indicated by a status. The following table lists the statuses of an Amazon
MQ broker.
Console API Description
Creation failed CREATION_FAILED The broker couldn't be created.
Creation in progress CREATION_IN_PROGRESS The broker is currently being

created.
Deletion in progress DELETION_IN_PROGRESS The broker is currently being

deleted.
Reboot in progress REBOOT_IN_PROGRESS The broker is currently being

rebooted.
Running RUNNING The broker is operational.
Configuration
then apply the configuration to one or more brokers.
41
Engine
Important
Making changes to a configuration does not apply the changes to the broker immediately. To
apply your changes, you must wait for the next maintenance window (p. 25) or reboot the
broker (p. 32). For more information, see Amazon MQ Broker Configuration Lifecycle (p. 54).
For information about creating, editing, and managing configurations, see the following:

• Limits Related to Configurations (p. 92)
To keep track of the changes you make to your configuration, you can create configuration revisions. For
more information, see Creating and Applying Broker Configurations (p. 21) and Editing and Managing
Broker Configurations (p. 23).
Attributes
A broker configuration has several attributes, for example:
• A name (MyConfiguration)
• An ID (c-1234a5b6-78cd-901e-2fgh-3i45j6k178l9)
• An Amazon Resource Name (ARN) (arn:aws:mq:us-
east-2:123456789012:configuration:MyConfiguration:c-1234a5b6-78cd-901e-2fgh-3i45j6k178l9
For a full list of configuration attributes, see the following in the Amazon MQ REST API Reference:
• REST Operation ID: Configuration

• REST Operation ID: Configurations
For a full list of configuration revision attributes, see the following:
• REST Operation ID: Configuration Revision

• REST Operation ID: Configuration Revisions
Engine
A broker engine is a type of message broker that runs on Amazon MQ.
Amazon MQ supports the following versions of ActiveMQ:
• ActiveMQ 5.15.9 (recommended)

• ActiveMQ 5.15.8
• ActiveMQ 5.15.6
• ActiveMQ 5.15.0
42
User
User
An ActiveMQ user is a person or an application that can access the queues and topics of an ActiveMQ
broker. You can configure users to have specific permissions. For example, you can allow some users to
access the ActiveMQ Web Console.
A group is a semantic label. You can assign a group to a user and configure permissions for groups to
send to, receive from, and administer specific queues and topics.
Important
Making changes to a user does not apply the changes to the user immediately. To apply your
changes, you must wait for the next maintenance window (p. 25) or reboot the broker (p. 32).
For more information, see Amazon MQ Broker Configuration Lifecycle (p. 54).
For information about users and groups, see the following in the Apache ActiveMQ documentation:
• Authorization
• Authorization Example
For information about creating, editing, and deleting ActiveMQ users, see the following:

• Limits Related to Users (p. 93)
Attributes
For a full list of user attributes, see the following in the Amazon MQ REST API Reference:
• REST Operation ID: User

• REST Operation ID: Users
Amazon MQ Broker Architecture

Amazon MQ brokers can be created as single-instance brokers or active/standby brokers. For both
deployment modes, Amazon MQ provides high durability by storing its data redundantly, across multiple
Availability Zones (multi-AZs) within an AWS Region. Amazon MQ ensures high availability by providing
failover to a standby instance in a second Availability Zone.
Note
Amazon MQ uses Apache KahaDB as its data store. Other data stores, such as JDBC and LevelDB,
aren't supported.
You can access your brokers by using any programming language that ActiveMQ supports and by
enabling TLS explicitly for the following protocols:
• AMQP
• MQTT
• OpenWire
• STOMP
43
Single-Instance Broker
Topics
• Amazon MQ Single-Instance Broker (p. 44)
• Amazon MQ Active/Standby Broker for High Availability (p. 45)
Amazon MQ Single-Instance Broker

A single-instance broker is comprised of one broker in one Availability Zone. The broker communicates
with your application and with an AWS storage location.
The following diagram illustrates a single-instance broker.
44
Active/Standby Broker for High Availability
Amazon MQ Active/Standby Broker for High

Availability
An active/standby broker is comprised of two brokers in two different Availability Zones, configured in
a redundant pair. These brokers communicate synchronously with your application, and with a shared
storage location.
Normally, only one of the broker instances is active at any time, while the other broker instance is on
standby. If one of the broker instances malfunctions or undergoes maintenance, it takes Amazon MQ a
short while to take the inactive instance out of service, allowing the healthy standby instance to become
active and to begin accepting incoming communications. When you reboot a broker, the failover takes
only a few seconds.
For an active/standby broker, Amazon MQ provides two ActiveMQ Web Console URLs, but only one
URL is active at a time. Likewise, Amazon MQ provides two endpoints for each wire-level protocol, but
only one endpoint is active in each pair at a time. The -1 and -2 suffixes denote a redundant pair. For
wire-level protocol endpoints, you can allow your application to connect to either endpoint by using the
Failover Transport.
The following diagram illustrates an active/standby broker.
45
Network of Brokers
Amazon MQ Network of Brokers

Amazon MQ supports ActiveMQ's network of brokers feature.
A network of brokers is comprised of multiple simultaneously active single-instance brokers (p. 44)
or active/standby brokers (p. 45). You can configure networks of brokers in a variety of
topologies (p. 48) (for example, concentrator, hub-and-spokes, tree, or mesh), depending on your
application's needs, such as high availability and scalability. For instance, a hub and spoke (p. 50)
network of brokers can increase resiliency, preserving messages if one broker is not reachable. A network
of brokers with a concentrator (p. 51) topology can collect messages from a larger number of brokers
accepting incoming messages, and concentrate them to more central brokers, to better handle the load
of many incoming messages.
For a tutorial and detailed configuration information, see the following:
• Creating and Configuring a Network of Brokers (p. 16)

46
Network of Brokers

• Networks of Brokers in the ActiveMQ documentation
The following are benefits of using a network of brokers:
• Creating a network of brokers allows you to increase your aggregate throughput and maximum
producer and consumer connection count by adding broker instances.
• You can ensure better availability by allowing your producers and consumers to be aware of multiple
active broker instances. This allows them to reconnect to a new instance if the one they're currently
connected to becomes unavailable.
• Because producers and consumers can reconnect to another node in the network of brokers
immediately, and because there's no need to wait for a standby broker instance to become promoted,
client reconnection within a network of brokers is faster than for an active/standby broker for high
availability (p. 45).
Topics
• How Does a Network of Brokers Work? (p. 47)
• How Does a Network of Brokers Handle Credentials? (p. 48)
• Sample Blueprints (p. 48)
• Network of Brokers Topologies (p. 48)
• Cross Region (p. 52)
• Dynamic Failover With Transport Connectors (p. 53)
How Does a Network of Brokers Work?

Amazon MQ supports the ActiveMQ network of brokers feature in a number of ways. First, you can edit
the parameters within each broker's configuration to create a network of brokers, just as you would with
native ActiveMQ. Second, Amazon MQ has sample blueprints that use AWS CloudFormation to automate
the creation of a network of brokers. You can deploy these sample blueprints directly from the Amazon
MQ console, or you can edit the related AWS CloudFormation templates to create your own topologies
and configurations.
A network of brokers is established by connecting one broker to another using network connectors. Once
connected, these brokers provide message forwarding. For instance, if Broker1 establishes a network
connector to Broker2, messages on Broker1 are forwarded to Broker2 if there is a consumer on that
broker for the queue or topic. If the network connector is configured as duplex, messages are also
forwarded from Broker2 to Broker1. Network connectors are configured in the broker configuration.
See, Configuration (p. 41). For instance, here is and example networkConnector entry in a broker
configuration:
<networkConnectors>
<networkConnector name="connector_1_to_2" userName="myCommonUser" duplex="true"
A network of brokers ensures that messages flow from one broker instance to another, forwarding
messages only to the broker instances that have corresponding consumers. For the benefit of broker
instances adjacent to each other within the network, ActiveMQ sends messages to advisory topics about
producers and consumers connecting to and disconnecting from the network. When a broker instance
receives information about a producer that consumes from a particular destination, the broker instance
begins to forward messages. For more information, see Advisory Topics in the ActiveMQ documentation.
47
Network of Brokers
How Does a Network of Brokers Handle Credentials?

For broker A to connect to broker B in a network, broker A must use valid credentials, like any
other producer or consumer. Instead of providing a password in broker A's <networkConnector>
configuration, you must first create a user on broker A with the same values as another user on broker B
(these are separate, unique users that share the same username and password values). When you specify
the userName attribute in the <networkConnector> configuration, Amazon MQ will add the password
automatically at runtime.
Important
Don't specify the password attribute for the <networkConnector>. We don't recommend
storing plaintext passwords in broker configuration files, because this makes the passwords
visible in the Amazon MQ console. For more information, see Configure Network Connectors for
Your Broker (p. 18).
Brokers must be in the same VPC or in peered VPCs. For more information, see Prerequisites (p. 17) in the
Creating and Configuring a Network of Brokers (p. 16) tutorial.
Sample Blueprints
To get started using a Network of Brokers, Amazon MQ provides sample blueprints. These
sample blueprints create a Network of Brokers deployment, and all related resources using, AWS
CloudFormation. The two sample blueprints available are:
1. Mesh network of single instance brokers

2. Mesh network of active/standby brokers
From the Create brokers page, select one of the sample blueprints and choose Next. Once the resources
have been created, review the generated brokers and their configurations in the Amazon MQ console.
By creating brokers and configuring different networkConnector elements in the broker

configurations, you can create a network of brokers in many different topologies. For more information
on configuring a network of brokers, see Networks of Brokers in the ActiveMQ documentation.
Network of Brokers Topologies

By deploying brokers, and then configuring networkConnector entries in their configurations, you
can build a network of brokers using different network topologies. A network connector provides on-
48
Network of Brokers
demand message forwarding between connected brokers. Connections can be configured as duplex,
where messages are forwarded both ways between brokers, or not duplex, where the forwarding only
propagates from one broker to the other. For example, if we have a duplex connection between Broker1
and Broker2, messages will be forwarded from each to the other if there is a consumer.
With a duplex network connector, messages are forwarded from each broker to the other. These are
forwarded on-demand: if there is a consumer on Broker2 for a message on Broker1, the message is
forwarded. Similarly, if there is a consumer on Broker1 for a message on Broker2 the message is also
forwarded.
For non-duplex connections, messages are forwarded only from one broker to the other. In this example,
if there is a consumer on Broker2 for a message on Broker1, the message is forwarded. But messages will
not be forwarded from Broker2 to Broker1.
Using both duplex and non-duplex network connectors, it is possible to build a network of brokers in any
number of network topologies.
Note
In each of the network topology examples, the networkConnector elements reference
the endpoint of the brokers they connect to. Replace the broker endpoint entries in the
uri attributes with the endpoints of your brokers. See, Listing Brokers and Viewing Broker
Details (p. 29).
Mesh Topology
A mesh topology provides multiple brokers that are all connected to each other. This simple example
connects three single-instance brokers, but you can configure more brokers as a mesh.
This topology, and one that includes a mesh of active/standby pairs of brokers, can be created using
sample blueprints in the Amazon MQ console. You can create these sample blueprint deployment to see
a working network of brokers, and review how they are configured.
49
Network of Brokers
You can configure a three broker mesh network like this by adding a network connector to Broker1 that
makes duplex connections to both Broker2 and Broker3, and a single duplex connection between Broker2
and Broker3.
Network connectors for Broker1:
<networkConnectors>
uri="static:(ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-2.mq.us-
uri="static:(ssl://b-743c885d-2244-4c95-af67-a85017ff234e-3.mq.us-
<networkConnectors>
By adding the above connectors to the configurations of Broker1 and Broker2, you can create a mesh
between these three brokers that forwards message between all the brokers on demand. For more
information, see Amazon MQ Broker Configuration Parameters (p. 54).
Hub and Spoke Topology

In a hub and spoke topology, messages are preserved if there is a disruption to any broker on a spoke.
Messages are forwarded throughout, and only the central Broker1 is critical to the network’s operation.
To configure the hub and spoke network of brokers in this example, you could add a
networkConnector to each of the brokers on the spokes in the configuration of Broker1.
<networkConnectors>
50
Network of Brokers
<networkConnector name="connector_hub_and_spoke_2" userName="myCommonUser"

duplex="true"
duplex="true"
duplex="true"
duplex="true"
uri="static:(ssl://b-62a7fb31-d51c-466a-a873-905cd660b553-4.mq.us-
Concentrator Topology
In this example topology, the three brokers on the bottom can handle a large number of connections,
and those messages are concentrated to Broker1 and Broker2. Each of the other brokers has a non-
duplex connection to the more central brokers. To scale the capacity of this topology, you can add
additional brokers that receive messages and concentrate those messages in Broker1 and Broker2.
To configure this topology, each of the brokers on the bottom would contain a network connector to
each of the brokers they are concentrating messages to.
<networkConnectors>
<networkConnector name="3_to_1" userName="myCommonUser" duplex="false"
<networkConnectors>
51
Network of Brokers
<networkConnectors>
Cross Region
To configure a network of brokers that spans AWS regions, deploy brokers in those regions, and
configure network connectors to the endpoints of those brokers.
To configure a network of brokers like this example, you could add networkConnectors entries to the
configurations of Broker1 and Broker4 that reference the wire-level endpoints of those brokers.
<networkConnectors>
<networkConnector name="1_to_2" userName="myCommonUser" duplex="true"
west-2.amazonaws.com)"/>
uri="static:(ssl://b-62a7fb31-d51c-466a-a873-905cd660b553-4.mq.us-
52
Network of Brokers
Network connector for Broker2:
<networkConnectors>
<networkConnectors>
Dynamic Failover With Transport Connectors

In addition to configuring networkConnector elements, you can configure your broker
transportConnector options to enable dynamic failover, and to rebalance connections when brokers
are added or removed from the network.
<transportConnectors>
<transportConnector name="openwire" updateClusterClients="true"
rebalanceClusterClients="true" updateClusterClientsOnRemove="true"/>
</transportConnectors>
In this example both updateClusterClients and rebalanceClusterClients are set to true. In

this case clients will be provided a list of brokers in the network, and will request them to rebalance if a
new broker joins.
Available options:
• updateClusterClients: Passes information to clients about changes in the network of broker

topology.
• rebalanceClusterClients: Causes clients to re-balance across brokers when a new broker is added
to a network of brokers.
• updateClusterClientsOnRemove: Updates clients with topology information when a broker leaves
a network of brokers.
When updateClusterClients is set to true, clients can be configured to connect to a single broker in
a network of brokers.
failover:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617)
When a new broker connects, it will be receive a list of URIs of all brokers in the network. If the
connection to the broker fails, it can dynamically switch to one of the brokers provided when it
connected.
53
Broker Configuration Lifecycle
For more information on failover, see Broker-side Options for Failover in the Active MQ documentation.
Amazon MQ Broker Configuration Lifecycle

Making changes to a configuration revision or an ActiveMQ user does not apply the changes immediately.
To apply your changes, you must wait for the next maintenance window (p. 25) or reboot the
broker (p. 32). For more information, see Amazon MQ Broker Configuration Lifecycle (p. 54).
The following diagram illustrates the configuration lifecycle.

Important
The next scheduled maintenance window triggers a reboot. If the broker is rebooted before the
next scheduled maintenance window, the changes are applied after the reboot.
For information about creating, editing, and managing configurations, see the following:

For information about creating, editing, and deleting ActiveMQ users, see the following:

• Limits Related to Users (p. 93)
Amazon MQ Broker Configuration Parameters

then apply the configuration to one or more brokers. For more information, see the following:
54
Working with Spring XML Configuration Files

• Limits Related to Configurations (p. 92)
Working with Spring XML Configuration Files

ActiveMQ brokers are configured using Spring XML files. You can configure many aspects of your
ActiveMQ broker, such as predefined destinations, destination policies, authorization policies, and
plugins. Amazon MQ controls some of these configuration elements, such as network transports and
storage. Other configuration options, such as creating networks of brokers, aren't currently supported.
The full set of supported configuration options is specified in the Amazon MQ XML schemas:
• Amazon MQ XML schema — 5.15.9

You can use these schemas to validate and sanitize your configuration files. Amazon MQ also lets you
provide configurations by uploading XML files. When you upload an XML file, Amazon MQ automatically
sanitizes and removes invalid and prohibited configuration parameters according to the schema.
Note
You can use only static values for attributes. Amazon MQ sanitizes elements and attributes that
contain Spring expressions, variables, and element references from your configuration.
Topics
• Elements Permitted in Amazon MQ Configurations (p. 55)
• Elements and Their Attributes Permitted in Amazon MQ Configurations (p. 57)
• Elements, Child Collection Elements, and Their Child Elements Permitted in Amazon MQ
Configurations (p. 65)
Elements Permitted in Amazon MQ Configurations

The following is a detailed listing of the elements permitted in Amazon MQ configurations. For more
information, see XML Configuration in the Apache ActiveMQ documentation.
Element
abortSlowAckConsumerStrategy (attributes) (p. 57)
abortSlowConsumerStrategy (attributes) (p. 58)
authorizationEntry (attributes) (p. 58)
authorizationMap (child collection elements) (p. 65)
authorizationPlugin (child collection elements) (p. 65)
broker (attributes (p. 58) | child collection elements) (p. 65)
cachedMessageGroupMapFactory (attributes) (p. 59)
55
Permitted Elements
Element
compositeQueue (attributes (p. 59) | child collection elements) (p. 66)
compositeTopic (attributes (p. 59) | child collection elements) (p. 66)
constantPendingMessageLimitStrategy (attributes) (p. 59)
discarding (attributes) (p. 59)
discardingDLQBrokerPlugin (attributes) (p. 60)
fileCursor
fileDurableSubscriberCursor
fileQueueCursor
filteredDestination (attributes) (p. 60)
fixedCountSubscriptionRecoveryPolicy (attributes) (p. 60)
fixedSizedSubscriptionRecoveryPolicy (attributes) (p. 60)
forcePersistencyModeBrokerPlugin (attributes) (p. 60)
individualDeadLetterStrategy (attributes) (p. 60)
lastImageSubscriptionRecoveryPolicy
messageGroupHashBucketFactory (attributes) (p. 60)
mirroredQueue (attributes) (p. 60)
noSubscriptionRecoveryPolicy
oldestMessageEvictionStrategy (attributes) (p. 60)
oldestMessageWithLowestPriorityEvictionStrategy (attributes) (p. 61)
policyEntry (attributes (p. 61) | child collection elements) (p. 66)
policyMap (child collection elements) (p. 67)
prefetchRatePendingMessageLimitStrategy (attributes) (p. 62)
priorityDispatchPolicy
priorityNetworkDispatchPolicy
queryBasedSubscriptionRecoveryPolicy (attributes) (p. 62)
queue (attributes) (p. 62)
redeliveryPlugin (attributes (p. 62) | child collection elements) (p. 67)
redeliveryPolicy (attributes) (p. 62)
redeliveryPolicyMap (child collection elements) (p. 67)
retainedMessageSubscriptionRecoveryPolicy (child collection elements) (p. 67)
roundRobinDispatchPolicy
56
Permitted Attributes
Element
sharedDeadLetterStrategy (attributes (p. 63) | child collection elements) (p. 67)
simpleDispatchPolicy
simpleMessageGroupMapFactory
statisticsBrokerPlugin
storeCursor
storeDurableSubscriberCursor (attributes) (p. 63)
strictOrderDispatchPolicy
tempDestinationAuthorizationEntry (attributes) (p. 63)
tempQueue (attributes) (p. 63)
tempTopic (attributes) (p. 63)
timedSubscriptionRecoveryPolicy (attributes) (p. 63)
timeStampingBrokerPlugin (attributes) (p. 63)
topic (attributes) (p. 64)
transportConnector (attributes) (p. 64)
uniquePropertyMessageEvictionStrategy (attributes) (p. 64)
virtualDestinationInterceptor (child collection elements) (p. 68)
virtualTopic (attributes) (p. 64)
vmCursor
vmDurableCursor
vmQueueCursor
Elements and Their Attributes Permitted in Amazon

MQ Configurations
The following is a detailed listing of the elements and their attributes permitted in Amazon MQ
configurations. For more information, see XML Configuration in the Apache ActiveMQ documentation.
Element Attribute
abortSlowAckConsumerStrategy abortConnection
checkPeriod
ignoreIdleConsumers
ignoreNetworkConsumers
maxSlowCount
57
Element Attribute
maxSlowDuration
maxTimeSinceLastAck
name
abortSlowConsumerStrategy abortConnection
checkPeriod
ignoreNetworkConsumers
maxSlowCount
maxSlowDuration
name
authorizationEntry admin
queue
read
tempQueue
tempTopic
topic
write
broker advisorySupport
allowTempAutoCreationOnSend
cacheTempDestinations
consumerSystemUsagePortion
dedicatedTaskRunner
deleteAllMessagesOnStartup
keepDurableSubsActive
maxPurgedDestinationsPerSweep
monitorConnectionSplits
networkConnectorStartAsync (p. 65)
offlineDurableSubscriberTaskSchedule
offlineDurableSubscriberTimeout
persistenceThreadPriority
persistent
populateJMSXUserID
58
Element Attribute
producerSystemUsagePortion
rejectDurableConsumers
rollbackOnlyOnAsyncException
schedulePeriodForDestinationPurge
schedulerSupport
splitSystemUsageForProducersConsumers
taskRunnerPriority
timeBeforePurgeTempDestinations
useAuthenticatedPrincipalForJMSXUserID
useMirroredQueues
useTempMirroredQueues
useVirtualDestSubs
useVirtualDestSubsOnCreation
useVirtualTopics
cachedMessageGroupMapFactory cacheSize
compositeQueue concurrentSend
copyMessage
forwardOnly
name
compositeTopic concurrentSend
copyMessage
forwardOnly
name
constantPendingMessageLimitStrategy limit
discarding deadLetterQueue
enableAudit
expiration
maxAuditDepth
maxProducersToAudit
processExpired
processNonPersistent
59
Element Attribute
discardingDLQBrokerPlugin dropAll
dropOnly
dropTemporaryQueues
dropTemporaryTopics
reportInterval
filteredDestination queue
selector
topic
fixedCountSubscriptionRecoveryPolicy maximumSize
fixedSizedSubscriptionRecoveryPolicy maximumSize
useSharedBuffer
forcePersistencyModeBrokerPlugin persistenceFlag
individualDeadLetterStrategy destinationPerDurableSubscriber
enableAudit
expiration
maxAuditDepth
maxProducersToAudit
processExpired
queuePrefix
queueSuffix
topicPrefix
topicSuffix
useQueueForQueueMessages
useQueueForTopicMessages
messageGroupHashBucketFactory bucketCount
cacheSize
mirroredQueue copyMessage
postfix
prefix
oldestMessageEvictionStrategy evictExpiredMessagesHighWatermark
60
Element Attribute
oldestMessageWithLowestPriorityEvictionStrategy
evictExpiredMessagesHighWatermark
policyEntry advisoryForConsumed
advisoryForDelivery
advisoryForDiscardingMessages
advisoryForFastProducers
advisoryForSlowConsumers
advisoryWhenFull
allConsumersExclusiveByDefault
alwaysRetroactive
blockedProducerWarningInterval
consumersBeforeDispatchStarts
cursorMemoryHighWaterMark
doOptimzeMessageStorage
durableTopicPrefetch
enableAudit
expireMessagesPeriod
gcInactiveDestinations
gcWithNetworkConsumers
inactiveTimeoutBeforeGC
inactiveTimoutBeforeGC
includeBodyForAdvisory
lazyDispatch
maxAuditDepth
maxBrowsePageSize
maxDestinations
maxExpirePageSize
maxPageSize
maxProducersToAudit
maxQueueAuditDepth
memoryLimit
messageGroupMapFactoryType
61
Element Attribute
minimumMessageSize
optimizedDispatch
optimizeMessageStoreInFlightLimit
persistJMSRedelivered
prioritizedMessages
producerFlowControl
queue
queueBrowserPrefetch
queuePrefetch
reduceMemoryFootprint
sendAdvisoryIfNoConsumers
storeUsageHighWaterMark
strictOrderDispatch
tempQueue
tempTopic
timeBeforeDispatchStarts
topic
topicPrefetch
useCache
useConsumerPriority
usePrefetchExtension
prefetchRatePendingMessageLimitStrategy multiplier
queryBasedSubscriptionRecoveryPolicy query
queue DLQ
physicalName
redeliveryPlugin fallbackToDeadLetter
sendToDlqIfMaxRetriesExceeded
redeliveryPolicy backOffMultiplier
collisionAvoidancePercent
initialRedeliveryDelay
maximumRedeliveries
62
Element Attribute
maximumRedeliveryDelay
preDispatchCheck
queue
redeliveryDelay
tempQueue
tempTopic
topic
useCollisionAvoidance
useExponentialBackOff
sharedDeadLetterStrategy enableAudit
expiration
maxAuditDepth
maxProducersToAudit
processExpired
storeDurableSubscriberCursor immediatePriorityDispatch
useCache
tempDestinationAuthorizationEntry admin
queue
read
tempQueue
tempTopic
topic
write
tempQueue DLQ
physicalName
tempTopic DLQ
physicalName
timedSubscriptionRecoveryPolicy zeroExpirationOverride
timeStampingBrokerPlugin recoverDuration
futureOnly
63
Element Attribute
processNetworkMessages
ttlCeiling
topic DLQ
physicalName
transportConnector •
name
updateClusterClients
rebalanceClusterClients
updateClusterClientsOnRemove
uniquePropertyMessageEvictionStrategy evictExpiredMessagesHighWatermark
propertyName
virtualTopic concurrentSend
local
name
postfix
prefix
selectorAware
transactedSend
Amazon MQ Parent Element Attributes

The following is a detailed explanation of parent element attributes. For more information, see XML
Configuration in the Apache ActiveMQ documentation.
Topics
• broker (p. 64)
broker
broker is a parent collection element.
Attributes
networkConnectionStartAsync
To mitigate network latency and to allow other networks to start in a timely manner, use the
<networkConnectionStartAsync> tag. The tag instructs the broker to use an executor to start
network connections in parallel, asynchronous to a broker start.
Default: false
64
Permitted Collections
Example Configuration
<broker networkConnectorStartAsync="false"/>
Elements, Child Collection Elements, and Their Child

Elements Permitted in Amazon MQ Configurations
The following is a detailed listing of the elements, child collection elements, and their child elements
permitted in Amazon MQ configurations. For more information, see XML Configuration in the Apache
ActiveMQ documentation.
Element Child Collection Element Child Element
authorizationMap authorizationEntries authorizationEntry (p. 68)
tempDestinationAuthorizationEntry
defaultEntry authorizationEntry
authorizationPlugin map authorizationMap
broker destinationInterceptors mirroredQueue
virtualDestinationInterceptor
destinationPolicy policyMap
destinations queue
tempQueue
tempTopic
topic
networkConnectors networkConnector (p. 68)
persistenceAdapter kahaDB (p. 70)
plugins authorizationPlugin
discardingDLQBrokerPlugin
forcePersistencyModeBrokerPlugin
redeliveryPlugin
statisticsBrokerPlugin
timeStampingBrokerPlugin
transportConnector name
updateClusterClients
rebalanceClusterClients
65
updateClusterClientsOnRemove
compositeQueue forwardTo queue
tempQueue
tempTopic
topic
filteredDestination
compositeTopic forwardTo queue
tempQueue
tempTopic
topic
filteredDestination
policyEntry deadLetterStrategy discarding
individualDeadLetterStrategy
sharedDeadLetterStrategy
destination queue
tempQueue
tempTopic
topic
dispatchPolicy priorityDispatchPolicy
priorityNetworkDispatchPolicy
roundRobinDispatchPolicy
simpleDispatchPolicy
strictOrderDispatchPolicy
messageEvictionStrategy oldestMessageEvictionStrategy
oldestMessageWithLowestPriorityEvict
uniquePropertyMessageEvictionStrateg
messageGroupMapFactory cachedMessageGroupMapFactory
messageGroupHashBucketFactory
simpleMessageGroupMapFactory
pendingDurableSubscriberPolicy
fileDurableSubscriberCursor
storeDurableSubscriberCursor
66
vmDurableCursor
pendingMessageLimitStrategyconstantPendingMessageLimitStrategy
prefetchRatePendingMessageLimitStrat
pendingQueuePolicy fileQueueCursor
storeCursor
vmQueueCursor
pendingSubscriberPolicy fileCursor
vmCursor
slowConsumerStrategy abortSlowAckConsumerStrategy
abortSlowConsumerStrategy
subscriptionRecoveryPolicy fixedCountSubscriptionRecoveryPolicy
fixedSizedSubscriptionRecoveryPolicy
queryBasedSubscriptionRecoveryPolicy
retainedMessageSubscriptionRecoveryP
timedSubscriptionRecoveryPolicy
policyMap defaultEntry policyEntry
policyEntries policyEntry
redeliveryPlugin redeliveryPolicyMap redeliveryPolicyMap
redeliveryPolicyMap defaultEntry redeliveryPolicy
redeliveryPolicyEntries redeliveryPolicy
retainedMessageSubscriptionRecoveryPolicy
wrapped fixedCountSubscriptionRecoveryPolicy
fixedSizedSubscriptionRecoveryPolicy
queryBasedSubscriptionRecoveryPolicy
retainedMessageSubscriptionRecoveryP
timedSubscriptionRecoveryPolicy
sharedDeadLetterStrategy deadLetterQueue queue
tempQueue
67
tempTopic
topic
virtualDestinationInterceptor
virtualDestinations compositeQueue
compositeTopic
virtualTopic
Amazon MQ Child Element Attributes

The following is a detailed explanation of child element attributes. For more information, see XML
Configuration in the Apache ActiveMQ documentation.
Topics
• authorizationEntry (p. 68)
• kahaDB (p. 70)
authorizationEntry
authorizationEntry is a child of the authorizationEntries child collection element.
Attributes
admin|read|write
The permissions granted to a group of users. For more information, see Always Configure an
Authorization Map (p. 86).
Default: null
<authorizationPlugin>
<map>
<authorizationMap>
<authorizationEntries>
<authorizationEntry admin="admins,activemq-webconsole"
read="admins,users,activemq-webconsole" write="admins,activemq-webconsole" queue=">"/>
<authorizationEntry admin="admins,activemq-webconsole"
read="admins,users,activemq-webconsole" write="admins,activemq-webconsole" topic=">"/>
</authorizationEntries>
</authorizationMap>
</map>
</authorizationPlugin>
networkConnector
networkConnector is a child of the networkConnectors child collection element.
Topics
• Attributes (p. 69)
68
• Example Configurations (p. 69)
Attributes
conduitSubscriptions
Specifies whether a network connection in a network of brokers treats multiple consumers subscribed to
the same destination as one consumer. For example, if conduitSubscriptions is set to true and two
consumers connect to broker B and consume from a destination, broker B combines the subscriptions
into a single logical subscription over the network connection to broker A, so that only a single copy of a
message is forwarded from broker A to broker B.
Note
Setting conduitSubscriptions to true can reduce redundant network traffic. However,
using this attribute can have implications for the load-balancing of messages across consumers
and might cause incorrect behavior in certain scenarios (for example, with JMS message
selectors or with durable topics).
Default: true
duplex
Specifies whether the connection in the network of brokers is used to produce and consume messages.
For example, if broker A creates a connection to broker B in non-duplex mode, messages can be
forwarded only from broker A to broker B. However, if broker A creates a duplex connection to broker B,
then broker B can forward messages to broker A without having to configure a <networkConnector>.
Default: false
name
The name of the bridge in the network of brokers.
Default: bridge
uri
The wire-level protocol endpoint for one of two brokers (or for multiple brokers) in a network of brokers.
Default: null
username
The username common to the brokers in a network of brokers.
Default: null
Example Configurations
Note
When using a networkConnector to define a network of brokers, don't include the password
for the user common to your brokers.
A Network of Brokers with Two Brokers

In this configuration, two brokers are connected in a network of brokers. The name of the network
connector is connector_1_to_2, the username common to the brokers is myCommonUser, the
connection is duplex, and the OpenWire endpoint URI is prefixed by static:, indicating a one-to-one
connection between the brokers.
<networkConnectors>
69
Working Java Examples

For more information, see Configure Network Connectors for Your Broker (p. 18).
A Network of Brokers with Multiple Brokers

In this configuration, multiple brokers are connected in a network of brokers. The name of the network
connector is connector_1_to_2, the username common to the brokers is myCommonUser, the
connection is duplex, and the comma-separated list of OpenWire endpoint URIs is prefixed by
masterslave:, indicating a failover connection between the brokers. The failover from broker to broker
isn't randomized and reconnection attempts continue indefinitely.
<networkConnectors>
uri="masterslave:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617,
ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-2.mq.us-east-2.amazonaws.com:61617)"/>
Note
We recommend using the masterslave: prefix for networks of brokers. The prefix is identical
to the more explicit static:failover:()?randomize=false&maxReconnectAttempts=0
syntax.
kahaDB
kahaDB is a child of the persistenceAdapter child collection element.
Attribute
concurrentStoreAndDispatchQueues
Specifies whether to use concurrent store and dispatch for queues. For more information, see Disable
Concurrent Store and Dispatch for Queues with Slow Consumers (p. 89).
Default: true
Example
<persistenceAdapter>
<kahaDB concurrentStoreAndDispatchQueues="false"/>
</persistenceAdapter>
Working Examples of Using Java Message Service

(JMS) with ActiveMQ
The following examples show how you can work with ActiveMQ programmatically:
• The OpenWire example Java code connects to a broker, creates a queue, and sends and receives
a message. For a detailed breakdown and explanation, see Connecting a Java Application to Your
Broker (p. 26).
70
Prerequisites
• The MQTT example Java code connects to a broker, creates a topic, and publishes and receives a
message.
• The STOMP+WSS example Java code connects to a broker, creates a queue, and publishes and receives
a message.
Prerequisites


a. Choose Add Rule.

e. Choose Save.

OpenWire
<dependencies>
<dependency>
</dependency>
<dependency>
71
Prerequisites
</dependency>
</dependencies>
For more information about activemq-client.jar, see Initial Configuration in the Apache
ActiveMQ documentation.
MQTT
Add the org.eclipse.paho.client.mqttv3.jar package to your Java class path. The following
example shows this dependency in a Maven project pom.xml file.
<dependencies>
<dependency>
<groupId>org.eclipse.paho</groupId>
<artifactId>org.eclipse.paho.client.mqttv3</artifactId>
</dependency>
</dependencies>
For more information about org.eclipse.paho.client.mqttv3.jar, see Eclipse Paho Java

Client.
STOMP+WSS
Add the following packages to your Java class path:
• spring-messaging.jar
• spring-websocket.jar
• javax.websocket-api.jar
• jetty-all.jar
• slf4j-simple.jar
• jackson-databind.jar
The following example shows these dependencies in a Maven project pom.xml file.
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-messaging</artifactId>
<version>5.0.5.RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-websocket</artifactId>
<version>5.0.5.RELEASE</version>
</dependency>
<dependency>
<groupId>javax.websocket</groupId>
<artifactId>javax.websocket-api</artifactId>
<version>1.1</version>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.aggregate</groupId>
<artifactId>jetty-all</artifactId>
<type>pom</type>
<version>9.3.3.v20150827</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
72
AmazonMQExample.java
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
</dependencies>
For more information, see STOMP Support in the Spring Framework documentation.
Important
OpenWire
/*
* Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* https://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*
*/
import org.apache.activemq.ActiveMQConnectionFactory;
import org.apache.activemq.jms.pool.PooledConnectionFactory;
import javax.jms.*;
public class AmazonMQExample {
// Specify the connection parameters.

private final static String WIRE_LEVEL_ENDPOINT
= "ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617";
private final static String ACTIVE_MQ_USERNAME = "MyUsername123";
private final static String ACTIVE_MQ_PASSWORD = "MyPassword456";
public static void main(String[] args) throws JMSException {

final ActiveMQConnectionFactory connectionFactory =
createActiveMQConnectionFactory();
final PooledConnectionFactory pooledConnectionFactory =
createPooledConnectionFactory(connectionFactory);
sendMessage(pooledConnectionFactory);
receiveMessage(connectionFactory);
}
73
private static void

sendMessage(PooledConnectionFactory pooledConnectionFactory) throws JMSException {
final Connection producerConnection = pooledConnectionFactory
.createConnection();
final Session producerSession = producerConnection
.createSession(false, Session.AUTO_ACKNOWLEDGE);

final Destination producerDestination = producerSession
.createQueue("MyQueue");

final MessageProducer producer = producerSession
.createProducer(producerDestination);
final TextMessage producerMessage = producerSession
.createTextMessage(text);

// Clean up the producer.

producer.close();
}
private static void

receiveMessage(ActiveMQConnectionFactory connectionFactory) throws JMSException {
// Note: Consumers should not use PooledConnectionFactory.
final Session consumerSession = consumerConnection
.createSession(false, Session.AUTO_ACKNOWLEDGE);

final Destination consumerDestination = consumerSession
.createQueue("MyQueue");

final MessageConsumer consumer = consumerSession
.createConsumer(consumerDestination);


// Clean up the consumer.

consumer.close();
}
74
private static PooledConnectionFactory

createPooledConnectionFactory(ActiveMQConnectionFactory connectionFactory) {
final PooledConnectionFactory pooledConnectionFactory =
new PooledConnectionFactory();
return pooledConnectionFactory;
}
private static ActiveMQConnectionFactory createActiveMQConnectionFactory() {

final ActiveMQConnectionFactory connectionFactory =
new ActiveMQConnectionFactory(WIRE_LEVEL_ENDPOINT);

connectionFactory.setUserName(ACTIVE_MQ_USERNAME);
connectionFactory.setPassword(ACTIVE_MQ_PASSWORD);
return connectionFactory;
}
}
MQTT
/*
*
*
*
*
*/
import org.eclipse.paho.client.mqttv3.*;
public class AmazonMQExampleMqtt implements MqttCallback {

private final static String WIRE_LEVEL_ENDPOINT =
"ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
public static void main(String[] args) throws Exception {

new AmazonMQExampleMqtt().run();
}
private void run() throws MqttException, InterruptedException {
// Specify the topic name and the message text.

final String topic = "myTopic";
// Create the MQTT client and specify the connection options.

final String clientId = "abc123";
final MqttClient client = new MqttClient(WIRE_LEVEL_ENDPOINT, clientId);
75
final MqttConnectOptions connOpts = new MqttConnectOptions();

connOpts.setUserName(ACTIVE_MQ_USERNAME);
connOpts.setPassword(ACTIVE_MQ_PASSWORD.toCharArray());
// Create a session and subscribe to a topic filter.

client.connect(connOpts);
client.setCallback(this);
client.subscribe("+");
final MqttMessage message = new MqttMessage(text.getBytes());
// Publish the message to a topic.

client.publish(topic, message);
System.out.println("Published message.");
// Wait for the message to be received.

Thread.sleep(3000L);
// Clean up the connection.

client.disconnect();
}
@Override
public void connectionLost(Throwable cause) {
System.out.println("Lost connection.");
}
@Override
public void messageArrived(String topic, MqttMessage message) throws MqttException
{
System.out.println("Received message from topic " + topic + ": " + message);
}
@Override
public void deliveryComplete(IMqttDeliveryToken token) {
System.out.println("Delivered message.");
}
}
STOMP+WSS
/*
*
*
*
*
*/
import org.springframework.messaging.converter.StringMessageConverter;
import org.springframework.messaging.simp.stomp.*;
import org.springframework.web.socket.WebSocketHttpHeaders;
import org.springframework.web.socket.client.WebSocketClient;
import org.springframework.web.socket.client.standard.StandardWebSocketClient;
76
import org.springframework.web.socket.messaging.WebSocketStompClient;
import java.lang.reflect.Type;
public class AmazonMQExampleStompWss {

private final static String DESTINATION = "/queue";
private final static String WIRE_LEVEL_ENDPOINT =
"wss://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
public static void main(String[] args) throws Exception {

final AmazonMQExampleStompWss example = new AmazonMQExampleStompWss();
final StompSession stompSession = example.connect();

System.out.println("Subscribed to a destination using session.");
example.subscribeToDestination(stompSession);
System.out.println("Sent message to session.");

example.sendMessage(stompSession);
Thread.sleep(60000);
}
private StompSession connect() throws Exception {

// Create a client.
final WebSocketClient client = new StandardWebSocketClient();
final WebSocketStompClient stompClient = new WebSocketStompClient(client);
stompClient.setMessageConverter(new StringMessageConverter());
final WebSocketHttpHeaders headers = new WebSocketHttpHeaders();
// Create headers with authentication parameters.

final StompHeaders head = new StompHeaders();
head.add(StompHeaders.LOGIN, ACTIVE_MQ_USERNAME);
head.add(StompHeaders.PASSCODE, ACTIVE_MQ_PASSWORD);
final StompSessionHandler sessionHandler = new MySessionHandler();
// Create a connection.
return stompClient.connect(WIRE_LEVEL_ENDPOINT, headers, head,
sessionHandler).get();
}
private void subscribeToDestination(final StompSession stompSession) {

stompSession.subscribe(DESTINATION, new MyFrameHandler());
}
private void sendMessage(final StompSession stompSession) {

stompSession.send(DESTINATION, "Hello from Amazon MQ!".getBytes());
}
private static class MySessionHandler extends StompSessionHandlerAdapter {

public void afterConnected(final StompSession stompSession,
final StompHeaders stompHeaders) {
System.out.println("Connected to broker.");
}
}
private static class MyFrameHandler implements StompFrameHandler {

public Type getPayloadType(final StompHeaders headers) {
return String.class;
}
77
Tagging resources
public void handleFrame(final StompHeaders stompHeaders,

final Object message) {
System.out.print("Received message from topic: " + message);
}
}
}
Tagging resources
Amazon MQ supports resource tagging to help track your cost allocation. You can tag resources when
creating them, or by viewing the details of that resource.
Topics
• Tagging for Cost Allocation (p. 78)
• Managing Tags in the Amazon MQ Console (p. 78)
• Managing Using Amazon MQ API Actions (p. 79)
Tagging for Cost Allocation

To organize and identify your Amazon MQ resources for cost allocation, you can add metadata tags
that identify the purpose of a broker or configuration. This is especially useful when you have many
brokers. You can use cost allocation tags to organize your AWS bill to reflect your own cost structure. To
do this, sign up to get your AWS account bill to include the tag keys and values. For more information,
see Setting Up a Monthly Cost Allocation Report in the AWS Billing and Cost Management User Guide.
For instance, you could add tags that represent the cost center and purpose of your Amazon MQ
resources:
Resource Key Value
Cost Center 34567

Broker1
Stack Production
Cost Center 34567

Broker2
Stack Production
Cost Center 12345

Broker3
Stack Development
This tagging scheme allows you to group two state machines performing related tasks in the same cost
center, while tagging an unrelated broker with a different cost allocation tag.
Managing Tags in the Amazon MQ Console

Adding Tags to New Resources
Amazon MQ lets you to add tags to resources as they are created. You can quickly add tags to the
resources you are creating in the Amazon MQ console.
To add tags as you create a new broker:
78
Managing Using Amazon MQ API Actions
1. From the Create a broker page, select Additional settings.

2. Under Tags, select Add tag.
3. Enter a Key and Value pair.
4. (Optional) Select Add tag to add multiple tags to your broker.

5. Select Create broker.
To add tags as you create a configuration:
1. From the Create configuration page, select Advanced.

2. Under Tags on the Create configuration page, select Add tag.
3. Enter a Key and Value pair.
4. (Optional) Select Add tag to add multiple tags to your configuration.
5. Select Create configuration.
Viewing and Managing Tags for Existing Resources

Amazon MQ allows you to view and manage the tags for your resources in the Amazon MQ console. You
can manage tags for an individual resource by editing the tags on the details page for that resource. To
edit tags on Amazon MQ resources:
1. Select either Brokers or Configurations in the Amazon MQ console.
Under the Tags section, review the existing tags for that resource.
2. To add new or manage existing tags, select Edit (or Create tag if have no existing tags).
3. Update tags for your resource:
• To modify existing tags, edit the Key and Value.

• To remove existing tags, select Remove.
• To add a new tag, select Add tag and enter a Key and Value.
4. Select Save.
Managing Using Amazon MQ API Actions

Amazon MQ allows you to view and manage the tags of your resources using the REST API.
For more information, see the Amazon MQ REST API Reference.
79
Without Service Interruption
Migrating to Amazon MQ
Use the following topics to get started with migrating your on-premises message broker to Amazon MQ.
Topics
• Migrating to Amazon MQ without Service Interruption (p. 80)
• Migrating to Amazon MQ with Service Interruption (p. 82)
For detailed information and examples, see Migrating from RabbitMQ to Amazon MQ in the AWS
Compute Blog.
Migrating to Amazon MQ without Service

Interruption
The following diagrams illustrate the scenario of migrating from an on-premises message broker to an
Amazon MQ broker in the AWS Cloud without service interruption.
Important
This scenario might cause messages to be delivered out of order. If you're concerned
about message ordering, follow the steps in Migrating to Amazon MQ with Service
Interruption (p. 82).
80
To migrate to Amazon MQ without service interruption
On-Premises Message Broker Migration to Amazon MQ with

Standard (Unordered) Queues
To migrate to Amazon MQ without service

interruption
Create and configure an Amazon MQ broker (p. 12) and note your broker's endpoint, for example:
For either of the following cases, use the Failover Transport to allow your consumers to randomly
connect to your on-premises broker's endpoint or your Amazon MQ broker's endpoint. For example:
failover:(ssl://on-premises-broker.example.com:61617,ssl://
b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617)?randomize=true
Do one of the following:
• One by one, point each existing consumer to your Amazon MQ broker's endpoint.
81
With Service Interruption
• Create new consumers and point them to your Amazon MQ broker's endpoint.
Note
If you scale up your consumer fleet during the migration process, it is a best practice to scale it
down afterward.
One by one, stop each existing producer, point the producer to your Amazon MQ broker's endpoint,
and then restart the producer.
Wait for your consumers to drain the destinations on your on-premises broker.
Change your consumers' Failover transport to include only your Amazon MQ broker's endpoint. For
example:
failover:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617)
Stop your on-premises broker.
Migrating to Amazon MQ with Service Interruption

The following diagrams illustrate the scenario of migrating from an on-premises message broker to an
Amazon MQ broker in the AWS Cloud with service interruption.
Important
This scenario requires you to point your producer to your Amazon MQ broker's endpoint
before you do the same for your consumers. This sequence ensures that any messages in a
FIFO (first-in-first-out) queue maintain their order during the migration process. If you're not
concerned about message ordering, follow the steps in Migrating to Amazon MQ without
Service Interruption (p. 80).
82
To migrate to Amazon MQ with service interruption
On-Premises Message Broker Migration to Amazon MQ

with FIFO (Ordered) Queues

Create and configure an Amazon MQ broker (p. 12) and note your broker's endpoint, for example:
Stop your existing producer, point the producer to your Amazon MQ broker's endpoint, and then
restart the producer.
Important
This step requires an interruption of your application's functionality because no consumers are
yet consuming messages from the Amazon MQ broker.
Wait for your consumers to drain the destinations on your on-premises broker.
Do one of the following:
• One by one, point each existing consumer to your Amazon MQ broker's endpoint.
83
• Create new consumers and point them to your Amazon MQ broker's endpoint.
Note
If you scale up your consumer fleet during the migration process, it is a best practice to scale it
down afterward.
Stop your on-premises broker.
84
Using Amazon MQ Securely
Best Practices for Amazon MQ

Use these best practices to make the most of Amazon MQ.
Topics
• Using Amazon MQ Securely (p. 85)
• Connecting to Amazon MQ (p. 86)
• Ensuring Effective Amazon MQ Performance (p. 88)
• Avoid Slow Restarts by Recovering Prepared XA Transactions (p. 90)
Using Amazon MQ Securely

The following design patterns can improve the security of your Amazon MQ broker.
Topics
• Prefer Brokers without Public Accessibility (p. 85)
• Always Use Client-Side Encryption as a Complement to TLS (p. 85)
• Always Configure an Authorization Map (p. 86)
• Always Configure a System Group (p. 86)
• Block Unnecessary Protocols with VPC Security Groups (p. 86)
Prefer Brokers without Public Accessibility

Brokers created without public accessibility can't be accessed from outside of your VPC. This greatly
reduces your broker's susceptibility to Distributed Denial of Service (DDoS) attacks from the public
internet. For more information, see Accessing the ActiveMQ Web Console of a Broker without Public
Accessibility (p. 15) in this guide and How to Help Prepare for DDoS Attacks by Reducing Your Attack
Surface on the AWS Security Blog.
Always Use Client-Side Encryption as a Complement

to TLS
You can access your brokers using the following protocols with TLS enabled:
• AMQP
• MQTT
• OpenWire
• STOMP
Amazon MQ encrypts messages at rest and in transit using encryption keys that it manages and stores
securely. For additional security, we highly recommend designing your application to use client-side
encryption. For more information, see the AWS Encryption SDK Developer Guide.
85
Always Configure an Authorization Map
Always Configure an Authorization Map

Because ActiveMQ has no authorization map configured by default, any authenticated user can perform
any action on the broker. Thus, it is a best practice to restrict permissions by group. For more information,
see authorizationEntry (p. 68).
Always Configure a System Group

Amazon MQ uses a system group (called activemq-webconsole) to allow the ActiveMQ Web Console
to communicate with the ActiveMQ broker.
The settings for the activemq-webconsole group in the authorization map restrict which operations
can be performed on queues or topics from the web console. For more information and an example
configuration, see authorizationEntry (p. 68).
Important
If you specify an authorization map which doesn't include the activemq-webconsole group,
you can't use the ActiveMQ Web Console because the group isn't authorized to send messages
to, or receive messages from, the Amazon MQ broker.
Block Unnecessary Protocols with VPC Security

Groups
To improve security, you should restrict the connections of unnecessary protocols and ports by properly
configuring your Amazon VPC Security Group. For instance, to restrict access to most protocols while
allowing access to OpenWire and the ActiveMQ web console, you could allow access to only 61617 and
8162. This limits your exposure by blocking protocols you are not using, while allowing OpenWire and
the ActiveMQ web console to function normally.
Allow only the protocol ports that you are using.
• AMQP: 5671
• MQTT: 8883
• OpenWire: 61617
• STOMP: 61614
• WebSocket: 61619
For more information see.
• Configure Advanced Broker Settings (p. 13)

• Security Groups for your VPC
• Default Security Group for Your VPC
• Working with Security Groups
Connecting to Amazon MQ
The following design patterns can improve the effectiveness of your application's connection to your
Amazon MQ broker.
Topics
• Never Modify or Delete the Amazon MQ Elastic Network Interface (p. 87)
• Always Use Connection Pooling (p. 87)
86
Never Modify or Delete the Amazon
MQ Elastic Network Interface
• Always Use the Failover Transport to Connect to Multiple Broker Endpoints (p. 88)
• Avoid Using Message Selectors (p. 88)
• Prefer Virtual Destinations to Durable Subscriptions (p. 88)
Never Modify or Delete the Amazon MQ Elastic

Network Interface
When you first create an Amazon MQ broker (p. 12), Amazon MQ provisions an elastic network
interface in the Virtual Private Cloud (VPC) under your account and, thus, requires a number of EC2
permissions (p. 107). The network interface allows your client (producer or consumer) to communicate
with the Amazon MQ broker. The network interface is considered to be within the service scope of
Amazon MQ, despite being part of your account's VPC.
Warning
You must not modify or delete this network interface. Modifying or deleting the network
interface can cause a permanent loss of connection between your VPC and your broker.
Currently, you can't recover your broker if you delete its network interface. You can only
recreate your broker.
Always Use Connection Pooling

In a scenario with a single producer and single consumer (such as the Getting Started with Amazon
MQ (p. 6) tutorial), you can use a single ActiveMQConnectionFactory class for every producer and
consumer. For example:



87
Always Use the Failover Transport to
Connect to Multiple Broker Endpoints
However, in more realistic scenarios with multiple producers and consumers, it can be costly and
inefficient to create a large number of connections for multiple producers. In these scenarios, you should
group multiple producer requests using the PooledConnectionFactory class. For example:
Note
Message consumers should never use the PooledConnectionFactory class.




Always Use the Failover Transport to Connect to

Multiple Broker Endpoints
If you need your application to connect to multiple broker endpoints—for example, when you use an
active/standby broker (p. 12) or when you migrate from an on-premises message broker to Amazon
MQ (p. 80)—use the Failover Transport to allow your consumers to randomly connect to either one. For
example:
failover:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617,ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-2.mq.us-
east-2.amazonaws.com:61617)?randomize=true
Avoid Using Message Selectors

It is possible to use JMS selectors to attach filters to topic subscriptions (to route messages to consumers
based on their content). However, the use of JMS selectors fills up the Amazon MQ broker's filter buffer,
preventing it from filtering messages.
In general, avoid letting consumers route messages because, for optimal decoupling of consumers and
producers, both the consumer and the producer should be ephemeral.
Prefer Virtual Destinations to Durable Subscriptions

A durable subscription can help ensure that the consumer receives all messages published to a topic, for
example, after a lost connection is restored. However, the use of durable subscriptions also precludes
the use of competing consumers and might have performance issues at scale. Consider using virtual
destinations instead.
Ensuring Effective Amazon MQ Performance

The following design patterns can improve the effectiveness and performance of your Amazon MQ
broker.
88
Disable Concurrent Store and Dispatch
for Queues with Slow Consumers
Topics
• Disable Concurrent Store and Dispatch for Queues with Slow Consumers (p. 89)
• Choose the Correct Broker Instance Type for the Best Throughput (p. 89)
Disable Concurrent Store and Dispatch for Queues

with Slow Consumers
By default, Amazon MQ optimizes for queues with fast consumers:
• Consumers are considered fast if they are able to keep up with the rate of messages generated by
producers.
• Consumers are considered slow if a queue builds up a backlog of unacknowledged messages,
potentially causing a decrease in producer throughput.
To instruct Amazon MQ to optimize for queues with slow consumers, set the
concurrentStoreAndDispatchQueues attribute to false. For an example configuration, see
concurrentStoreAndDispatchQueues (p. 70).
Choose the Correct Broker Instance Type for the Best

Throughput
The message throughput of a broker instance type (p. 38) depends on your application's use case and the
following factors:
• Use of ActiveMQ in persistent mode

• Message size
• The number of producers and consumers
• The number of destinations
Understanding the Relationship Between Message Size, Latency,

and Throughput
Depending on your use case, a larger broker instance type might not necessarily improve system
throughput. When ActiveMQ writes messages to durable storage, the size of your messages determines
your system's limiting factor:
• If your messages are smaller than 100 KB, persistent storage latency is the limiting factor.
• If your messages are larger than 100 KB, persistent storage throughput is the limiting factor.
When you use ActiveMQ in persistent mode, writing to storage normally occurs when there are either
few consumers or when the consumers are slow. In non-persistent mode, writing to storage also occurs
with slow consumers if the heap memory of the broker instance is full. Because Amazon MQ has highly-
durable storage (all persistent messages are replicated across three Availability Zones), the throughput to
persistent storage is smaller than the throughput to local, single-AZ storage.
To determine the best broker instance type for your application, we recommend testing different
broker instance types. For more information, see Broker Instance Types (p. 38) and also Measuring the
Throughput for Amazon MQ using the JMS Benchmark.
89
Configure Your Network of Brokers Correctly
Note
You can't change an existing broker to a different broker instance type. Using a different
broker instance type requires creating a new broker (p. 12), modifying your application's
configuration (p. 26) to use the new broker's wire-level protocol endpoint, and deleting the old
broker. You must also drain all the messages from the old broker before using the new broker.
Use Cases for Larger Broker Instance Types

There are three common use cases when larger broker instance types improve throughput:
• Non-persistent mode – When your application is less sensitive to losing messages during broker
instance failover (p. 45) (for example, when broadcasting sports scores), you can often use ActiveMQ's
non-persistent mode. In this mode, ActiveMQ writes messages to persistent storage only if the heap
memory of the broker instance is full. Systems that use non-persistent mode can benefit from the
higher amount of memory, faster CPU, and faster network available on larger broker instance types.
• Fast consumers – When active consumers are available and the
concurrentStoreAndDispatchQueues (p. 70) flag is enabled, ActiveMQ allows messages to
flow directly from producer to consumer without sending messages to storage (even in persistent
mode). If your application can consume messages quickly (or if you can design your consumers to
do this), your application can benefit from a larger broker instance type. To let your application
consume messages more quickly, add consumer threads to your application instances or scale up your
application instances vertically or horizontally.
• Batched transactions – When you use persistent mode and send multiple messages per transaction,
you can achieve an overall higher message throughput by using larger broker instance types. For more
information, see Should I Use Transactions? in the ActiveMQ documentation.
Configure Your Network of Brokers Correctly

When you create a network of brokers (p. 46), configure it correctly for your application:
• Enable persistent mode – Because (relative to its peers) each broker instance acts like a producer
or a consumer, networks of brokers don't provide distributed replication of messages. The first
broker that acts as a consumer receives a message and persists it to storage. This broker sends an
acknowledgement to the producer and forwards the message to the next broker. When the second
broker acknowledges the persistence of the message, the first broker deletes the message.
If persistent mode is disabled, the first broker acknowledges the producer without persisting the
message to storage. For more information, see Replicated Message Store and What is the difference
between persistent and non-persistent delivery? in the Apache ActiveMQ documentation.
• Don't disable advisory messages for broker instances – For more information, see Advisory Message
in the Apache ActiveMQ documentation.
• Don't use multicast broker discovery – Amazon MQ doesn't support broker discovery using multicast.
For more information, see What is the difference between discovery, multicast, and zeroconf? in the
Apache ActiveMQ documentation.
Avoid Slow Restarts by Recovering Prepared XA

Transactions
ActiveMQ supports distributed (XA) transactions. Knowing how ActiveMQ processes XA transactions can
help avoid slow recovery times for broker restarts and failovers in Amazon MQ
Unresolved prepared XA transactions are replayed on every restart. If these remain unresolved, their
number will grow over time, significantly increasing the time needed to start up the broker. This affects
90
Avoid Slow Restarts by Recovering
Prepared XA Transactions
restart and failover time. You must resolve these transactions with a commit() or a rollback() so that
performance doesn't degrade over time.
One cause of these unresolved transactions is an issue with Apache ActiveMQ. This may cause unresolved
prepared transactions when Amazon MQ restarts. For more information, see the related Apache
ActiveMQ defect.
To monitor your unresolved prepared XA transactions, you can use the

JournalFilesForFastRecovery metric in Amazon CloudWatch Logs. If this number is increasing, or
is consistently higher than 1, you should recover your unresolved transactions with code similar to the
following example. For more information, see Limits in Amazon MQ (p. 92).
The following example code walks through prepared XA transactions and closes them with a
rollback().
import org.apache.activemq.ActiveMQXAConnectionFactory;
import javax.jms.XAConnection;
import javax.jms.XASession;
import javax.transaction.xa.XAResource;
import javax.transaction.xa.Xid;
public class RecoverXaTransactions {

private static final ActiveMQXAConnectionFactory ACTIVE_MQ_CONNECTION_FACTORY;
final static String WIRE_LEVEL_ENDPOINT =
"tcp://localhost:61616";;
static {
final String activeMqUsername = "MyUsername123";
final String activeMqPassword = "MyPassword456";
ACTIVE_MQ_CONNECTION_FACTORY = new ActiveMQXAConnectionFactory(activeMqUsername,
activeMqPassword, WIRE_LEVEL_ENDPOINT);
ACTIVE_MQ_CONNECTION_FACTORY.setUserName(activeMqUsername);
ACTIVE_MQ_CONNECTION_FACTORY.setPassword(activeMqPassword);
}
public static void main(String[] args) {

try {
final XAConnection connection =
ACTIVE_MQ_CONNECTION_FACTORY.createXAConnection();
XASession xaSession = connection.createXASession();
XAResource xaRes = xaSession.getXAResource();
for (Xid id : xaRes.recover(XAResource.TMENDRSCAN)) {

xaRes.rollback(id);
}
connection.close();
} catch (Exception e) {
}
}
}
In a real-world scenario, you could check your prepared XA transactions against your XA Transaction
Manager. Then you can decide whether to handle each prepared transaction with a rollback() or a
commit().
91
Brokers
Limits in Amazon MQ
This topic lists limits within Amazon MQ. Many of the following limits can be changed for specific AWS
accounts. To request an increase for a limit, see AWS Service Limits in the Amazon Web Services General
Reference.
Topics
• Brokers (p. 92)
• Configurations (p. 92)
• Users (p. 93)
• Data Storage (p. 93)
• API Throttling (p. 93)
Brokers
The following table lists limits related to Amazon MQ brokers.
Limit Description
Broker name • Must be unique in your AWS account.

• Must be 1-50 characters long.
• Must contain only characters specified in the
ASCII Printable Character Set.
• Can contain only alphanumeric characters,
dashes, periods, underscores, and tildes (- . _
~).
Brokers per broker instance type (p. 38), per AWS 20

account, per region
Broker configuration history depth 10
Connections per wire-level protocol 1,000 (100 for mq.t2.micro brokers)
Security groups per broker 5
Destinations (queues and topics) monitored in CloudWatch monitors only the first 200
CloudWatch destinations.
Configurations
The following table lists limits related to Amazon MQ configurations.
Limit Description
Configuration name • Must be 1-150 characters long.

92
Users
Limit Description
~).
Configurations per AWS account 1,000
Revisions per configuration 300
Users
The following table lists limits related to Amazon MQ users.
Limit Description
Username • Must be 1-100 characters long.

~).
• Must not contain commas (,).
Password • Must be 12-250 characters long.

• Must contain at least 4 unique characters.
• Must not contain commas (,).
Users per broker 250
Groups per user 20
Data Storage
The following table lists limits related to Amazon MQ data storage.
Limit Description
Storage capacity per new mq.t2.micro broker. 20 GB

See Broker Instance Types (p. 38).
Storage capacity per broker for other instance 200 GB

types. See Broker Instance Types (p. 38).
API Throttling
The following throttling limits are aggregated per AWS account, across all Amazon MQ APIs to maintain
service bandwidth. For more information about Amazon MQ APIs, see the Amazon MQ REST API
Reference.
93
API Throttling
Important
These limits don't apply to ActiveMQ broker messaging APIs. For example, Amazon MQ doesn't
throttle the sending or receiving of messages.
Bucket Size Refill Rate per Second
100 15
94
Monitoring Brokers Using CloudWatch
Monitoring and Logging Amazon MQ

Brokers
This section provides information about monitoring and logging Amazon MQ broker activity.
Topics
• Monitoring Amazon MQ Brokers Using Amazon CloudWatch (p. 95)
• Logging Amazon MQ API Calls Using AWS CloudTrail (p. 99)
• Configuring Amazon MQ to Publish General and Audit Logs to Amazon CloudWatch Logs (p. 101)
Monitoring Amazon MQ Brokers Using Amazon

CloudWatch
Amazon MQ and Amazon CloudWatch are integrated so you can use CloudWatch to view and analyze
metrics for your ActiveMQ broker and the broker's destinations (queues and topics). You can view and
analyze your Amazon MQ metrics from the CloudWatch console, the AWS CLI, or the CloudWatch CLI.
CloudWatch metrics for Amazon MQ are automatically polled from the broker and then pushed to
CloudWatch every minute.
For information about accessing Amazon MQ CloudWatch metrics, see Accessing CloudWatch Metrics for
Amazon MQ (p. 33).
Note
The following statistics are valid for all of the metrics:
• Average
• Minimum
• Maximum
• Sum
The AWS/AmazonMQ namespace includes the following metrics.
Broker Metrics
Metric Unit Description
CpuCreditBalance Credits (vCPU-minutes) Important

This metric is
available only for the
mq.t2.micro broker
instance type.
CPU credit metrics are
available only at five-
minute intervals.
The number of earned CPU

credits that an instance has
95
Broker Metrics

accrued since it was launched or
started (including the number
of launch credits). The credit
balance is available for the
broker instance to spend on
bursts beyond the baseline CPU
utilization.
Credits are accrued in the credit

balance after they're earned
and removed from the credit
balance after they're spent. The
credit balance has a maximum
limit. Once the limit is reached,
any newly earned credits are
discarded.
CpuUtilization Percent The percentage of allocated EC2

compute units that the broker
currently uses.
CurrentConnectionsCount Count The current number of active

connections on the current
broker.
EstablishedConnectionsCountCount The total number of

connections, active and inactive,
that have been established on
the broker.
Count
InactiveDurableTopicSubscribersCount The number of inactive durable
topic subscribers, up to a
maximum of 2000.
JournalFilesForFastRecoveryCount The number of journal files that

will be replayed after a clean
shutdown.
JournalFilesForFullRecoveryCount The number of journal files that

will be replayed after an unclean
shutdown.
HeapUsage Percent The percentage of the ActiveMQ

JVM memory limit that the
broker currently uses.
NetworkIn Bytes The volume of incoming traffic

for the broker.
NetworkOut Bytes The volume of outgoing traffic

for the broker.
OpenTransactionsCount Count The total number of transactions

in progress.
96
Destination (Queue and Topic) Metrics
StorePercentUsage Percent The percent used by the storage

limit. If this reaches 100 the
broker will refuse messages.
TotalConsumerCount Count The number of message

consumers subscribed to
destinations on the current
broker.
TotalMessageCount Count The number of messages stored

on the broker.
TotalProducerCount Count The number of message

producers active on destinations
on the current broker.
Dimension for Broker Metrics
Dimension Description
Broker The name of the broker.

Note
A single-instance broker has the suffix
-1. An active-standby broker for high
availability has the suffixes -1 and -2 for
its redundant pair.

Important
The following metrics include per-minute counts for the CloudWatch polling period.
• EnqueueCount
• ExpiredCount
• DequeueCount
• DispatchCount
• InFlightCount
For instance, in a 5 minute CloudWatch period, EnqueueCount has 5 count values, each for a
1 minute portion of the period. The Minimum and Maximum statistics provide the lowest and
highest per-minute value during the specified period.
ConsumerCount Count The number of consumers

subscribed to the destination.
EnqueueCount Count The number of messages sent to

the destination, per minute.
97
EnqueueTime Time (milliseconds) The end-to-end latency from

when a message arrives at a
broker until it is delivered to a
consumer.
ExpiredCount Count The number of messages that

couldn't be delivered because
they expired, per minute.
DispatchCount Count The number of messages sent to

consumers, per minute.
DequeueCount Count The number of messages

acknowledged by consumers,
per minute.
ReceiveCount Count The number of messages that

have been received from the
remote broker for a duplex
network connector.
InFlightCount Count The number of messages sent to

consumers that have not been
acknowledged.
MemoryUsage Percent The percentage of the memory

limit that the destination
currently uses.
ProducerCount Count The number of producers for the

destination.
QueueSize Count The number of messages in the

queue.
Important
This metric applies only
to queues.
Dimensions for Destination (Queue and Topic) Metrics
Dimension Description
Broker The name of the broker.

Note
A single-instance broker has the suffix
-1. An active-standby broker for high
availability has the suffixes -1 and -2 for
its redundant pair.
Topic or Queue The name of the topic or queue.
NetworkConnector The name of the network connector.
98
Logging API Calls Using CloudTrail
Logging Amazon MQ API Calls Using AWS

CloudTrail
Amazon MQ is integrated with AWS CloudTrail, a service that provides a record of the Amazon MQ calls
that a user, role, or AWS service makes. CloudTrail captures API calls related to Amazon MQ brokers and
configurations as events, including calls from the Amazon MQ console and code calls from Amazon MQ
APIs. For more information about CloudTrail, see the AWS CloudTrail User Guide.
Note
CloudTrail doesn't log API calls related to ActiveMQ operations (for example, sending and
receiving messages) or to the ActiveMQ Web Console. To log information related to ActiveMQ
operations, you can configure Amazon MQ to publish general and audit logs to Amazon
CloudWatch Logs (p. 101).
Using the information that CloudTrail collects, you can identify a specific request to an Amazon MQ API,
the IP address of the requester, the requester's identity, the date and time of the request, and so on. If
you configure a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket.
If you don't configure a trail, you can view the most recent events in the event history in the CloudTrail
console. For more information, see Overview for Creating a Trail in the AWS CloudTrail User Guide.
Amazon MQ Information in CloudTrail

When you create your AWS account, CloudTrail is enabled. When a supported Amazon MQ event activity
occurs, it is recorded in a CloudTrail event with other AWS service events in the event history. You can
view, search, and download recent events for your AWS account. For more information, see Viewing
Events with CloudTrail Event History in the AWS CloudTrail User Guide.
A trail allows CloudTrail to deliver log files to an Amazon S3 bucket. You can create a trail to keep
an ongoing record of events in your AWS account. By default, when you create a trail using the AWS
Management Console, the trail applies to all AWS Regions. The trail logs events from all AWS Regions
and delivers log files to the specified Amazon S3 bucket. You can also configure other AWS services to
further analyze and act on the event data collected in CloudTrail logs. For more information, see the
following topics in the AWS CloudTrail User Guide:
• CloudTrail Supported Services and Integrations

• Configuring Amazon SNS Notifications for CloudTrail
• Receiving CloudTrail Log Files from Multiple Regions
• Receiving CloudTrail Log Files from Multiple Accounts
Amazon MQ supports logging both the request parameters and the responses for the following APIs as
events in CloudTrail log files:
• CreateConfiguration
• DeleteBroker
• DeleteUser
• RebootBroker
• UpdateBroker
Important
For the GET methods of the following APIs, the request parameters are logged, but the
responses are redacted:
• DescribeBroker
99
Example Amazon MQ Log File Entry
• DescribeConfiguration
• DescribeConfigurationRevision
• DescribeUser
• ListBrokers
• ListConfigurationRevisions
• ListConfigurations
• ListUsers
For the following APIs, the data and password request parameters are hidden by asterisks
(***):
• CreateBroker (POST)
• CreateUser (POST)
• UpdateConfiguration (PUT)
• UpdateUser (PUT)
Every event or log entry contains information about the requester. This information helps you determine
the following:
• Was the request made with root or IAM user credentials?

• Was the request made with temporary security credentials for a role or a federated user?
• Was the request made by another AWS service?
For more information, see CloudTrail userIdentity Element in the AWS CloudTrail User Guide.
Example Amazon MQ Log File Entry

A trail is a configuration that allows the delivery of events as log files to the specified Amazon S3 bucket.
CloudTrail log files contain one or more log entries.
An event represents a single request from any source and includes information about the request to
an Amazon MQ API, the IP address of the requester, the requester's identity, the date and time of the
request, and so on.
The following example shows a CloudTrail log entry for a CreateBroker API call.
Note
Because CloudTrail log files aren't an ordered stack trace of public APIs, they don't list
information in any specific order.
{
"eventVersion": "1.06",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::111122223333:user/AmazonMqConsole",
"accountId": "111122223333",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "AmazonMqConsole"
},
"eventTime": "2018-06-28T22:23:46Z",
"eventSource": "amazonmq.amazonaws.com",
"eventName": "CreateBroker",
"awsRegion": "us-west-2",
"sourceIPAddress": "203.0.113.0",
100
Configuring Amazon MQ to
Publish Logs to CloudWatch Logs
"userAgent": "PostmanRuntime/7.1.5",
"requestParameters": {
"engineVersion": "5.15.9",
"deploymentMode": "ACTIVE_STANDBY_MULTI_AZ",
"maintenanceWindowStartTime": {
"dayOfWeek": "THURSDAY",
"timeOfDay": "22:45",
"timeZone": "America/Los_Angeles"
},
"engineType": "ActiveMQ",
"hostInstanceType": "mq.m5.large",
"users": [
{
"username": "MyUsername123",
"password": "***",
"consoleAccess": true,
"groups": [
"admins",
"support"
]
},
{
"username": "MyUsername456",
"password": "***",
"groups": [
"admins"
]
}
],
"creatorRequestId": "1",
"publiclyAccessible": true,
"securityGroups": [
"sg-a1b234cd"
],
"brokerName": "MyBroker",
"autoMinorVersionUpgrade": false,
"subnetIds": [
"subnet-12a3b45c",
"subnet-67d8e90f"
]
},
"responseElements": {
"brokerId": "b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9",
"brokerArn": "arn:aws:mq:us-
east-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9"
},
"requestID": "a1b2c345-6d78-90e1-f2g3-4hi56jk7l890",
"eventID": "a12bcd3e-fg45-67h8-ij90-12k34d5l16mn",
"readOnly": false,
"eventType": "AwsApiCall",
"recipientAccountId": "111122223333"
}
Configuring Amazon MQ to Publish General and

Audit Logs to Amazon CloudWatch Logs
Amazon MQ is integrated with Amazon CloudWatch Logs, a service that monitors, stores, and accesses
your log files from a variety of sources. For example, you can configure CloudWatch alarms to receive
notifications of broker reboots or troubleshoot broker configuration (p. 54) errors. For more information
about CloudWatch Logs, see the Amazon CloudWatch Logs User Guide.
101
Understanding the Structure
of Logging in CloudWatch Logs
To allow Amazon MQ to publish logs to CloudWatch Logs, you must add a permission to your Amazon
MQ user (p. 102) and also configure a resource-based policy for Amazon MQ (p. 103) before you
create or restart the broker.
For more information about configuring Amazon MQ to publish general and audit logs to CloudWatch
Logs, see Configure Advanced Broker Settings (p. 13).
Topics
• Understanding the Structure of Logging in CloudWatch Logs (p. 102)
• Add the CreateLogGroup Permission to Your Amazon MQ User (p. 102)
• Configure a Resource-Based Policy for Amazon MQ (p. 103)
• Troubleshooting CloudWatch Logs Configuration (p. 104)
Understanding the Structure of Logging in

CloudWatch Logs
You can enable general and audit logging when you configure advanced broker settings (p. 13) when you
create a broker, or when you edit a broker.
General logging enables the default INFO logging level (DEBUG logging isn't supported) and publishes
activemq.log to a log group in your CloudWatch account. The log group has a format similar to the
following:
/aws/amazonmq/broker/b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9/general
Audit logging enables logging of management actions taken using JMX or using the ActiveMQ Web
Console and publishes audit.log to a log group in your CloudWatch account. The log group has a
format similar to the following:
/aws/amazonmq/broker/b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9/audit
Depending on whether you have a single-instance broker (p. 44) or an active/standby broker (p. 45),
Amazon MQ creates either one or two log streams within each log group. The log streams have a format
similar to the following.
activemq-b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.log
activemq-b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-2.log
The -1 and -2 suffixes denote individual broker instances. For more information, see Working with Log
Groups and Log Streams in the Amazon CloudWatch Logs User Guide.
Add the CreateLogGroup Permission to Your Amazon

MQ User
To allow Amazon MQ to create a CloudWatch Logs log group, you must ensure that the user who creates
or reboots the broker has the logs:CreateLogGroup permission.
Important
If you don't add the CreateLogGroup permission to your Amazon MQ user before the user
creates or reboots the broker, Amazon MQ doesn't create the log group.
The following example IAM-based policy grants permission for logs:CreateLogGroup to user
111122223333.
102
Configure a Resource-Based Policy for Amazon MQ
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "111122223333"
},
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:*:*:log-group:/aws/amazonmq/*"
}
]
}
For more information, see CreateLogGroup in the Amazon CloudWatch Logs API Reference.
Configure a Resource-Based Policy for Amazon MQ

To allow Amazon MQ to publish logs to your CloudWatch Logs log group, configure a resource-based
policy to give Amazon MQ access to the following CloudWatch Logs API actions:
• CreateLogStream – Creates a CloudWatch Logs log stream for the specified log group.
• PutLogEvents – Delivers events to the specified CloudWatch Logs log stream.
Important
If you don't configure a resource-based policy for Amazon MQ, the broker can't publish the logs
to CloudWatch Logs.
The following example resource-based policy grants permission for logs:CreateLogStream and
logs:PutLogEvents to AWS.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "mq.amazonaws.com"
},
"Action":[
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource" : "arn:aws:logs:*:*:log-group:/aws/amazonmq/*"
}
]
}
Note
Because this example uses the /aws/amazonmq/ prefix, you need to configure the resource-
based policy only once per AWS account, per region.
You can achieve the same effect using the following AWS CLI command:
aws --region us-east-1 logs put-resource-policy --policy-name AmazonMQ-logs \

--policy-document '{ "Version": "2012-10-17", "Statement": [ {
"Effect": "Allow", "Principal": { "Service": "mq.amazonaws.com" },
"Action":[ "logs:CreateLogStream", "logs:PutLogEvents" ],
103
Troubleshooting CloudWatch Logs Configuration
"Resource" : "arn:aws:logs:*:*:log-group:/aws/amazonmq/*" } ] }'
Troubleshooting CloudWatch Logs Configuration

In some cases, CloudWatch Logs might not always behave as expected. This section gives an overview of
common issues and shows how to resolve them.
Log Groups Don't Appear in CloudWatch

Add the CreateLogGroup permission to your Amazon MQ user (p. 102) and reboot the broker. This
allows Amazon MQ to create the log group.
Log Streams Don't Appear in CloudWatch Log Groups

Configure a resource-based policy for Amazon MQ (p. 103). This allows your broker to publish its logs.
104
Tag-based Policies
Amazon MQ Security
This section provides information about Amazon MQ and ActiveMQ authentication and authorization.
For information about security best practices, see Using Amazon MQ Securely (p. 85).
Topics
• Tag-based Policies (p. 105)
• Authentication (p. 105)
• API Authentication and Authorization for Amazon MQ (p. 107)
• Messaging Authentication and Authorization for ActiveMQ (p. 109)
Tag-based Policies
Amazon MQ supports policies based on tags. For instance, you could deny access to Amazon MQ
resources that include a tag with the key environment and the value production:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"mq:DeleteBroker",
"mq:RebootBroker",
"mq:DeleteTag"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": "production"
}
}
}
]
}
This policy will Deny the ability to delete or reboot an Amazon MQ broker that includes the tag
environment/production.
For more information on tagging, see:
• Tagging resources (p. 78)

• Controlling Access Using IAM Tags
Authentication
You can access AWS as any of the following types of identities:
• AWS account root user – When you first create an AWS account, you begin with a single sign-in
identity that has complete access to all AWS services and resources in the account. This identity is
105
Authentication
called the AWS account root user and is accessed by signing in with the email address and password
that you used to create the account. We strongly recommend that you do not use the root user for
your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the
root user only to create your first IAM user. Then securely lock away the root user credentials and use
them to perform only a few account and service management tasks.
• IAM user – An IAM user is an identity within your AWS account that has specific custom permissions
(for example, permissions to create a broker in Amazon MQ). You can use an IAM user name and
password to sign in to secure AWS webpages like the AWS Management Console, AWS Discussion
Forums, or the AWS Support Center.
In addition to a user name and password, you can also generate access keys for each user. You can
use these keys when you access AWS services programmatically, either through one of the several
SDKs or by using the AWS Command Line Interface (CLI). The SDK and CLI tools use the access keys
to cryptographically sign your request. If you don’t use AWS tools, you must sign the request yourself.
Amazon MQ supports Signature Version 4, a protocol for authenticating inbound API requests. For
more information about authenticating requests, see Signature Version 4 Signing Process in the AWS
General Reference.

• IAM role – An IAM role is an IAM identity that you can create in your account that has specific
permissions. An IAM role is similar to an IAM user in that it is an AWS identity with permissions policies
that determine what the identity can and cannot do in AWS. However, instead of being uniquely
associated with one person, a role is intended to be assumable by anyone who needs it. Also, a role
does not have standard long-term credentials such as a password or access keys associated with it.
Instead, when you assume a role, it provides you with temporary security credentials for your role
session. IAM roles with temporary credentials are useful in the following situations:

• Federated user access – Instead of creating an IAM user, you can use existing identities from AWS
Directory Service, your enterprise user directory, or a web identity provider. These are known as
federated users. AWS assigns a role to a federated user when access is requested through an identity
provider. For more information about federated users, see Federated Users and Roles in the IAM User
Guide.

• AWS service access – A service role is an IAM role that a service assumes to perform actions in your
account on your behalf. When you set up some AWS service environments, you must define a role
for the service to assume. This service role must include all the permissions that are required for
the service to access the AWS resources that it needs. Service roles vary from service to service, but
many allow you to choose your permissions as long as you meet the documented requirements
for that service. Service roles provide access only within your account and cannot be used to grant
access to services in other accounts. You can create, modify, and delete a service role from within
IAM. For example, you can create a role that allows Amazon Redshift to access an Amazon S3 bucket
on your behalf and then load data from that bucket into an Amazon Redshift cluster. For more
information, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.

• Applications running on Amazon EC2 – You can use an IAM role to manage temporary credentials
for applications that are running on an EC2 instance and making AWS CLI or AWS API requests. This
is preferable to storing access keys within the EC2 instance. To assign an AWS role to an EC2 instance
and make it available to all of its applications, you create an instance profile that is attached to
the instance. An instance profile contains the role and enables programs that are running on the
EC2 instance to get temporary credentials. For more information, see Using an IAM Role to Grant
Permissions to Applications Running on Amazon EC2 Instances in the IAM User Guide.
106
API Authentication and Authorization
API Authentication and Authorization for Amazon

MQ
Amazon MQ uses standard AWS request signing for API authentication. For more information, see
Signing AWS API Requests in the AWS General Reference.
Note
Currently, Amazon MQ doesn't support IAM authentication using resource-based permissions or
resource-based policies.
To authorize AWS users to work with brokers, configurations, and users, you must edit your IAM policy
permissions.
Topics
• IAM Permissions Required to Create an Amazon MQ Broker (p. 107)
• Amazon MQ REST API Permissions Reference (p. 108)
• Resource-Level Permissions for Amazon MQ API Actions (p. 109)
IAM Permissions Required to Create an Amazon MQ

Broker
To create a broker, you must either use the AmazonMQFullAccess IAM policy or include the following
EC2 permissions in your IAM policy.
The following custom policy is comprised of two statements (one conditional) which grant permissions
to manipulate the resources which Amazon MQ requires to create an ActiveMQ broker.
Important
• The ec2:CreateNetworkInterface action is required to allow Amazon MQ to create an

elastic network interface (ENI) in your account on your behalf.
• The ec2:CreateNetworkInterfacePermission action authorizes Amazon MQ to attach
the ENI to an ActiveMQ broker.
• The ec2:AuthorizedService condition key ensures that ENI permissions can be granted
only to Amazon MQ service accounts.
{
"Version": "2012-10-17",
"Statement": [{
"Action": [
"mq:*",
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface",
"ec2:DetachNetworkInterface",
"ec2:DescribeInternetGateways",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs"
],
"Effect": "Allow",
"Resource": "*"
},{
"Action": [
107
REST API Permissions Reference
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DescribeNetworkInterfacePermissions"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:AuthorizedService": "mq.amazonaws.com"
}
}
}]
}
For more information, see Create an IAM User and Get Your AWS Credentials (p. 4) and Never Modify or
Delete the Amazon MQ Elastic Network Interface (p. 87).
Amazon MQ REST API Permissions Reference

The following table lists Amazon MQ REST APIs and the corresponding IAM permissions.
Amazon MQ REST APIs and Required Permissions
Amazon MQ REST APIs Required Permissions
CreateBroker mq:CreateBroker
CreateConfiguration mq:CreateConfiguration
CreateTags mg:CreateTags
CreateUser mq:CreateUser
DeleteBroker mq:DeleteBroker
DeleteUser mq:DeleteUser
DescribeBroker mq:DescribeBroker
DescribeConfiguration mq:DescribeConfiguration
DescribeConfigurationRevision mq:DescribeConfigurationRevision
DescribeUser mq:DescribeUser
ListBrokers mq:ListBrokers
ListConfigurationRevisions mq:ListConfigurationRevisions
ListConfigurations mq:ListConfigurations
ListTags mq:ListTags
ListUsers mq:ListUsers
RebootBroker mq:RebootBroker
UpdateBroker mq:UpdateBroker
UpdateConfiguration mq:UpdateConfiguration
UpdateUser mq:UpdateUser
108
Supported Resource-Level Permissions
Resource-Level Permissions for Amazon MQ API

Actions
The term resource-level permissions refers to the ability to specify the resources on which users are
allowed to perform actions. Amazon MQ has partial support for resource-level permissions. For certain
Amazon MQ actions, you can control when users are allowed to use those actions based on conditions
that have to be fulfilled, or specific resources that users are allowed to use.
The following table describes the Amazon MQ API actions that currently support resource-level
permissions, as well as the supported resources, resource ARNs, and condition keys for each action.
Important
If an Amazon MQ API action is not listed in this table, then it does not support resource-level
permissions. If an Amazon MQ API action does not support resource-level permissions, you can
grant users permission to use the action, but you have to specify a * wildcard for the resource
element of your policy statement.
API Action Resource Types (*required)
CreateConfiguration configurations*
CreateTags brokers, configurations
CreateUser brokers*
DeleteBroker brokers*
DeleteUser brokers*
DescribeBroker brokers*
DescribeConfiguration configurations*
DescribeConfigurationRevision configurations*
DescribeUser brokers*
ListConfigurationRevisions configurations*
ListConfigurationRevisions configurations*
ListTags brokers, configurations
ListUsers brokers*
RebootBroker brokers*
UpdateBroker brokers*
UpdateConfiguration configurations*
UpdateUser brokers*
Messaging Authentication and Authorization for

ActiveMQ
You can access your brokers using the following protocols with TLS enabled:
109
Messaging Authentication and Authorization
• AMQP
• MQTT
• OpenWire
• STOMP
Amazon MQ uses native ActiveMQ authentication to manage user permissions. For information about
restrictions related to ActiveMQ usernames and passwords, see Limits Related to Users (p. 93).
To authorize ActiveMQ users and groups to works with queues and topics, you must edit your broker's
configuration (p. 23). Amazon MQ uses ActiveMQ's Simple Authentication Plugin to restrict reading and
writing to destinations. For more information and examples, see Always Configure an Authorization
Map (p. 86) and authorizationEntry (p. 68).
Note
Currently, Amazon MQ doesn't support Client Certificate Authentication or plugins for Java
Authentication and Authorization Service (JAAS).
110
Amazon MQ Resources
Related Resources
Amazon MQ Resources
The following table lists useful resources for working with Amazon MQ.
Resource Description
Amazon MQ REST API Reference Descriptions of REST resources, example requests,

HTTP methods, schemas, parameters, and the
errors that the service returns.
Amazon MQ in the AWS CLI Command Reference Descriptions of the AWS CLI commands that you
can use to work with message brokers.
Amazon MQ in the AWS CloudFormation User The AWS::Amazon MQ::Broker resource lets
Guide you create Amazon MQ brokers, add configuration
changes or modify users for the specified broker,
return information about the specified broker, and
delete the specified broker.
The AWS::Amazon MQ::Configuration

resource lets you create Amazon MQ
configurations, add configuration changes or
modify users, and return information about the
specified configuration.
Regions and Endpoints Information about Amazon MQ regions and

endpoints
Product Page The primary web page for information about

Amazon MQ.
Discussion Forum A community-based forum for developers to

discuss technical questions related to Amazon
MQ.
AWS Premium Support Information The primary web page for information about
AWS Premium Support, a one-on-one, fast-
response support channel to help you build and
run applications on AWS infrastructure services
Apache ActiveMQ Resources

The following table lists useful resources for working with Apache ActiveMQ.
Apache ActiveMQ Getting Started Guide The official documentation of Apache ActiveMQ.
111
Apache ActiveMQ Resources
ActiveMQ in Action A guide to Apache ActiveMQ that covers the

anatomy of JMS messages, connectors, message
persistence, authentication, and authorization.
Cross-Language Clients A list of programming languages and

corresponding Apache ActiveMQ libraries. See also
ActiveMQ Client and QpidJMS Client.
112
Amazon MQ Release Notes

The following table lists Amazon MQ feature releases and improvements. For changes to the Amazon MQ
Developer Guide, see Amazon MQ Document History (p. 118).
Date Documentation Update
June 19, 2019 Amazon MQ is available in the EU (Paris) and Asia Pacific (Mumbai) regions. For
information on available regions, see AWS Regions and Endpoints.
June 12, 2019 Amazon MQ is available in the Canada (Central) region. For information on
available regions, see AWS Regions and Endpoints.
June 3, 2019 Two new Amazon CloudWatch metrics are available:

EstablishedConnectionsCount and InactiveDurableSubscribers. See:
• Monitoring Amazon MQ Using CloudWatch (p. 95)

• Broker Metrics (p. 95)
May 10, 2019 Data storage for new mq.t2.micro instance types are limited to 20 GB. See:
• Limits Related to Data Storage (p. 93)

• Broker Instance Types (p. 38)
April 29, 2019 You can now use tag-based policies and resource-level permissions. For more
information, see:

April 16, 2019 You can now retrieve information about broker engine and broker instance
options using the REST API. For more information, see:
• Broker Instance Options

• Broker Engine Types
April 8, 2019 Amazon MQ supports ActiveMQ 5.15.9. For more information, see the following.
Resolved bugs and improvements in ActiveMQ:
• ActiveMQ 5.15.9 Release Notes
For more information:
• Broker Engine (p. 42)

• Working with Spring XML Configuration Files (p. 55)
March 4, 2019 Improved the documentation for configuring dynamic failover and the
rebalancing of clients for a network of brokers. Enable dynamic failover by
configuring transportConnectors along with networkConnectors
configuration options. For more information, see:

113
February 27, 2019 Amazon MQ is available in the EU (London) Region in addition to the following
regions:
• Asia Pacific (Singapore)

• US East (Ohio)
• US East (N. Virginia)
• US West (N. California)
• US West (Oregon)
• Asia Pacific (Tokyo)
• Asia Pacific (Seoul)
• Asia Pacific (Sydney)
• EU (Frankfurt)
• EU (Ireland)
January 24, 2019 The default configuration now includes a policy to purge inactive destinations.
January 17, 2019 Amazon MQ mq.t2.micro instance types now support only 100 connections per
wire-level protocol. See, Limits in Amazon MQ (p. 92).
December 19, You can configure a series of Amazon MQ brokers in a network of brokers. For
2018 more information, see the following sections:

December 11, Amazon MQ supports ActiveMQ 5.15.8, 5.15.6, and 5.15.0. For more information,
2018 see the following:
• Resolved bugs and improvements in ActiveMQ:

December 5, 2018 AWS supports resource tagging to help track your cost allocation. You can tag
resources when creating them, or by viewing the details of that resource. See
Tagging resources.
November 19, AWS has expanded its SOC compliance program to include Amazon MQ as an SOC
2018 compliant service.
October 15, 2018 • The maximum number of groups per user is 20. For more information, see
Limits Related to Users (p. 93).
• The maximum number of connections per broker, per wire-level protocol is
1,000. For more information, see Limits Related to Brokers (p. 92).
October 2, 2018 AWS has expanded its HIPAA compliance program to include Amazon MQ as a
HIPAA Eligible Service.
114
September 27, Amazon MQ supports ActiveMQ 5.15.6, in addition to 5.15.0. For more
2018 information, see the following:
• Editing Broker Engine Version, CloudWatch Logs, and Maintenance

Preferences (p. 20)
• Resolved bugs and improvements in the ActiveMQ documentation:
• ActiveMQ Client 5.15.6
August 31, 2018 • The following metrics are available:

• CurrentConnectionsCount
• TotalConsumerCount
• TotalProducerCount
For more information, see the Broker Metrics (p. 95) section.
• The IP address of the broker is displayed on the Details page.
Note
For brokers with public accessibility disabled, the internal IP address is
displayed.
August 30, 2018 Amazon MQ is available in the Asia Pacific (Singapore) Region in addition to the
following regions:
• US East (Ohio)
• Asia Pacific (Tokyo)
• Asia Pacific (Seoul)
• EU (Frankfurt)
• EU (Ireland)
July 30, 2018 You can configure Amazon MQ to publish general and audit logs to Amazon
CloudWatch Logs. For more information, see Configuring Amazon MQ to Publish
Logs to Amazon CloudWatch Logs (p. 101).
115
July 25, 2018 Amazon MQ is available in the Asia Pacific (Tokyo) and Asia Pacific (Seoul) Regions
in addition to the following regions:
• US East (Ohio)
• EU (Frankfurt)
• EU (Ireland)
July 19, 2018 You can use AWS CloudTrail to log Amazon MQ API calls. For more information,
see Logging Amazon MQ API Calls Using CloudTrail (p. 99).
June 29, 2018 In addition to mq.t2.micro and mq.m4.large, the following broker instance
types are available for regular development, testing, and production workloads
that require high throughput:
• mq.m5.large
• mq.m5.xlarge
• mq.m5.2xlarge
• mq.m5.4xlarge
For more information, see Broker Instance Types (p. 38).
June 27, 2018 Amazon MQ is available in the US West (N. California) Region in addition to the
following regions:
• US East (Ohio)
• EU (Frankfurt)
• EU (Ireland)
116
June 14, 2018 • You can use the AWS::Amazon MQ::Broker AWS CloudFormation resource to
perform the following actions:
• Create a broker.
• Add configuration changes or modify users for the specified broker.
• Return information about the specified broker.
• Delete the specified broker.
Note
When you change any property of the Amazon MQ Broker
ConfigurationId or Amazon MQ Broker User property type, the broker
is rebooted immediately.
• You can use the AWS::Amazon MQ::Configuration AWS CloudFormation
resource to perform the following actions:
• Create a configuration.
• Update the specified configuration.
• Return information about the specified configuration.
Note
You can use AWS CloudFormation to modify—but not delete—an
Amazon MQ configuration.
June 7, 2018 The Amazon MQ console supports German, Brazilian Portuguese, Spanish, Italian,
and Traditional Chinese.
May 17, 2018 The limit of number of users per broker is 250. For more information, see Limits
Related to Users (p. 93).
March 13, 2018 Creating a broker takes about 15 minutes. For more information, see Finish
creating the broker (p. 14).
March 1, 2018 • You can configure the concurrent store and dispatch (p. 89) for Apache KahaDB
using the concurrentStoreAndDispatchQueues (p. 70) attribute.
• The CpuCreditBalance CloudWatch metric (p. 95) is available for
mq.t2.micro broker instance type.
January 10, 2018 The following changes affect the Amazon MQ console:
• In the broker list, the Creation column is hidden by default. To customize the
page size and columns, choose .
• On the MyBroker page, in the Connections section, choosing the name of
your security group or opens the EC2 console (instead of the VPC console).
The EC2 console allows more intuitive configuration of inbound and outbound
rules. For more information, see the updated Enable Inbound Connections (p. 7)
section.
January 9, 2018 • The permission for REST operation ID UpdateBroker is listed correctly as
mq:UpdateBroker on the IAM console.
• The erroneous mq:DescribeEngine permission is removed from the IAM
console.
117
Document History
November 28, This is the initial release of Amazon MQ and the Amazon MQ Developer Guide.
2017
• Amazon MQ is avaialble in the following regions:
• US East (Ohio)
• EU (Frankfurt)
• EU (Ireland)
Using the mq.t2.micro instance type is subject to CPU credits and baseline
performance—with the ability to burst above the baseline level (for more
information, see the CpuCreditBalance (p. 95) metric). If your application
requires fixed performance, consider using an mq.m5.large instance type.
• You can create mq.m4.large and mq.t2.micro brokers.
Using the mq.t2.micro instance type is subject to CPU credits and baseline
performance—with the ability to burst above the baseline level (for more
information, see the CpuCreditBalance (p. 95) metric). If your application
requires fixed performance, consider using an mq.m5.large instance type.
• You can use the ActiveMQ 5.15.0 broker engine.
• You can also create and manage brokers programmatically using Amazon MQ
REST API and AWS SDKs.
• You can access your brokers by using any programming language that
ActiveMQ supports and by enabling TLS explicitly for the following protocols:
• AMQP
• MQTT
• OpenWire
• STOMP
• You can connect to ActiveMQ brokers using various ActiveMQ clients. We
recommend using the ActiveMQ Client. For more information, see Connecting a
Java Application to Your Broker (p. 26).
• Your broker can send and receive messages of any size.
Amazon MQ Document History

The following table lists changes to the Amazon MQ Developer Guide. For Amazon MQ feature releases
and improvements, see Amazon MQ Release Notes (p. 113).
April 22, 2019 Added new topics for tag-based policies and resource-level permissions.

118
Document History
March 4, 2019 Improved the documentation for configuring dynamic failover and the
rebalancing of clients for a network of brokers. Enable dynamic failover by
configuring transportConnectors along with networkConnectors
configuration options. For more information, see:

January 5, 2019 Improved documentation on some per-minute metrics. See: Destination (Queue
and Topic) Metrics (p. 97).
December 19, • Added the following sections:

2018 • Amazon MQ Network of Brokers (p. 46)
• Added the networkConnectors child collection element to the Elements,
Child Collection Elements, and Their Child Elements Permitted in Amazon MQ
Configurations (p. 65) section.
December 11, Updated documentation to reflect availability of ActiveMQ version 5.15.8.

2018
December 5, 2018 Added a new topic on cost allocation tagging. See: Tagging resources (p. 78).
October 26, 2018 Added a new Best Practices topic. See: Avoid Slow Restarts by Recovering
Prepared XA Transactions (p. 90).
October 15, 2018 Updated the Limits in Amazon MQ (p. 92) section.
October 8, 2018 Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
October 3, 2018 Corrected outdated links in the Setting Up Amazon MQ (p. 4) and Amazon MQ
Tutorials (p. 12) sections.
October 1, 2018 Corrected the information in the Next Steps (p. 10) section.
September 27, • Added the Editing Broker Engine Version, CloudWatch Logs, and Maintenance
2018 Preferences (p. 20) section.
• Updated the following sections:
• Broker Engine (p. 42)
• Create an ActiveMQ Broker (p. 6)
• Configure Basic Broker Settings (p. 12)
September 18, Added the following note to the Creating and Managing Amazon MQ Broker
2018 Users (p. 30) section: You can't configure groups independently of users. A group
label is created when you add at least one user to it and deleted when you
remove all users from it.
September 10, Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
2018
119
Document History
August 31, 2018 • Clarified the terminology for active/standby brokers. For more information, see
Amazon MQ Active/Standby Broker for High Availability (p. 45).
• Simplified the terminology for the maintenance window. For more information,
see Amazon MQ Broker Configuration Lifecycle (p. 54).
• Rewrote the Configure Advanced Broker Settings (p. 13) section.
• Updated the Broker Metrics (p. 95) and Listing Brokers and Viewing Broker
Details (p. 29) sections.
August 15, 2018 Corrected the information in the Create an ActiveMQ Broker (p. 6) section.
August 13, 2018 Added the Accessing the ActiveMQ Web Console of a Broker without Public
Accessibility (p. 15) section.
August 3, 2018 Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
August 2, 2018 • Added the Troubleshooting CloudWatch Logs Configuration (p. 104) section.
• Added the following admonition throughout this guide:
Important
In the following example code, producers and consumers run in a
single thread. For production systems (or to test broker instance
failover), make sure that your producers and consumers run on
separate hosts or threads.
August 1, 2018 Corrected the information in the following sections:
• Understanding the Structure of Logging in CloudWatch Logs (p. 102)

• Connect a Java Application to Your Broker (p. 7)
July 31, 2018 • Moved the 3-minute demo video to the Getting Started with Amazon MQ (p. 6)
section.
• Added the 3-minute getting started video to the What is Amazon MQ? (p. 1)
section.
July 30, 2018 • Added the Configuring Amazon MQ to Publish Logs to Amazon CloudWatch
Logs (p. 101) section.
• Updated the Configure Advanced Broker Settings (p. 13) section.
July 19, 2018 • Added the Logging Amazon MQ API Calls Using CloudTrail (p. 99) section.
• Corrected the information in the What Are the Main Benefits of Amazon
MQ? (p. 1) section.
July 5, 2018 • Added an authorizationEntry child element cross-reference to the Always

Configure an Authorization Map (p. 86) section.
• Clarified the information in the Messaging Authentication and Authorization for
ActiveMQ (p. 109) section.
• Clarified the information in the Limits Related to API Throttling (p. 93) section.
• Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
June 29, 2018 • Updated the information in the Broker Instance Types (p. 38) section.
• Added the Choose the Correct Broker Instance Type for the Best
Throughput (p. 89) section.
June 26, 2018 Added a link to a related resource to the Migrating to Amazon MQ (p. 80) section.
120
Document History
June 8, 2018 Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
June 4, 2018 In addition to GitHub, HTML, PDF, and Kindle, the Amazon MQ Developer Guide
release notes are available as an RSS feed.
May 29, 2018 Made the following changes in the Working Java Example (p. 70) section:
• Added a STOMP+WSS Java example. The STOMP+WSS example Java code

connects to a broker, creates a queue, and publishes and receives a message.
• Improved the MQTT Java example.
• Improved the OpenWire Java example.
May 24, 2018 Corrected the wire-level protocol endpoint port in the MQTT Java example in the
Working Java Example (p. 70) section.
May 22, 2018 Corrected the information in all Java dependency sections.
May 17, 2018 Corrected the information in the Limits Related to Users (p. 93) section.
May 15, 2018 Corrected the information in the Ensuring Effective Amazon MQ
Performance (p. 88) section.
May 8, 2018 • Placed the Amazon MQ REST API Permissions Reference (p. 108) in its own
section.
• Created the IAM Permissions Required to Create an Amazon MQ Broker (p. 107)
section with an example custom IAM policy.
May 7, 2018 • Clarified throughout this guide that the broker maintenance window is 2
hours long. For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 54).
• Added explanations for why the ec2:CreateNetworkInterface and
ec2:CreateNetworkInterfacePermission permissions are necessary
for creating a broker. For more information, see API Authentication and
Authorization for Amazon MQ (p. 107).
May 4, 2018 Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
May 1, 2018 Clarified the information about the maintenance window for active/standby
brokers in the following sections:
• Amazon MQ Active/Standby Broker for High Availability (p. 45)

• Creating and Configuring a Broker (p. 12)
121
Document History
April 27, 2018 Rewrote the following sections and optimized example Java code to match the
recommendation to use connection pooling only for producers, not consumers:

• Create a Message Producer and Send a Message (p. 8)
• Create a Message Consumer and Receive the Message (p. 9)
• AmazonMQExample.java (p. 73)
April 26, 2018 Added an MQTT Java example to the Working Java Example (p. 70) section. The
MQTT example Java code connects to a broker, creates a topic, and publishes and
receives a message.
April 6, 2018 Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
April 4, 2018 Renamed the Communicating with Amazon MQ section to Connecting to Amazon
MQ (p. 86).
April 3, 2018 Clarified and corrected the information in the Disable Concurrent Store and
Dispatch for Queues with Slow Consumers (p. 89) section.
April 2, 2018 Moved the Concurrent Store and Dispatch for Queues in Amazon MQ
section to the Disable Concurrent Store and Dispatch for Queues with Slow
Consumers (p. 89) section.
March 27, 2018 • Replaced the re:Invent launch video with a 3-minute demo video in the What is
Amazon MQ? (p. 1) section.
• Rewrote the What Are the Main Benefits of Amazon MQ? (p. 1) section to
include information about recently released features.
• Restructured the following sections:
• Amazon MQ Broker Architecture (p. 43)
• How Amazon MQ Works (p. 36)
• Migrating to Amazon MQ (p. 80)
• Moved Amazon MQ Broker Configuration Lifecycle (p. 54) under the Amazon
MQ Broker Architecture (p. 43) section.
March 22, 2018 Clarified the following statement throughout this guide: Amazon MQ encrypts
messages at rest and in transit using encryption keys that it manages and stores
securely. For additional security, we highly recommend designing your application
to use client-side encryption. For more information, see the AWS Encryption SDK
Developer Guide.
March 19, 2018 Clarified the following statement throughout this guide: An Active/standby
broker is comprised of two brokers in two different Availability Zones, configured
in a redundant pair. These brokers communicate synchronously with your
application, and with a shared storage location.
March 15, 2018 • Restructured the Amazon MQ Basic Elements (p. 36) section.
• Improved the explanation of the diagrams in the following sections:
• Migrating to Amazon MQ without Service Interruption (p. 80)
• Migrating to Amazon MQ with Service Interruption (p. 82)
122
Document History
March 12, 2018 • Clarified and corrected the information in the Using Amazon MQ
Securely (p. 85) and Connecting to Amazon MQ (p. 86) sections.
• Added the Disable Concurrent Store and Dispatch for Queues with Slow
Consumers (p. 89) section.
• Grouped admonitions into a preface for the Configure advanced broker
settings (p. 13) section.
March 9, 2018 • Clarified and corrected the information in the Always Configure an
Authorization Map (p. 86) and Always Configure a System Group (p. 86)
sections.
• Added the authorizationEntry (p. 68) section and updated the kahaDB (p. 70)
section.
March 8, 2018 • Added the Always Configure an Authorization Map (p. 86) and Always Configure
a System Group (p. 86) sections.
• Added notes about broker suffixes to the Monitoring Amazon MQ Using
CloudWatch (p. 95) section.
March 7, 2018 Updated the Frequently Viewed Amazon MQ Topics (p. 3) section.
March 6, 2018 Added the following note throughout this guide:

Note
Using the mq.t2.micro instance type is subject to CPU credits and
baseline performance—with the ability to burst above the baseline
level (for more information, see the CpuCreditBalance (p. 95)
metric). If your application requires fixed performance, consider using an
mq.m5.large instance type.
March 1, 2018 • Added the CpuCreditBalance metric to the Broker Metrics (p. 95) section.
• Added the Amazon MQ Child Element Attributes (p. 68) section.
• Added links from elements in the the section called “Permitted
Elements” (p. 55) section to their attributes and to child collection elements.
• Made corrections to the AWS Glossary in GitHub.
February 28, 2018 Corrected image display in GitHub.
February 27, 2018 In addition to HTML, PDF, and Kindle, the Amazon MQ Developer Guide is available
on GitHub. To leave feedback, choose the GitHub icon in the upper right-hand
corner.
February 26, 2018 • Made regions consistent in all examples and diagrams.
• Optimized links to the AWS console and product webpages.
123
Document History
February 22, 2018 Clarified and corrected the information in the following sections:
• Prefer Brokers without Public Accessibility (p. 85)

• Always Use Client-Side Encryption as a Complement to TLS (p. 85)
• Always Use the Failover Transport to Connect to Multiple Broker
Endpoints (p. 88)
• API Authentication and Authorization for Amazon MQ (p. 107)
• Messaging Authentication and Authorization for ActiveMQ (p. 109)
February 21, 2018 Corrected the Java code in the following sections:
• Working Java Example (p. 70)

• Connect a Java Application to Your Broker (p. 7)
February 20, 2018 Clarified and corrected the information in the Amazon MQ Security (p. 105) and
Best Practices for Amazon MQ (p. 85) sections.
February 19, 2018 • Corrected the Java code in the Always Use Connection Pooling (p. 87) section.
• Clarified and corrected the information in the Always Use Client-Side
Encryption as a Complement to TLS (p. 85) section.
• Restructured and expanded the Best Practices for Amazon MQ (p. 85) and
Amazon MQ Security (p. 105) sections.
February 16, 2018 • Added the Using Amazon MQ Securely (p. 85) section.
• Updated the Connecting to Amazon MQ (p. 86) section.
• Corrected the Java code in the following sections:
• Getting Started with Amazon MQ (p. 6)
• AmazonMQExample.java (p. 73)
February 15, 2018 • Restructured and expanded the Best Practices for Amazon MQ (p. 85) section.
• Updated the following sections:
• How Can I Get Started with Amazon MQ? (p. 2)
• Next Steps (p. 10) (Getting Started)
• Related Resources (p. 111)
February 14, 2018 Updated the following sections:
• Limits in Amazon MQ (p. 92)

• Limits Related to API Throttling (p. 93)
• Best Practices for Amazon MQ (p. 85)
• Amazon MQ Security (p. 105)
February 13, 2018 • Updated the Related Resources (p. 111) section.
• Updated the Limits in Amazon MQ (p. 92) section.
• Added the We Want to Hear from You (p. 2) section.
February 2, 2018 Created the Frequently Viewed Amazon MQ Topics (p. 3) section.
124
Document History
January 25, 2018 • Fixed an error in the Add Java Dependencies (p. 71) subsection of the Working
Java Example (p. 70) section.
• The permission for REST operation ID RebootBroker is listed correctly as
mq:RebootBroker on the IAM console.
January 24, 2018 • Added the Never Modify or Delete the Amazon MQ Elastic Network
Interface (p. 87) section.
• Updated all diagrams throughout this guide.
• Added links to the Amazon MQ REST API Reference throughout this guide and
links to specific REST APIs to the API Authentication and Authorization for
Amazon MQ (p. 107) section.
January 19, 2018 Updated the information in the Apache ActiveMQ Resources (p. 111) section.
January 18, 2018 Clarified and corrected the information in the Limits in Amazon MQ (p. 92)
section.
January 17, 2018 Reinstated the recommendation to prefer virtual destinations over durable
subscriptions (p. 88), with an improved explanation.
January 11, 2018 • The Amazon MQ Developer Guide is available in Kindle format, in addition to
HTML and PDF.
• Clarified and corrected information in the API Authentication and Authorization
for Amazon MQ (p. 107) and Create an IAM User and Get Your AWS
Credentials (p. 4) sections.
January 3, 2018 Added DescribeConfigurationRevision to the API Authentication and

Authorization for Amazon MQ (p. 107) section.
December 15, Removed the recommendation against durable subscriptions from the Best
2017 Practices for Amazon MQ (p. 85) section.
December 8, 2017 • Added the Enable Inbound Connections (p. 7) prerequisite to the Connecting
a Java Application to Your Broker (p. 26) and Working Java Example (p. 70)
sections.
• Added the following note throughout this guide: Currently, you can't delete a
configuration.
December 7, 2017 • Improved the code in the AmazonMQExample.java (p. 73).

• Added the API Authentication and Authorization for Amazon MQ (p. 107)
section.
December 5, 2017 • Clarified and corrected information in the Monitoring Amazon MQ Using
CloudWatch (p. 95) section:
• Improved the metric descriptions.
• Added the Dimension for Broker Metrics (p. 97) and Dimensions for
Destination (Queue and Topic) Metrics (p. 98) sub-sections.
• Added the "Introducing Amazon MQ" video to the What is Amazon MQ? (p. 1)
section.
125
Document History
December 4, 2017 • Clarified the following information in the Limits Related to Data Storage (p. 93)
section: Storage capacity per broker is 200 GB.
• Added the Prerequisites (p. 71) to the Working Java Example (p. 70) section.
(The activemq-client.jar and activemq-pool.jar packages are
required for the example to work. For more information, see Connecting a Java
Application to Your Broker (p. 26)).
December 1, 2017 • Updated and improved the screenshots in all the tutorials.
• Clarified the following explanation throughout this guide: Making changes
to a configuration revision or an ActiveMQ user does not apply the changes
immediately. To apply your changes, you must wait for the next maintenance
window (p. 25) or reboot the broker (p. 32). For more information, see Amazon
MQ Broker Configuration Lifecycle (p. 54).
126
AWS Glossary
For the latest AWS terminology, see the AWS Glossary in the AWS General Reference.
127

Amazon MQ DG

Uploaded by

Copyright:

Available Formats

Amazon MQ DG

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Amazon MQ DG

Uploaded by

Copyright:

Available Formats

Amazon MQ

Amazon MQ: Developer Guide

Deleting a Broker ..................................................................................................................... 33

API Throttling .......................................................................................................................... 93

What Is Amazon MQ?

What Are the Main Beneﬁts of Amazon MQ?

How Is Amazon MQ Diﬀerent from Amazon SQS or

How Can I Get Started with Amazon MQ?

We Want to Hear from You

Frequently Viewed Amazon MQ

Amazon MQ Developer Guide Amazon MQ REST API Reference

1. Working Java Example (p. 70) 1. Broker

Step 1: Create an AWS Account and an IAM

Step 2: Create an IAM User and Get Your AWS

1. Sign in to the AWS Identity and Access Management console.

Step 3: Get Ready to Use the Example Code

Getting Started with Amazon MQ

Step 1: Create an ActiveMQ Broker

1. Sign in to the Amazon MQ console.

Creating the broker takes about 15 minutes.

Step 2: Connect a Java Application to Your Broker

Enable Inbound Connections

The Security Groups page of the EC2 Dashboard is displayed.

a. Choose Add Rule.

Your broker can now accept inbound connections.

Add Java Dependencies

Create a Message Producer and Send a Message

// Create a connection factory.

// Pass the username and password.

// Create a pooled connection factory.

// Establish a connection for the producer.

// Create a queue named "MyQueue".

// Create a producer from the session to the queue.

// Send the message.

4. Clean up the producer.

Create a Message Consumer and Receive the Message

// Create a connection factory.

// Pass the username and password.

// Establish a connection for the consumer.

// Create a queue named "MyQueue".

// Create a message consumer from the session to the queue.

// Begin to wait for messages.

// Receive the message when it arrives.

Step 3: Delete Your Broker

1. Sign in to the Amazon MQ console.

Deleting a broker takes about 5 minutes.

• Creating and Conﬁguring a Broker (p. 12) (Advanced Settings)

Tutorial: Creating and Conﬁguring an Amazon MQ

Step 1: Conﬁgure Basic Broker Settings

Step 2: (Optional) Conﬁgure Advanced Broker

1. Expand the Advanced settings section.

a. Do one of the following:

• Choose Use the default VPC, subnet(s), and security group(s).

• To allow Amazon MQ to select the maintenance window automatically, choose No

Step 3: Finish Creating the Broker

Creating the broker takes about 15 minutes.

Accessing the ActiveMQ Web Console of a Broker

To Access the ActiveMQ Web Console of a Broker without Public

ssh -i ~/.ssh/id_rsa -N -C -q -f -D 8080 ec2-user@203.0.113.0