0% found this document useful (0 votes)

19 views

Amazon MQ DG

This document provides information about Amazon MQ and how to set up and manage message brokers. It describes how to create ActiveMQ and RabbitMQ brokers, connect applications, and perform management tasks like upgrading and monitoring brokers.

Uploaded by

tienmh

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

19 views

Amazon MQ DG

Uploaded by

tienmh

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 235

Amazon MQ

Developer Guide
Amazon MQ Developer Guide

Amazon MQ: Developer Guide

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 aﬃliated with, connected to, or sponsored by Amazon.
Amazon MQ Developer Guide

Table of Contents
What is Amazon MQ? ......................................................................................................................... 1
How is Amazon MQ diﬀerent from Amazon SQS or Amazon SNS? .................................................... 1
How can I get started with Amazon MQ? ...................................................................................... 1
We want to hear from you .......................................................................................................... 1
Setting up ......................................................................................................................................... 2
Create an AWS account and an IAM administrator user ................................................................... 2
Create an IAM user and get your AWS credentials .......................................................................... 2
Step 3: get ready to use the example codes .................................................................................. 3
Next steps ................................................................................................................................. 3
Getting started .................................................................................................................................. 4
Prerequisites .............................................................................................................................. 4
Creating and connecting to an ActiveMQ broker ............................................................................ 4
Step 1: create an ActiveMQ broker ....................................................................................... 4
Step 2: connect a Java application to your broker .................................................................. 6
Step 3: (Optional) connect to an AWS Lambda function .......................................................... 9
Step 4: delete your broker ................................................................................................. 11
Next steps ....................................................................................................................... 11
Creating and connecting to a RabbitMQ broker ............................................................................ 11
Step 1: create a RabbitMQ broker ...................................................................................... 11
Step 2: connect a JVM-based application to your broker ........................................................ 13
Step 3: (Optional) connect to an AWS Lambda function ........................................................ 16
Step 4: delete your broker ................................................................................................. 18
Next steps ....................................................................................................................... 18
Managing a broker ........................................................................................................................... 19
Maintaining a broker ................................................................................................................ 19
Adjusting the broker maintenance window .......................................................................... 20
Upgrading the engine version .................................................................................................... 21
Manually upgrading the engine version ............................................................................... 22
Automatically upgrading the minor engine version ............................................................... 24
Broker statuses ........................................................................................................................ 25
Listing brokers and viewing broker details ................................................................................... 25
To list brokers and view broker details ................................................................................ 26
Accessing the broker web console without public accessibility ........................................................ 28
Prerequisites .................................................................................................................... 28
To Access a broker's web console of a Broker without Public Accessibility ................................. 28
Rebooting a broker ................................................................................................................... 29
To Reboot an Amazon MQ Broker ...................................................................................... 29
Deleting a broker ..................................................................................................................... 29
Deleting an Amazon MQ broker ......................................................................................... 30
Instance types .......................................................................................................................... 30
Amazon MQ for ActiveMQ instance types ............................................................................ 30
Amazon MQ for RabbitMQ instance types ........................................................................... 33
Tagging resources ..................................................................................................................... 34
Tagging for Cost Allocation ............................................................................................... 34
Managing Tags in the Amazon MQ Console ......................................................................... 35
Managing Using Amazon MQ API Actions ............................................................................ 36
Amazon MQ for ActiveMQ ................................................................................................................. 37
ActiveMQ engine ...................................................................................................................... 37
Basic Elements ................................................................................................................. 37
Broker architecture ........................................................................................................... 44
Broker conﬁguration parameters ........................................................................................ 57
Version management ........................................................................................................ 75
Working Java examples ..................................................................................................... 76
ActiveMQ tutorials .................................................................................................................... 84

iii
Amazon MQ Developer Guide

Creating and conﬁguring a broker ...................................................................................... 84

Editing broker preferences ................................................................................................. 87
Creating and configuring a network of brokers ..................................................................... 88
Creating and applying configurations .................................................................................. 92
Editing configurations and managing configuration revisions ................................................. 94
Connecting a Java application to your broker ....................................................................... 97
Integrating ActiveMQ brokers with LDAP ........................................................................... 100
Creating and managing broker users ................................................................................. 111
Amazon MQ for ActiveMQ best practices ................................................................................... 113
Connecting to Amazon MQ .............................................................................................. 113
Ensuring effective Amazon MQ performance ...................................................................... 115
Avoid slow restarts by recovering prepared XA transactions ................................................. 117
Amazon MQ for RabbitMQ .............................................................................................................. 119
RabbitMQ engine .................................................................................................................... 119
Basic elements ............................................................................................................... 119
Broker architecture ......................................................................................................... 128
Version management ...................................................................................................... 130
RabbitMQ tutorials ................................................................................................................. 132
Editing broker preferences ............................................................................................... 132
Using Python Pika with Amazon MQ for RabbitMQ ............................................................. 132
Resolving paused queue sync ........................................................................................... 137
Amazon MQ for RabbitMQ best practices .................................................................................. 141
Enable lazy queues ......................................................................................................... 141
Use persistent and durable queues ................................................................................... 141
Keep queues short .......................................................................................................... 142
Configure acknowledgement and confirmation ................................................................... 142
Configure pre-fetching .................................................................................................... 143
Configure Celery ............................................................................................................. 144
Automatically recover from network failures ...................................................................... 144
Security ......................................................................................................................................... 145
Data protection ...................................................................................................................... 145
Encryption ..................................................................................................................... 146
Encryption at rest ........................................................................................................... 146
Encryption in transit ....................................................................................................... 147
Identity and access management .............................................................................................. 148
Audience ....................................................................................................................... 148
Authenticating with identities .......................................................................................... 149
Managing access using policies ......................................................................................... 151
How Amazon MQ works with IAM .................................................................................... 152
Identity-based policy examples ........................................................................................ 156
API authentication and authorization ................................................................................ 158
AWS managed policies .................................................................................................... 161
Using service-linked roles ................................................................................................ 162
Troubleshooting ............................................................................................................. 166
Compliance validation ............................................................................................................. 167
Resilience .............................................................................................................................. 168
Infrastructure security ............................................................................................................. 168
Security best practices ............................................................................................................ 168
Prefer brokers without public accessibility ......................................................................... 169
Always configure an authorization map ............................................................................. 169
Block Unnecessary Protocols ............................................................................................ 169
Logging and monitoring .................................................................................................................. 170
Accessing CloudWatch metrics .................................................................................................. 170
AWS Management Console .............................................................................................. 170
AWS Command Line Interface .......................................................................................... 172
Amazon CloudWatch API ................................................................................................. 173
Monitoring brokers using CloudWatch ....................................................................................... 173

iv
Amazon MQ Developer Guide

Logging and monitoring Amazon MQ for ActiveMQ brokers ................................................. 173

Logging and monitoring Amazon MQ for RabbitMQ brokers ................................................. 178
Logging API calls using CloudTrail ............................................................................................ 182
Amazon MQ Information in CloudTrail .............................................................................. 183
Example Amazon MQ Log File Entry ................................................................................. 184
Configuring Amazon MQ to publish logs to CloudWatch Logs ....................................................... 185
Configuring Amazon MQ for ActiveMQ logs ....................................................................... 186
Configuring Amazon MQ for RabbitMQ logs ...................................................................... 189
Quotas .......................................................................................................................................... 190
Brokers .................................................................................................................................. 190
Configurations ........................................................................................................................ 190
Users ..................................................................................................................................... 191
Data Storage .......................................................................................................................... 191
API Throttling ........................................................................................................................ 192
Troubleshooting ............................................................................................................................. 193
Troubleshooting: General ......................................................................................................... 193
I can't connect to my broker web console or endpoints. ....................................................... 194
SSL exceptions ............................................................................................................... 197
I created a broker but broker creation failed. ..................................................................... 197
My broker restarted and I'm not sure why. ......................................................................... 197
Troubleshooting: Amazon MQ for ActiveMQ ............................................................................... 198
Retrieving CloudWatch Logs ............................................................................................ 198
Connecting to broker after a restart ................................................................................. 199
Some clients unable to connect ....................................................................................... 199
JSP exception on the web console ................................................................................... 200
Troubleshooting: Amazon MQ for RabbitMQ .............................................................................. 200
I can’t see metrics for my queues or virtual hosts in CloudWatch. .......................................... 200
How do I enable plugins in Amazon MQ for RabbitMQ? ....................................................... 201
I'm unable to change Amazon VPC configuration for the broker. ........................................... 201
Troubleshooting: Amazon MQ action required codes ................................................................... 201
RABBITMQ_MEMORY_ALARM ............................................................................................ 201
Related resources ........................................................................................................................... 206
Amazon MQ resources ............................................................................................................. 206
Amazon MQ for ActiveMQ resources ......................................................................................... 206
Amazon MQ for RabbitMQ resources ........................................................................................ 207
Release notes ................................................................................................................................. 208
Document History .................................................................................................................. 220
AWS glossary ................................................................................................................................. 230

v
Amazon MQ Developer Guide
How is Amazon MQ diﬀerent from
Amazon SQS or Amazon SNS?

What is Amazon MQ?

Amazon MQ is a managed message broker service 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. Currently, Amazon MQ
supports Apache ActiveMQ and RabbitMQ engine types.

Amazon MQ works with your existing applications and services without the need to manage, operate, or
maintain your own messaging system.

Topics
• How is Amazon MQ diﬀerent from Amazon SQS or Amazon SNS? (p. 1)
• How can I get started with Amazon MQ? (p. 1)
• We want to hear from you (p. 1)

How is Amazon MQ diﬀerent 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 0-9-1, AMQP 1.0, 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
beneﬁt from nearly unlimited scalability and simple APIs.

How can I get started with Amazon MQ?

• To create your ﬁrst broker with Amazon MQ, see Getting Started with Amazon MQ (p. 4).
• To discover the functionality and architecture of Amazon MQ, see How Amazon MQ Works.
• To ﬁnd out the guidelines and caveats that will help you make the most of Amazon MQ, see Working
with Amazon MQ for ActiveMQ (p. 37) and Working with Amazon MQ for RabbitMQ (p. 119)
• 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.

1
Amazon MQ Developer Guide
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. 2)
• Step 2: create an IAM user and get your AWS credentials (p. 2)
• Step 3: get ready to use the example codes (p. 3)
• Next steps (p. 3)

Step 1: create an AWS account and an IAM

administrator user
To access any AWS service, you must ﬁrst create an Amazon Web Services 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 Amazon Web Services ]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 ﬁnish creating your AWS account, follow the instructions in the IAM User Guide to create
your ﬁrst 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 ﬁlter, choose AmazonMQFullAccess, and then choose Next: Review.
8. On the Review page, choose Create user.

2
Amazon MQ Developer Guide
Step 3: get ready to use the example codes

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/bPxRﬁCYEXAMPLEKEY
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 ﬁle in a secure location.

Step 3: get ready to use the example codes

The following tutorials show how you can work with Amazon MQ brokers using the AWS Management
Console as well as how to connect to your Amazon MQ for ActiveMQ and Amazon MQ for RabbitMQ
brokers programatically. To use the ActiveMQ Java 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. 4).
Depending on your broker engine type, you can then connect a Java application to your Amazon MQ for
ActiveMQ broker (p. 6) or use the RabbitMQ Java client library to connect a JVM-based application to
your Amazon MQ for RabbitMQ broker (p. 13).

3
Amazon MQ Developer Guide
Prerequisites

Getting started with Amazon MQ

This section will help you become more familiar with Amazon MQ by showing you how to create an
Amazon MQ for ActiveMQ or RabbitMQ broker and how to connect your application to it.

Creating and connecting to a broker instance is slightly diﬀerent for each broker engine. Choose one of
the following engine types that you want to use for detailed information on creating and connecting to a
broker. After you have created and connected to your broker, you can ﬁnd instructions to help you delete
it.

Topics
• Prerequisites (p. 4)
• Creating and connecting to an ActiveMQ broker (p. 4)
• Creating and connecting to a RabbitMQ broker (p. 11)

Prerequisites
Before you begin, complete the steps in Setting Up Amazon MQ (p. 2).

Creating and connecting to 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, t3) and size (large, micro) is a
broker instance type (for example, mq.m5.large). For more information, see Broker (p. 37).

Topics
• Step 1: create an ActiveMQ broker (p. 4)
• Step 2: connect a Java application to your broker (p. 6)
• Step 3: (Optional) connect to an AWS Lambda function (p. 9)
• Step 4: delete your broker (p. 11)
• Next steps (p. 11)

Step 1: create an ActiveMQ broker

The ﬁrst 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. On the Select broker engine page, choose Apache ActiveMQ.
3. On the Select deployment and storage page, in the Deployment mode and storage type section,
do the following:

a. Choose the Deployment mode (for example, Active/standby broker). For more information,
see Broker Architecture (p. 44).

4
Amazon MQ Developer Guide
Step 1: create an ActiveMQ broker

• A Single-instance broker is comprised of one broker in one Availability Zone. The broker
communicates with your application and with an Amazon EBS or Amazon EFS storage volume.
For more information, see Amazon MQ single-instance broker (p. 45).
• 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 Amazon EFS. For more information, see Amazon MQ active/
standby broker for high availability (p. 46).
• For more information on the sample blueprints for a network of brokers, see Sample
blueprints (p. 48).
b. Choose the Storage type (for example, EBS). For more information, see Storage (p. 43).
Note
Amazon EBS replicates data within a single Availability Zone and doesn't support the
ActiveMQ active/standby (p. 46) deployment mode.
c. Choose Next.
4. On the Configure settings page, in the Details section, do the following:

a. Enter the Broker name.

Important
Do not add personally identiﬁable information (PII) or other conﬁdential or sensitive
information in broker names. Broker names are accessible to other AWS services,
including CloudWatch Logs. Broker names are not intended to be used for private or
sensitive data.
b. Choose the Broker instance type (for example, mq.m5.large). For more information, see Broker
instance types (p. 30).
5. In the ActiveMQ Web Console access section, provide a Username and Password. The following
restrictions apply to broker usernames and passwords:

• Your username can contain only alphanumeric characters, dashes, periods, underscores, and tildas
(- . _ ~).
• Your password must be at least 12 characters long, contain at least 4 unique characters and must
not contain commas, colons, or equal signs (,:=).

Important
Do not add personally identiﬁable information (PII) or other conﬁdential or sensitive
information in broker usernames. Broker usernames are accessible to other AWS services,
including CloudWatch Logs. Broker usernames are not intended to be used for private or
sensitive data.
6. Choose Deploy.

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.

7. Choose MyBroker.

5
Amazon MQ Developer Guide
Step 2: connect a Java application to your broker

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 ActiveMQ 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. 76).

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

1. Sign in to the Amazon MQ console.
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
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. 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 a broker web console).

a. Choose Add Rule.

b. For Type, select Custom TCP.
c. For Port Range, type the 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 web console (for example, 192.0.2.1).
e. Choose Save.

Your broker can now accept inbound connections.

6
Amazon MQ Developer Guide
Step 2: connect a Java application to your broker

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 ﬁle.

<dependencies>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-client</artifactId>
<version>5.15.8</version>
</dependency>
<dependency>
<groupId>org.apache.activemq</groupId>
<artifactId>activemq-pool</artifactId>
<version>5.15.8</version>
</dependency>
</dependencies>

For more information about activemq-client.jar, see Initial Conﬁguration 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
suﬃxes denote a redundant pair. For more information, see Broker Architecture (p. 44)).
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.

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. 114).
2. Create a session, a queue named MyQueue, and a message producer.

7
Amazon MQ Developer Guide
Step 2: connect a Java application to your broker

// 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.

// Create a connection factory.

final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);

// Pass the username and password.

connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);

// Establish a connection for the consumer.

final Connection consumerConnection = connectionFactory.createConnection();
consumerConnection.start();

Note
Message consumers should never use the PooledConnectionFactory class. For more
information, see Always Use Connection Pooling (p. 114).
2. Create a session, a queue named MyQueue, and a message consumer.

// Create a session.
final Session consumerSession = consumerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);

// Create a queue named "MyQueue".

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

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

8
Amazon MQ Developer Guide
Step 3: (Optional) connect to an AWS Lambda function

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();

Step 3: (Optional) connect to an AWS Lambda

function
AWS Lambda can connect to and consume messages from your Amazon MQ broker. When you connect
a broker to Lambda, you create an event source mapping that reads messages from a queue and invokes
the function synchronously. The event source mapping you create reads messages from your broker in
batches and converts them into a Lambda payload in the form of a JSON object.

To connect your broker to a Lambda function

1. Add the following IAM role permissions to your Lambda function execution role.

• mq:DescribeBroker
• ec2:CreateNetworkInterface
• ec2:DeleteNetworkInterface
• ec2:DescribeNetworkInterfaces
• ec2:DescribeSecurityGroups
• ec2:DescribeSubnets
• ec2:DescribeVpcs
• logs:CreateLogGroup
• logs:CreateLogStream
• logs:PutLogEvents
• secretsmanager:GetSecretValue

Note
Without the necessary IAM permissions, your function will not be able to successfully read
records from Amazon MQ resources.
2. (Optional) If you have created a broker without public accessibility, you must do one of the following
to allow Lambda to connect to your broker:

9
Amazon MQ Developer Guide
Step 3: (Optional) connect to an AWS Lambda function

• Configure one NAT gateway per public subnet. For more information, see Internet and service
access for VPC-connected functions in the AWS Lambda Developer Guide.
• Create a connection between your Amazon Virtual Private Cloud (Amazon VPC) and Lambda using
a VPC endpoint. Your Amazon VPC must also connect to AWS Security Token Service (AWS STS)
and Secrets Manager endpoints. For more information, see Configuring interface VPC endpoints
for Lambda in the AWS Lambda Developer Guide.
3. Configure your broker as an event source for a Lambda function using the AWS Management
Console. You can also use the create-event-source-mapping AWS Command Line Interface
command.
4. Write some code for your Lambda function to process the messages consumed from your broker.
The Lambda payload that retrieved by your event source mapping depends on the engine type
of the broker. The following is an example of a Lambda payload for an Amazon MQ for ActiveMQ
queue.
Note
In the example, testQueue is the name of the queue.

{
"eventSource": "aws:amq",
"eventSourceArn": "arn:aws:mq:us-
west-2:112556298976:broker:test:b-9bcfa592-423a-4942-879d-eb284b418fc8",
"messages": {
[
{
"messageID": "ID:b-9bcfa592-423a-4942-879d-eb284b418fc8-1.mq.us-
west-2.amazonaws.com-37557-1234520418293-4:1:1:1:1",
"messageType": "jms/text-message",
"data": "QUJDOkFBQUE=",
"connectionId": "myJMSCoID",
"redelivered": false,
"destination": {
"physicalname": "testQueue"
},
"timestamp": 1598827811958,
"brokerInTime": 1598827811958,
"brokerOutTime": 1598827811959
},
{
"messageID": "ID:b-9bcfa592-423a-4942-879d-eb284b418fc8-1.mq.us-
west-2.amazonaws.com-37557-1234520418293-4:1:1:1:1",
"messageType":"jms/bytes-message",
"data": "3DTOOW7crj51prgVLQaGQ82S48k=",
"connectionId": "myJMSCoID1",
"persistent": false,
"destination": {
"physicalname": "testQueue"
},
"timestamp": 1598827811958,
"brokerInTime": 1598827811958,
"brokerOutTime": 1598827811959
}
]
}
}

For more information about connecting Amazon MQ to Lambda, the options Lambda supports for an
Amazon MQ event source, and event source mapping errors, see Using Lambda with Amazon MQ in the
AWS Lambda Developer Guide.

10
Amazon MQ Developer Guide
Step 4: delete your broker

Step 4: 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.

1. Sign in to the Amazon MQ 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:

• Creating and conﬁguring a broker (p. 84) (Additional Settings)

• Editing broker engine version, Amazon CloudWatch Logs, and maintenance preferences (p. 87)
• Creating and applying broker conﬁgurations (p. 92)
• Editing and Managing Broker Conﬁgurations (p. 94)
• Listing brokers and viewing broker details (p. 25)
• Creating and managing ActiveMQ broker users (p. 111)
• Rebooting a Broker (p. 29)
• Accessing CloudWatch metrics for Amazon MQ (p. 170)

You can also begin to dive deep into Best Practices for Amazon MQ and Amazon MQ REST APIs, and then
plan to migrate to Amazon MQ.

Creating and connecting to a RabbitMQ broker

Topics
• Step 1: create a RabbitMQ broker (p. 11)
• Step 2: connect a JVM-based application to your broker (p. 13)
• Step 3: (Optional) connect to an AWS Lambda function (p. 16)
• Step 4: delete your broker (p. 18)
• Next steps (p. 18)

Step 1: create a RabbitMQ broker

The ﬁrst 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.

11
Amazon MQ Developer Guide
Step 1: create a RabbitMQ broker

1. Sign in to the Amazon MQ console.

2. On the Select broker engine page, choose RabbitMQ, and then choose Next.
3. On the Select deployment mode page, choose the Deployment mode, for example, Cluster
deployment, and then choose Next.

• A single-instance broker is comprised of one broker in one Availability Zone behind a Network
Load Balancer (NLB). The broker communicates with your application and with an Amazon EBS
storage volume. For more information, see Single-instance broker (p. 128).
• A RabbitMQ cluster deployment for high availability is a logical grouping of three RabbitMQ
broker nodes behind a Network Load Balancer, each sharing users, queues, and a distributed state
across multiple Availability Zones (AZ). For more information, see Cluster deployment for high
availability (p. 129).
4. On the Conﬁgure settings page, in the Details section, the following:

a. Enter the Broker name.

Note
The Additional settings section provides options to enable CloudWatch logs and configure
network access for your broker. If you create a private RabbitMQ broker without public
accessibility, you must select a Virtual Private Cloud (VPC) and configure a security group to
access your broker.
5. On the Configure settings page, in the RabbitMQ access section, provide a Username and
Password. The following restrictions apply to broker usernames and passwords:

• Your username can contain only alphanumeric characters, dashes, periods, and underscores (- .
_). This value must not contain any tilde (~) characters. Amazon MQ prohibits using guest as a
username.
• Your password must be at least 12 characters long, contain at least 4 unique characters and must
not contain commas, colons, or equal signs (,:=).

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.

12
Amazon MQ Developer Guide
Step 2: connect a JVM-based application to your broker

9. Choose MyBroker.

On the MyBroker page, in the Connect section, note your broker's RabbitMQ web console URL, for
example:

https://b-c8349341-ec91-4a78-ad9c-a57f23f235bb.mq.us-west-2.amazonaws.com

Also, note your broker's secure-AMQP Endpoint. The following is an example of an amqps endpoint
exposing listener port 5671.

amqps://b-c8349341-ec91-4a78-ad9c-a57f23f235bb.mq.us-west-2.amazonaws.com:5671

Step 2: connect a JVM-based application to your

broker
After you create a RabbitMQ broker, you can connect your application to it. The following examples show
how you can use the RabbitMQ Java client library to create a connection to your broker, create a queue,
and send a message. You can connect to RabbitMQ brokers using supported RabbitMQ client libraries for
a variety of languages. For more information about supported RabbitMQ client libraries, see RabbitMQ
client libraries and developer tools.

Prerequisites
Note
The following prerequisite steps are only applicable to RabbitMQ brokers created without public
accessibility. If you are creating a broker with public accessibility you can skip them.

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

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.

13
Amazon MQ Developer Guide
Step 2: connect a JVM-based application to your broker

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 a broker web console).

a. Choose Add Rule.

b. For Type, select Custom TCP.
c. For Source, leave Custom selected and then type the IP address of the system that you want to
be able to access the web console (for example, 192.0.2.1).
d. Choose Save.

Your broker can now accept inbound connections.

Add Java dependencies

If you are using Apache Maven for automating builds, add the following dependency to your pom.xml
ﬁle. For more information about Project Object Model ﬁles in Apache Maven, see Introduction to the
POM.

<dependency>
<groupId>com.rabbitmq</groupId>
<artifactId>amqp-client</artifactId>
<version>5.9.0</version>
</dependency>

If you are using Gradle for automating builds, declare the following dependency.

dependencies {
compile 'com.rabbitmq:amqp-client:5.9.0'
}

Import Connection and Channel classes

RabbitMQ Java client uses com.rabbitmq.client as its top-level package, with Connection and
Channel API classes representing an AMQP 0-9-1 connection and channel, respectively. Import the
Connection and Channel classes before using them, as shown in the following example.

import com.rabbitmq.client.Connection;
import com.rabbitmq.client.Channel;

Create a ConnectionFactory and connect to your broker

Use the following example to create an instance of the ConnectionFactory class with the given
parameters. Use the setHost method to conﬁgure the broker endpoint you noted earlier. For AMQPS
wire-level connections, use port 5671.

ConnectionFactory factory = new ConnectionFactory();

factory.setUsername(username);
factory.setPassword(password);

//Replace the URL with your information

factory.setHost("b-c8352341-ec91-4a78-ad9c-a43f23d325bb.mq.us-west-2.amazonaws.com");
factory.setPort(5671);

// Allows client to establish a connection over TLS

factory.useSslProtocol()

14
Amazon MQ Developer Guide
Step 2: connect a JVM-based application to your broker

// Create a connection
Connection conn = factory.newConnection();

// Create a channel
Channel channel = conn.createChannel();

Publish a message to an exchange

You can use Channel.basicPublish to publish messages to an exchange. The following example uses
the AMQP Builder class to build a message properties object with content-type plain/text.

byte[] messageBodyBytes = "Hello, world!".getBytes();

channel.basicPublish(exchangeName, routingKey,
new AMQP.BasicProperties.Builder()
.contentType("text/plain")
.userId("userId")
.build(),
messageBodyBytes);

Note
Note that BasicProperties is an inner class of the autogenerated holder class, AMQP.

Subscribe to a queue and receive a message

You can receive a message by subscribing to a queue using the Consumer interface. Once subscribed,
messages will then be delivered automatically as they arrive.

The easiest way to implement a Consumer is to use the subclass DefaultConsumer. A

DefaultConsumer object can be passed as part of a basicConsume call to set up the subscription as
shown in the following example.

boolean autoAck = false;

channel.basicConsume(queueName, autoAck, "myConsumerTag",
new DefaultConsumer(channel) {
@Override
public void handleDelivery(String consumerTag,
Envelope envelope,
AMQP.BasicProperties properties,
byte[] body)
throws IOException
{
String routingKey = envelope.getRoutingKey();
String contentType = properties.getContentType();
long deliveryTag = envelope.getDeliveryTag();
// (process the message components here ...)
channel.basicAck(deliveryTag, false);
}
});

Note
Because we speciﬁed autoAck = false, it is necessary to acknowledge messages delivered
to the Consumer, most conveniently done in the handleDelivery method, as shown in the
example.

Close your connection and disconnect from the broker

In order to disconnect from your RabbitMQ broker, close both the channel and connection as shown in
the following.

15
Amazon MQ Developer Guide
Step 3: (Optional) connect to an AWS Lambda function

channel.close();
conn.close();

Note
For more information about working with the RabbitMQ Java client library, see the RabbitMQ
Java Client API Guide.

Step 3: (Optional) connect to an AWS Lambda

To connect your broker to a Lambda function

1. Add the following IAM role permissions to your Lambda function execution role.

• Configure one NAT gateway per public subnet. For more information, see Internet and service
access for VPC-connected functions in the AWS Lambda Developer Guide.
• Create a connection between your Amazon Virtual Private Cloud (Amazon VPC) and Lambda using
a VPC endpoint. Your Amazon VPC must also connect to AWS Security Token Service (AWS STS)
and Secrets Manager endpoints. For more information, see Configuring interface VPC endpoints
for Lambda in the AWS Lambda Developer Guide.
3. Configure your broker as an event source for a Lambda function using the AWS Management
Console. You can also use the create-event-source-mapping AWS Command Line Interface
command.
4. Write some code for your Lambda function to process the messages from your consumed from
your broker. The Lambda payload that retrieved by your event source mapping depends on the
engine type of the broker. The following is an example of a Lambda payload for an Amazon MQ for
RabbitMQ queue.
16
Amazon MQ Developer Guide
Step 3: (Optional) connect to an AWS Lambda function

Note
In the example, test is the name of the queue, and / is the name of the default virtual
host. When receiving messages, the event source lists messages under test::/.

{
"eventSource": "aws:rmq",
"eventSourceArn": "arn:aws:mq:us-
west-2:112556298976:broker:test:b-9bcfa592-423a-4942-879d-eb284b418fc8",
"rmqMessagesByQueue": {
"test::/": [
{
"basicProperties": {
"contentType": "text/plain",
"contentEncoding": null,
"headers": {
"header1": {
"bytes": [
118,
97,
108,
117,
101,
49
]
},
"header2": {
"bytes": [
118,
97,
108,
117,
101,
50
]
},
"numberInHeader": 10
}
"deliveryMode": 1,
"priority": 34,
"correlationId": null,
"replyTo": null,
"expiration": "60000",
"messageId": null,
"timestamp": "Jan 1, 1970, 12:33:41 AM",
"type": null,
"userId": "AIDACKCEVSQ6C2EXAMPLE",
"appId": null,
"clusterId": null,
"bodySize": 80
},
"redelivered": false,
"data": "eyJ0aW1lb3V0IjowLCJkYXRhIjoiQ1pybWYwR3c4T3Y0YnFMUXhENEUifQ=="
}
]
}
}

17
Amazon MQ Developer Guide
Step 4: delete your broker

Step 4: 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.

1. Sign in to the Amazon MQ 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:

• Editing broker engine version, Amazon CloudWatch Logs, and maintenance preferences (p. 87)
• Listing brokers and viewing broker details (p. 25)
• Creating and managing ActiveMQ broker users (p. 111)
• Rebooting a Broker (p. 29)
• Accessing CloudWatch metrics for Amazon MQ (p. 170)

You can also begin to dive deep into Best Practices for Amazon MQ and Amazon MQ REST APIs before
planning to migrate to Amazon MQ.

18
Amazon MQ Developer Guide
Maintaining a broker

Managing an Amazon MQ broker

In the following sections, you can ﬁnd instructions for managing and maintaining your Amazon MQ
brokers.

Topics
• Maintaining an Amazon MQ broker (p. 19)
• Upgrading an Amazon MQ broker engine version (p. 21)
• Broker statuses (p. 25)
• Listing Amazon MQ brokers and viewing broker details (p. 25)
• Accessing the broker web console without public accessibility (p. 28)
• Rebooting an Amazon MQ broker (p. 29)
• Deleting an Amazon MQ broker (p. 29)
• Instance types (p. 30)
• Tagging resources (p. 34)

Maintaining an Amazon MQ broker

Periodically, Amazon MQ performs maintenance to the hardware, operating system, or the engine
software a message broker. The duration of the maintenance varies, but can last up to two hours,
depending on the operations that are scheduled for your message broker. For example, if you've
activated automatic minor engine version upgrades (p. 24), or changed the broker instance type,
Amazon MQ will apply your changes during the next scheduled maintenance window.

To minimize downtime during a maintenance window, we recommend selecting a broker deployment

mode with high availability across multiple Availability Zones (AZ). Depending on your broker engine
type, Amazon MQ provides the following Multi-AZ deployment modes.

• Amazon MQ for ActiveMQ – Amazon MQ for ActiveMQ provides active/standby (p. 46)
deployments for high availability. In active/standby mode, Amazon MQ performs maintenance
operations one instance at a time, ensuring that at least one instance remains available. In addition,
you can conﬁgure a network of brokers (p. 46) with maintenance windows scattered across the
week.
• Amazon MQ for RabbitMQ – Amazon MQ for RabbitMQ provides the cluster (p. 129) deployments
for high availability. In cluster deployments, Amazon MQ performs maintenance operations, one node
at a time, keeping at least two running nodes at all times.

For more information about Amazon MQ recommended best practices to ensure your brokers perform
eﬀectively during, and after a maintenance window, see the following documentation for your broker
engine type.

• the section called “Amazon MQ for ActiveMQ best practices” (p. 113)
• the section called “Amazon MQ for RabbitMQ best practices” (p. 141)

You can schedule maintenance to occur once a week at a speciﬁed time which lasts up to two hours. This
sets the window for maintenance actions from Amazon MQ to be scheduled and started.

You can schedule the maintenance window when you ﬁrst create your broker, or by updating your broker
preferences. The following topic describes adjusting the broker maintenance window using the AWS
Management Console, AWS CLI, and the Amazon MQ API.

19
Amazon MQ Developer Guide
Adjusting the broker maintenance window

Topics
• Adjusting the broker maintenance window (p. 20)

Adjusting the broker maintenance window

To adjust the broker maintenance window, you can use the AWS Management Console, the AWS CLI, or
the Amazon MQ API.
Important
You can only adjust the maintenance window of a broker up to four times before the next
scheduled maintenance window. Amazon MQ applies a limit of four maintenance window
adjustments to ensure that critical software and security patches, as well as important hardware
upgrades, are not indeﬁnitely deferred and postponed.
Once a broker maintenance window is completed, Amazon MQ resets the limit, allowing you to
adjust the schedule before the next maintenance window occurs.

AWS Management Console

To adjust the broker maintenance window by using the AWS Management Console

1. Sign in to the Amazon MQ console.

2. In the left navigation pane, choose Brokers, and then choose the broker that you want to upgrade
from the list.
3. On the broker details page, choose Edit.
4. Under Maintenance, do the following.

a. For Start day, choose a day of the week, for example, Sunday, from the drop-down list.
b. For Start time, choose the hour and minute of the day that you want to schedule for the next
broker maintenance window, for example, 12:00.
Note
The Start time options are conﬁgured in UTC+0 time zone.
5. Scroll to the bottom of the page, and choose Save. The maintenance window is adjusted
immediately.
6. On the broker details page, under Maintenance window, verify that your new preferred schedule is
displayed.

AWS CLI
To adjust the broker maintenance window using the AWS CLI

1. Use the update-broker CLI command and specify the following parameters, as shown in the
example.

• --broker-id – The unique ID that Amazon MQ generates for the broker. You can parse
the ID from your broker ARN. For example, given the following ARN, arn:aws:mq:us-
east-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9,
the broker ID would be b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9.
• --maintenance-window-start-time – The parameters that determine the weekly
maintenance window start time provided in the following structure.
• DayOfWeek – The day of the week, in the following syntax: MONDAY| TUESDAY | WEDNESDAY
| THURSDAY | FRIDAY | SATURDAY | SUNDAY
• TimeOfDay – The time, in 24-hour format.

20
Amazon MQ Developer Guide
Upgrading the engine version

• TimeZone – (Optional) The time zone, in either the Country/City, or the UTC oﬀset format. Set
to UTC by default.

aws mq update-broker --broker-id broker-id \

--maintenance-window-start-time DayOfWeek=SUNDAY,TimeOfDay=13:00,TimeZone=America/
Los_Angeles

2. (Optional) Use the describe-broker CLI command to verify that the maintenance window is
successfully updated.

aws mq describe-broker --broker-id broker-id

Amazon MQ API
To adjust the broker maintenance window using the Amazon MQ API

1. Use the UpdateBroker API operation. Specify broker-id as a path parameter. The following
examples assumes a broker in the us-west-2 region. For more information about available Amazon
MQ endpoints, see Amazon MQ endpoints and quotas. in the AWS General Reference

PUT /v1/brokers/broker-id HTTP/1.1

Host: mq.us-west-2.amazonaws.com
Date: Wed, 7 July 2021 12:00:00 GMT
x-amz-date: Wed, 7 July 2021 12:00:00 GMT
Authorization: authorization-string

Use the maintenanceWindowStartTime parameter and the WeeklyStartTime resource type in

the request payload.

{
"maintenanceWindowStartTime": {
"dayOfWeek": "SUNDAY",
"timeZone": "America/Los_Angeles",
"timeOfDay": "13:00"
}
}

2. (Optional) Use the DescribeBroker API operation to verify that the maintenance window has been
successfully updated. broker-id is speciﬁed as a path parameter.

GET /v1/brokers/broker-id HTTP/1.1

Host: mq.us-west-2.amazonaws.com
Date: Wed, 7 July 2021 12:00:00 GMT
x-amz-date: Wed, 7 July 2021 12:00:00 GMT
Authorization: authorization-string

Upgrading an Amazon MQ broker engine version

Amazon MQ provides new broker engine versions for all supported broker engine type. New engine
versions might include security patches, bug ﬁxes and other broker engine improvements. When Amazon
MQ supports a new engine version, you can control how and when to upgrade your broker.

Broker engine versions are organized as X.Y.Z. In the Amazon MQ implementation of each engine type,
X.Y is considered a major version and Z is considered a minor version. There are two types of upgrades:

21
Amazon MQ Developer Guide
Manually upgrading the engine version

• Major version upgrade – Occurs when the major engine version numbers change. For example,
upgrading from version 1.0 to version 1.1 is considered a major version upgrade.
• Minor version upgrade – Occurs when only the minor engine version number changes. For example,
upgrading from version 1.1.0 to version 1.1.1 is considered a minor version upgrade.

For more information about major and minor version management for each speciﬁc broker engine type,
see the following topics.

• the section called “Version management” (p. 75)

• the section called “Version management” (p. 130)

When you activate the automatic minor version upgrade option, Amazon MQ upgrades your broker to
new minor versions as they become available. Automatic minor version upgrades occur only if the broker
is running a minor engine version that is lower than the new recommended minor version. For major
upgrades, you must manually upgrade the engine version.

Both manual and automatic version upgrades occur during the scheduled maintenance window or after
you reboot your broker (p. 29).

The following topics describe how you can manually upgrade the broker engine version, and activate
automatic minor version upgrades.

Topics
• Manually upgrading the engine version (p. 22)
• Automatically upgrading the minor engine version (p. 24)

Manually upgrading the engine version

To manually upgrade the engine version of a broker to a new major or minor version, you can use the
AWS Management Console, the AWS CLI, or the Amazon MQ API.

AWS Management Console

To upgrade the engine version of a broker by using the AWS Management Console

1. Sign in to the Amazon MQ console.

2. In the left navigation pane, choose Brokers, and then choose the broker that you want to upgrade
from the list.
3. On the broker details page, choose Edit.
4. Under Specifications, for Broker engine version choose the new version number from the
dropdown list.
5. Scroll to the bottom of the page, and choose Schedule modifications.
6. On the Schedule broker modifications page, for When to apply modifications, choose one of the
following.

• Choose After the next reboot, if you want Amazon MQ to complete the version upgrade during
the next scheduled maintenance window.
• Choose Immediately, if you want to reboot the broker and upgrade the engine version
immediately.
Important
Your broker will be oﬄine while it is being rebooted.

22
Amazon MQ Developer Guide
Manually upgrading the engine version

7. Choose Apply to ﬁnish applying the changes.

AWS CLI
To upgrade the engine version of a broker by using the AWS CLI

1. Use the update-broker CLI command and specify the following parameters, as shown in the
example.

aws mq update-broker --broker-id broker-id --engine-version version-number

2. (Optional) Use the reboot-broker CLI command to reboot your broker if, you want to upgrade the
engine version immediately.

aws mq reboot-broker --broker-id broker-id

If you do not want to reboot your broker and apply the changes immediately, Amazon MQ will
upgrade the broker during the next scheduled maintenance window.
Important
Your broker will be oﬄine while it is being rebooted.

Amazon MQ API
To upgrade the engine version of a broker by using the Amazon MQ API

PUT /v1/brokers/broker-id HTTP/1.1

Host: mq.us-west-2.amazonaws.com
Date: Mon, 7 June 2021 12:00:00 GMT
x-amz-date: Mon, 7 June 2021 12:00:00 GMT
Authorization: authorization-string

Use engineVersion in the request payload to specify the version number for the broker to
upgrade to.

{
"engineVersion": "engine-version-number"
}

2. (Optional) Use the RebootBroker API operation to reboot your broker, if you want to upgrade the
engine version immediately. broker-id is speciﬁed as a path parameter.

POST /v1/brokers/broker-id/reboot-broker HTTP/1.1

Host: mq.us-west-2.amazonaws.com
Date: Mon, 7 June 2021 12:00:00 GMT

23
Amazon MQ Developer Guide
Automatically upgrading the minor engine version

x-amz-date: Mon, 7 June 2021 12:00:00 GMT

Authorization: authorization-string

Automatically upgrading the minor engine version

You can control whether automatic minor version upgrade is activated for a broker when you ﬁrst create
the broker, or by modifying broker preferences. To activate auto minor version upgrades for an existing
broker, you can use the AWS Management Console, the AWS CLI, or the Amazon MQ API.

AWS Management Console

To activate automatic minor version upgrades by using the AWS Management Console

1. Sign in to the Amazon MQ console.

2. In the left navigation pane, choose Brokers, and then choose the broker that you want to upgrade
from the list.
3. On the broker details page, choose Edit.
4. Under Maintenance, choose Enable automatic minor version upgrades.
Note
If the option is already selected, you do not need to make any changes.
5. Choose Save at the bottom of the page.

AWS CLI
To activate automatic minor version upgrades via the AWS CLI, use the update-broker CLI command and
specify the following parameters.

aws mq update-broker --broker-id broker-id --auto-minor-version-upgrade

If you want to deactivate auto minor version upgrades for your broker, use the --no-auto-minor-
version-upgrade parameter.

Amazon MQ API
To activate automatic minor version upgrades via the Amazon MQ API, use the UpdateBroker API
operation. Specify broker-id as a path parameter. The following example assumes a broker in the us-
west-2 region. For more information about available Amazon MQ endpoints, see Amazon MQ endpoints
and quotas. in the AWS General Reference

PUT /v1/brokers/broker-id HTTP/1.1

24
Amazon MQ Developer Guide
Broker statuses

Host: mq.us-west-2.amazonaws.com
Date: Mon, 7 June 2021 12:00:00 GMT
x-amz-date: Mon, 7 June 2021 12:00:00 GMT
Authorization: authorization-string

Use the autoMinorVersionUpgrade property in the request payload to activate auto minor version
upgrade.

{
"autoMinorVersionUpgrade": "true"
}

If you want to deactivate auto minor version upgrades for your broker, set
"autoMinorVersionUpgrade": "false" in the request payload.

Broker 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.

Critical action required CRITICAL_ACTION_REQUIRED The broker is running, but is in

a degraded state and requires
immediate action. You can
ﬁnd instructions to resolve the
issue by chosing the action
required code from the list in the
section called “Troubleshooting:
Amazon MQ action required
codes” (p. 201).

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 conﬁrm your broker's existence by listing your brokers in the
current region using the AWS Management Console.

25
Amazon MQ Developer Guide
To list brokers and view broker details

To list brokers and view broker details

1. Sign in to the Amazon MQ console.

Your brokers in the current region are listed.

The following information is displayed for each broker:

• Name
• Creation date
• Status (p. 25)
• Deployment mode
• Instance type (p. 30)
2. Choose your broker's name .

For ActiveMQ brokers, on the MyBroker page, the conﬁgured (p. 42) Details are displayed for
your broker:

For Amazon MQ for RabbitMQ brokers, you can view your selected settings on the MyBroker2 page,
under the Detailssection as shown in the following.

26
Amazon MQ Developer Guide
To list brokers and view broker details

Under the Details section, the following information is displayed:

• In the Connections section, for Amazon MQ for ActiveMQ brokers, the web console URL and the
wire-level protocol endpoints.

In the Connections section, for Amazon MQ for RabbitMQ brokers, the web console URL and the
secure AMQP endpoint.

• For Amazon MQ for ActiveMQ brokers, in the Users section, the users (p. 43) associated with
the broker

27
Amazon MQ Developer Guide
Accessing the broker web console
without public accessibility

Important
Managing users via the AWS Management Console and the Amazon MQ API is not
supported for Amazon MQ for RabbitMQ brokers.

Accessing the broker web console 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 web console.
Note
The names of the VPCs and security groups are speciﬁc to the following example.

Prerequisites
To perform the following steps, you must conﬁgure 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 conﬁgured 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 a broker's 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 conﬁgured correctly, establish an ssh connection to the EC2 instance and
use the curl command with the URI of your broker.
3. From your machine, create an ssh tunnel to the EC2 instance using the path to your private key ﬁle
and the IP address of your public EC2 instance. For example:

ssh -i ~/.ssh/id_rsa -N -C -q -f -D 8080 [email protected]

A forward proxy server is started on your machine.

4. Install a proxy client such as FoxyProxy on your machine.
5. Conﬁgure your proxy client using the following settings:

28
Amazon MQ Developer Guide
Rebooting a broker

• 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 web console on your machine.

Rebooting an Amazon MQ broker

To apply a new conﬁguration 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

1. Sign in to the Amazon MQ console.
2. From the broker list, choose the name of your broker (for example, MyBroker).
3. On the MyBroker page, choose Actions, Reboot broker.
Important
Your broker will be oﬄine while it is being rebooted.

4. In the Reboot broker dialog box, choose Reboot.

Rebooting the broker takes about 5 minutes.

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.

29
Amazon MQ Developer Guide
Deleting an Amazon MQ broker

Deleting an Amazon MQ broker

1. Sign in to the Amazon MQ 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.

Instance types
The combined description of the broker instance class (m5, t3) 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 for each supported engine type.

Topics
• Amazon MQ for ActiveMQ instance types (p. 30)
• Amazon MQ for RabbitMQ instance types (p. 33)

Amazon MQ for ActiveMQ instance types

Important
You can use Amazon EBS only with the mq.m5 broker instance type family. For more
information, see Storage (p. 43).

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)
qualiﬁes 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

30
Amazon MQ Developer Guide
Amazon MQ for ActiveMQ instance types

mq.t3.micro 2 1 Low Use the

mq.t3.micro
instance type for
basic evaluation
of Amazon MQ.
This instance type
(single-instance
brokers only)
qualiﬁes for the
AWS Free Tier.

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.

mq.m5.large 2 8 High Use the

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

31
Amazon MQ Developer Guide
Amazon MQ for ActiveMQ instance types

Instance Type vCPU Memory (GiB) Network Notes

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

32
Amazon MQ Developer Guide
Amazon MQ for RabbitMQ instance types

For more information about throughput considerations, see Choose the Correct Broker Instance Type for
the Best Throughput (p. 116).

Amazon MQ for RabbitMQ instance types

Instance Type vCPU Memory (GiB) Network Notes
Performance

mq.t3.micro 2 1 Low Use the

mq.t3.micro
instance type for
basic evaluation
of Amazon MQ.
This instance type
(single-instance
brokers only)
qualiﬁes for the
AWS Free Tier.
Important
The
mq.t3.micro
instance
type
does not
support
cluster
deployment (p. 129).

mq.m5.large 2 8 High Use the

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

mq.m5.xlarge 4 16 High Use the

mq.m5.xlarge,
mq.m5.2xlarge 8 32 High mq.m5.2xlarge,
and

33
Amazon MQ Developer Guide
Tagging resources

Instance Type vCPU Memory (GiB) Network Notes

Performance

mq.m5.4xlarge 16 64 High mq.m5.4xlarge

instance types
for regular
development,
testing and
production
workloads that
require high
throughput.

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. 34)
• Managing Tags in the Amazon MQ Console (p. 35)
• Managing Using Amazon MQ API Actions (p. 36)

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 conﬁguration. This is especially useful when you have many
brokers. You can use cost allocation tags to organize your AWS bill to reﬂect 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 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 brokers performing related tasks in the same cost center,
while tagging an unrelated broker with a diﬀerent cost allocation tag.

34
Amazon MQ Developer Guide
Managing Tags in the Amazon MQ Console

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:

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 conﬁguration:

1. From the Create conﬁguration 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 Conﬁgurations 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.

35
Amazon MQ Developer Guide
Managing Using Amazon MQ API Actions

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.

36
Amazon MQ Developer Guide
ActiveMQ engine

Working with Amazon MQ for

ActiveMQ
Amazon MQ makes it easy to create a message broker with the computing and storage resources that ﬁt
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 for ActiveMQ and RabbitMQ engine types,
lists available Amazon MQ broker instance types and their statuses, and provides an overview of broker
architecture and conﬁguration options.

To learn about Amazon MQ REST APIs, see the Amazon MQ REST API Reference.

Topics
• ActiveMQ engine (p. 37)
• ActiveMQ tutorials (p. 84)
• Amazon MQ for ActiveMQ best practices (p. 113)

ActiveMQ engine
This section describes the basic elements of an ActiveMQ broker, provides an overview of ActiveMQ
broker architecture options, explains broker conﬁguration parameters, and oﬀers a working example
using Java Message Service (JMS).

Topics
• Basic elements (p. 37)
• Broker architecture (p. 44)
• Amazon MQ for ActiveMQ broker conﬁguration parameters (p. 57)
• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working examples of using Java Message Service (JMS) with ActiveMQ (p. 76)

Basic elements
This section introduces key concepts essential to understanding ActiveMQ on Amazon MQ.

Topics
• Broker (p. 37)
• Broker instance types (p. 30)
• Conﬁguration (p. 42)
• User (p. 43)
• Storage (p. 43)

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, t3) and size (large, micro)

37
Amazon MQ Developer Guide
Basic Elements

is a broker instance type (for example, mq.m5.large). For more information, see Broker instance
types (p. 30).

• A single-instance broker is comprised of one broker in one Availability Zone. The broker communicates
with your application and with an Amazon EBS or Amazon EFS storage volume.
• An active/standby broker is comprised of two brokers in two diﬀerent Availability Zones, conﬁgured in
a redundant pair. These brokers communicate synchronously with your application, and with Amazon
EFS.

For more information, see Broker Architecture (p. 44).

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 deﬁned 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 conﬁguring a broker (p. 84)

• Brokers (p. 190)
• Broker statuses (p. 25)

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
An ActiveMQ 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

38
Amazon MQ Developer Guide
Basic Elements

• mqtt+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:8883
• ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617
Note
This is an OpenWire endpoint.
• stomp+ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61614
• wss://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61619

For more information, see Conﬁguring Transports in the Apache ActiveMQ documentation.

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

Broker instance types

Important
You can use Amazon EBS only with the mq.m5 broker instance type family. For more
information, see Storage (p. 43).

Instance Type vCPU Memory (GiB) Network Notes

Performance

mq.t2.micro 1 1 Low Use the

39
Amazon MQ Developer Guide
Basic Elements

mq.t3.micro 2 1 Low Use the

mq.t3.micro
instance type for
basic evaluation
of Amazon MQ.
This instance type
(single-instance
brokers only)
qualiﬁes for the
AWS Free Tier.

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.

mq.m5.large 2 8 High Use the

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

40
Amazon MQ Developer Guide
Basic Elements

Instance Type vCPU Memory (GiB) Network Notes

Performance

mq.m5.xlarge 4 16 High Use the

41
Amazon MQ Developer Guide
Basic Elements

For more information about throughput considerations, see Choose the Correct Broker Instance Type for
the Best Throughput (p. 116).

Configuration
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.
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. 96) or reboot the
broker (p. 29). For more information, see Amazon MQ Broker Configuration Lifecycle (p. 56).
Currently, you can't delete a configuration.

For information about creating, editing, and managing conﬁgurations, see the following:

• Creating and applying broker conﬁgurations (p. 92)

• Editing and Managing Broker Configurations (p. 94)
• Configurations (p. 190)
• Amazon MQ Broker Configuration Parameters (p. 57)

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. 92) and Editing and Managing
Broker Configurations (p. 94).

Attributes
A broker conﬁguration 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 conﬁguration attributes, see the following in the Amazon MQ REST API Reference:

• REST Operation ID: Conﬁguration

• REST Operation ID: Conﬁgurations

42
Amazon MQ Developer Guide
Basic Elements

For a full list of conﬁguration revision attributes, see the following:

• REST Operation ID: Conﬁguration Revision

• REST Operation ID: Conﬁguration Revisions

User
An ActiveMQ user is a person or an application that can access the queues and topics of an ActiveMQ
broker. You can conﬁgure users to have speciﬁc 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. 96) or reboot the broker (p. 29).
For more information, see Amazon MQ Broker Configuration Lifecycle (p. 56).

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:

• Creating and managing ActiveMQ broker users (p. 111)

• Users (p. 191)

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

Storage
Amazon MQ for ActiveMQ supports Amazon Elastic File System (EFS) and Amazon Elastic Block Store
(EBS). By default, ActiveMQ brokers use Amazon EFS for broker storage. To take advantage of high
durability and replication across multiple Availability Zones, use Amazon EFS. To take advantage of low
latency and high throughput, use Amazon EBS.
Important

• You can use Amazon EBS only with the mq.m5 broker instance type family.
• Although you can change the broker instance type, you can't change the broker storage type
after you create the broker.
• Amazon EBS replicates data within a single Availability Zone and doesn't support the
ActiveMQ active/standby (p. 46) deployment mode.

43
Amazon MQ Developer Guide
Broker architecture

Diﬀerences between Storage Types

The following table provides a brief overview of the diﬀerences between in-memory, Amazon EFS, and
Amazon EBS storage types for ActiveMQ brokers.

Storage Type Persistence Example Use Case Approximate Replication

Maximum
Number of
Messages
Enqueued per
Producer, per
Second (1KB
Message)

In-memory Non-persistent • Stock quotes 5,000 None

• Location data
updates
• Frequently
changed data

Amazon EBS Persistent • High volumes of 500 Multiple copies

text within a single
• Order Availability Zone
processing (AZ)

Amazon EFS Persistent Financial 80 Multiple copies

transactions across multiple
AZs

In-memory message storage provides the lowest latency and the highest throughput. However,
messages are lost during instance replacement or broker restart.

Amazon EFS is designed to be highly durable, replicated across multiple AZs to prevent the loss of data
resulting from the failure of any single component or an issue that aﬀects the availability of an AZ.
Amazon EBS is optimized for throughput and replicated across multiple servers within a single AZ.

Broker architecture
Amazon MQ for ActiveMQ 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.
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
• MQTT over WebSocket
• OpenWire
• STOMP

44
Amazon MQ Developer Guide
Broker architecture

• STOMP over WebSocket

Topics
• Amazon MQ single-instance broker (p. 45)
• Amazon MQ active/standby broker for high availability (p. 46)
• Amazon MQ Network of brokers (p. 46)
• Amazon MQ broker conﬁguration lifecycle (p. 56)

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 Amazon EBS or Amazon EFS storage volume. Amazon EFS storage
volumes are designed to provide the highest level of durability and availability by storing data
redundantly across multiple Availability Zones (AZs). Amazon EBS provides block level storage
optimized for low-latency and high throughput. For more information about storage options, see
Storage (p. 43).

The following diagram illustrates a single-instance broker with Amazon EFS storage replicated across
multiple AZs.

The following diagram illustrates a single-instance broker with Amazon EBS storage replicated across
multiple servers within a single AZ.

45
Amazon MQ Developer Guide
Broker architecture

Amazon MQ active/standby broker for high availability

An active/standby broker is comprised of two brokers in two diﬀerent Availability Zones, conﬁgured in
a redundant pair. These brokers communicate synchronously with your application, and with Amazon
EFS. Amazon EFS storage volumes are designed to provide the highest level of durability, and availability
by storing data redundantly across multiple Availability Zones (AZs). For more information, see
Storage (p. 43).

Usually, 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. This allows 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 suﬃxes 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 with Amazon EFS storage replicated across
multiple AZs.

Amazon MQ Network of brokers

Amazon MQ supports ActiveMQ's network of brokers feature.

46
Amazon MQ Developer Guide
Broker architecture

A network of brokers is comprised of multiple simultaneously active single-instance brokers (p. 45)
or active/standby brokers (p. 46). You can conﬁgure networks of brokers in a variety of
topologies (p. 49) (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. 51)
network of brokers can increase resiliency, preserving messages if one broker is not reachable. A network
of brokers with a concentrator (p. 52) 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 conﬁguration information, see the following:

• Creating and Conﬁguring a Network of Brokers (p. 88)

• Conﬁgure Your Network of Brokers Correctly (p. 117)
• networkConnector (p. 71)
• networkConnectionStartAsync (p. 67)
• Networks of Brokers in the ActiveMQ documentation

The following are beneﬁts 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. 46).

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. 49)
• Cross region (p. 53)
• Dynamic Failover With Transport Connectors (p. 55)

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 conﬁguration 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 conﬁgurations.

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. 42). For instance, here is an example networkConnector entry in a broker
configuration:

47
Amazon MQ Developer Guide
Broker architecture

A network of brokers ensures that messages ﬂow from one broker instance to another, forwarding
messages only to the broker instances that have corresponding consumers. For the beneﬁt 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.

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. 90).

Brokers must be in the same VPC or in peered VPCs. For more information, see Prerequisites (p. 89) in
the Creating and Conﬁguring a Network of Brokers (p. 88) 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

48
Amazon MQ Developer Guide
Broker architecture

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 conﬁgurations in the Amazon MQ console.

By creating brokers and conﬁguring diﬀerent 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-
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. 25).

49
Amazon MQ Developer Guide
Broker architecture

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 conﬁgure 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 conﬁgured.

You can conﬁgure 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:

Network connectors for Broker2:

50
Amazon MQ Developer Guide
Broker architecture

</networkConnectors>

By adding the above connectors to the conﬁgurations 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 Conﬁguration Parameters (p. 57).

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 conﬁgure 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 conﬁguration of Broker1.

51
Amazon MQ Developer Guide
Broker architecture

<networkConnector name="connector_hub_and_spoke_2" userName="myCommonUser"

duplex="true"
uri="static:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617)"/>
<networkConnector name="connector_hub_and_spoke_3" userName="myCommonUser"
duplex="true"
uri="static:(ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-2.mq.us-
east-2.amazonaws.com:61617)"/>
<networkConnector name="connector_hub_and_spoke_4" userName="myCommonUser"
duplex="true"
uri="static:(ssl://b-743c885d-2244-4c95-af67-a85017ff234e-3.mq.us-
east-2.amazonaws.com:61617)"/>
<networkConnector name="connector_hub_and_spoke_5" userName="myCommonUser"
duplex="true"
uri="static:(ssl://b-62a7fb31-d51c-466a-a873-905cd660b553-4.mq.us-
east-2.amazonaws.com:61617)"/>
</networkConnectors>

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 conﬁgure this topology, each of the brokers on the bottom would contain a network connector to
each of the brokers they are concentrating messages to.

Network connectors for Broker3:

52
Amazon MQ Developer Guide
Broker architecture

<networkConnector name="3_to_1" userName="myCommonUser" duplex="false"

uri="static:(ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61617)"/>
<networkConnector name="3_to_2" userName="myCommonUser" duplex="false"
uri="static:(ssl://b-9876l5k4-32ji-109h-8gfe-7d65c4b132a1-2.mq.us-
east-2.amazonaws.com:61617)"/>
</networkConnectors>

Network connectors for Broker4:

Network connectors for Broker5:

Cross region
To conﬁgure a network of brokers that spans AWS regions, deploy brokers in those regions, and
conﬁgure network connectors to the endpoints of those brokers.

53
Amazon MQ Developer Guide
Broker architecture

To conﬁgure a network of brokers like this example, you could add networkConnectors entries to the
conﬁgurations of Broker1 and Broker4 that reference the wire-level endpoints of those brokers.

Network connectors for Broker1:

54
Amazon MQ Developer Guide
Broker architecture

<networkConnector name="1_to_4" userName="myCommonUser" duplex="true"

uri="static:(ssl://b-62a7fb31-d51c-466a-a873-905cd660b553-4.mq.us-
east-2.amazonaws.com:61617)"/>
</networkConnectors>

Network connector for Broker2:

Network connectors for Broker4:

Dynamic Failover With Transport Connectors

In addition to conﬁguring networkConnector elements, you can conﬁgure your broker
transportConnector options to enable dynamic failover, and to rebalance connections when brokers
are added or removed from the network.

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 conﬁgured 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 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.

For more information on failover, see Broker-side Options for Failover in the Active MQ documentation.

55
Amazon MQ Developer Guide
Broker architecture

Amazon MQ broker conﬁguration lifecycle

Making changes to a conﬁguration revision or an ActiveMQ user does not apply the changes immediately.
To apply your changes, you must wait for the next maintenance window (p. 96) or reboot the
broker (p. 29). For more information, see Amazon MQ Broker Conﬁguration Lifecycle (p. 56).

The following diagram illustrates the conﬁguration 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 conﬁgurations, see the following:

• Creating and applying broker conﬁgurations (p. 92)

• Editing and Managing Broker Conﬁgurations (p. 94)
• Amazon MQ Broker Conﬁguration Parameters (p. 57)

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

• Creating and managing ActiveMQ broker users (p. 111)

56
Amazon MQ Developer Guide
Broker conﬁguration parameters

• Users (p. 191)

Amazon MQ for ActiveMQ broker conﬁguration

parameters
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. For more information, see the following:

• Conﬁguration (p. 42)

• Creating and applying broker configurations (p. 92)
• Editing and Managing Broker Configurations (p. 94)
• Configurations (p. 190)

Working with Spring XML conﬁguration ﬁles

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. Download
zip files of the supported schemas using the following links.

• amazon-mq-active-mq-5.17.1.xsd.zip
• amazon-mq-active-mq-5.16.5.xsd.zip
• amazon-mq-active-mq-5.16.4.xsd.zip
• amazon-mq-active-mq-5.16.3.xsd.zip
• amazon-mq-active-mq-5.16.2.xsd.zip
• amazon-mq-active-mq-5.15.15.xsd.zip
• amazon-mq-active-mq-5.15.14.xsd.zip
• amazon-mq-active-mq-5.15.13.xsd.zip
• amazon-mq-active-mq-5.15.12.xsd.zip
• amazon-mq-active-mq-5.15.10.xsd.zip
• amazon-mq-active-mq-5.15.9.xsd.zip
• amazon-mq-active-mq-5.15.8.xsd.zip
• amazon-mq-active-mq-5.15.6.xsd.zip
• amazon-mq-active-mq-5.15.0.xsd.zip

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 Conﬁgurations (p. 58)
• Elements and Their Attributes Permitted in Amazon MQ Conﬁgurations (p. 60)

57
Amazon MQ Developer Guide
Broker conﬁguration parameters

• Elements, Child Collection Elements, and Their Child Elements Permitted in Amazon MQ
Conﬁgurations (p. 68)

Elements Permitted in Amazon MQ Conﬁgurations

The following is a detailed listing of the elements permitted in Amazon MQ conﬁgurations. For more
information, see XML Conﬁguration in the Apache ActiveMQ documentation.

Element

abortSlowAckConsumerStrategy (attributes) (p. 60)

abortSlowConsumerStrategy (attributes) (p. 60)

authorizationEntry (attributes) (p. 60)

authorizationMap (child collection elements) (p. 68)

authorizationPlugin (child collection elements) (p. 68)

broker (attributes (p. 60) | child collection elements) (p. 68)

cachedMessageGroupMapFactory (attributes) (p. 61)

compositeQueue (attributes (p. 61) | child collection elements) (p. 69)

compositeTopic (attributes (p. 62) | child collection elements) (p. 69)

constantPendingMessageLimitStrategy (attributes) (p. 62)

discarding (attributes) (p. 62)

discardingDLQBrokerPlugin (attributes) (p. 62)

fileCursor

fileDurableSubscriberCursor

fileQueueCursor

filteredDestination (attributes) (p. 62)

fixedCountSubscriptionRecoveryPolicy (attributes) (p. 62)

fixedSizedSubscriptionRecoveryPolicy (attributes) (p. 63)

forcePersistencyModeBrokerPlugin (attributes) (p. 63)

individualDeadLetterStrategy (attributes) (p. 63)

lastImageSubscriptionRecoveryPolicy

messageGroupHashBucketFactory (attributes) (p. 63)

mirroredQueue (attributes) (p. 63)

noSubscriptionRecoveryPolicy

oldestMessageEvictionStrategy (attributes) (p. 63)

oldestMessageWithLowestPriorityEvictionStrategy (attributes) (p. 63)

58
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element

policyEntry (attributes (p. 63) | child collection elements) (p. 69)

policyMap (child collection elements) (p. 70)

prefetchRatePendingMessageLimitStrategy (attributes) (p. 65)

priorityDispatchPolicy

priorityNetworkDispatchPolicy

queryBasedSubscriptionRecoveryPolicy (attributes) (p. 65)

queue (attributes) (p. 65)

redeliveryPlugin (attributes (p. 65) | child collection elements) (p. 70)

redeliveryPolicy (attributes) (p. 65)

redeliveryPolicyMap (child collection elements) (p. 70)

retainedMessageSubscriptionRecoveryPolicy (child collection elements) (p. 70)

roundRobinDispatchPolicy

sharedDeadLetterStrategy (attributes (p. 66) | child collection elements) (p. 70)

simpleDispatchPolicy

simpleMessageGroupMapFactory

statisticsBrokerPlugin

storeCursor

storeDurableSubscriberCursor (attributes) (p. 66)

strictOrderDispatchPolicy

tempDestinationAuthorizationEntry (attributes) (p. 66)

tempQueue (attributes) (p. 66)

tempTopic (attributes) (p. 66)

timedSubscriptionRecoveryPolicy (attributes) (p. 66)

timeStampingBrokerPlugin (attributes) (p. 66)

topic (attributes) (p. 66)

transportConnector (attributes) (p. 67)

uniquePropertyMessageEvictionStrategy (attributes) (p. 67)

virtualDestinationInterceptor (child collection elements) (p. 71)

virtualTopic (attributes) (p. 67)

vmCursor

vmDurableCursor

59
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element

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

maxSlowDuration

maxTimeSinceLastAck

name

abortSlowConsumerStrategy abortConnection

checkPeriod

ignoreNetworkConsumers

maxSlowCount

maxSlowDuration

name

authorizationEntry admin

queue

read

tempQueue

tempTopic

topic

write

broker advisorySupport

allowTempAutoCreationOnSend

cacheTempDestinations

60
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Attribute

consumerSystemUsagePortion

dedicatedTaskRunner

deleteAllMessagesOnStartup

keepDurableSubsActive

enableMessageExpirationOnActiveDurableSubs

maxPurgedDestinationsPerSweep

maxSchedulerRepeatAllowed

monitorConnectionSplits

networkConnectorStartAsync (p. 67)

offlineDurableSubscriberTaskSchedule

offlineDurableSubscriberTimeout

persistenceThreadPriority

persistent

populateJMSXUserID

producerSystemUsagePortion

rejectDurableConsumers

rollbackOnlyOnAsyncException

schedulePeriodForDestinationPurge

schedulerSupport

splitSystemUsageForProducersConsumers

taskRunnerPriority

timeBeforePurgeTempDestinations

useAuthenticatedPrincipalForJMSXUserID

useMirroredQueues

useTempMirroredQueues

useVirtualDestSubs

useVirtualDestSubsOnCreation

useVirtualTopics

cachedMessageGroupMapFactory cacheSize

compositeQueue concurrentSend

copyMessage

61
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Attribute

forwardOnly

name

sendWhenNotMatched

compositeTopic concurrentSend

copyMessage

forwardOnly

name

sendWhenNotMatched

conditionalNetworkBridgeFilterFactory rateDuration

rateLimit

replayDelay

replayWhenNoConsumers

selectorAware
Supported in
Apache ActiveMQ 5.16.x

constantPendingMessageLimitStrategy limit

discarding deadLetterQueue

enableAudit

expiration

maxAuditDepth

maxProducersToAudit

processExpired

processNonPersistent

discardingDLQBrokerPlugin dropAll

dropOnly

dropTemporaryQueues

dropTemporaryTopics

reportInterval

filteredDestination queue

selector

topic

fixedCountSubscriptionRecoveryPolicy maximumSize

62
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Attribute

fixedSizedSubscriptionRecoveryPolicy maximumSize

useSharedBuffer

forcePersistencyModeBrokerPlugin persistenceFlag

individualDeadLetterStrategy destinationPerDurableSubscriber

enableAudit

expiration

maxAuditDepth

maxProducersToAudit

processExpired

processNonPersistent

queuePrefix

queueSuffix

topicPrefix

topicSuffix

useQueueForQueueMessages

useQueueForTopicMessages

messageGroupHashBucketFactory bucketCount

cacheSize

mirroredQueue copyMessage

postfix

prefix

oldestMessageEvictionStrategy evictExpiredMessagesHighWatermark

oldestMessageWithLowestPriorityEvictionStrategy
evictExpiredMessagesHighWatermark

policyEntry advisoryForConsumed

advisoryForDelivery

advisoryForDiscardingMessages

advisoryForFastProducers

advisoryForSlowConsumers

advisoryWhenFull

allConsumersExclusiveByDefault

alwaysRetroactive

63
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Attribute

blockedProducerWarningInterval

consumersBeforeDispatchStarts

cursorMemoryHighWaterMark

doOptimzeMessageStorage

durableTopicPrefetch

enableAudit

expireMessagesPeriod

gcInactiveDestinations

gcWithNetworkConsumers

inactiveTimeoutBeforeGC

inactiveTimoutBeforeGC

includeBodyForAdvisory

lazyDispatch

maxAuditDepth

maxBrowsePageSize

maxDestinations

maxExpirePageSize

maxPageSize

maxProducersToAudit

maxQueueAuditDepth

memoryLimit

messageGroupMapFactoryType

minimumMessageSize

optimizedDispatch

optimizeMessageStoreInFlightLimit

persistJMSRedelivered

prioritizedMessages

producerFlowControl

queue

queueBrowserPrefetch

queuePrefetch

64
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Attribute

reduceMemoryFootprint

sendAdvisoryIfNoConsumers

sendFailIfNoSpace

sendFailIfNoSpaceAfterTimeout
Supported in
Apache ActiveMQ 5.16.4 and above

sendDuplicateFromStoreToDLQ

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

maximumRedeliveryDelay

preDispatchCheck

queue

redeliveryDelay

tempQueue

65
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Attribute

tempTopic

topic

useCollisionAvoidance

useExponentialBackOff

sharedDeadLetterStrategy enableAudit

expiration

maxAuditDepth

maxProducersToAudit

processExpired

processNonPersistent

storeDurableSubscriberCursor immediatePriorityDispatch

useCache

tempDestinationAuthorizationEntry admin

queue

read

tempQueue

tempTopic

topic

write

tempQueue DLQ

physicalName

tempTopic DLQ

physicalName

timedSubscriptionRecoveryPolicy zeroExpirationOverride

timeStampingBrokerPlugin recoverDuration

futureOnly

processNetworkMessages

ttlCeiling

topic DLQ

physicalName

66
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Attribute

transportConnector •

name

updateClusterClients

rebalanceClusterClients

updateClusterClientsOnRemove

uniquePropertyMessageEvictionStrategy evictExpiredMessagesHighWatermark

propertyName

virtualTopic concurrentSend

local

dropOnResourceLimit

name

postfix

prefix

selectorAware

setOriginalDestination

transactedSend

Amazon MQ Parent Element Attributes

The following is a detailed explanation of parent element attributes. For more information, see XML
Conﬁguration in the Apache ActiveMQ documentation.

Topics
• broker (p. 67)

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

Example Conﬁguration

67
Amazon MQ Developer Guide
Broker conﬁguration parameters

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. 71)

tempDestinationAuthorizationEntry

defaultEntry authorizationEntry

tempDestinationAuthorizationEntry

tempDestinationAuthorizationEntry
tempDestinationAuthorizationEntry

authorizationPlugin map authorizationMap

broker destinationInterceptors mirroredQueue

virtualDestinationInterceptor

destinationPolicy policyMap

destinations queue

tempQueue

tempTopic

topic

networkConnectors networkConnector (p. 71)

persistenceAdapter kahaDB (p. 73)

plugins authorizationPlugin

discardingDLQBrokerPlugin

forcePersistencyModeBrokerPlugin

redeliveryPlugin

statisticsBrokerPlugin

timeStampingBrokerPlugin

systemUsage systemUsage (p. 74)

transportConnector name

updateClusterClients

rebalanceClusterClients

updateClusterClientsOnRemove

68
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Child Collection Element Child Element

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

clientIdFilterDispatchPolicy

messageEvictionStrategy oldestMessageEvictionStrategy

oldestMessageWithLowestPriorityEvict

uniquePropertyMessageEvictionStrateg

messageGroupMapFactory cachedMessageGroupMapFactory

messageGroupHashBucketFactory

simpleMessageGroupMapFactory

pendingDurableSubscriberPolicy
fileDurableSubscriberCursor

storeDurableSubscriberCursor

69
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Child Collection Element Child Element

vmDurableCursor

pendingMessageLimitStrategyconstantPendingMessageLimitStrategy

prefetchRatePendingMessageLimitStrat

pendingQueuePolicy fileQueueCursor

storeCursor

vmQueueCursor

pendingSubscriberPolicy fileCursor

vmCursor

slowConsumerStrategy abortSlowAckConsumerStrategy

abortSlowConsumerStrategy

subscriptionRecoveryPolicy fixedCountSubscriptionRecoveryPolicy

fixedSizedSubscriptionRecoveryPolicy

lastImageSubscriptionRecoveryPolicy

noSubscriptionRecoveryPolicy

queryBasedSubscriptionRecoveryPolicy

retainedMessageSubscriptionRecoveryP

timedSubscriptionRecoveryPolicy

policyMap defaultEntry policyEntry

policyEntries policyEntry

redeliveryPlugin redeliveryPolicyMap redeliveryPolicyMap

redeliveryPolicyMap defaultEntry redeliveryPolicy

redeliveryPolicyEntries redeliveryPolicy

retainedMessageSubscriptionRecoveryPolicy
wrapped fixedCountSubscriptionRecoveryPolicy

fixedSizedSubscriptionRecoveryPolicy

lastImageSubscriptionRecoveryPolicy

noSubscriptionRecoveryPolicy

queryBasedSubscriptionRecoveryPolicy

retainedMessageSubscriptionRecoveryP

timedSubscriptionRecoveryPolicy

sharedDeadLetterStrategy deadLetterQueue queue

tempQueue

70
Amazon MQ Developer Guide
Broker conﬁguration parameters

Element Child Collection Element Child Element

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
Conﬁguration in the Apache ActiveMQ documentation.

Topics
• authorizationEntry (p. 71)
• networkConnector (p. 71)
• kahaDB (p. 73)
• systemUsage (p. 74)

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 conﬁgure an
authorization map (p. 169).

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.

Default: null

Example Conﬁguration

networkConnector
networkConnector is a child of the networkConnectors child collection element.

71
Amazon MQ Developer Guide
Broker conﬁguration parameters

Topics
• Attributes (p. 72)
• Example Conﬁgurations (p. 72)

Attributes

conduitSubscriptions
Speciﬁes 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 traﬃc. 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
Speciﬁes 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 conﬁgure 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 Conﬁgurations
Note
When using a networkConnector to deﬁne 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 conﬁguration, 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 preﬁxed by static:, indicating a one-to-one
connection between the brokers.

72
Amazon MQ Developer Guide
Broker conﬁguration parameters

For more information, see Conﬁgure Network Connectors for Your Broker (p. 90).

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.

Note
We recommend using the masterslave: preﬁx for networks of brokers. The preﬁx is identical
to the more explicit static:failover:()?randomize=false&maxReconnectAttempts=0
syntax.

kahaDB
kahaDB is a child of the persistenceAdapter child collection element.

Attributes
concurrentStoreAndDispatchQueues
Speciﬁes whether to use concurrent store and dispatch for queues. For more information, see Disable
Concurrent Store and Dispatch for Queues with Slow Consumers (p. 116).

Default: true

cleanupOnStop
Supported in
Apache ActiveMQ 15.16.x and above

If deactivated, garbage collection and cleanup does not take place when the broker is stopped, which
speeds up the shutdown process. The increased speed is useful in cases with large databases or scheduler
databases.

Default: true

journalDiskSyncInterval
Interval (ms) for when to perform a disk sync if journalDiskSyncStrategy=periodic. For more
information, see the Apache ActiveMQ kahaDB documentation.

Default: 1000

journalDiskSyncStrategy
Supported in
Apache ActiveMQ 15.14.x and above

73
Amazon MQ Developer Guide
Broker conﬁguration parameters

Conﬁgures the disk sync policy. For more information, see the Apache ActiveMQ kahaDB documentation.

Default: always
Note
The ActiveMQ documentation states that the data loss is limited to the duration of
journalDiskSyncInterval, which has a default of 1s. The data loss can be longer than the
interval, but it is diﬃcult to be precise. Use caution.

preallocationStrategy

Configures how the broker will try to preallocate the journal files when a new journal file is needed. For
more information, see the Apache ActiveMQ kahaDB documentation.

Default: sparse_file

Example Conﬁguration

Example

systemUsage

systemUsage is a child of the systemUsage child collection element. It controls the maximum amount
of space the broker will use before slowing down producers. For more information, see Producer Flow
Control in the Apache ActiveMQ documentation.

Child Element

memoryUsage

memoryUsage is a child of the systemUsage child element. It manages memory usage. Use
memoryUsage to keep track of how much of something is being used so that you can control working set
usage productively. For more information, see the schema in the Apache ActiveMQ documentation.

Child Element

memoryUsage is a child of the memoryUsage child element.

Attribute

percentOfJvmHeap

Integer between 0 (inclusive) and 70 (inclusive).

Default: 70

Attributes

sendFailIfNoSpace

Sets whether a send() method should fail if there is no space free. The default value is false, which
blocks the send() method until space becomes available. For more information, see the schema in the
Apache Active MQ documentation.

74
Amazon MQ Developer Guide
Version management

Default: false

sendFailIfNoSpaceAfterTimeout

Default: null

Example Conﬁguration

Example

Managing Amazon MQ for ActiveMQ engine versions

Apache ActiveMQ organizes version numbers according to semantic versioning speciﬁcation as X.Y.Z.
In Amazon MQ for ActiveMQ implementations, X.Y denotes the major version, and Z represents the
minor version number. Amazon MQ considers a version change to be major if the major version numbers
change. For example, upgrading from version 5.15 to 5.16 is considered a major version upgrade. A
version change is considered minor if only the minor version number changes. For example, upgrading
from version 5.15.14 to 5.15.15 is considered a minor version upgrade.

Amazon MQ for ActiveMQ currently supports the following engine versions of Apache ActiveMQ.

Major versions Minor versions

ActiveMQ 5.17 • 5.17.1 (recommended)

ActiveMQ 5.16 • 5.16.5 (recommended)

• 5.16.4
• 5.16.3
• 5.16.2

ActiveMQ 5.15 • 5.15.15

• 5.15.14
• 5.15.13
• 5.15.12
• 5.15.10
• 5.15.9
• 5.15.8
• 5.15.6
• 5.15.0

Note
ActiveMQ 5.15.15 is the last minor version planned for the 5.15.x release. We recommend
upgrading your brokers to the latest supported ActiveMQ major engine version, 5.17.x.

75
Amazon MQ Developer Guide
Working Java examples

When you create a new Amazon MQ for ActiveMQ broker, you can specify any supported ActiveMQ
engine version. If you use the AWS Management Console to create a broker, Amazon MQ automatically
defaults to the latest engine version number. If you use the AWS CLI or the Amazon MQ API to create
a broker, the engine version number is required. If you don't provide a version number, the operation
will result in an exception. To learn more, see create-broker in the AWS CLI Command Reference and
CreateBroker in the Amazon MQ REST API Reference.

Topics
• Major and minor version upgrades (p. 76)
• Listing supported engine versions (p. 76)

Major and minor version upgrades

With Amazon MQ, you control when to upgrade your brokers to new versions. When automatic minor
version upgrade is activated, Amazon MQ will automatically upgrade your broker engine to new minor
versions as they are released and supported by Amazon MQ.

To perform a major version upgrade, you must manually upgrade your broker's engine version number.
Minor and major version upgrades occure at the same time as other broker patching operations, during
your scheduled maintenance window (p. 19). If you opt out of automatic minor version upgrades, you
can manually upgrade your broker to a new supported minor version by following the same procedure as
a major upgrade.

For more information about updating your broker preferences to activate or deactivate minor
version upgrades, and manually upgrading your broker, see the section called “Upgrading the engine
version” (p. 21).

Listing supported engine versions

You can list all supported minor and major engine versions by using the describe-broker-instance-
options AWS CLI command.

aws mq describe-broker-instance-options

To ﬁlter the results by engine and instance type use the --engine-type and --host-instance-type
options as shown in the following.

aws mq describe-broker-instance-options --engine-type engine-type --host-instance-

type instance-type

For example, to ﬁlter the results for ActiveMQ, and mq.m5.large instance type, replace engine-type
with ACTIVEMQ and instance-type with mq.m5.large.

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. 97).
• The MQTT example Java code connects to a broker, creates a topic, and publishes and receives a
message.

76
Amazon MQ Developer Guide
Working Java examples

• The STOMP+WSS example Java code connects to a broker, creates a queue, and publishes and receives
a message.

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

The Security Groups page of the EC2 Dashboard is displayed.

a. Choose Add Rule.

Your broker can now accept inbound connections.

Add Java dependencies

OpenWire

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 ﬁle.

77
Amazon MQ Developer Guide
Working Java examples

For more information about activemq-client.jar, see Initial Conﬁguration 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 ﬁle.

<dependencies>
<dependency>
<groupId>org.eclipse.paho</groupId>
<artifactId>org.eclipse.paho.client.mqttv3</artifactId>
<version>1.2.0</version>
</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 ﬁle.

<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>
<version>1.6.6</version>
</dependency>
<dependency>

78
Amazon MQ Developer Guide
Working Java examples

<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.5.0</version>
</dependency>
</dependencies>

For more information, see STOMP Support in the Spring Framework documentation.

AmazonMQExample.java
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.

OpenWire

/*
* Copyright 2010-2019 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);

pooledConnectionFactory.stop();
}

private static void

sendMessage(PooledConnectionFactory pooledConnectionFactory) throws JMSException {
// Establish a connection for the producer.
final Connection producerConnection = pooledConnectionFactory

79
Amazon MQ Developer Guide
Working Java examples

.createConnection();
producerConnection.start();

// 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);

// Create a message.
final String text = "Hello from Amazon MQ!";
final TextMessage producerMessage = producerSession
.createTextMessage(text);

// Send the message.

producer.send(producerMessage);
System.out.println("Message sent.");

// Clean up the producer.

producer.close();
producerSession.close();
producerConnection.close();
}

private static void

receiveMessage(ActiveMQConnectionFactory connectionFactory) throws JMSException {
// Establish a connection for the consumer.
// Note: Consumers should not use PooledConnectionFactory.
final Connection consumerConnection = connectionFactory.createConnection();
consumerConnection.start();

// Create a session.
final Session consumerSession = consumerConnection
.createSession(false, Session.AUTO_ACKNOWLEDGE);

// Create a queue named "MyQueue".

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

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

final MessageConsumer consumer = consumerSession
.createConsumer(consumerDestination);

// 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());

// Clean up the consumer.

consumer.close();
consumerSession.close();
consumerConnection.close();
}

private static PooledConnectionFactory

createPooledConnectionFactory(ActiveMQConnectionFactory connectionFactory) {
// Create a pooled connection factory.

80
Amazon MQ Developer Guide
Working Java examples

final PooledConnectionFactory pooledConnectionFactory =

new PooledConnectionFactory();
pooledConnectionFactory.setConnectionFactory(connectionFactory);
pooledConnectionFactory.setMaxConnections(10);
return pooledConnectionFactory;
}

private static ActiveMQConnectionFactory createActiveMQConnectionFactory() {

// Create a connection factory.
final ActiveMQConnectionFactory connectionFactory =
new ActiveMQConnectionFactory(WIRE_LEVEL_ENDPOINT);

// Pass the username and password.

connectionFactory.setUserName(ACTIVE_MQ_USERNAME);
connectionFactory.setPassword(ACTIVE_MQ_PASSWORD);
return connectionFactory;
}
}

MQTT

import org.eclipse.paho.client.mqttv3.*;

public class AmazonMQExampleMqtt implements MqttCallback {

// 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:8883";
private final static String ACTIVE_MQ_USERNAME = "MyUsername123";
private final static String ACTIVE_MQ_PASSWORD = "MyPassword456";

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";
final String text = "Hello from Amazon MQ!";

// Create the MQTT client and specify the connection options.

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

// Pass the username and password.

connOpts.setUserName(ACTIVE_MQ_USERNAME);

81
Amazon MQ Developer Guide
Working Java examples

connOpts.setPassword(ACTIVE_MQ_PASSWORD.toCharArray());

// Create a session and subscribe to a topic filter.

client.connect(connOpts);
client.setCallback(this);
client.subscribe("+");

// Create a message.
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;
import org.springframework.web.socket.messaging.WebSocketStompClient;

import java.lang.reflect.Type;

82
Amazon MQ Developer Guide
Working Java examples

public class AmazonMQExampleStompWss {

// Specify the connection parameters.

private final static String DESTINATION = "/queue";
private final static String WIRE_LEVEL_ENDPOINT =
"wss://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
east-2.amazonaws.com:61619";
private final static String ACTIVE_MQ_USERNAME = "MyUsername123";
private final static String ACTIVE_MQ_PASSWORD = "MyPassword456";

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;
}

public void handleFrame(final StompHeaders stompHeaders,

final Object message) {
System.out.print("Received message from topic: " + message);
}

83
Amazon MQ Developer Guide
ActiveMQ tutorials

}
}

ActiveMQ tutorials
The following tutorials show how you can create and connect to your ActiveMQ brokers. To use the
ActiveMQ Java example code, you must install the Java Standard Edition Development Kit and make
some changes to the code

Topics
• Creating and configuring an ActiveMQ broker (p. 84)
• Editing broker engine version, instance type, CloudWatch logs, and maintenance
preferences (p. 87)
• Creating and configuring an Amazon MQ network of brokers (p. 88)
• Creating and applying ActiveMQ broker configurations (p. 92)
• Editing ActiveMQ broker configurations and managing configuration revisions (p. 94)
• Connecting a Java application to your Amazon MQ broker (p. 97)
• Integrating ActiveMQ brokers with LDAP (p. 100)
• Creating and managing ActiveMQ broker users (p. 111)

Creating and conﬁguring an ActiveMQ broker

The ﬁrst and most common Amazon MQ task is creating a broker. The following example shows how you
can create and conﬁgure a broker using the AWS Management Console.

Topics
• Step 1: Conﬁgure Basic Broker Settings (p. 84)
• Step 2: (Optional) Conﬁgure Additional Broker Settings (p. 85)
• Step 3: Finish Creating the Broker (p. 86)

Step 1: Conﬁgure Basic Broker Settings

1. Sign in to the Amazon MQ console.
2. On the Select broker engine page, choose Apache ActiveMQ.
3. On the Select deployment and storage page, in the Deployment mode and storage type section,
do the following:

a. Choose the Deployment mode (for example, Active/standby broker). For more information,
see Broker Architecture (p. 44).

84
Amazon MQ Developer Guide
Creating and conﬁguring a broker

with your application, and with Amazon EFS. For more information, see Amazon MQ active/
standby broker for high availability (p. 46).
• For more information on the sample blueprints for a network of brokers, see Sample
blueprints (p. 48).
b. Choose the Storage type (for example, EBS). For more information, see Storage (p. 43).
Note
Amazon EBS replicates data within a single Availability Zone and doesn't support the
ActiveMQ active/standby (p. 46) deployment mode.
c. Choose Next.
4. On the Conﬁgure settings page, in the Details section, do the following:

a. Enter the Broker name.

Step 2: (Optional) Conﬁgure Additional 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.
• Encryption – Choose the customer master key to encrypt your data. See Encryption at
rest (p. 146).
• Public accessibility – Disabling public accessibility makes the broker accessible only within
your VPC. For more information, see Prefer brokers without public accessibility (p. 169) and
Accessing the broker web console without public accessibility (p. 28).

1. Expand the Additional settings section.

85
Amazon MQ Developer Guide
Creating and conﬁguring a broker

2. In the Configuration section, choose Create a new configuration with default values or Select an
existing configuration. For more information, see Configuration (p. 42) and Amazon MQ Broker
Configuration Parameters (p. 57).
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. 185).
Important
If you don't add the CreateLogGroup permission to your Amazon MQ user (p. 186)
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. 187), 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 customer master key (CMK) that will be used to encrypt your data. See Encryption at
rest (p. 146).
c. Choose the Public accessibility of your broker.
5. In the Maintenance section, conﬁgure 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 deﬁned 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. This
allows 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 Deploy.

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.
86
Amazon MQ Developer Guide
Editing broker preferences

2. 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

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 suﬃxes denote a
redundant pair. For more information, see Broker Architecture (p. 44)).
For wire-level protocol endpoints, you can allow your application to connect to either endpoint
by using the Failover Transport.

Editing broker engine version, instance type,

CloudWatch logs, and maintenance preferences
In addition to editing broker configurations and managing configuration revisions (p. 94), 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. 56).

The following example shows how you can edit Amazon MQ ActiveMQ broker preferences using the AWS
Management Console.

Edit ActiveMQ broker options

1. Sign in to the Amazon MQ console.
2. From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3. On the Edit MyBroker page, in the Speciﬁcations section, select a Broker engine version or a
Broker Instance type.

4. In the Configuration section, select the configuration and revision for your broker. For more
information, see Editing and Managing Broker Configurations (p. 94).
5. In the Security and network section, select a group from the Security group(s) drop-down, or
choose Create a new security group to open the Amazon VPC console.
6. In the CloudWatch Logs section, choose whether to publish General logs and Audit logs to Amazon
CloudWatch Logs.

87
Amazon MQ Developer Guide
Creating and conﬁguring a network of brokers

For more information about configuring CloudWatch logs for ActiveMQ brokers, see Configuring
Amazon MQ to publish logs to Amazon CloudWatch Logs (p. 185).
Important
If you don't add the CreateLogGroup permission to your Amazon MQ user (p. 186)
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. 187), the broker can't
publish the logs to CloudWatch Logs.
7. 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 deﬁned 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. This
allows the healthy standby instance to become active and to begin accepting incoming
communications.
8. Choose Schedule modiﬁcations.
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 speciﬁed time.

Creating and conﬁguring an Amazon MQ network of

brokers
A network of brokers is comprised of multiple simultaneously active single-instance brokers (p. 45)
or active/standby brokers (p. 46). You can conﬁgure networks of brokers in a variety of
topologies (p. 49) (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. 51)
network of brokers can increase resiliency, preserving messages if one broker is not reachable. A network
of brokers with a concentrator (p. 52) 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 conﬁguration information, see the following:

• Amazon MQ Network of brokers (p. 46)

• Conﬁgure Your Network of Brokers Correctly (p. 117)
• networkConnector (p. 71)
• networkConnectionStartAsync (p. 67)
• 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
• Prerequisites (p. 89)

88
Amazon MQ Developer Guide
Creating and conﬁguring a network of brokers

• Step 1: Allow Traﬃc between Brokers (p. 89)

• Step 2: Conﬁgure Network Connectors for Your Broker (p. 90)
• Next Steps (p. 91)

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 conﬁguring a broker (p. 84).
• 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 ﬁrst. 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 ActiveMQ broker users (p. 111).
Note
When integrating LDAP authentication with a network of brokers, make sure that the user
exists both as an ActiveMQ brokers, as well as an LDAP user.

The following example uses two single-instance brokers (p. 45). However, you can create networks of
brokers using active/standby brokers (p. 46) or a combination of broker deployment modes.

Step 1: Allow Traﬃc between Brokers

After you create your brokers, you must allow traﬃc 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 .

The Security Groups page of the EC2 Dashboard is displayed.

2. From the security group list, choose your security group.
3. At the bottom of the page, choose Inbound, and then choose Edit.
4. In the Edit inbound rules dialog box, add a rule for the OpenWire endpoint.

a. Choose Add Rule.

b. For Type, select Custom TCP.
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.

89
Amazon MQ Developer Guide
Creating and conﬁguring a network of brokers

• 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.

Your broker can now accept inbound connections.

Step 2: Conﬁgure Network Connectors for Your Broker

After you allow traﬃc between your brokers, you must conﬁgure network connectors for one of them.

1. Edit the conﬁguration revision for broker MyBroker1.

a. On the MyBroker1 page, choose Edit.

b. On the Edit MyBroker1 page, in the Conﬁguration 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. 89) 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: preﬁx and the
OpenWire endpoint uri for MyBroker2. For example:

• If you are connecting the broker to an active/standby broker, use the static+failover
transport and the OpenWire endpoint uri for both brokers with the following query
parameters ?randomize=false&maxReconnectAttempts=0. For example:

Note
Don't include the password for the ActiveMQ user.
f. Choose Save.

90
Amazon MQ Developer Guide
Creating and conﬁguring a network of brokers

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 conﬁguration.
2. Edit MyBroker1 to set the latest conﬁguration revision to apply immediately.

a. On the MyBroker1 page, choose Edit.

b. On the Edit MyBroker1 page, in the Configuration section, choose Schedule Modifications.
c. In the Schedule broker modifications section, choose to apply modifications Immediately.
d. Choose Apply.

MyBroker1 is rebooted and your conﬁguration revision is applied.

The network of brokers is created.

Next Steps
After you conﬁgure your network of brokers, you can test it by producing and consuming messages.
Important
Make sure that you enable inbound connections (p. 77) from your local machine for broker
MyBroker1 on port 8162 (for the ActiveMQ Web Console) and port 61617 (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 MyBroker2 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

91
Amazon MQ Developer Guide
Creating and applying conﬁgurations

The producer connects to the OpenWire endpoint of MyBroker1 and begins to produce persistent
messages to queue MyQueue.

Creating and applying ActiveMQ 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 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. This allows the healthy
standby instance to become active and to begin accepting incoming communications.

For more information, see the following:

• Conﬁguration (p. 42)

• Amazon MQ Broker Configuration Lifecycle (p. 56)
• Amazon MQ Broker Configuration Parameters (p. 57)
• Editing and Managing Broker Configurations (p. 94)

The following example shows how you can create and apply an Amazon MQ broker conﬁguration using
the AWS Management Console.

Topics
• Step 1: Create a Configuration from Scratch (p. 92)
• Step 2: Create a New Configuration Revision (p. 93)
• Step 3: Apply a Configuration Revision to Your Broker (p. 93)

Step 1: Create a Conﬁguration from Scratch

1. Sign in to the Amazon MQ console.
2. On the left, expand the navigation panel and choose Conﬁgurations.

3. On the Conﬁgurations page, choose Create conﬁguration.

4. On the Create conﬁguration page, in the Details section, type the Conﬁguration name (for
example, MyConfiguration) and select a Broker engine version.

92
Amazon MQ Developer Guide
Creating and applying conﬁgurations

Note
To learn more about ActiveMQ engine versions supported by Amazon MQ for ActiveMQ, see
the section called “Version management” (p. 75).
5. Choose Create conﬁguration.

Step 2: Create a New Conﬁguration Revision

1. From the configuration list, choose MyConfiguration.
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
configuration in XML format are displayed.
Note
Editing the current configuration creates a new configuration revision.

3. Choose Edit conﬁguration and make changes to the XML conﬁguration.

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 conﬁguration 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. 57).
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. 96) or
reboot the broker (p. 29). For more information, see Amazon MQ Broker Configuration
Lifecycle (p. 56).
Currently, you can't delete a configuration.

Step 3: Apply a Conﬁguration Revision to Your Broker

1. On the left, expand the navigation panel and choose Brokers.

93
Amazon MQ Developer Guide
Editing conﬁgurations and
managing conﬁguration revisions

2. From the broker list, select your broker (for example, MyBroker) and then choose Edit.
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 conﬁguration revision is applied to your broker at the speciﬁed time.

Editing ActiveMQ broker conﬁgurations and

managing configuration revisions
A configuration contains all of the settings for your ActiveMQ broker, in XML format (similar to
ActiveMQ's activemq.xml file). You can apply a configuration immediately or during a maintenance
window.
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. This allows the healthy
standby instance to become active and to begin accepting incoming communications.

To keep track of the changes you make to your conﬁguration, you can create conﬁguration revisions.

For more information, see the following:

• Conﬁguration (p. 42)

• Amazon MQ Broker Configuration Lifecycle (p. 56)
• Amazon MQ Broker Configuration Parameters (p. 57)
• Creating and applying broker configurations (p. 92)

The following examples show how you can edit Amazon MQ broker conﬁgurations and manage broker
conﬁguration revisions using the AWS Management Console.

Topics
• To View a Previous Configuration Revision (p. 95)
• To Edit the Current Configuration Revision (p. 87)
• To Apply a Configuration Revision to Your Broker (p. 96)
• To Roll Back Your Broker to the Last Configuration Revision (p. 96)

94
Amazon MQ Developer Guide
Editing conﬁgurations and
managing conﬁguration revisions

To View a Previous Conﬁguration Revision

1. Sign in to the Amazon MQ console.
2. From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3. On the Edit MyBroker page, in the Configuration section, select a Configuration and a Revision
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 conﬁguration uses (for
example, Apache ActiveMQ 5.15.8) are displayed.
4. Choose Revision history.
5. The conﬁguration Revision number, Revision date, and Description are displayed for each revision.
6. Select a revision and choose View details.

The broker conﬁguration in XML format is displayed.

To Edit the Current Conﬁguration Revision

1. Sign in to the Amazon MQ console.
2. From the broker list, select your broker (for example, MyBroker) and then choose Edit.
3. On the MyBroker page, choose Edit.
4. On the Edit MyBroker page, in the Configuration section, select a Configuration and a Revision
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
configuration in XML format are displayed.
Note
Editing the current configuration creates a new configuration revision.

6. Choose Edit conﬁguration and make changes to the XML conﬁguration.

7. Choose Save.

The Save revision dialog box is displayed.

95
Amazon MQ Developer Guide
Editing conﬁgurations and
managing conﬁguration revisions

8. (Optional) Type A description of the changes in this revision.

9. Choose Save.

The new revision of the conﬁguration is saved.

To Apply a Conﬁguration Revision to Your Broker

1. Sign in to the Amazon MQ console.
2. From the broker list, select your broker (for example, MyBroker) and then choose Edit.
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 conﬁguration revision is applied to your broker at the speciﬁed time.

To Roll Back Your Broker to the Last Conﬁguration Revision

1. Sign in to the Amazon MQ console.
2. From the broker list, choose the name of your broker (for example, MyBroker).
3. On the MyBroker page, choose Actions, Roll back to last conﬁguration.

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.

96
Amazon MQ Developer Guide
Connecting a Java application to your broker

5. 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.
6. Choose Apply.

Your conﬁguration revision is applied to your broker at the speciﬁed time.

Connecting a Java application to your Amazon MQ

broker
After you create an Amazon MQ ActiveMQ 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. 76).

You can connect to ActiveMQ brokers using various ActiveMQ clients. We recommend using the
ActiveMQ Client.

Topics
• Prerequisites (p. 97)
• To Create a Message Producer and Send a Message (p. 98)
• To Create a Message Consumer and Receive the Message (p. 99)

Enable Inbound Connections

The Security Groups page of the EC2 Dashboard is displayed.

a. Choose Add Rule.

97
Amazon MQ Developer Guide
Connecting a Java application to your broker

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 ﬁle.

To Create a Message Producer and Send a Message

// Create a connection factory.

final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);

// Pass the username and password.

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();

98
Amazon MQ Developer Guide
Connecting a Java application to your broker

// 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();

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.

// Create a connection factory.

final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);

// Pass the username and password.

connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);

// Establish a connection for the consumer.

final Connection consumerConnection = connectionFactory.createConnection();
consumerConnection.start();

// Create a session.
final Session consumerSession = consumerConnection.createSession(false,
Session.AUTO_ACKNOWLEDGE);

99
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

// Create a queue named "MyQueue".

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();

Integrating ActiveMQ brokers with LDAP

Important
LDAP integration is not supported for RabbitMQ brokers.

You can access your ActiveMQ brokers using the following protocols with TLS enabled:

• AMQP
• MQTT
• MQTT over WebSocket
• OpenWire
• STOMP
• STOMP over WebSocket

Amazon MQ oﬀers a choice between native ActiveMQ authentication and LDAP authentication and
authorization to manage user permissions. For information about restrictions related to ActiveMQ
usernames and passwords, see Users (p. 191).

To authorize ActiveMQ users and groups to works with queues and topics, you must edit your broker's
configuration (p. 94). 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. 169) and authorizationEntry (p. 71).
Note
Currently, Amazon MQ doesn't support Client Certificate Authentication.

Topics
• Integrate LDAP with ActiveMQ (p. 101)
• Prerequisites (p. 101)
• Getting Started with LDAP (p. 101)

100
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

• How LDAP integration works (p. 104)

Integrate LDAP with ActiveMQ

You can authenticate Amazon MQ users through the credentials stored in your lightweight directory
access protocol (LDAP) server. You can also add, delete, and modify Amazon MQ users and assign
permissions to topics and queues through it. Management operations like creating, updating and
deleting brokers still require IAM credentials and are not integrated with LDAP.

Customers who want to simplify and centralize their Amazon MQ broker authentication and
authorization using an LDAP server can use this feature. Keeping all user credentials in the LDAP server
saves time and eﬀort by providing a central location for storing and managing these credentials.

Amazon MQ provides LDAP support using the Apache ActiveMQ JAAS plugin. Any LDAP server, such as
Microsoft Active Directory or OpenLDAP that is supported by the plugin is also supported by Amazon
MQ. For more information about the plugin, see the Security section of the Active MQ documentation.

In addition to users, you can specify access to topics and queues for a specific group or a user through
your LDAP server. You do this by creating entries that represent topics and queues in your LDAP server
and then assigning permissions to a specific LDAP user or a group. You can then configure broker to
retrieve authorization data from the LDAP server.

Prerequisites
Before you add LDAP support to a new or existing Amazon MQ broker, you must set up a service account.
This service account is required to initiate a connection to an LDAP server and must have the correct
permissions to make this connection. This service account will set up LDAP authentication for your
broker. Any successive client connections will be authenticated through the same connection.

The service account is an account in your LDAP server, which has access to initiate a connection. It is a
standard LDAP requirement and you have to provide the service account credentials only once. After the
connection is setup, all the future client connections are authenticated through your LDAP server. Your
service account credentials are stored securely in an encrypted form, which is accessible only to Amazon
MQ.

To integrate with ActiveMQ, a specific Directory Information Tree (DIT) is required on the LDAP server.
For an example ldif file that clearly shows this structure, see Import the following LDIF file into the
LDAP server in the Security section of the ActiveMQ documentation.

Getting Started with LDAP

To get started, navigate to the Amazon MQ console and choose LDAP authentication and authorization
when you create a new Amazon MQ or edit an existing broker instance.

Provide the following information about the service account:

• Fully qualified domain name The location of the LDAP server to which authentication and
authorization requests are to be issued.
Note
The fully qualified domain name of the LDAP server you supply must not include the protocol
or port number. Amazon MQ will prepend the fully qualified domain name with the protocol
ldaps, and will append the port number 636.
For example, if you provide the following fully qualified domain: example.com, Amazon MQ
will access your LDAP server using the following URL: ldaps://example.com:636.
For the broker host to be able to successfully communicate with the LDAP server, the fully
qualified domain name must be publicly resolvable. To keep the LDAP server private and

101
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

secure, restrict inbound traﬃc in the server's inbound rules to only allow traﬃc originated
from within the broker's VPC.
• Service account username The distinguished name of the user that will be used to perform the initial
bind to the LDAP server.
• Service account password The password of the user performing the initial bind.

The following image highlights where to supply these details.

In the LDAP login conﬁguration section, provide the following required information:

• User Base The distinguished name of the node in the directory information tree (DIT) that will be
searched for users.
• User Search Matching The LDAP search filter that will be used to find users within the userBase.
The client's username will be substituted into the {0} placeholder in the search filter. For more
information, see Authentication (p. 104) and Authorization (p. 105).
• Role Base The distinguished name of the node in the DIT that will be searched for roles. Roles can
be configured as explicit LDAP group entries in your directory. A typical role entry may consist of
one attribute for the name of the role, such as common name (CN), and another attribute, such as
member, with values representing the distinguished names or usernames of the users belonging to
the role group. For example, given the organizational unit, group, you can provide the following
distinguished name: ou=group,dc=example,dc=com.
• Role Search Matching The LDAP search filter that will be used to find roles within the roleBase.
The distinguished name of the user matched by userSearchMatching will be substituted into
the {0} placeholder in the search filter. The client's username will be substituted in place of the
{1} placeholder. For example, if role entries in your directory include an attribute named member,

102
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

containing the usernames for all users in that role, you can provide the following search ﬁlter:
(member:=uid={1}).

The following image highlights where to specify these details.

In the Optional settings section, you can provide the following optional information:

• User Role Name The name of the LDAP attribute in the user's directory entry for the user's group
membership. In some cases, user roles may be identiﬁed by the value of an attribute in the user's
directory entry. The userRoleName option allows you to provide the name of this attribute. For
example, let's consider the following user entry:

dn: uid=jdoe,ou=user,dc=example,dc=com
objectClass: user
uid: jdoe
sn: jane
cn: Jane Doe
mail: [email protected]
memberOf: role1
userPassword: password

To provide the correct userRoleName for the example above, you would specify the memberOf
attribute. If authentication is successful, the user is assigned the role role1.
• Role Name The group name attribute in a role entry whose value is the name of that role. For
example, you can specify cn for a group entry's common name. If authentication succeeds, the user is
assigned the the value of the cn attribute for each role entry that they are a member of.

103
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

• User Search Subtree Defines the scope for the LDAP user search query. If true, the scope is set to
search the entire subtree under the node defined by userBase.
• Role Search Subtree Defines the scope for the LDAP role search query. If true, the scope is set to
search the entire subtree under the node defined by roleBase.

The following image highlights where to specify these optional settings.

How LDAP integration works

You can think of integration in two main categories: the structure for authentication, and the structure
for authorization.

Authentication
For authentication, client credentials must be valid. These credentials are validated against users in the
user base in the LDAP server.

The user base supplied to the ActiveMQ broker must point to the node in the DIT where users are stored
in the LDAP server. For example, if you are using AWS Managed Microsoft AD, and you have the domain
components corp, example, and com, and within those you have organizational units corp and Users,
you would use the following as your user base:

OU=Users,OU=corp,DC=corp,DC=example,DC=com

The ActiveMQ broker would search at this location in the DIT for users in order to authenticate client
connection requests to the broker.

104
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

Because the ActiveMQ source code hardcodes the attribute name for users to uid, you must make sure
that each user has this attribute set. For simplicity, you can use the user’s connection username. For more
information, see the activemq source code and Conﬁguring ID mappings in Active Directory Users and
Computers for Windows Server 2016 (and subsequent) versions.

To enable ActiveMQ console access for speciﬁc users, make sure they belong to the amazonmq-
console-admins group.

Authorization
For authorization, permissions search bases are specified in the broker configuration. Authorization is
done on a per-destination basis (or wildcard, destination set) via the cachedLdapAuthorizationMap
element, found in the broker’s activemq.xml configuration file. For more information, see Cached
LDAP Authorization Module.
Note
To be able to use the cachedLdapAuthorizationMap element in your broker's
activemq.xml configuration file, you must choose the LDAP Authentication and
Authorization option when creating a configuration via the AWS Management

105
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

Console (p. 92), or set the authenticationStrategy property to LDAP when creating a
new conﬁguration using the Amazon MQ API.

You must provide the following three attributes as part of the cachedLDAPAuthorizationMap
element:

• queueSearchBase
• topicSearchBase
• tempSearchBase

Important
To prevent sensitive information from being directly placed in the broker's
conﬁguration ﬁle, Amazon MQ blocks the following attributes from being used in
cachedLdapAuthorizationMap:

• connectionURL
• connectionUsername
• connectionPassword

When you create a broker, Amazon MQ substitutes the values you provide via the AWS
Management Console, or in the ldapServerMetadata property of your API request, for the
above attributes.

The following demonstrates a working example of the cachedLdapAuthorizationMap.

These values identify the locations within the DIT where permissions for each type of destination
are speciﬁed. So for the above example with AWS Managed Microsoft AD, using the same domain
components of corp, example, and com, you would specify an organizational unit named destination
to contain all your destination types. Within that OU, you would create one for queues, one for topics,
and one for temp destinations.

This would mean that your queue search base, which provides authorization information for destinations
of type queue, would have the following location in your DIT:

OU=Queue,OU=Destination,OU=corp,DC=corp,DC=example,DC=com

106
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

Similarly, permissions rules for topics and temp destinations would be located at the same level in the
DIT:

OU=Topic,OU=Destination,OU=corp,DC=corp,DC=example,DC=com
OU=Temp,OU=Destination,OU=corp,DC=corp,DC=example,DC=com

Within the OU for each type of destination (queue, topic, temp), either a wildcard or speciﬁc destination
name can be provided. For example, to provide an authorization rule for all queues that start with the
preﬁx DEMO.EVENTS.$., you could create the following OU:

OU=DEMO.EVENTS.$,OU=Queue,OU=Destination,OU=corp,DC=corp,DC=example,DC=com

107
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

Note
The DEMO.EVENTS.$ OU is within the Queue OU.

For more info on wildcards in ActiveMQ, see Wildcards

To provide authorization rules for speciﬁc queues, such as DEMO.MYQUEUE, specify something like the
following:

OU=DEMO.MYQUEUE,OU=Queue,OU=Destination,OU=corp,DC=corp,DC=example,DC=com

108
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

Security Groups
Within each OU that represents a destination or a wildcard, you must create three security groups. As
with all permissions in ActiveMQ, these are read/write/admin permissions. For more information on what
each of these permissions allows a user to do, see Security in the ActiveMQ documentation.

109
Amazon MQ Developer Guide
Integrating ActiveMQ brokers with LDAP

You must name these security groups read, write, and admin. Within each of these security groups,
you can add users or groups, who will then have permission to perform the associated actions. You’ll
need these security groups for each wildcard destination set or individual destination.

Note
When you create the admin group, a conflict will arise with the group name. This conflict
happens because the legacy pre-Windows 2000 rules do not allow groups to share the same
name, even if the groups are in different locations of the DIT. The value in the pre-Windows
2000 text box has no impact on the setup, but it must be globally unique. To avoid this conflict,
you can append a uuid suffix to each admin group.

110
Amazon MQ Developer Guide
Creating and managing broker users

Adding a user to the admin security group for a particular destination will enable the user to create and
delete that topic. Adding them to the read security group will enable them to read from the destination,
and adding them to the write group will enable them to write to the destination.

In addition to adding individual users to security group permissions, you can also add entire groups.
However, because ActiveMQ again hardcodes attribute names for groups, you must ensure the group you
want to add has the object class groupOfNames, as shown in the activemq source code.

To do this, follow the same process as with the uid for users. See Conﬁguring ID mappings in Active
Directory Users and Computers for Windows Server 2016 (and subsequent) versions.

Creating and managing ActiveMQ broker users

An ActiveMQ user is a person or an application that can access the queues and topics of an ActiveMQ
broker. You can conﬁgure users to have speciﬁc 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.

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. 111)
• To edit an existing user (p. 112)
• To delete an existing user (p. 112)

To create a new user

1. Sign in to the Amazon MQ console.
2. From the broker list, choose the name of your broker (for example, MyBroker) and then choose View
details.

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. 96) or

111
Amazon MQ Developer Guide
Creating and managing broker users

reboot the broker (p. 29). For more information, see Amazon MQ Broker Conﬁguration
Lifecycle (p. 56).

To edit an existing user

1. Sign in to the Amazon MQ console.
2. From the broker list, choose the name of your broker (for example, MyBroker) and then choose View
details.

On the MyBroker page, in the Users section, all the users for this broker are listed.

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).
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
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. 96) or
reboot the broker (p. 29). For more information, see Amazon MQ Broker Conﬁguration
Lifecycle (p. 56).

To delete an existing user

1. Sign in to the Amazon MQ console.
2. From the broker list, choose the name of your broker (for example, MyBroker) and then choose View
details.

On the MyBroker page, in the Users section, all the users for this broker are listed.

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

4. To conﬁrm deleting the user, in the Delete MyUser? dialog box, choose Delete.
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. 96) or
reboot the broker (p. 29). For more information, see Amazon MQ Broker Conﬁguration
Lifecycle (p. 56).

112
Amazon MQ Developer Guide
Amazon MQ for ActiveMQ best practices

Amazon MQ for ActiveMQ best practices

Use this as a reference to quickly ﬁnd recommendations for maximizing performance and minimizing
throughput costs when working with ActiveMQ brokers on Amazon MQ.

Topics
• Connecting to Amazon MQ (p. 113)
• Ensuring eﬀective Amazon MQ performance (p. 115)
• Avoid slow restarts by recovering prepared XA transactions (p. 117)

Connecting to Amazon MQ
The following design patterns can improve the eﬀectiveness of your application's connection to your
Amazon MQ broker.

Topics
• Never Modify or Delete the Amazon MQ Elastic Network Interface (p. 113)
• Always Use Connection Pooling (p. 114)
• Always Use the Failover Transport to Connect to Multiple Broker Endpoints (p. 115)
• Avoid Using Message Selectors (p. 115)
• Prefer Virtual Destinations to Durable Subscriptions (p. 115)
• If using Amazon VPC peering, avoid client IPs in CIDR range 10.0.0.0/16 (p. 115)

Never Modify or Delete the Amazon MQ Elastic Network

Interface
When you ﬁrst create an Amazon MQ broker (p. 84), 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. 158). 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.

113
Amazon MQ Developer Guide
Connecting to Amazon MQ

Always Use Connection Pooling

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

// Create a connection factory.

final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);

// Pass the username and password.

connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);

// Establish a connection for the consumer.

final Connection consumerConnection = connectionFactory.createConnection();
consumerConnection.start();

However, in more realistic scenarios with multiple producers and consumers, it can be costly and
ineﬃcient 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.

// Create a connection factory.

final ActiveMQConnectionFactory connectionFactory = new
ActiveMQConnectionFactory(wireLevelEndpoint);

// Pass the username and password.

connectionFactory.setUserName(activeMqUsername);
connectionFactory.setPassword(activeMqPassword);

114
Amazon MQ Developer Guide
Ensuring eﬀective Amazon MQ performance

// 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();

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 (p. 84) deployment mode or when you migrate from an on-premises message broker
to Amazon MQ—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.

If using Amazon VPC peering, avoid client IPs in CIDR range

10.0.0.0/16
If you are setting up Amazon VPC peering between on-premise infrastructure and your Amazon MQ
broker, you must not conﬁgure client connections with IPs in CIDR range 10.0.0.0/16.

Ensuring eﬀective Amazon MQ performance

The following design patterns can improve the eﬀectiveness and performance of your Amazon MQ
broker.

Topics
• Disable Concurrent Store and Dispatch for Queues with Slow Consumers (p. 116)
• Choose the Correct Broker Instance Type for the Best Throughput (p. 116)
• Choose the correct broker storage type for the best throughput (p. 117)

115
Amazon MQ Developer Guide
Ensuring eﬀective Amazon MQ performance

• Conﬁgure Your Network of Brokers Correctly (p. 117)

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 conﬁguration, see
concurrentStoreAndDispatchQueues (p. 73).

Choose the Correct Broker Instance Type for the Best

Throughput
The message throughput of a broker instance type (p. 30) 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.

To determine the best broker instance type for your application, we recommend testing diﬀerent
broker instance types. For more information, see Broker instance types (p. 30) and also Measuring the
Throughput for Amazon MQ using the JMS Benchmark.

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. 46) (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 beneﬁt

116
Amazon MQ Developer Guide
Avoid slow restarts by recovering prepared XA transactions

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. 73) 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.

Choose the correct broker storage type for the best throughput
To take advantage of high durability and replication across multiple Availability Zones, use Amazon EFS.
To take advantage of low latency and high throughput, use Amazon EBS. For more information, see
Storage (p. 43).

Conﬁgure Your Network of Brokers Correctly

When you create a network of brokers (p. 46), conﬁgure 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 ﬁrst
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 ﬁrst 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, signiﬁcantly increasing the time needed to start up the broker. This aﬀects
restart and failover time. You must resolve these transactions with a commit() or a rollback() so that
performance doesn't degrade over time.

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 Quotas in Amazon MQ (p. 190).

117
Amazon MQ Developer Guide
Avoid slow restarts by recovering prepared XA transactions

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().

118
Amazon MQ Developer Guide
RabbitMQ engine

Working with Amazon MQ for

RabbitMQ
Amazon MQ makes it easy to create a message broker with the computing and storage resources that ﬁt
your needs. You can create, manage, and delete brokers using the AWS Management Console, Amazon
MQ REST API, or the AWS Command Line Interface.

To learn about Amazon MQ REST APIs, see the Amazon MQ REST API Reference.

Topics
• RabbitMQ engine (p. 119)
• RabbitMQ tutorials (p. 132)
• Amazon MQ for RabbitMQ best practices (p. 141)

RabbitMQ engine
This section describes the basic elements of a RabbitMQ broker and its supported plugins, and provides
an overview of RabbitMQ broker architecture options on Amazon MQ.

Topics
• Basic elements (p. 119)
• Broker architecture (p. 128)
• Managing Amazon MQ for RabbitMQ engine versions (p. 130)

Basic elements
This section introduces key concepts essential to understanding RabbitMQ on Amazon MQ.

Topics
• Broker (p. 119)
• Broker defaults (p. 121)
• User (p. 125)
• Plugins (p. 126)

119
Amazon MQ Developer Guide
Basic elements

is a broker instance type (for example, mq.m5.large). For more information, see Broker instance
types (p. 30).

• A single-instance broker is comprised of one broker in one Availability Zone behind a Network Load
Balancer (NLB) The broker communicates with your application and with an Amazon EBS storage
volume.
• A cluster deployment is a logical grouping of three RabbitMQ broker nodes behind a Network Load
Balancer, each sharing users, queues, and a distributed state across multiple Availability Zones (AZ).

For more information, see Broker architecture (p. 128).

You can enable automatic minor version upgrades to new minor versions of the broker engine, as new
versions of the RabbitMQ engine are released. Automatic upgrades occur during the maintenance window
deﬁned by the day of the week, the time of day (in 24-hour format), and the time zone (UTC by default).

Supported protocols
You can access your RabbitMQ brokers by using any programming language that RabbitMQ supports and
by enabling TLS for the following protocols:

• AMQP (0-9-1)

Listener ports
Amazon MQ managed RabbitMQ brokers support the following listener ports for application-level
connectivity via amqps, as well as client connections using the RabbitMQ web console and the
management API.

• Listener port 5671 - Used for connections made via the secure AMQP URL. For example, given a broker
with broker ID b-c8352341-ec91-4a78-ad9c-a43f23d325bb, deployed in the us-west-2 region,
the following is the broker's full amqp URL: b-c8352341-ec91-4a78-ad9c-a43f23d325bb.mq.us-
west-2.amazonaws.com:5671.
• Listener ports 443 and 15671 - Both listener ports can be used interchangably to access a broker via
the RabbitMQ web console or the mangement API.

Attributes
A RabbitMQ broker has several attributes:

• A name. For example, MyBroker.

• An ID. For example, b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9.
• An Amazon Resource Name (ARN). For example, arn:aws:mq:us-
east-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9.
• A RabbitMQ web console URL. For example, https://
b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com.

For more information, see RabbitMQ web console in the RabbitMQ documentation.
• A secure AMQP endpoint. For example, amqps://
b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com.

For a full list of broker attributes, see the following in the Amazon MQ REST API Reference:

• REST Operation ID: Broker

120
Amazon MQ Developer Guide
Basic elements

• REST Operation ID: Brokers

• REST Operation ID: Broker Reboot

Broker defaults
When you create an Amazon MQ for RabbitMQ broker, Amazon MQ applies a default set of broker
policies and vhost limits to optimize your broker's performance. Amazon MQ applies vhost limits only to
the default (/) vhost. Amazon MQ will not apply default policies to newly created vhosts. We recommend
keeping these defaults for all new and existing brokers. However, you can modify, override, or delete
these defaults at any time.

Amazon MQ creates policies and limits based on the instance type and broker deployment mode that
you choose when you create your broker. The default policies are named according to the deployment
mode, as follows:

• Single-instance – AWS-DEFAULT-POLICY-SINGLE-INSTANCE
• Cluster deployment – AWS-DEFAULT-POLICY-CLUSTER-MULTI-AZ

For single-instance brokers (p. 128), Amazon MQ sets the policy priority value to 0. To override the
default priority value, you can create your own custom policies with higher priority values. For cluster
deployments (p. 129), Amazon MQ sets the priority value to 1 for broker defaults. To create your own
custom policy for clusters, assign a priority value greater than 1.
Note
In cluster deployments, ha-mode and ha-sync-mode broker policies are required for classic
mirroring and high availability (HA).
If you delete the default AWS-DEFAULT-POLICY-CLUSTER-MULTI-AZ policy, Amazon MQ uses
the ha-all-AWS-OWNED-DO-NOT-DELETE policy with a priority value of 0. This ensures that
the required ha-mode and ha-sync-mode policies are still in eﬀect. If you create your own
custom policy, Amazon MQ automatically appends ha-mode and ha-sync-mode to your policy
deﬁnitions.

Topics
• Policy and limit descriptions (p. 121)
• Recommended default values (p. 122)
• Manually applying default policies and limits (p. 123)

Policy and limit descriptions

The following list describes the default policies and limits that Amazon MQ applies to a newly created
broker. The values for max-length, max-queues, and max-connections vary based on your
broker's instance type and deployment mode. These values are listed in the Recommended default
values (p. 122) section.

• queue-mode: lazy (policy) – Enables lazy queues. By default, queues keep an in-memory cache of
messages, enabling the broker to deliver messages to consumers as fast as possible. This can lead to
the broker running out of memory and raising a high-memory alarm. Lazy queues attempt to move
messages to disk as early as is practical. This means that fewer messages are kept in memory under
normal operating conditions. Using lazy queues, Amazon MQ for RabbitMQ can support much larger
messaging loads and longer queues. Note that for certain use cases, brokers with lazy queues might
perform marginally slower. This is because messages are moved from disk to broker, as opposed to
delivering messages from an in-memory cache.
Deployment modes
Single-instance, cluster

121
Amazon MQ Developer Guide
Basic elements

• max-length: number-of-messages (policy) – Sets a limit for the number of messages in a queue.
In cluster deployments, the limit prevents paused queue synchronization in cases such as broker
reboots, or following a maintenance window.
Deployment modes
Cluster
• overflow: reject-publish (policy) – Enforces queues with a max-length policy to reject new
messages after the number of messages in the queue reaches the max-length value. To ensure that
messages aren't lost if a queue is in an overflow state, client applications that publish messages to the
broker must implement publisher confirms (p. 142). For information about implementing publisher
confirms, see Publisher Confirms on the RabbitMQ website.
Deployment modes
Cluster
• max-queues: number-of-queues-per-vhost (vhost limit) – Sets the limit for the number of
queues in a broker. Similar to the max-length policy definition, limiting the number of queues in
cluster deployments prevents paused queue synchronization following broker reboots or maintenance
windows. Limiting queues also prevents excessive amounts of CPU usage for maintaining queues.
Deployment modes
Single-instance, cluster
• max-connections: number-of-connections-per-vhost (vhost limit) – Sets the limit for the
number of client connections to the broker. Limiting the number of connections according to the
recommended values prevents excessive broker memory usage, which could result in the broker raising
a high memory alarm and pausing operations.
Deployment modes
Single-instance, cluster

Recommended default values

Note
The max-length and max-queue default limits are tested and evaluated based on an average
message size of 5 kB. If your messages are signiﬁcantly larger than 5 kB, you will need to adjust
and reduce the max-length and max-queue limits.

The following table lists the default limit values for a newly created broker. Amazon MQ applies these
values according to the broker's instance type and deployment mode.

Instance type Deployment max-length max-queues max-

mode connections

t3.micro Single-instance N/A 500 500

m5.large Single-instance N/A 20,000 4,000

Cluster 8,000,000 4,000 15,000

m5.xlarge Single-instance N/A 30,000 8,000

Cluster 9,000,000 5,000 20,000

m5.2xlarge Single-instance N/A 60,000 15,000

Cluster 10,000,000 6,000 40,000

m5.4xlarge Single-instance N/A 150,000 30,000

Cluster 12,000,000 10,000 100,000

122
Amazon MQ Developer Guide
Basic elements

Manually applying default policies and limits

The following section describes applying custom policies and limits with Amazon MQ recommended
default values. If you have deleted the recommended default policies and limits, and want to re-create
them, or you have created additional vhosts and want to apply the default policies and limits to your
new vhosts, you can use the following steps.
Important
To perform the following steps, you must have an Amazon MQ for RabbitMQ broker user
with administrator permissions. You can use the administrator user created when you ﬁrst
created the broker, or another user that you might have created afterwards. The following table
provides the necessary administrator user tag and permissions as regular expression (regexp)
patterns.

Tags Read regexp Conﬁgure regexp Write regexp

administrator .* .* .*

For more information about creating RabbitMQ users and managing user tags and permissions,
see User (p. 125).

To apply default policies and virtual host limits using the RabbitMQ web console

1. Sign in to the Amazon MQ console.

2. In the left navigation pane, choose Brokers.
3. From the list of brokers, choose the name of the broker to which you want to apply the new policy.
4. On the broker details page, in the Connections section, choose the RabbitMQ web console URL. The
RabbitMQ web console opens in a new browser tab or window.
5. Log in to the RabbitMQ web console with your broker administrator user name and password.
6. In the RabbitMQ web console, at the top of the page, choose Admin.
7. On the Admin page, in the right navigation pane, choose Policies.
8. On the Policies page, you can see a list of the broker's current User policies. Below User policies,
expand Add / update a policy.
9. To create a new broker policy, under Add / update a policy, do the following:

a. For Virtual host, choose the name of the vhost to which you want to attach the policies from
the dropdown list. To choose the default vhost, choose /.
Note
If you have not created additional vhosts, the Virtual host option is not shown in the
RabbitMQ console, and the policies are applied only to the default vhost.
b. For Name, enter a name for your policy, for example, policy-defaults.
c. For Pattern, enter the regexp pattern .* so that the policy matches all queues on the broker.
d. For Apply to, choose Exchanges and queues from the dropdown list.
e. For Priority, enter an integer greater than all other policies applied to the vhost. You can apply
exactly one set of policy deﬁnitions to RabbitMQ queues and exchanges at any given time.
RabbitMQ chooses the matching policy with the highest priority value. For more information
about policy priorities and how to combine policies, see Policies in the RabbitMQ Server
Documentation.
f. For Deﬁnition, add the following key-value pairs:

• queue-mode=lazy. Choose String from the dropdown list.

123
Amazon MQ Developer Guide
Basic elements

• overflow=reject-publish. Choose String from the dropdown list.

Note
Does not apply to single-instance brokers.
• max-length=number-of-messages. Replace number-of-messages with the Amazon MQ
recommended value (p. 122) according to the broker's instance size and deployment mode,
for example, 8000000 for an mq.m5.large cluster. Choose Number from the dropdown list.
Note
Does not apply to single-instance brokers.
g. Choose Add / update policy.
10. Conﬁrm that the new policy appears in the list of User policies.
Note
For cluster brokers, Amazon MQ automatically applies the ha-mode: all and ha-sync-
mode: automatic policy deﬁnitions.
11. From the right navigation pane, choose Limits.
12. On the Limits page, you can see a list of the broker's current Virtual host limits. Below Virtual host
limits, expand Set / update a virtual host limit.
13. To create a new vhost limit, under Set / update a virtual host limit, do the following:

a. For Virtual host, choose the name of the vhost to which you want to attach the policies from
the dropdown list. To choose the default vhost, choose /.
b. For Limit, choose max-connections from the dropdown options.
c. For Value, enter the Amazon MQ recommended value (p. 122) according to the broker's
instance size and deployment mode, for example, 15000 for an mq.m5.large cluster.
d. Choose Set / update limit.
e. Repeat the steps above, and for Limit, choose max-queues from the dropdown options.
14. Conﬁrm that the new limits appear in the list of Virtual host limits.

To apply default policies and virtual host limits using the RabbitMQ management API

1. Sign in to the Amazon MQ console.

2. In the left navigation pane, choose Brokers.
3. From the list of brokers, choose the name of the broker to which you want to apply the new policy.
4. On the broker's page, in the Connections section, note the RabbitMQ web console URL. This is the
broker endpoint that you use in an HTTP request.
5. Open a new terminal or command line window of your choice.
6. To create a new broker policy, enter the following curl command. This command assumes a queue
on the default / vhost, which is encoded as %2F. To apply the policy to another vhost, replace %2F
with the vhost's name.
Note
Replace username and password with your administrator user name and password.
Replace number-of-messages with the Amazon MQ recommended value (p. 122)
according to the broker's instance size and deployment mode. Replace policy-name with a
name for your policy. Replace broker-endpoint with the URL that you noted previously.

curl -i -u username:password -H "content-type:application/json" -XPUT \

-d '{"pattern":".*", "priority":1, "definition":{"queue-mode":lazy, "overflow":"reject-
publish", "max-length":"number-of-messages"}}' \
broker-endpoint/api/policies/%2F/policy-name

124
Amazon MQ Developer Guide
Basic elements

7. To conﬁrm that the new policy is added to your broker's user policies, enter the following curl
command to list all broker policies.

curl -i -u username:password broker-endpoint/api/policies

8. To create a new max-connections virtual host limits, enter the following curl command. This
command assumes a queue on the default / vhost, which is encoded as %2F. To apply the policy to
another vhost, replace %2F with the vhost's name.
Note
Replace username and password with your administrator user name and password.
Replace max-connections with the Amazon MQ recommended value (p. 122) according
to the broker's instance size and deployment mode. Replace the broker endpoint with the
URL that you noted previously.

curl -i -u username:password -H "content-type:application/json" -XPUT \

-d '{"value":"number-of-connections"}' \
broker-endpoint/api/vhost-limits/%2F/max-connections

9. To create a new max-queues virtual host limit, repeat the previous step, but modify the curl
command as shown in the following.

curl -i -u username:password -H "content-type:application/json" -XPUT \

-d '{"value":"number-of-queues"}' \
broker-endpoint/api/vhost-limits/%2F/max-queues

10. To conﬁrm that the new limits are added to your broker's virtual host limits, enter the following
curl command to list all broker virtual host limits.

curl -i -u username:password broker-endpoint/api/vhost-limits

User
Every AMQP 0-9-1 client connection has an associated user which must be authenticated. Each client
connection also targets a virtual host (vhost) for which the user must have a set of permissions. A user
may have permission to conﬁgure, write to, and read from queues and exchanges in a vhost. User
credentials, and the target vhost are speciﬁed at the time the connection is established.

When you ﬁrst create an Amazon MQ for RabbitMQ broker, Amazon MQ uses the username and
password you provide to create a RabbitMQ user with the administrator tag. You can then add and
manage users via the RabbitMQ management API or the RabbitMQ web console. You can also use the
RabbitMQ web console or the management API to set or modify user permissions and tags.
Note
RabbitMQ users will not be stored or displayed via the Amazon MQ Users API.

To create a new user with the RabbitMQ management API, use the following API endpoint and request
body. Replace username and password with your new username and password. When creating users
via the RabbitMQ web console or the management API, avoid guest as a username. Amazon MQ
for RabbitMQ prohibits users with the guest username from accessing the broker remotely via the
RabbitMQ web console, the management API, or via an application-level connection.

POST /api/users/username HTTP/1.1

{"password":"password","tags":"administrator"}

125
Amazon MQ Developer Guide
Basic elements

Important

• Do not add personally identiﬁable information (PII) or other conﬁdential or sensitive

information in broker usernames. Broker usernames are accessible to other AWS services,
including CloudWatch Logs. Broker usernames are not intended to be used for private or
sensitive data.
• If you've forgetten the admin password you set while creating the broker, you cannot reset
your credentials. If you've created multiple administrators, you can log in using another admin
user and reset or recreate your credentials. If you have only one admin user, you must delete
the broker and create a new one with new credentials. We recommend consuming or backing
up messages before deleting the broker.

The tags key is mandatory, and is a comma-separated list of tags for the user. Amazon MQ supports
administrator, management, and monitoring user tags.

You can set permissions for an individual user by using the following API endpoint and request body.
Replace vhost and username with your information. For the default vhost /, use 2f%.

POST /api/permissions/vhost/username HTTP/1.1

{"configure":".*","write":".*","read":".*"}

Note
The configure, read, and write keys are all mandatory.

By using the wildcard .* value, this operation will grant read, write, and conﬁgure permissions for all
queues in the speciﬁed vhost to the user. For more information about managing users via the RabbitMQ
management API, see RabbitMQ Management HTTP API.

Plugins
Amazon MQ for RabbitMQ supports the RabbitMQ management plugin which powers the management
API and the RabbitMQ web console. You can use the web console and the management API to create and
manage broker users and policies.

In addition to the management plugin, Amazon MQ for RabbitMQ also supports the following plugins.

Topics
• Shovel plugin (p. 126)
• Federation plugin (p. 127)
• Consistent Hash exchange plugin (p. 128)

Shovel plugin
Amazon MQ managed brokers support RabbitMQ shovel, allowing you to move messages from queues
and exchanges on one broker instance to another. You can use shovel to connect loosely coupled brokers
and distribute messages away from nodes with heavier message loads.

Amazon MQ managed RabbitMQ brokers support dynamic shovels. Dynamic shovels are conﬁgured using
runtime parameters, and can be started and stopped at any time programatically by a client connection.
For example, using the RabbitMQ management API, you can create a PUT request to the following API
endpoint to conﬁgure a dynamic shovel. In the example, {vhost} can be replaced by the name of the
broker's vhost, and {name} replaced by the name of the new dynamic shovel.

/api/parameters/shovel/{vhost}/{name}

126
Amazon MQ Developer Guide
Basic elements

In the request body, you must specify either a queue or an exchange but not both. This example below
configures a dynamic shovel between a local queue specified in src-queue and a remote queue defined
in dest-queue. Similairly, you can use src-exchange and dest-exchange parameters to configure a
shovel between two exchanges.

{
"value": {
"src-protocol": "amqp091",
"src-uri": "amqp://localhost",
"src-queue": "source-queue-name",
"dest-protocol": "amqp091",
"dest-uri": "amqps://b-c8352341-ec91-4a78-ad9c-a43f23d325bb.mq.us-
west-2.amazonaws.com:5671",
"dest-queue": "destination-queue-name"
}
}

Important
You cannot conﬁgure shovel between queues or exchanges if the shovel destination is a private
broker. You can only conﬁgure shovel between queues or exchanges in public brokers, or
between a source in a private broker, and a destination in a public broker.

For more information about using dynamic shovels, see RabbitMQ dynamic shovel plugin.
Note
Amazon MQ does not support using static shovels.

Federation plugin
Amazon MQ supports federated exchanges and queues. With federation, you can replicate the ﬂow
of messages between queues, exchanges and consumers on separate brokers. Federated queues and
exchanges use point-to-point links to connect to peers in other brokers. While federated exchanges, by
default, route messages once, federated queues can move messages any number of times as needed by
consumers.

You can use federation to allow a downstream broker to consume a message from an exchange or a
queue on an upstream. You can enable federation on downstream brokers by using the RabbitMQ web
console or the management API.
Important
You cannot conﬁgure federation if the downstream queue or exchange is in a private broker.
You can only conﬁgure federation between queues or exchanges in public brokers, or between
an upstream queue or exchange in a private broker, and a downstream queue or exchange in a
public broker.

For example, using the management API, you can conﬁgure federation by doing the following.

• Configure one or more upstreams that define federation connections to other nodes. You can define
federation connections by using the RabbitMQ web console or the management API. Using the
management API, you can create a POST request to /api/parameters/federation-upstream/
%2f/my-upstream with the following request body.

{"value":{"uri":"amqp://server-name","expires":3600000}}

• Conﬁgure a policy to enable your queues or exchanges to become federated. You can conﬁgure
policies by using the RabbitMQ web console, or the management API. Using the management API, you
can create a POST request to /api/policies/%2f/federate-me with the following request body.

{"pattern":"^amq\.", "definition":{"federation-upstream-set":"all"}, "apply-

to":"exchanges"}

127
Amazon MQ Developer Guide
Broker architecture

Note
The request body assumes exchanges on the server are named beginning with amq. Using
regular expression ^amq\. will ensure that federation is enabled for all exchanges whose
names begin with "amq." The exchanges on your RabbitMQ server can be named diﬀerently.

For more information about conﬁguring the federation plugin, see RabbitMQ federation plugin.

Consistent Hash exchange plugin

By default, Amazon MQ for RabbitMQ supports the Consistent Hash exchange type plugin. Consistent
Hash exchanges route messages to queues based on a hash value calculated from the routing key of
a message. Given a reasonably even routing key, Consistent Hash exchanges can distribute messages
between queues reasonably evenly.

For queues bound to a Consistent Hash exchange, the binding key is a number-as-a-string that
determines the binding weight of each queue. Queues with a higher binding weight will receive a
proportionally higher distribution of messages from the Consistent Hash exchange to which they
are bound. In a Consistent Hash exchange topology, publishers can simply publish messages to the
exchange, but consumers must be explicitly conﬁgured to consume messages from speciﬁc queues.

For more information about Consistent Hash exchanges, see RabbitMQ Consistent Hash Exchange Type
on the GitHub website.

Broker architecture
RabbitMQ brokers can be created as single-instance brokers or in a cluster deployment. For both
deployment modes, Amazon MQ provides high durability by storing its data redundantly.

You can access your RabbitMQ brokers by using any programming language that RabbitMQ supports and
by enabling TLS for the following protocols:

• AMQP (0-9-1)

Topics
• Single-instance broker (p. 128)
• Cluster deployment for high availability (p. 129)

Single-instance broker
A single-instance broker is comprised of one broker in one Availability Zone behind a Network Load
Balancer (NLB). The broker communicates with your application and with an Amazon EBS storage
volume. Amazon EBS provides block level storage optimized for low-latency and high throughput.

Using an Network Load Balancer ensures that your Amazon MQ for RabbitMQ broker endpoint remains
unchanged if the broker instance is replaced during a maintenance window or because of underlying
Amazon EC2 hardware failures. An Network Load Balancer allows your applications and users to continue
to use the same endpoint to connect to the broker.

The following diagram illustrates an Amazon MQ for RabbitMQ single-instance broker.

128
Amazon MQ Developer Guide
Broker architecture

Cluster deployment for high availability

A cluster deployment is a logical grouping of three RabbitMQ broker nodes behind a Network Load
Balancer, each sharing users, queues, and a distributed state across multiple Availability Zones (AZ).

In a cluster deployment, Amazon MQ automatically manages broker policies to enable classic mirroring
across all nodes, ensuring high availability (HA). Each mirrored queue consists of one main node and one
or more mirrors. Each queue has its own main node. All operations for a given queue are ﬁrst applied on
the queue's main node and then propagated to mirrors. Amazon MQ creates a default system policy that
sets the ha-mode to all and ha-sync-mode to automatic. This ensures that data is replicated to all
nodes in the cluster across diﬀerent Availability Zones for better durability.
Note
During a maintenance window, all maintenance to a cluster is performed one node at a time,
keeping at least two running nodes at all times. Each time a node is brought down, client
connections to that node are severed and need to be re-established. You must ensure that
your client code is designed to automatically reconnect to your cluster. For more information
about connection recovery, see the section called “Automatically recover from network
failures” (p. 144).
Because Amazon MQ sets ha-sync-mode: automatic, during a maintenance window, queues
will synchronize when each node re-joins the cluster. Queue synchronization blocks all other
queue operations. You can mitigate the impact of queue synchronization during maintenance
windows by keeping queues short.

The default policy should not be deleted. If you do delete this policy, Amazon MQ will be automatically
recreate it. Amazon MQ will also ensure that HA properties are applied to all other policies that you
create on a clustered broker. If you add a policy without the HA properties, Amazon MQ will add them
for you. If you add a policy with diﬀerent high availability properties, Amazon MQ will replace them. For
more information about classic mirroring, see Classic mirrored queues.
Important
Amazon MQ does not support quorum queues. Enabling the quorum queue feature ﬂag and
creating quorum queues will result in data loss.

The following diagram illustrates a RabbitMQ cluster broker deployment with three nodes in three
Availability Zones (AZ), each with its own Amazon EBS volume and a shared state. Amazon EBS provides
block level storage optimized for low-latency and high throughput.

129
Amazon MQ Developer Guide
Version management

Managing Amazon MQ for RabbitMQ engine versions

RabbitMQ organizes version numbers according to semantic versioning speciﬁcation as X.Y.Z. In
Amazon MQ for RabbitMQ implementations, X.Y denotes the major version, and Z represents the minor
version number. Amazon MQ considers a version change to be major if the major version numbers
change. For example, upgrading from version 3.8 to 3.9 is considered a major version upgrade. A version
change is considered minor if only the minor version number changes. For example, upgrading from
version 3.8.23 to 3.8.26 is considered a minor version upgrade.

Amazon MQ for RabbitMQ currently supports the following engine versions of RabbitMQ.
Note
Currently, Amazon MQ does not support streams, or using structured logging in JSON,
introduced in RabbitMQ 3.9.

Major versions Minor versions

RabbitMQ 3.9 • 3.9.16 (recommended)

• 3.9.13

130
Amazon MQ Developer Guide
Version management

Major versions Minor versions

RabbitMQ 3.8 • 3.8.30

• 3.8.27
• 3.8.26
• 3.8.23
• 3.8.22
• 3.8.17 (existing brokers only)
• 3.8.11
• 3.8.6

When you create a new Amazon MQ for RabbitMQ broker, you can specify any supported RabbitMQ
engine version. If you use the AWS Management Console to create a broker, Amazon MQ automatically
defaults to the latest engine version number. If you use the AWS CLI or the Amazon MQ API to create
a broker, the engine version number is required. If you don't provide a version number, the operation
will result in an exception. To learn more, see create-broker in the AWS CLI Command Reference and
CreateBroker in the Amazon MQ REST API Reference.

Topics
• Major and minor version upgrades (p. 131)
• Listing supported engine versions (p. 131)

Major and minor version upgrades

Listing supported engine versions

You can list all supported minor and major engine versions by using the describe-broker-instance-
options AWS CLI command.

aws mq describe-broker-instance-options

To ﬁlter the results by engine and instance type use the --engine-type and --host-instance-type
options as shown in the following.

aws mq describe-broker-instance-options --engine-type engine-type --host-instance-

type instance-type

For example, to ﬁlter the results for RabbitMQ, and mq.m5.large instance type, replace engine-type
with RABBITMQ- and instance-type with mq.m5.large.

131
Amazon MQ Developer Guide
RabbitMQ tutorials

RabbitMQ tutorials
The following tutorials show how you can conﬁgure and use RabbitMQ on Amazon MQ. To learn more
about working with supported client libraries in a variety of programming languages such as Node.js,
Python, .NET, and more, see RabbitMQ Tutorials in the RabbitMQ Getting Started Guide.

Topics
• Editing broker preferences (p. 132)
• Using Python Pika with Amazon MQ for RabbitMQ (p. 132)
• Resolving RabbitMQ paused queue synchronization (p. 137)

Editing broker preferences

You can edit your broker preferences, such as enabling or disabling CloudWatch logs using the AWS
Management Console.

Edit RabbitMQ broker options

4. In the CloudWatch Logs section, click the toggle button to enable or disable general logs. No other
steps are required.
Note

• For RabbitMQ brokers, Amazon MQ automatically uses a Service-Linked Role (SLR) to

publish general logs to CloudWatch. For more information, see the section called “Using
service-linked roles” (p. 162)
• Amazon MQ does not support audit logging for RabbitMQ brokers.
5. In the Maintenance section, conﬁgure your broker's maintenance schedule:

Your preferences are applied to your broker at the speciﬁed time.

Using Python Pika with Amazon MQ for RabbitMQ

The following tutorial shows how you can set up a Python Pika client with TLS conﬁgured to connect to
an Amazon MQ for RabbitMQ broker. Pika is a Python implementation of the AMQP 0-9-1 protocol for
RabbitMQ. This tutorial guides you through installing Pika, declaring a queue, setting up a publisher to
send messages to the broker's default exchange, and setting up a consumer to recieve messages from
the queue.

132
Amazon MQ Developer Guide
Using Python Pika with Amazon MQ for RabbitMQ

Topics
• Prerequisites (p. 133)
• Permissions (p. 133)
• Step one: Create a basic Python Pika client (p. 133)
• Step two: Create a publisher and send a message (p. 134)
• Step three: Create a consumer and recieve a message (p. 135)
• Step four: (Optional) Set up an event loop and consume messages (p. 136)
• What's next? (p. 137)

Prerequisites
To complete the steps in this tutorial, you need the following prerequisites:

• An Amazon MQ for RabbitMQ broker. For more information, see Creating an Amazon MQ for
RabbitMQ broker (p. 11).
• Python 3 installed for your operating system.
• Pika installed using Python pip. To install Pika, open a new terminal window and run the following.

$ python3 -m pip install pika

Permissions
For this tutorial, you need at least one Amazon MQ for RabbitMQ broker user with permission to write
to, and read from, a vhost. The following table describes the neccessary minimum permissions as regular
expression (regexp) patterns.

Tags Conﬁgure regexp Write regexp Read regexp

none .* .*

The user permissions listed provide only read and write permissions to the user, without granting access
to the management plugin to perform administrative operations on the broker. You can further restrict
permissions by providing regexp patterns that limit the user's access to speciﬁed queues. For example, if
you change the read regexp pattern to ^[hello world].*, the user will only have permission to read
from queues that start with hello world.

For more information about creating RabbitMQ users and managing user tags and permissions, see
User (p. 125).

Step one: Create a basic Python Pika client

To create a Python Pika client base class that deﬁnes a constructor and provides the SSL context
necessary for TLS conﬁguration when interacting with an Amazon MQ for RabbitMQ broker, do the
following.

1. Open a new terminal window, create a new directory for your project, and navigate to the directory.

$ mkdir pika-tutorial
$ cd pika-tutorial

133
Amazon MQ Developer Guide
Using Python Pika with Amazon MQ for RabbitMQ

2. Create a new ﬁle, basicClient.py, that contains the following Python code.

import ssl
import pika

class BasicPikaClient:

def init(self, rabbitmq_broker_id, rabbitmq_user, rabbitmq_password, region):

# SSL Context for TLS configuration of Amazon MQ for RabbitMQ

ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
ssl_context.set_ciphers('ECDHE+AESGCM:!ECDSA')

url = f"amqps://{rabbitmq_user}:{rabbitmq_password}@{rabbitmq_broker_id}.mq.
{region}.amazonaws.com:5671"
parameters = pika.URLParameters(url)
parameters.ssl_options = pika.SSLOptions(context=ssl_context)

self.connection = pika.BlockingConnection(parameters)
self.channel = self.connection.channel()

You can now deﬁne additional classes for your publisher and consumer that inherit from
BasicPikaClient.

Step two: Create a publisher and send a message

To create a publisher that declares a queue, and sends a single message, do the following.

1. Copy the contents of the following code sample, and save locally as publisher.py in the same
directory you created in the previous step.

from basicClient import BasicPikaClient

class BasicMessageSender(BasicPikaClient):

def declare_queue(self, queue_name):

print(f"Trying to declare queue({queue_name})...")
self.channel.queue_declare(queue=queue_name)

def send_message(self, exchange, routing_key, body):

channel = self.connection.channel()
channel.basic_publish(exchange=exchange,
routing_key=routing_key,
body=body)
print(f"Sent message. Exchange: {exchange}, Routing Key: {routing_key}, Body:
{body}")

def close(self):
self.channel.close()
self.connection.close()

if __name__ == "__main__":

# Initialize Basic Message Sender which creates a connection

# and channel for sending messages.
basic_message_sender = BasicMessageSender(
"<broker-id>",
"<username>",
"<password>",
"<region>"
)

134
Amazon MQ Developer Guide
Using Python Pika with Amazon MQ for RabbitMQ

# Declare a queue
basic_message_sender.declare_queue("hello world queue")

# Send a message to the queue.

basic_message_sender.send_message(exchange="", routing_key="hello world queue",
body=b'Hello World!')

# Close connections.
basic_message_sender.close()

The BasicMessageSender class inherits from BasicPikaClient and implements additional

methods for delaring a queue, sending a message to the queue, and closing connections. The code
sample routes a message to the default exchange, with a routing key equal to the name of the
queue.
2. Under if __name__ == "__main__":, replace the parameters passed to the
BasicMessageSender constructor statement with the following information.

• <broker-id> – The unique ID that Amazon MQ generates for the broker. You can parse
the ID from your broker ARN. For example, given the following ARN, arn:aws:mq:us-
east-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9,
the broker ID would be b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9.
• <username> – The username for a broker user with suﬃcient permissions to write messages to
the broker.
• <password> – The password for a broker user with suﬃcient permissions to write messages to
the broker.
• <region> – The AWS region in which you created your Amazon MQ for RabbitMQ broker. For
example, us-west-2.
3. Run the following command in the same directory you created publisher.py.

$ python3 publisher.py

If the code runs successfully, you will see the following output in your terminal window.

Trying to declare queue(hello world queue)...

Sent message. Exchange: , Routing Key: hello world queue, Body: b'Hello World!'

Step three: Create a consumer and recieve a message

To create a consumer that recieves a single message from the queue, do the following.

1. Copy the contents of the following code sample, and save locally as consumer.py in the same
directory.

from basicClient import BasicPikaClient

class BasicMessageReceiver(BasicPikaClient):

def get_message(self, queue):

method_frame, header_frame, body = self.channel.basic_get(queue)
if method_frame:
print(method_frame, header_frame, body)
self.channel.basic_ack(method_frame.delivery_tag)
return method_frame, header_frame, body
else:
print('No message returned')

135
Amazon MQ Developer Guide
Using Python Pika with Amazon MQ for RabbitMQ

def close(self):
self.channel.close()
self.connection.close()

if __name__ == "__main__":

# Create Basic Message Receiver which creates a connection

# and channel for consuming messages.
basic_message_receiver = BasicMessageReceiver(
"<broker-id>",
"<username>",
"<password>",
"<region>"
)

# Consume the message that was sent.

basic_message_receiver.get_message("hello world queue")

# Close connections.
basic_message_receiver.close()

Similar to the the publisher you created in the previous step, BasicMessageReciever inherits
from BasicPikaClient and implements additional methods for recieving a single message, and
closing connections.
2. Under the if __name__ == "__main__": statement, replace the parameters passed to the
BasicMessageReciever constructor with your information.
3. Run the following command in your project directory.

$ python3 consumer.py

If the code runs successfully, you will see the message body, and headers including the routing key,
displayed in your terminal window.

<Basic.GetOk(['delivery_tag=1', 'exchange=', 'message_count=0', 'redelivered=False',

'routing_key=hello world queue'])> <BasicProperties> b'Hello World!'

Step four: (Optional) Set up an event loop and consume

messages
To consume multiple messages from a queue, use Pika's basic_consume method and a callback
function as shown in the following

1. In consumer.py, add the following method deﬁnition to the BasicMessageReceiver class.

def consume_messages(self, queue):

def callback(ch, method, properties, body):
print(" [x] Received %r" % body)

self.channel.basic_consume(queue=queue, on_message_callback=callback,
auto_ack=True)

print(' [*] Waiting for messages. To exit press CTRL+C')

self.channel.start_consuming()

2. In consumer.py, under if name == "main":, invoke the consume_msesages method

you deﬁned in the previous step.

136
Amazon MQ Developer Guide
Resolving paused queue sync

if __name__ == "__main__":

# Create Basic Message Receiver which creates a connection and channel for
consuming messages.
basic_message_receiver = BasicMessageReceiver(
"<broker-id>",
"<username>",
"<password>",
"<region>"
)

# Consume the message that was sent.

# basic_message_receiver.get_message("hello world queue")

# Consume multiple messages in an event loop.

basic_message_receiver.consume_messages("hello world queue")

# Close connections.
basic_message_receiver.close()

3. Run consumer.py again, and if successful, the queued messages will be displayed in your terminal
window.

[*] Waiting for messages. To exit press CTRL+C

[x] Received b'Hello World!'
[x] Received b'Hello World!'
...

What's next?
• For more information about other supported RabbitMQ client libraries, see RabbitMQ Client
Documentation on the RabbitMQ website.

Resolving RabbitMQ paused queue synchronization

In an Amazon MQ for RabbitMQ cluster deployment (p. 129), messages published to each queue are
replicated across three broker nodes. This replication, referred to as mirroring, provides high availability
(HA) for RabbitMQ brokers. Queues in a cluster deployment consist of a main replica on one node and
one or more mirrors. Every operation applied to a mirrored queue, including enqueuing messages, is ﬁrst
applied to the main queue and then replicated across its mirrors.

For example, consider a mirrored queue replicated across three nodes: the main node (main) and two
mirrors (mirror-1 and mirror-2). If all messages in this mirrored queue are successfully propagated
to all mirrors, then the queue is synchronized. If a node (mirror-1) becomes unavailable for an interval
of time, the queue is still operational and can continue to enqueue messages. However, for the queue
to synchronize, messages published to main while mirror-1 is unavailable must be replicated to
mirror-1.

For more information about mirroring, see Classic Mirrored Queues on the RabbitMQ website.

Maintenance and queue synchronization

During maintenance windows (p. 132), Amazon MQ performs all maintenance work one node at a time
to ensure that the broker remains operational. As a result, queues might need to synchronize as each
node resumes operation. During synchronization, messages that need to be replicated to mirrors are
loaded into memory from the corresponding Amazon Elastic Block Store (Amazon EBS) volume to be
processed in batches. Processing messages in batches lets queues synchronize faster.

137
Amazon MQ Developer Guide
Resolving paused queue sync

If queues are kept short and messages are small, the queues successfully synchronize and resume
operation as expected. However, if the amount of data in a batch approaches the node's memory limit,
the node raises a high memory alarm, pausing the queue sync. You can conﬁrm memory usage by
comparing the RabbitMemUsed and RabbitMqMemLimit broker node metrics in CloudWatch (p. 170).
Synchronization can't complete until messages are consumed or deleted, or the number of messages in
the batch is reduced.
Note
Reducing the queue synchronization batch size can result in a higher number of replication
transactions.

To resolve a paused queue synchronization, follow the steps in this tutorial, which demonstrates
applying an ha-sync-batch-size policy and restarting the queue sync.

Topics
• Prerequisites (p. 138)
• Step 1: Apply an ha-sync-batch-size policy (p. 138)
• Step 2: Restart the queue sync (p. 140)
• Next steps (p. 140)
• Related resources (p. 140)

Prerequisites
For this tutorial, you must have an Amazon MQ for RabbitMQ broker user with administrator
permissions. You can use the administrator user created when you ﬁrst created the broker, or another
user that you might have created afterwards. The following table provides the necessary administrator
user tag and permissions as regular expression (regexp) patterns.

Tags Read regexp Conﬁgure regexp Write regexp

administrator .* .* .*

For more information about creating RabbitMQ users and managing user tags and permissions, see
User (p. 125).

Step 1: Apply an ha-sync-batch-size policy

The following procedures demonstrate adding a policy that applies to all queues created on the broker.
You can use the RabbitMQ web console or the RabbitMQ management API. For more information, see
Management Plugin on the RabbitMQ website.

To apply an ha-sync-batch-size policy using the RabbitMQ web console

1. Sign in to the Amazon MQ console.

2. In the left navigation pane, choose Brokers.
3. From the list of brokers, choose the name of the broker to which you want to apply the new policy.
4. On the broker's page, in the Connections section, choose the RabbitMQ web console URL. The
RabbitMQ web console opens in a new browser tab or window.
5. Log in to the RabbitMQ web console with your broker administrator user name and password.
6. In the RabbitMQ web console, at the top of the page, choose Admin.
7. On the Admin page, in the right navigation pane, choose Policies.
8. On the Policies page, you can see a list of the broker's current User policies. Below User policies,
expand Add / update a policy.

138
Amazon MQ Developer Guide
Resolving paused queue sync

Note
By default, Amazon MQ for RabbitMQ clusters are created with an initial broker policy
named ha-all-AWS-OWNED-DO-NOT-DELETE. Amazon MQ manages this policy to
ensure that every queue on the broker is replicated to all three nodes and that queues are
synchronized automatically.
9. To create a new broker policy, under Add / update a policy, do the following:

a. For Name, enter a name for your policy, for example, batch-size-policy.
b. For Pattern, enter the regexp pattern .* so that the policy matches all queues on the broker.
c. For Apply to, choose Exchanges and queues from the dropdown list.
d. For Priority, enter an integer greater than all other policies in applied to the vhost. You can
apply exactly one set of policy deﬁnitions to RabbitMQ queues and exchanges at any given time.
RabbitMQ chooses the matching policy with the highest priority value. For more information
about policy priorities and how to combine policies, see Policies in the RabbitMQ Server
Documentation.
e. For Deﬁnition, add the following key-value pairs:

• ha-sync-batch-size=100. Choose Number from the dropdown list.

Note
You might need to adjust and calibrate the value of ha-sync-batch-size based on
the number and size of unsynchronized messages in your queues.
• ha-mode=all. Choose String from the dropdown list.
Important
The ha-mode definition is required for all HA-related policies. Omitting it results in a
validation failure.
• ha-sync-mode=automatic. Choose String from the dropdown list.
Note
The ha-sync-mode definition is required for all custom policies. If it is omitted,
Amazon MQ automatically appends the definition.
f. Choose Add / update policy.
10. Confirm that the new policy appears in the list of User policies.

To apply an ha-sync-batch-size policy using the RabbitMQ management API

1. Sign in to the Amazon MQ console.

2. In the left navigation pane, choose Brokers.
3. From the list of brokers, choose the name of the broker to which you want to apply the new policy.
4. On the broker's page, in the Connections section, note the RabbitMQ web console URL. This is the
broker endpoint that you use in an HTTP request.
5. Open a new terminal or command line window of your choice.
6. To create a new broker policy, enter the following curl command. This command assumes a queue
on the default / vhost, which is encoded as %2F.
Note
Replace username and password with your broker administrator user name and password.
You might need to adjust and calibrate the value of ha-sync-batch-size (100) based
on the number and size of unsynchronized messages in your queues. Replace the broker
endpoint with the URL that you noted previously.

curl -i -u username:password -H "content-type:application/json" -XPUT \

-d '{"pattern":".*", "priority":1, "definition":{"ha-sync-batch-size":100, "ha-
mode":"all", "ha-sync-mode":"automatic"}}' \

139
Amazon MQ Developer Guide
Resolving paused queue sync

https://b-589c045f-f8ln-4ab0-a89c-co62e1c32ef8.mq.us-west-2.amazonaws.com/api/policies/
%2F/batch-size-policy

7. To conﬁrm that the new policy is added to your broker's user policies, enter the following curl
command to list all broker policies.

curl -i -u username:password https://b-589c045f-f8ln-4ab0-a89c-co62e1c32ef8.mq.us-

west-2.amazonaws.com/api/policies

Step 2: Restart the queue sync

After applying a new ha-sync-batch-size policy to your broker, restart the queue sync.

To restart the queue sync using the RabbitMQ web console

Note
To open the RabbitMQ web console, see the previous instructions in Step 1 of this tutorial.

1. In the RabbitMQ web console, at the top of the page, choose Queues.
2. On the Queues page, under All queues, locate your paused queue. In the Features column, your
queue should list the name of the new policy that you created (for example, batch-size-policy).
3. To restart the synchronization process with a reduced batch size, choose Restart sync.

Note
If synchronization pauses and doesn't ﬁnish successfully, try reducing the ha-sync-batch-
size value and restarting the queue sync again.

Next steps
• Once your queue synchronizes successfully, you can monitor the amount of memory that your
RabbitMQ nodes use by viewing the Amazon CloudWatch metric RabbitMQMemUsed. You can also
view the RabbitMQMemLimit metric to monitor a node's memory limit. For more information, see
Accessing CloudWatch metrics for Amazon MQ (p. 170) and Logging and monitoring Amazon MQ for
RabbitMQ brokers (p. 178).
• To prevent paused queue synchronization, we recommend keeping queues short and processing
messages. For workloads with larger message sizes, we also recommend upgrading your broker
instance type to a larger instance size with more memory. For more information about broker instance
types and editing broker preferences, see Amazon MQ for RabbitMQ instance types (p. 33) and Editing
broker preferences (p. 132).
• When you create a new Amazon MQ for RabbitMQ broker, Amazon MQ applies a set of default policies
and virtual host limits to optimize broker performance. If your broker does not have the recommended
default policies and limits, we recommend creating them yourself. For more information about
creating default policies and vhost limits, see the section called “Broker defaults” (p. 121).

Related resources
• UpdateBrokerInput – Use this broker property to update a broker instance type using the Amazon MQ
API.
• Parameters and Policies (RabbitMQ Server Documentation) – Learn more about RabbitMQ parameters
and policies on the RabbitMQ website.
• RabbitMQ Management HTTP API – Learn more about the RabbitMQ management API.

140
Amazon MQ Developer Guide
Amazon MQ for RabbitMQ best practices

Amazon MQ for RabbitMQ best practices

Use this as a reference to quickly ﬁnd recommendations for maximizing performance and minimizing
throughput costs when working with RabbitMQ brokers on Amazon MQ.

Topics
• Enable lazy queues (p. 141)
• Use persistent and durable queues (p. 141)
• Keep queues short (p. 142)
• Configure acknowledgement and confirmation (p. 142)
• Configure pre-fetching (p. 143)
• Configure Celery (p. 144)
• Automatically recover from network failures (p. 144)

Enable lazy queues

If you are working with very long queues that process large volumes of messages, enabling lazy queues
can improve your broker's overall performance.

RabbitMQ's default behavior is to cache messages in memory and to move them to disk only when the
broker needs more available memory. This process of moving messages from memory to disk can take
time and stops the queue from processing messages. Enabling lazy queues can have a signiﬁcant impact
on speeding up the process of moving messages to disk as lazy queues store messages to disk as soon as
possible, resulting in fewer messages cached in memory.

You can enable lazy queues by setting the queue.declare arguments at the time of declaration, or
by conﬁguring a policy via the RabbitMQ management console. The following example demonstrates
declaring a lazy queue using the RabbitMQ Java client library.

Map<String, Object> args = new HashMap<String, Object>();

args.put("x-queue-mode", "lazy");
channel.queueDeclare("myqueue", false, false, false, args);

Note
Enabling lazy queues can increase disk I/O operations.

Use persistent and durable queues

Persistent messages can help prevent data loss in situations where a broker crashes or restarts. Persistent
messages are written to disk as soon as they arrive. Unlike lazy queues, however, persistent messages
are cached both in memory and in disk unless more memory is needed by the broker. In cases where
more memory is needed, messages are removed from memory by the RabbitMQ broker mechanism that
manages storing messages to disk, commonly referred to as the persistence layer.

To enable message persistence, you can declare your queues as durable and set message delivery mode
to persistent. The following example demonstrates using the RabbitMQ Java client library to declare
a durable queue.

boolean durable = true;

channel.queueDeclare("my_queue", durable, false, false, null);

Once you have conﬁgured your queue as durable, you can send a persistent message to your queue by
setting MessageProperties to PERSISTENT_TEXT_PLAIN as shown in the following example.

141
Amazon MQ Developer Guide
Keep queues short

import com.rabbitmq.client.MessageProperties;

channel.basicPublish("", "my_queue",
MessageProperties.PERSISTENT_TEXT_PLAIN,
message.getBytes());

Keep queues short

In cluster deployments, queues with a large number of messages can lead to resource overutilization.
When a broker is overutilized, rebooting an Amazon MQ for RabbitMQ broker can cause further
degradation of performance. If rebooted, overutilized brokers might become unresponsive in the
REBOOT_IN_PROGRESS state.

If queue synchronization is paused for a cluster deployment, we recommend consuming or deleting

messages to lower the number of messages in queues. Once queue depth is reduced and queue sync
completes, the broker status will change to RUNNING. To resolve a paused queue sync, you can also apply
a policy to reduce the queue synchronization batch-size (p. 137).
Warning
Do not reboot a broker that is running high on resources.
If you reboot a broker when queue synchronization is paused, the broker will reinitiate
the synchronization process, which can further degrade broker resources as messages are
transferred from storage to node memory, and result in the broker becoming unresponsive in
the REBOOT_IN_PROGRESS state.

Conﬁgure acknowledgement and conﬁrmation

When a client application sends confirmation of delivery and consumption of messages back to the
broker, it is known as consumer acknowledgment. Similarly, the process of sending confirmation to
a publisher is known as publisher confirm. Both acknowledgement and confirmation are essential to
ensuring data safety when working with RabbitMQ brokers.

Consumer delivery acknowledgement is typically conﬁgured on the client application. When working
with AMQP 0-9-1, acknowledgement can be enabled by conﬁguring the basic.consume or when a
message is fetched using the basic.code method.

Typically, delivery acknowledgement is enabled in a channel. For example, when working with the
RabbitMQ Java client library, you can use the Channel#basicAck to set up a simple basic.ack
positive acknowledgement as shown in the following example.

// this example assumes an existing channel instance

boolean autoAck = false;

channel.basicConsume(queueName, autoAck, "a-consumer-tag",

142
Amazon MQ Developer Guide
Conﬁgure pre-fetching

new DefaultConsumer(channel) {
@Override
public void handleDelivery(String consumerTag,
Envelope envelope,
AMQP.BasicProperties properties,
byte[] body)
throws IOException
{
long deliveryTag = envelope.getDeliveryTag();
// positively acknowledge a single delivery, the message will
// be discarded
channel.basicAck(deliveryTag, false);
}
});

Note
Unacknowledged messages must be cached in memory. You can limit the number of messages
that a consumer pre-fetches by conﬁguring pre-fetch (p. 143) settings for a client application.

Conﬁgure pre-fetching
You can use the RabbitMQ pre-fetch value to optimize how your consumers consume messages.
RabbitMQ implements the channel pre-fetch mechanism provided by AMQP 0-9-1 by applying the pre-
fetch count to consumers as opposed to channels. The pre-fetch value is used to specify how many
messages are being sent to the consumer at any given time. By default, RabbitMQ sets an unlimited
buﬀer size for client applications.

There are a variety of factors to consider when setting a pre-fetch count for your RabbitMQ consumers.
First, consider your consumers' environment and conﬁguration. Because consumers need to keep all
messages in memory as they are being processed, a high pre-fetch value can have a negative impact
on your consumers' performance, and in some cases, can result in a consumer potentially crashing all
together. Similarly, the RabbitMQ broker itself keeps all messages that it sends cached in memory until
it recieves consumer acknowledgement. A high pre-fetch value can cause your RabbitMQ server to run
out of memory quickly if automatic acknowledgement is not conﬁgured for consumers, and if consumers
take a relatively long time to process messages.

With the above considerations in mind, we recommend always setting a pre-fetch value in order to
prevent situations where a RabbitMQ broker or its consumers run out of memory due to a large number
number of unprocessed, or unacknowledged messages. If you need to optimize your brokers to process
large volumes of messages, you can test your brokers and consumers using a range of pre-fetch counts
to determine the value at which point network overhead becomes largely insigniﬁcant compared to the
time it takes a consumer to process messages.
Note

• If your client applications have conﬁgured to automatically acknowledge delivery of messages

to consumers, setting a pre-fetch value will have no eﬀect.
• All pre-fetched messages are removed from the queue.

The following example desmonstrate setting a pre-fetch value of 10 for a single consumer using the
RabbitMQ Java client library.

ConnectionFactory factory = new ConnectionFactory();

Connection connection = factory.newConnection();

Channel channel = connection.createChannel();

channel.basicQos(10, false);

143
Amazon MQ Developer Guide
Conﬁgure Celery

QueueingConsumer consumer = new QueueingConsumer(channel);

channel.basicConsume("my_queue", false, consumer);

Note
In the RabbitMQ Java client library, the default value for the global ﬂag is set to false, so the
above example can be written simply as channel.basicQos(10).

Conﬁgure Celery
Python Celery sends a lot of unnecessary messages that can make ﬁnding and processing the useful
information harder. To reduce the noise and make processing easier, enter the following command:

celery -A app_name worker --without-heartbeat --without-gossip --without-mingle

Automatically recover from network failures

We recommend always enabling automatic network recovery to prevent signiﬁcant downtime in cases
where client connections to RabbitMQ nodes fail. The RabbitMQ Java client library supports automatic
network recovery by default, beginning with version 4.0.0.

Automatic connection recovery is triggered if an unhandled exception is thrown in the connection's I/O
loop, if a socket read operation timeout is detected, or if the server misses a heartbeat.

In cases where the initial connection between a client and a RabbitMQ node fails, automatic recovery will
not be triggered. We recommend writing your application code to account for initial connection failures
by retrying the connection. The following example demonstrates retrying initial network failures using
the RabbitMQ Java client library.

ConnectionFactory factory = new ConnectionFactory();

// enable automatic recovery if using RabbitMQ Java client library prior to version 4.0.0.
factory.setAutomaticRecoveryEnabled(true);
// configure various connection settings

try {
Connection conn = factory.newConnection();
} catch (java.net.ConnectException e) {
Thread.sleep(5000);
// apply retry logic
}

Note
If an application closes a connection by using the Connection.Close method, automatic
network recovery will not be enabled or triggered.

144
Amazon MQ Developer Guide
Data protection

Security in Amazon MQ
Cloud security at AWS is the highest priority. As an AWS customer, you beneﬁt from data centers
and network architectures that are built to meet the requirements of the most security-sensitive
organizations.

Security is a shared responsibility between AWS and you. The shared responsibility model describes this
as security of the cloud and security in the cloud:

• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in
the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors
regularly test and verify the eﬀectiveness of our security as part of the AWS Compliance Programs.
To learn about the compliance programs that apply to Amazon MQ, see AWS Services in Scope by
Compliance Program.
• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also
responsible for other factors including the sensitivity of your data, your company’s requirements, and
applicable laws and regulations.

This documentation helps you understand how to apply the shared responsibility model when using
Amazon MQ. The following topics show you how to conﬁgure Amazon MQ to meet your security and
compliance objectives. You also learn how to use other AWS services that help you to monitor and secure
your Amazon MQ resources.

Topics
• Data protection in Amazon MQ (p. 145)
• Identity and access Management for Amazon MQ (p. 148)
• Compliance validation for Amazon MQ (p. 167)
• Resilience in Amazon MQ (p. 168)
• Infrastructure security in Amazon MQ (p. 168)
• Security best practices for Amazon MQ (p. 168)

Data protection in Amazon MQ

The AWS shared responsibility model applies to data protection in Amazon MQ. As described in this
model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You
are responsible for maintaining control over your content that is hosted on this infrastructure. This
content includes the security conﬁguration and management tasks for the AWS services that you use. For
more information about data privacy, see the Data Privacy FAQ. For information about data protection in
Europe, see the AWS Shared Responsibility Model and GDPR blog post on the AWS Security Blog.

For data protection purposes, we recommend that you protect AWS account credentials and set up
individual user accounts with AWS Identity and Access Management (IAM). That way each user is given
only the permissions necessary to fulﬁll their job duties. We also recommend that you secure your data
in the following ways:

• Use multi-factor authentication (MFA) with each account.

• Use SSL/TLS to communicate with AWS resources. We recommend TLS 1.2 or later.

145
Amazon MQ Developer Guide
Encryption

• Set up API and user activity logging with AWS CloudTrail.

• Use AWS encryption solutions, along with all default security controls within AWS services.
• Use advanced managed security services such as Amazon Macie, which assists in discovering and
securing personal data that is stored in Amazon S3.
• If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command
line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints,
see Federal Information Processing Standard (FIPS) 140-2.

We strongly recommend that you never put confidential or sensitive information, such as your
customers' email addresses, into tags or free-form fields such as a Name field. This includes when you
work with Amazon MQ or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data
that you enter into tags or free-form fields used for names may be used for billing or diagnostic logs.
If you provide a URL to an external server, we strongly recommend that you do not include credentials
information in the URL to validate your request to that server.

For both Amazon MQ for ActiveMQ and Amazon MQ for RabbitMQ brokers, do not use any personally
identiﬁable information (PII) or other conﬁdential or sensitive information for broker names or
usernames when creating resources via the broker web console, or the Amazon MQ API. Broker names
and usernames are accessible to other AWS services, including CloudWatch Logs. Broker usernames are
not intended to be used for private or sensitive data.

Encryption
User data stored in Amazon MQ is encrypted at rest. Amazon MQ encryption at rest provides enhanced
security by encrypting your data using encryption keys stored in the AWS Key Management Service
(KMS). This service helps reduce the operational burden and complexity involved in protecting sensitive
data. With encryption at rest, you can build security-sensitive applications that meet encryption
compliance and regulatory requirements.

All connections between Amazon MQ brokers use Transport layer Security (TLS) to provide encryption in
transit.

Amazon MQ encrypts messages at rest and in transit using encryption keys that it manages and stores
securely. For more information, see the AWS Encryption SDK Developer Guide.

Encryption at rest
Amazon MQ integrates with AWS Key Management Service (KMS) to oﬀer transparent server-side
encryption. Amazon MQ always encrypts your data at rest.

When you create an Amazon MQ for ActiveMQ broker, you can specify the AWS KMS key that you want
Amazon MQ to use to encrypt your data at rest. If you don’t specify a KMS key, Amazon MQ will use an
AWS owned KMS key for you to encrypt data at rest. For more information about KMS keys, see AWS
KMS keys.

When creating a broker, you can conﬁgure what Amazon MQ uses for your encryption key by selecting
one of the following.

• Amazon MQ owned KMS key (default) — The key is owned and managed by Amazon MQ and is not in
your account.
• AWS managed KMS key — The AWS managed KMS key (aws/mq) is a KMS key in your account that is
created, managed, and used on your behalf by Amazon MQ.
• Select existing customer managed KMS key — Customer managed KMS keys are created and
managed by you in AWS Key Management Service (KMS).

146
Amazon MQ Developer Guide
Encryption in transit

Important

• For Amazon MQ for ActiveMQ brokers that use Amazon Elastic File System (EFS) to store
message data, if you revoke the grant that gives Amazon EFS permission to use the KMS keys
in your account, Amazon MQ cannot access this data and your broker will stop working. When
you revoke a grant for Amazon EFS, it will not take place immediately. To revoke access rights,
delete your broker rather than revoking the grant.
• Note that disabling a key or revoking a grant will not take place immediately.
• Revoking a grant cannot be undone. Instead, we suggest deleting the broker if you need to
revoke access rights.

For more information about KMS keys, see AWS KMS keys in the AWS Key Management Service Developer
Guide.

Encryption in transit
Amazon MQ encrypts data in transit between the brokers of your Amazon MQ deployment. All data that
passes between Amazon MQ brokers is encrypted using Transport layer Security (TLS). This is true for all
available protocols.

By default, Amazon MQ brokers use the recommended TLS 1.2 to encrypt data.

Amazon MQ for ActiveMQ protocols

You can access your ActiveMQ brokers using the following protocols with TLS enabled:

• AMQP
• MQTT
• MQTT over WebSocket
• OpenWire
• STOMP
• STOMP over WebSocket

Supported TLS Cipher Suites for ActiveMQ

ActiveMQ on Amazon MQ supports the following cipher suites:

• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
• TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
• TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA
• TLS_RSA_WITH_AES_256_GCM_SHA384
• TLS_RSA_WITH_AES_256_CBC_SHA256
• TLS_RSA_WITH_AES_256_CBC_SHA
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

147
Amazon MQ Developer Guide
Identity and access management

• TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA
• TLS_RSA_WITH_AES_128_GCM_SHA256
• TLS_RSA_WITH_AES_128_CBC_SHA256
• TLS_RSA_WITH_AES_128_CBC_SHA

Amazon MQ for RabbitMQ protocols

You can access your RabbitMQ brokers using the following protocols with TLS enabled:

• AMQP (0-9-1)

Supported TLS Cipher Suites for RabbitMQ

RabbitMQ on Amazon MQ supports the following cipher suites:

• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Identity and access Management for Amazon MQ

AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely
control access to AWS resources. IAM administrators control who can be authenticated (signed in) and
authorized (have permissions) to use Amazon MQ resources. IAM is an AWS service that you can use with
no additional charge.

Topics
• Audience (p. 148)
• Authenticating with identities (p. 149)
• Managing access using policies (p. 151)
• How Amazon MQ works with IAM (p. 152)
• Amazon MQ Identity-based policy examples (p. 156)
• API authentication and authorization for Amazon MQ (p. 158)
• AWS managed policies for Amazon MQ (p. 161)
• Using service-linked roles for Amazon MQ (p. 162)
• Troubleshooting Amazon MQ identity and access (p. 166)

Audience
How you use AWS Identity and Access Management (IAM) diﬀers, depending on the work that you do in
Amazon MQ.

Service user – If you use the Amazon MQ service to do your job, then your administrator provides you
with the credentials and permissions that you need. As you use more Amazon MQ features to do your
work, you might need additional permissions. Understanding how access is managed can help you
request the right permissions from your administrator. If you cannot access a feature in Amazon MQ, see
Troubleshooting Amazon MQ identity and access (p. 166).

148
Amazon MQ Developer Guide
Authenticating with identities

Service administrator – If you're in charge of Amazon MQ resources at your company, you probably have
full access to Amazon MQ. It's your job to determine which Amazon MQ features and resources your
service users should access. You must then submit requests to your IAM administrator to change the
permissions of your service users. Review the information on this page to understand the basic concepts
of IAM. To learn more about how your company can use IAM with Amazon MQ, see How Amazon MQ
works with IAM (p. 152).

IAM administrator – If you're an IAM administrator, you might want to learn details about how you can
write policies to manage access to Amazon MQ. To view example Amazon MQ identity-based policies
that you can use in IAM, see Amazon MQ Identity-based policy examples (p. 156).

Authenticating with identities

Authentication is how you sign in to AWS using your identity credentials. For more information about
signing in using the AWS Management Console, see Signing in to the AWS Management Console as an
IAM user or root user in the IAM User Guide.

You must be authenticated (signed in to AWS) as the AWS account root user, an IAM user, or by assuming
an IAM role. You can also use your company's single sign-on authentication or even sign in using Google
or Facebook. In these cases, your administrator previously set up identity federation using IAM roles.
When you access AWS using credentials from another company, you are assuming a role indirectly.

To sign in directly to the AWS Management Console, use your password with your root user email
address or your IAM user name. You can access AWS programmatically using your root user or IAM
users access keys. AWS provides SDK and command line tools to cryptographically sign your request
using your credentials. If you don't use AWS tools, you must sign the request yourself. Do this using
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.

Regardless of the authentication method that you use, you might also be required to provide additional
security information. For example, AWS recommends that you use multi-factor authentication (MFA) to
increase the security of your account. To learn more, see Using multi-factor authentication (MFA) in AWS
in the IAM User Guide.

AWS account root user

When you create an AWS account, you begin with one sign-in identity that has complete access to
all AWS services and resources in the account. This identity is 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. Safeguard your root user
credentials and use them to perform the tasks that only the root user can perform. For the complete list
of tasks that require you to sign in as the root user, see Tasks that require root user credentials in the
AWS General Reference.

IAM users and groups

An IAM user is an identity within your AWS account that has speciﬁc permissions for a single person or
application. Where possible, we recommend relying on temporary credentials instead of creating IAM
users who have long-term credentials such as passwords and access keys. However, if you have speciﬁc
use cases that require long-term credentials with IAM users, we recommend that you rotate access keys.
For more information, see Rotate access keys regularly for use cases that require long-term credentials in
the IAM User Guide.

An IAM group is an identity that speciﬁes a collection of IAM users. You can't sign in as a group. You
can use groups to specify permissions for multiple users at a time. Groups make permissions easier to
manage for large sets of users. For example, you could have a group named IAMAdmins and give that
group permissions to administer IAM resources.

149
Amazon MQ Developer Guide
Authenticating with identities

Users are diﬀerent from roles. A user is uniquely associated with one person or application, but a role
is intended to be assumable by anyone who needs it. Users have permanent long-term credentials, but
roles provide temporary credentials. To learn more, see When to create an IAM user (instead of a role) in
the IAM User Guide.

IAM roles
An IAM role is an identity within your AWS account that has speciﬁc permissions. It is similar to an IAM
user, but is not associated with a speciﬁc person. You can temporarily assume an IAM role in the AWS
Management Console by switching roles. You can assume a role by calling an AWS CLI or AWS API
operation or by using a custom URL. For more information about methods for using roles, see Using IAM
roles in the IAM User Guide.

IAM roles with temporary credentials are useful in the following situations:

• Federated user access – To assign permissions to a federated identity, you create a role and deﬁne
permissions for the role. When a federated identity authenticates, the identity is associated with
the role and is granted the permissions that are deﬁned by the role. For information about roles for
federation, see Creating a role for a third-party Identity Provider in the IAM User Guide.

If you use IAM Identity Center, you configure a permission set. To control what your identities can
access after they authenticate, IAM Identity Center correlates the permission set to a role in IAM. For
information about permissions sets, see Permission sets in the AWS IAM Identity Center (successor to
AWS Single Sign-On) User Guide.
• Temporary IAM user permissions – An IAM user or role can assume an IAM role to temporarily take on
different permissions for a specific task.
• Cross-account access – You can use an IAM role to allow someone (a trusted principal) in a different
account to access resources in your account. Roles are the primary way to grant cross-account access.
However, with some AWS services, you can attach a policy directly to a resource (instead of using a role
as a proxy). To learn the difference between roles and resource-based policies for cross-account access,
see How IAM roles differ from resource-based policies in the IAM User Guide.
• Cross-service access – Some AWS services use features in other AWS services. For example, when you
make a call in a service, it's common for that service to run applications in Amazon EC2 or store objects
in Amazon S3. A service might do this using the calling principal's permissions, using a service role, or
using a service-linked role.
• Principal permissions – When you use an IAM user or role to perform actions in AWS, you are
considered a principal. Policies grant permissions to a principal. When you use some services, you
might perform an action that then triggers another action in a different service. In this case, you
must have permissions to perform both actions. To see whether an action requires additional
dependent actions in a policy, see Actions, Resources, and Condition Keys for Amazon MQ in the
Service Authorization Reference.
• Service role – A service role is an IAM role that a service assumes to perform actions on your behalf.
An IAM administrator can create, modify, and delete a service role from within IAM. For more
information, see Creating a role to delegate permissions to an AWS service in the IAM User Guide.
• Service-linked role – A service-linked role is a type of service role that is linked to an AWS service.
The service can assume the role to perform an action on your behalf. Service-linked roles appear
in your IAM account and are owned by the service. An IAM administrator can view, but not edit the
permissions for service-linked roles.
• 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.

150
Amazon MQ Developer Guide
Managing access using policies

To learn whether to use IAM roles or IAM users, see When to create an IAM role (instead of a user) in the
IAM User Guide.

Managing access using policies

You control access in AWS by creating policies and attaching them to AWS identities or resources. A
policy is an object in AWS that, when associated with an identity or resource, deﬁnes their permissions.
AWS evaluates these policies when a principal (user, root user, or role session) makes a request.
Permissions in the policies determine whether the request is allowed or denied. Most policies are stored
in AWS as JSON documents. For more information about the structure and contents of JSON policy
documents, see Overview of JSON policies in the IAM User Guide.

Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.

Every IAM entity (user or role) starts with no permissions. By default, users can do nothing, not even
change their own password. To give a user permission to do something, an administrator must attach
a permissions policy to a user. Or the administrator can add the user to a group that has the intended
permissions. When an administrator gives permissions to a group, all users in that group are granted
those permissions.

IAM policies deﬁne permissions for an action regardless of the method that you use to perform the
operation. For example, suppose that you have a policy that allows the iam:GetRole action. A user with
that policy can get role information from the AWS Management Console, the AWS CLI, or the AWS API.

Identity-based policies
Identity-based policies are JSON permissions policy documents that you can attach to an identity, such
as an IAM user, group of users, or role. These policies control what actions users and roles can perform,
on which resources, and under what conditions. To learn how to create an identity-based policy, see
Creating IAM policies in the IAM User Guide.

Identity-based policies can be further categorized as inline policies or managed policies. Inline policies
are embedded directly into a single user, group, or role. Managed policies are standalone policies that
you can attach to multiple users, groups, and roles in your AWS account. Managed policies include AWS
managed policies and customer managed policies. To learn how to choose between a managed policy or
an inline policy, see Choosing between managed policies and inline policies in the IAM User Guide.

Resource-based policies
Resource-based policies are JSON policy documents that you attach to a resource. Examples of resource-
based policies are IAM role trust policies and Amazon S3 bucket policies. In services that support resource-
based policies, service administrators can use them to control access to a specific resource. For the
resource where the policy is attached, the policy defines what actions a specified principal can perform
on that resource and under what conditions. You must specify a principal in a resource-based policy.
Principals can include accounts, users, roles, federated users, or AWS services.

Resource-based policies are inline policies that are located in that service. You can't use AWS managed
policies from IAM in a resource-based policy.

Access Control Lists (ACLs)

Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to
access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy
document format.

151
Amazon MQ Developer Guide
How Amazon MQ works with IAM

Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs. To learn more about
ACLs, see Access control list (ACL) overview in the Amazon Simple Storage Service Developer Guide.

Other policy types

AWS supports additional, less-common policy types. These policy types can set the maximum
permissions granted to you by the more common policy types.

• Permissions boundaries – A permissions boundary is an advanced feature in which you set the
maximum permissions that an identity-based policy can grant to an IAM entity (IAM user or role).
You can set a permissions boundary for an entity. The resulting permissions are the intersection of
entity's identity-based policies and its permissions boundaries. Resource-based policies that specify
the user or role in the Principal ﬁeld are not limited by the permissions boundary. An explicit deny
in any of these policies overrides the allow. For more information about permissions boundaries, see
Permissions boundaries for IAM entities in the IAM User Guide.
• Service control policies (SCPs) – SCPs are JSON policies that specify the maximum permissions for
an organization or organizational unit (OU) in AWS Organizations. AWS Organizations is a service for
grouping and centrally managing multiple AWS accounts that your business owns. If you enable all
features in an organization, then you can apply service control policies (SCPs) to any or all of your
accounts. The SCP limits permissions for entities in member accounts, including each AWS account
root user. For more information about Organizations and SCPs, see How SCPs work in the AWS
Organizations User Guide.
• Session policies – Session policies are advanced policies that you pass as a parameter when you
programmatically create a temporary session for a role or federated user. The resulting session's
permissions are the intersection of the user or role's identity-based policies and the session policies.
Permissions can also come from a resource-based policy. An explicit deny in any of these policies
overrides the allow. For more information, see Session policies in the IAM User Guide.

Multiple policy types

When multiple types of policies apply to a request, the resulting permissions are more complicated to
understand. To learn how AWS determines whether to allow a request when multiple policy types are
involved, see Policy evaluation logic in the IAM User Guide.

How Amazon MQ works with IAM

Before you use IAM to manage access to Amazon MQ, you should understand what IAM features are
available to use with Amazon MQ. To get a high-level view of how Amazon MQ and other AWS services
work with IAM, see AWS Services That Work with IAM in the IAM User Guide.

Amazon MQ uses IAM for creating, updating, and deleting operations, but native ActiveMQ
authentication for brokers. For more information, see Integrating ActiveMQ brokers with LDAP (p. 100).

Topics
• Amazon MQ identity-based policies (p. 152)
• Amazon MQ Resource-based policies (p. 155)
• Authorization based on Amazon MQ tags (p. 155)
• Amazon MQ IAM roles (p. 156)

Amazon MQ identity-based policies

With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the
conditions under which actions are allowed or denied. Amazon MQ supports speciﬁc actions, resources,

152
Amazon MQ Developer Guide
How Amazon MQ works with IAM

and condition keys. To learn about all of the elements that you use in a JSON policy, see IAM JSON Policy
Elements Reference in the IAM User Guide.

Actions
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.

The Action element of a JSON policy describes the actions that you can use to allow or deny access in a
policy. Policy actions usually have the same name as the associated AWS API operation. There are some
exceptions, such as permission-only actions that don't have a matching API operation. There are also
some operations that require multiple actions in a policy. These additional actions are called dependent
actions.

Include actions in a policy to grant permissions to perform the associated operation.

Policy actions in Amazon MQ use the following preﬁx before the action: mq:. For example, to grant
someone permission to run an Amazon MQ instance with the Amazon MQ CreateBroker API operation,
you include the mq:CreateBroker action in their policy. Policy statements must include either an
Action or NotAction element. Amazon MQ deﬁnes its own set of actions that describe tasks that you
can perform with this service.

To specify multiple actions in a single statement, separate them with commas as follows:

"Action": [
"mq:action1",
"mq:action2"

You can specify multiple actions using wildcards (*). For example, to specify all actions that begin with
the word Describe, include the following action:

"Action": "mq:Describe*"

To see a list of Amazon MQ actions, see Actions Deﬁned by Amazon MQ in the IAM User Guide.

Resources
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.

The Resource JSON policy element speciﬁes the object or objects to which the action applies.
Statements must include either a Resource or a NotResource element. As a best practice, specify
a resource using its Amazon Resource Name (ARN). You can do this for actions that support a speciﬁc
resource type, known as resource-level permissions.

For actions that don't support resource-level permissions, such as listing operations, use a wildcard (*) to
indicate that the statement applies to all resources.

"Resource": "*"

In the Amazon MQ, the primary AWS resources are an Amazon MQ message broker and its conﬁguration.
Amazon MQ brokers and conﬁgurations each have unique Amazon Resource Names (ARNs) associated
with them, as shown in the following table.

153
Amazon MQ Developer Guide
How Amazon MQ works with IAM

Resource ARN Condition Keys

Types

brokers arn:${Partition}:mq:${Region}: aws:ResourceTag/

${Account}:broker:${broker-id} ${TagKey} (p. 155)

conﬁgurations arn:${Partition}:mq:${Region}: aws:ResourceTag/

${Account}:configuration:${configuration-id} ${TagKey} (p. 155)

For more information about the format of ARNs, see Amazon Resource Names (ARNs) and AWS Service
Namespaces.

For example, to specify the i-1234567890abcdef0 broker in your statement, use the following ARN:

"Resource": "arn:aws:ec2:us-east-1:123456789012:broker/i-1234567890abcdef0"

To specify all brokers that belong to a speciﬁc account, use the wildcard (*):

"Resource": "arn:aws:ec2:us-east-1:123456789012:broker/*"

Some Amazon MQ actions, such as those for creating resources, cannot be performed on a speciﬁc
resource. In those cases, you must use the wildcard (*).

"Resource": "*"

The API action CreateTags requires both a broker and a conﬁguration. To specify multiple resources in
a single statement, separate the ARNs with commas.

"Resource": [
"resource1",
"resource2"

To see a list of Amazon MQ resource types and their ARNs, see Resources Deﬁned by Amazon MQ in
the IAM User Guide. To learn with which actions you can specify the ARN of each resource, see Actions
Deﬁned by Amazon MQ.

Condition keys
Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can
perform actions on what resources, and under what conditions.

The Condition element (or Condition block) lets you specify conditions in which a statement is in
eﬀect. The Condition element is optional. You can create conditional expressions that use condition
operators, such as equals or less than, to match the condition in the policy with values in the request.

If you specify multiple Condition elements in a statement, or multiple keys in a single Condition
element, AWS evaluates them using a logical AND operation. If you specify multiple values for a single
condition key, AWS evaluates the condition using a logical OR operation. All of the conditions must be
met before the statement's permissions are granted.

You can also use placeholder variables when you specify conditions. For example, you can grant an IAM
user permission to access a resource only if it is tagged with their IAM user name. For more information,
see IAM policy elements: variables and tags in the IAM User Guide.

154
Amazon MQ Developer Guide
How Amazon MQ works with IAM

AWS supports global condition keys and service-speciﬁc condition keys. To see all AWS global condition
keys, see AWS global condition context keys in the IAM User Guide.

Amazon MQ does not define any service-specific condition keys, but supports using some global
condition keys. To see a list of Amazon MQ condition keys, see the table below or Condition Keys for
Amazon MQ in the IAM User Guide. To learn with which actions and resources you can use a condition
key, see Actions Defined by Amazon MQ.

Condition Keys Description Type

aws:RequestTag/ Filters actions based on the tags that are passed in the String
${TagKey} request.

aws:ResourceTag/ Filters actions based on the tags associated with the String
${TagKey} resource.

aws:TagKeys Filters actions based on the tag keys that are passed in the String
request.

Examples

To view examples of Amazon MQ identity-based policies, see Amazon MQ Identity-based policy

examples (p. 156).

Amazon MQ Resource-based policies

Currently, Amazon MQ doesn't support IAM authentication using resource-based permissions or
resource-based policies.

Authorization based on Amazon MQ tags

You can attach tags to Amazon MQ resources or pass tags in a request to Amazon MQ. To control
access based on tags, you provide tag information in the condition element of a policy using the
mq:ResourceTag/key-name, aws:RequestTag/key-name, or aws:TagKeys condition keys.

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:DeleteTags"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": "production"
}
}
}
]

155
Amazon MQ Developer Guide
Identity-based policy examples

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. 34)

• Controlling Access Using IAM Tags

Amazon MQ IAM roles

An IAM role is an entity within your AWS account that has speciﬁc permissions.

Using Temporary Credentials with Amazon MQ

You can use temporary credentials to sign in with federation, assume an IAM role, or to assume a cross-
account role. You obtain temporary security credentials by calling AWS STS API operations such as
AssumeRole or GetFederationToken.

Amazon MQ supports using temporary credentials.

Service roles
This feature allows a service to assume a service role on your behalf. This role allows the service to
access resources in other services to complete an action on your behalf. Service roles appear in your
IAM account and are owned by the account. This means that an IAM administrator can change the
permissions for this role. However, doing so might break the functionality of the service.

Amazon MQ supports service roles.

Amazon MQ Identity-based policy examples

By default, IAM users and roles don't have permission to create or modify Amazon MQ resources.
They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API. An IAM
administrator must create IAM policies that grant users and roles permission to perform speciﬁc API
operations on the speciﬁed resources they need. The administrator must then attach those policies to
the IAM users or groups that require those permissions.

To learn how to create an IAM identity-based policy using these example JSON policy documents, see
Creating Policies on the JSON Tab in the IAM User Guide.

Topics
• Policy best practices (p. 156)
• Using the Amazon MQ console (p. 157)
• Allow users to view their own permissions (p. 157)

Policy best practices

Identity-based policies determine whether someone can create, access, or delete Amazon MQ resources
in your account. These actions can incur costs for your AWS account. When you create or edit identity-
based policies, follow these guidelines and recommendations:

156
Amazon MQ Developer Guide
Identity-based policy examples

• Get started with AWS managed policies and move toward least-privilege permissions – To get
started granting permissions to your users and workloads, use the AWS managed policies that grant
permissions for many common use cases. They are available in your AWS account. We recommend that
you reduce permissions further by defining AWS customer managed policies that are specific to your
use cases. For more information, see AWS managed policies or AWS managed policies for job functions
in the IAM User Guide.
• Apply least-privilege permissions – When you set permissions with IAM policies, grant only the
permissions required to perform a task. You do this by defining the actions that can be taken on
specific resources under specific conditions, also known as least-privilege permissions. For more
information about using IAM to apply permissions, see Policies and permissions in IAM in the IAM User
Guide.
• Use conditions in IAM policies to further restrict access – You can add a condition to your policies to
limit access to actions and resources. For example, you can write a policy condition to specify that all
requests must be sent using SSL. You can also use conditions to grant access to service actions if they
are used through a specific AWS service, such as AWS CloudFormation. For more information, see IAM
JSON policy elements: Condition in the IAM User Guide.
• Use IAM Access Analyzer to validate your IAM policies to ensure secure and functional permissions
– IAM Access Analyzer validates new and existing policies so that the policies adhere to the IAM
policy language (JSON) and IAM best practices. IAM Access Analyzer provides more than 100 policy
checks and actionable recommendations to help you author secure and functional policies. For more
information, see IAM Access Analyzer policy validation in the IAM User Guide.
• Require multi-factor authentication (MFA) – If you have a scenario that requires IAM users or root
users in your account, turn on MFA for additional security. To require MFA when API operations are
called, add MFA conditions to your policies. For more information, see Configuring MFA-protected API
access in the IAM User Guide.

For more information about best practices in IAM, see Security best practices in IAM in the IAM User
Guide.

Using the Amazon MQ console

To access the Amazon MQ console, you must have a minimum set of permissions. These permissions
must allow you to list and view details about the Amazon MQ resources in your AWS account. If you
create an identity-based policy that is more restrictive than the minimum required permissions, the
console won't function as intended for entities (IAM users or roles) with that policy.

To ensure that those entities can still use the Amazon MQ console, also attach the following AWS
managed policy to the entities. For more information, see Adding Permissions to a User in the IAM User
Guide:

AmazonMQReadOnlyAccess

You don't need to allow minimum console permissions for users that are making calls only to the AWS
CLI or the AWS API. Instead, allow access to only the actions that match the API operation that you're
trying to perform.

Allow users to view their own permissions

This example shows how you might create a policy that allows IAM users to view the inline and managed
policies that are attached to their user identity. This policy includes permissions to complete this action
on the console or programmatically using the AWS CLI or AWS API.

{
"Version": "2012-10-17",

157
Amazon MQ Developer Guide
API authentication and authorization

"Statement": [
{
"Sid": "ViewOwnUserInfo",
"Effect": "Allow",
"Action": [
"iam:GetUserPolicy",
"iam:ListGroupsForUser",
"iam:ListAttachedUserPolicies",
"iam:ListUserPolicies",
"iam:GetUser"
],
"Resource": ["arn:aws:iam::*:user/${aws:username}"]
},
{
"Sid": "NavigateInConsole",
"Effect": "Allow",
"Action": [
"iam:GetGroupPolicy",
"iam:GetPolicyVersion",
"iam:GetPolicy",
"iam:ListAttachedGroupPolicies",
"iam:ListGroupPolicies",
"iam:ListPolicyVersions",
"iam:ListPolicies",
"iam:ListUsers"
],
"Resource": "*"
}
]
}

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, conﬁgurations, and users, you must edit your IAM policy
permissions.

Topics
• IAM Permissions Required to Create an Amazon MQ Broker (p. 158)
• Amazon MQ REST API permissions reference (p. 159)
• Resource-level permissions for Amazon MQ API actions (p. 160)

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.

158
Amazon MQ Developer Guide
API authentication and authorization

• 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": [
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DescribeNetworkInterfacePermissions"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEquals": {
"ec2:AuthorizedService": "mq.amazonaws.com"
}
}
}]
}

For more information, see Step 2: create an IAM user and get your AWS credentials (p. 2) and Never
Modify or Delete the Amazon MQ Elastic Network Interface (p. 113).

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 mq:CreateTags

CreateUser mq:CreateUser

DeleteBroker mq:DeleteBroker

DeleteUser mq:DeleteUser

159
Amazon MQ Developer Guide
API authentication and authorization

Amazon MQ REST APIs Required Permissions

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

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 fulﬁlled, or speciﬁc 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 conﬁgurations*

CreateTags brokers, conﬁgurations

CreateUser brokers*

DeleteBroker brokers*

DeleteUser brokers*

DescribeBroker brokers*

DescribeConfiguration conﬁgurations*

160
Amazon MQ Developer Guide
AWS managed policies

API Action Resource Types (*required)

DescribeConfigurationRevision conﬁgurations*

DescribeUser brokers*

ListConfigurationRevisions conﬁgurations*

ListTags brokers, conﬁgurations

ListUsers brokers*

RebootBroker brokers*

UpdateBroker brokers*

UpdateConfiguration conﬁgurations*

UpdateUser brokers*

AWS managed policies for Amazon MQ

To add permissions to users, groups, and roles, it is easier to use AWS managed policies than to write
policies yourself. It takes time and expertise to create IAM customer managed policies that provide your
team with only the permissions they need. To get started quickly, you can use our AWS managed policies.
These policies cover common use cases and are available in your AWS account. For more information
about AWS managed policies, see AWS managed policies in the IAM User Guide.

AWS services maintain and update AWS managed policies. You can't change the permissions in AWS
managed policies. Services occasionally add additional permissions to an AWS managed policy to
support new features. This type of update aﬀects all identities (users, groups, and roles) where the policy
is attached. Services are most likely to update an AWS managed policy when a new feature is launched
or when new operations become available. Services do not remove permissions from an AWS managed
policy, so policy updates won't break your existing permissions.

Additionally, AWS supports managed policies for job functions that span multiple services. For example,
the ViewOnlyAccess AWS managed policy provides read-only access to many AWS services and
resources. When a service launches a new feature, AWS adds read-only permissions for new operations
and resources. For a list and descriptions of job function policies, see AWS managed policies for job
functions in the IAM User Guide.

AWS managed policy: AmazonMQServiceRolePolicy

You can't attach AmazonMQServiceRolePolicy to your IAM entities. This policy is attached to a
service-linked role that allows Amazon MQ to perform actions on your behalf. For more information
about this permission policy and the actions it allows Amazon MQ to perform, see the section called
“Service-linked role permissions for Amazon MQ” (p. 162).

Amazon MQ updates to AWS managed policies

161
Amazon MQ Developer Guide
Using service-linked roles

View details about updates to AWS managed policies for Amazon MQ since this service began tracking
these changes. For automatic alerts about changes to this page, subscribe to the RSS feed on the
Amazon MQ Document history (p. 208) page.

Change Description Date

Amazon MQ started tracking Amazon MQ started tracking May 5, 2021

changes changes for its AWS managed
policies.

Using service-linked roles for Amazon MQ

Amazon MQ uses AWS Identity and Access Management (IAM) service-linked roles. A service-linked role
is a unique type of IAM role that is linked directly to Amazon MQ. Service-linked roles are predeﬁned by
Amazon MQ and include all the permissions that the service requires to call other AWS services on your
behalf.

A service-linked role makes setting up Amazon MQ easier because you don’t have to manually add the
necessary permissions. Amazon MQ defines the permissions of its service-linked roles, and unless defined
otherwise, only Amazon MQ can assume its roles. The defined permissions include the trust policy and
the permissions policy, and that permissions policy cannot be attached to any other IAM entity.

You can delete a service-linked role only after ﬁrst deleting their related resources. This protects your
Amazon MQ resources because you can't inadvertently remove permission to access the resources.

For information about other services that support service-linked roles, see AWS services that work with
IAM and look for the services that have Yes in the Service-Linked Role column. Choose a Yes with a link
to view the service-linked role documentation for that service.

Service-linked role permissions for Amazon MQ

Amazon MQ uses the service-linked role named AWSServiceRoleForAmazonMQ – Amazon MQ uses this
service-linked role to call AWS services on your behalf.

The AWSServiceRoleForAmazonMQ service-linked role trusts the following services to assume the role:

• mq.amazonaws.com

Amazon MQ uses the permission policy AmazonMQServiceRolePolicy, which is attached to the

AWSServiceRoleForAmazonMQ service-linked role, to complete the following actions on the speciﬁed
resources:

• Action: ec2:CreateVpcEndpoint on the vpc resource.

• Action: ec2:CreateVpcEndpoint on the subnet resource.

• Action: ec2:CreateVpcEndpoint on the security-group resource.

• Action: ec2:CreateVpcEndpoint on the vpc-endpoint resource.

• Action: ec2:DescribeVpcEndpoints on the vpc resource.

• Action: ec2:DescribeVpcEndpoints on the subnet resource.

• Action: ec2:CreateTags on the vpc-endpoint resource.

162
Amazon MQ Developer Guide
Using service-linked roles

• Action: logs:PutLogEvents on the log-group resource.

• Action: logs:DescribeLogStreams on the log-group resource.

• Action: logs:DescribeLogGroups on the log-group resource.

• Action: CreateLogStream on the log-group resource.

• Action: CreateLogGroup on the log-group resource.

When you create an Amazon MQ for RabbitMQ broker, the AmazonMQServiceRolePolicy permission
policy allows Amazon MQ to perform the following tasks on your behalf.

• Create a Amazon VPC endpoint for the broker using the Amazon VPC, subnet, and security-group you
provide. You can use the endpoint created for your broker to connect to the broker via the RabbitMQ
management console, the management API, or programatically.
• Create log groups, and publish broker logs to Amazon CloudWatch Logs.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeVpcEndpoints"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpoint"
],
"Resource": [
"arn:aws:ec2:*:*:vpc/*",
"arn:aws:ec2:*:*:subnet/*",
"arn:aws:ec2:*:*:security-group/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpoint"
],
"Resource": [
"arn:aws:ec2:*:*:vpc-endpoint/*"
],
"Condition": {
"StringEquals": {
"aws:RequestTag/AMQManaged": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:*:vpc-endpoint/*",

163
Amazon MQ Developer Guide
Using service-linked roles

"Condition": {
"StringEquals": {
"ec2:CreateAction": "CreateVpcEndpoint"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:DeleteVpcEndpoints"
],
"Resource": "arn:aws:ec2:*:*:vpc-endpoint/*",
"Condition": {
"StringEquals": {
"ec2:ResourceTag/AMQManaged": "true"
}
}
},
{
"Effect": "Allow",
"Action": [
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"logs:DescribeLogGroups",
"logs:CreateLogStream",
"logs:CreateLogGroup"
],
"Resource": [
"arn:aws:logs:*:*:log-group:/aws/amazonmq/*"
]
}
]
}

You must conﬁgure permissions to allow an IAM entity (such as a user, group, or role) to create, edit, or
delete a service-linked role. For more information, see Service-Linked Role Permissions in the IAM User
Guide.

Creating a service-linked role for Amazon MQ

You don't need to manually create a service-linked role. When you ﬁrst create a broker, Amazon MQ
creates a service-linked role to call AWS services on your behalf. All subsequent brokers that you create
will use the same role and no new role is created.
Important
This service-linked role can appear in your account if you completed an action in another service
that uses the features supported by this role. To learn more, see A New Role Appeared in My IAM
Account.

If you delete this service-linked role, and then need to create it again, you can use the same process to
recreate the role in your account.

You can also use the IAM console to create a service-linked role with the Amazon MQ use case. In the
AWS CLI or the AWS API, create a service-linked role with the mq.amazonaws.com service name. For
more information, see Creating a service-linked role in the IAM User Guide. If you delete this service-
linked role, you can use this same process to create the role again.

Editing a service-linked role for Amazon MQ

Amazon MQ does not allow you to edit the AWSServiceRoleForAmazonMQ service-linked role. However,
you can edit the description of the role using IAM. For more information, see Editing a service-linked role
in the IAM User Guide.

164
Amazon MQ Developer Guide
Using service-linked roles

Deleting a service-linked role for Amazon MQ

If you no longer need to use a feature or service that requires a service-linked role, we recommend
that you delete that role. That way you don’t have an unused entity that is not actively monitored
or maintained. However, you must clean up the resources for your service-linked role before you can
manually delete it.
Note
If the Amazon MQ service is using the role when you try to delete the resources, then the
deletion might fail. If that happens, wait for a few minutes and try the operation again.

To delete Amazon MQ resources used by the AWSServiceRoleForAmazonMQ

• Delete your Amazon MQ brokers using the AWS Management Console, Amazon MQ CLI, or Amazon
MQ API. For more information about deleting brokers, see ??? (p. 29).

To manually delete the service-linked role using IAM

Use the IAM console, the AWS CLI, or the AWS API to delete the AWSServiceRoleForAmazonMQ service-
linked role. For more information, see Deleting a Service-Linked Role in the IAM User Guide.

Supported regions for Amazon MQ service-linked roles

Amazon MQ supports using service-linked roles in all of the regions where the service is available. For
more information, see AWS Regions and Endpoints.

Region name Region identity Support in Amazon MQ

US East (N. Virginia) us-east-1 Yes

US East (Ohio) us-east-2 Yes

US West (N. California) us-west-1 Yes

US West (Oregon) us-west-2 Yes

Asia Paciﬁc (Mumbai) ap-south-1 Yes

Asia Paciﬁc (Osaka) ap-northeast-3 Yes

Asia Paciﬁc (Seoul) ap-northeast-2 Yes

Asia Paciﬁc (Singapore) ap-southeast-1 Yes

Asia Paciﬁc (Sydney) ap-southeast-2 Yes

Asia Paciﬁc (Tokyo) ap-northeast-1 Yes

Canada (Central) ca-central-1 Yes

Europe (Frankfurt) eu-central-1 Yes

Europe (Ireland) eu-west-1 Yes

Europe (London) eu-west-2 Yes

Europe (Paris) eu-west-3 Yes

South America (São Paulo) sa-east-1 Yes

165
Amazon MQ Developer Guide
Troubleshooting

Region name Region identity Support in Amazon MQ

AWS GovCloud (US) us-gov-west-1 No

Troubleshooting Amazon MQ identity and access

Use the following information to help you diagnose and ﬁx common issues that you might encounter
when working with Amazon MQ and IAM.

Topics
• I Am Not Authorized to Perform an Action in Amazon MQ (p. 166)
• I am not authorized to perform iam:PassRole (p. 166)
• I want to view my access keys (p. 166)
• I'm an administrator and want to allow others to access Amazon MQ (p. 167)
• I want to allow people outside of my AWS account to access my Amazon MQ resources (p. 167)

I Am Not Authorized to Perform an Action in Amazon MQ

If the AWS Management Console tells you that you're not authorized to perform an action, then you
must contact your administrator for assistance. Your administrator is the person that provided you with
your user name and password.

The following example error occurs when the mateojackson IAM user tries to use the console to view
details about a widget but does not have mq:GetWidget permissions.

User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform:

mq:GetWidget on resource: my-example-widget

In this case, Mateo asks his administrator to update his policies to allow him to access the my-example-
widget resource using the mq:GetWidget action.

I am not authorized to perform iam:PassRole

If you receive an error that you're not authorized to perform the iam:PassRole action, your policies
must be updated to allow you to pass a role to Amazon MQ.

Some AWS services allow you to pass an existing role to that service instead of creating a new service
role or service-linked role. To do this, you must have permissions to pass the role to the service.

The following example error occurs when an IAM user named marymajor tries to use the console to
perform an action in Amazon MQ. However, the action requires the service to have permissions that are
granted by a service role. Mary does not have permissions to pass the role to the service.

User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole

In this case, Mary's policies must be updated to allow her to perform the iam:PassRole action.

If you need help, contact your AWS administrator. Your administrator is the person who provided you
with your sign-in credentials.

I want to view my access keys

After you create your IAM user access keys, you can view your access key ID at any time. However, you
can't view your secret access key again. If you lose your secret key, you must create a new access key pair.

166
Amazon MQ Developer Guide
Compliance validation

Access keys consist of two parts: an access key ID (for example, AKIAIOSFODNN7EXAMPLE) and a secret
access key (for example, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY). Like a user name and
password, you must use both the access key ID and secret access key together to authenticate your
requests. Manage your access keys as securely as you do your user name and password.
Important
Do not provide your access keys to a third party, even to help ﬁnd your canonical user ID. By
doing this, you might give someone permanent access to your account.

When you create an access key pair, you are prompted to save the access key ID and secret access key in
a secure location. The secret access key is available only at the time you create it. If you lose your secret
access key, you must add new access keys to your IAM user. You can have a maximum of two access keys.
If you already have two, you must delete one key pair before creating a new one. To view instructions,
see Managing access keys in the IAM User Guide.

I'm an administrator and want to allow others to access Amazon

MQ
To allow others to access Amazon MQ, you must create an IAM entity (user or role) for the person or
application that needs access. They will use the credentials for that entity to access AWS. You must then
attach a policy to the entity that grants them the correct permissions in Amazon MQ.

To get started right away, see Creating your ﬁrst IAM delegated user and group in the IAM User Guide.

I want to allow people outside of my AWS account to access my

Amazon MQ resources
You can create a role that users in other accounts or people outside of your organization can use to
access your resources. You can specify who is trusted to assume the role. For services that support
resource-based policies or access control lists (ACLs), you can use those policies to grant people access to
your resources.

To learn more, consult the following:

• To learn whether Amazon MQ supports these features, see How Amazon MQ works with IAM (p. 152).
• To learn how to provide access to your resources across AWS accounts that you own, see Providing
access to an IAM user in another AWS account that you own in the IAM User Guide.
• To learn how to provide access to your resources to third-party AWS accounts, see Providing access to
AWS accounts owned by third parties in the IAM User Guide.
• To learn how to provide access through identity federation, see Providing access to externally
authenticated users (identity federation) in the IAM User Guide.
• To learn the diﬀerence between using roles and resource-based policies for cross-account access, see
How IAM roles diﬀer from resource-based policies in the IAM User Guide.

Compliance validation for Amazon MQ

Third-party auditors assess the security and compliance of Amazon MQ as part of multiple AWS
compliance programs. These include SOC, PCI, HIPAA, and others.

To learn whether or other AWS services are within the scope of speciﬁc compliance programs, see AWS
Services in Scope by Compliance Program. For general information, see AWS Compliance Programs.

You can download third-party audit reports using AWS Artifact. For more information, see Downloading
Reports in AWS Artifact.

167
Amazon MQ Developer Guide
Resilience

Your compliance responsibility when using AWS services is determined by the sensitivity of your data,
your company's compliance objectives, and applicable laws and regulations. AWS provides the following
resources to help with compliance:

• Security and Compliance Quick Start Guides – These deployment guides discuss architectural
considerations and provide steps for deploying baseline environments on AWS that are security and
compliance focused.
• Architecting for HIPAA Security and Compliance on Amazon Web Services – This whitepaper describes
how companies can use AWS to create HIPAA-eligible applications.
Note
Not all AWS services are HIPAA eligible. For more information, see the HIPAA Eligible Services
Reference.
• AWS Compliance Resources – This collection of workbooks and guides might apply to your industry
and location.
• Evaluating Resources with Rules in the AWS Config Developer Guide – The AWS Config service assesses
how well your resource configurations comply with internal practices, industry guidelines, and
regulations.
• AWS Security Hub – This AWS service provides a comprehensive view of your security state within AWS
that helps you check your compliance with security industry standards and best practices.
• AWS Audit Manager – This AWS service helps you continuously audit your AWS usage to simplify how
you manage risk and compliance with regulations and industry standards.

Resilience in Amazon MQ
The AWS global infrastructure is built around AWS Regions and Availability Zones. AWS Regions provide
multiple physically separated and isolated Availability Zones, which are connected with low-latency,
high-throughput, and highly redundant networking. With Availability Zones, you can design and operate
applications and databases that automatically fail over between zones without interruption. Availability
Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data
center infrastructures.

For more information about AWS Regions and Availability Zones, see AWS Global Infrastructure.

Infrastructure security in Amazon MQ

As a managed service, Amazon MQ is protected by the AWS global network security procedures that are
described in the Amazon Web Services: Overview of Security Processes whitepaper.

You use AWS published API calls to access Amazon MQ through the network. Clients must support
Transport Layer Security (TLS) 1.0 or later. We recommend TLS 1.2 or later. Clients must also support
cipher suites with perfect forward secrecy (PFS) such as Ephemeral Diﬃe-Hellman (DHE) or Elliptic Curve
Ephemeral Diﬃe-Hellman (ECDHE). Most modern systems such as Java 7 and later support these modes.

Additionally, requests must be signed by using an access key ID and a secret access key that is associated
with an IAM principal. Or you can use the AWS Security Token Service (AWS STS) to generate temporary
security credentials to sign requests.

Security best practices for Amazon MQ

The following design patterns can improve the security of your Amazon MQ broker.

168
Amazon MQ Developer Guide
Prefer brokers without public accessibility

Topics
• Prefer brokers without public accessibility (p. 169)
• Always conﬁgure an authorization map (p. 169)
• Block unnecessary protocols with VPC security groups (p. 169)

For more information about how Amazon MQ encrypts your data, as well as a list of supported protocols,
see Data Protection (p. 145).

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 broker web console without public accessibility (p. 28)
in this guide and How to Help Prepare for DDoS Attacks by Reducing Your Attack Surface on the AWS
Security Blog.

Always conﬁgure an authorization map

Because ActiveMQ has no authorization map conﬁgured 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. 71).
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
conﬁguring your Amazon VPC Security Group. For instance, to restrict access to most protocols while
allowing access to OpenWire and the 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 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:

• Conﬁgure Additional Broker Settings (p. 85)

• Security Groups for your VPC
• Default Security Group for Your VPC
• Working with Security Groups

169
Amazon MQ Developer Guide
Accessing CloudWatch metrics

Logging and monitoring Amazon

MQ brokers
Monitoring is an important part of maintaining the reliability, availability, and performance of your AWS
solutions. You should collect monitoring data from all of the parts of your AWS solution so that you can
more easily debug a multi-point failure if one occurs. AWS provides several tools for monitoring your
Amazon MQ resources and responding to potential incidents:

Topics
• Accessing CloudWatch metrics for Amazon MQ (p. 170)
• Monitoring Amazon MQ brokers using Amazon CloudWatch (p. 173)
• Logging Amazon MQ API calls using AWS CloudTrail (p. 182)
• Conﬁguring Amazon MQ to publish logs to Amazon CloudWatch Logs (p. 185)

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. 173).

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.
For ActiveMQ brokers, CloudWatch monitors only the ﬁrst 200 destinations.
For RabbitMQ brokers, CloudWatch monitors only the ﬁrst 500 destinations, ordered by number
of consumers.

Topics
• AWS Management Console (p. 170)
• AWS Command Line Interface (p. 172)
• Amazon CloudWatch API (p. 173)

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.

170
Amazon MQ Developer Guide
AWS Management Console

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.

171
Amazon MQ Developer Guide
AWS Command Line Interface

5. You can now examine your Amazon MQ metrics:

• To sort the metrics, use the column heading.

• To graph the metric, select the check box next to the metric.
• To ﬁlter 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.

172
Amazon MQ Developer Guide
Amazon CloudWatch API

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.

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, see Accessing CloudWatch metrics for Amazon MQ (p. 170).
Note
The following statistics are valid for all of the metrics:

• Average
• Minimum
• Maximum
• Sum

The AWS/AmazonMQ namespace includes the following metrics.

Topics
• Logging and monitoring Amazon MQ for ActiveMQ brokers (p. 173)
• Logging and monitoring Amazon MQ for RabbitMQ brokers (p. 178)

Logging and monitoring Amazon MQ for ActiveMQ

brokers
Amazon MQ for ActiveMQ metrics

Metric Unit Description

AmqpMaximumConnections Count The maximum number of

clients you can connect to your
broker using AMQP. For more
information on connection
quotas, see Quotas in Amazon
MQ (p. 190).

BurstBalance Percent The percentage of burst credits

remaining on the Amazon EBS
volume used to persist message

173
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for ActiveMQ brokers

Metric Unit Description

data for throughput-optimized
brokers. If this balance reaches
zero, the IOPS provided by
the Amazon EBS volume will
decrease until the Burst Balance
reﬁlls. For more information
on how Burst Balances work in
Amazon EBS, see: I/O Credits
and Burst Performance.

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 ﬁve-
minute intervals.

The number of earned CPU

credits that an instance has
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

Amazon 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.

HeapUsage Percent The percentage of the ActiveMQ

JVM memory limit that the
broker currently uses.

174
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for ActiveMQ brokers

Metric Unit Description

Count
InactiveDurableTopicSubscribersCount The number of inactive durable
topic subscribers, up to a
maximum of 2000.

Percent
JobSchedulerStorePercentUsage The percentage of disk space
used by the job scheduler store.

JournalFilesForFastRecoveryCount The number of journal ﬁles that

will be replayed after a clean
shutdown.

JournalFilesForFullRecoveryCount The number of journal ﬁles that

will be replayed after an unclean
shutdown.

MqttMaximumConnections Count The maximum number of

clients you can connect to your
broker using MQTT. For more
information on connection
quotas, see Quotas in Amazon
MQ (p. 190).

Count
NetworkConnectorConnectionCount The number of nodes connected
to the broker in a network
of brokers (p. 46) using
NetworkConnector.

NetworkIn Bytes The volume of incoming traﬃc

for the broker.

NetworkOut Bytes The volume of outgoing traﬃc

for the broker.

OpenTransactionCount Count The total number of transactions

in progress.

OpenwireMaximumConnections Count The maximum number of clients

you can connect to your broker
using OpenWire. For more
information on connection
quotas, see Quotas in Amazon
MQ (p. 190).

StompMaximumConnections Count The maximum number of

clients you can connect to your
broker using STOMP. For more
information on connection
quotas, see Quotas in Amazon
MQ (p. 190).

StorePercentUsage Percent The percent used by the storage

limit. If this reaches 100, the
broker will refuse messages.

TempPercentUsage Percent The percentage of available

temporary storage used by non-
persistent messages.

175
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for ActiveMQ brokers

Metric Unit Description

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.

VolumeReadOps Count The number of read operations

performed on the Amazon EBS
volume.

VolumeWriteOps Count The number of write operations

performed on the Amazon EBS
volume.

WsMaximumConnections Count The maximum number of clients

you can connect to your broker
using WebSocket. For more
information on connection
quotas, see Quotas in Amazon
MQ (p. 190).

Dimensions for ActiveMQ broker metrics

Dimension Description

Broker The name of the broker

Note
A single-instance broker has the suﬃx
-1. An active/standby broker for high
availability has the suﬃxes -1 and -2 for
its redundant pair.

ActiveMQ destination (queue and topic) metrics

Important
The following metrics include per-minute counts for the CloudWatch polling period.

• EnqueueCount
• ExpiredCount
• DequeueCount
• DispatchCount
• InFlightCount

176
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for ActiveMQ brokers

For example, in a five-minute CloudWatch period, EnqueueCount has five count values, each
for a one-minute portion of the period. The Minimum and Maximum statistics provide the lowest
and highest per-minute value during the specified period.

Metric Unit Description

ConsumerCount Count The number of consumers

subscribed to the destination.

EnqueueCount Count The number of messages sent to

the destination, per minute.

EnqueueTime Time (milliseconds) The end-to-end latency from

when a message arrives at a
broker until it is delivered to a
consumer.
Note
EnqueueTime does
not measure the end-
to-end latency from
when a message is sent
by a producer until it
reaches the broker,
nor the latency from
when a message is
received by a broker
until it is acknowledged
by the broker. Rather,
EnqueueTime is the
number of milliseconds
from the moment a
message is received by
the broker until it is
successfully 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.

InFlightCount Count The number of messages sent to

consumers that have not been
acknowledged.

ReceiveCount Count The number of messages that

have been received from the
remote broker for a duplex
network connector.

177
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for RabbitMQ brokers

Metric Unit Description

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.

TotalEnqueueCount Count The total number of messages

that have been sent to the
broker.

TotalDequeueCount Count The total number of messages

that have been consumed by
clients.

Note
TotalEnqueueCount and TotalDequeueCount metrics include messages for advisory topics.
For more information about advisory topic messages, see the ActiveMQ documentation.

Dimensions for ActiveMQ destination (queue and topic) metrics

Dimension Description

Broker The name of the broker.

Note
A single-instance broker has the suﬃx
-1. An active/standby broker for high
availability has the suﬃxes -1 and -2 for
its redundant pair.

Topic or Queue The name of the topic or queue.

NetworkConnector The name of the network connector.

Logging and monitoring Amazon MQ for RabbitMQ

brokers
RabbitMQ broker metrics

Metric Unit Description

ExchangeCount Count The total number of exchanges

conﬁgured on the broker.

178
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for RabbitMQ brokers

Metric Unit Description

QueueCount Count The total number of queues

conﬁgured on the broker.

ConnectionCount Count The total number of connections

established on the broker.

ChannelCount Count The total number of channels

established on the broker.

ConsumerCount Count The total number of consumers

connected to the broker.

MessageCount Count The total number of messages in

the queues.
Note
The number produced is
the total sum of ready
and unackknowledged
messages on the broker.

MessageReadyCount Count The total number of ready

messages in the queues.

MessageUnacknowledgedCount Count The total number of

unacknowledged messages in
the queues.

PublishRate Count The rate at which messages are

published to the broker.

The number produced

represents the number of
messages per second at the time
of sampling.

ConfirmRate Count The rate at which the RabbitMQ

server is conﬁrming published
messages. You can compare this
metric with PublishRate to
better understand how your
broker is performing.

The number produced

represents the number of
messages per second at the time
of sampling.

AckRate Count The rate at which messages

are being acknowledged by
consumers.

The number produced

represents the number of
messages per second at the time
of sampling.

179
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for RabbitMQ brokers

Metric Unit Description

SystemCpuUtilization Percent The percentage of allocated

Amazon EC2 compute units
that the broker currently uses.
For cluster deployments, this
value represents the aggregate
of all three RabbitMQ nodes'
correspondig metric values.

RabbitMQMemLimit Bytes The RAM limit for a RabbitMQ

broker. For cluster deployments,
this value represents the
aggregate of all three RabbitMQ
nodes' correspondig metric
values.

RabbitMQMemUsed Bytes The volume of RAM used

by a RabbitMQ broker. For
cluster deployments, this value
represents the aggregate of
all three RabbitMQ nodes'
correspondig metric values.

RabbitMQDiskFreeLimit Bytes The disk limit for a RabbitMQ

broker. For cluster deployments,
this value represents the
aggregate of all three RabbitMQ
nodes' correspondig metric
values. This metric is diﬀerent
per instance size. For more
information about Amazon
MQ instance types, see the
section called “Amazon
MQ for RabbitMQ instance
types” (p. 33).

RabbitMQDiskFree Bytes The total volume of free disk

space available in a RabbitMQ
broker. When disk usage goes
above its limit, the cluster will
block all producer connections.
For cluster deployments, this
value represents the aggregate
of all three RabbitMQ nodes'
correspondig metric values.

RabbitMQFdUsed Count Number of ﬁle descriptors used.

For cluster deployments, this
value represents the aggregate
of all three RabbitMQ nodes'
correspondig metric values.

180
Amazon MQ Developer Guide
Logging and monitoring Amazon MQ for RabbitMQ brokers

Dimensions for RabbitMQ broker metrics

Dimension Description

Broker The name of the broker.

RabbitMQ node metrics

Metric Unit Description

SystemCpuUtilization Percent The percentage of allocated

Amazon EC2 compute units that
the broker currently uses.

RabbitMQMemLimit Bytes The RAM limit for a RabbitMQ

node.

RabbitMQMemUsed Bytes The volume of RAM used by a

RabbitMQ node. When memory
use goes above the limit, the
cluster will block all producer
connections.

RabbitMQDiskFreeLimit Bytes The disk limit for a RabbitMQ

node. This metric is diﬀerent
per instance size. For more
information about Amazon
MQ instance types, see the
section called “Amazon
MQ for RabbitMQ instance
types” (p. 33).

RabbitMQDiskFree Bytes The total volume of free disk

space available in a RabbitMQ
node. When disk usage goes
above its limit, the cluster will
block all producer connections.

RabbitMQFdUsed Count Number of ﬁle descriptors used.

Dimensions for RabbitMQ node metrics

Dimension Description

Node The name of the node.

Note
A node name consists of two
parts: a preﬁx (usuallly rabbit)
and a hostname. For example,
[email protected]
west-2.compute.internal is a
node name with the preﬁx rabbit and

181
Amazon MQ Developer Guide
Logging API calls using CloudTrail

Dimension Description
the hostname ip-10-0-0-230.us-
west-2.compute.internal.

Broker The name of the broker.

RabbitMQ queue metrics

Metric Unit Description

ConsumerCount Count The number of consumers

subscribed to the queue.

MessageReadyCount Count The number of messages that

are currently available to be
delivered.

MessageUnacknowledgedCount Count The number of messages for

which the server is awaiting
acknowledgement.

MessageCount Count The total number of

MessageReadyCount and
MessageUnacknowledgedCount
(also known as queue depth).

Dimensions for RabbitMQ queue metrics

Note
Amazon MQ for RabbitMQ will not publish metrics for virtual hosts and queues with names
containing blank spaces, tabs or other non-ASCII characters.
For more information about dimension names, see Dimension in the Amazon CloudWatch API
Reference.

Dimension Description

Queue The name of the queue.

VirtualHost The name of the virtual host.

Broker The name of the broker.

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
conﬁgurations 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.

182
Amazon MQ Developer Guide
Amazon MQ Information in CloudTrail

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 conﬁgure Amazon MQ to publish general and audit logs to Amazon
CloudWatch Logs (p. 185).

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

• Conﬁguring Amazon SNS Notiﬁcations 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 ﬁles:

• 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
• DescribeConfiguration
• DescribeConfigurationRevision
• DescribeUser
• ListBrokers
• ListConfigurationRevisions
• ListConfigurations

183
Amazon MQ Developer Guide
Example Amazon MQ Log File Entry

• 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 ﬁles aren't an ordered stack trace of public APIs, they don't list
information in any speciﬁc 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",
"userAgent": "PostmanRuntime/7.1.5",
"requestParameters": {
"engineVersion": "5.15.9",
"deploymentMode": "ACTIVE_STANDBY_MULTI_AZ",
"maintenanceWindowStartTime": {
"dayOfWeek": "THURSDAY",
"timeOfDay": "22:45",

184
Amazon MQ Developer Guide
Conﬁguring Amazon MQ to
publish logs to CloudWatch Logs

"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"
}

Conﬁguring Amazon MQ to publish 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 ActiveMQ broker configuration (p. 57) errors. For more
information about CloudWatch Logs, see the Amazon CloudWatch Logs User Guide

Topics
• Conﬁguring Amazon MQ for ActiveMQ logs (p. 186)
• Conﬁguring Amazon MQ for RabbitMQ logs (p. 189)

185
Amazon MQ Developer Guide
Conﬁguring Amazon MQ for ActiveMQ logs

Conﬁguring Amazon MQ for ActiveMQ logs

To allow Amazon MQ to publish logs to CloudWatch Logs, you must add a permission to your Amazon
MQ user (p. 186) and also conﬁgure a resource-based policy for Amazon MQ (p. 187) before you
create or restart the broker.

The following describes the steps to conﬁgure CloudWatch logs for your ActiveMQ brokers.

Topics
• Understanding the structure of logging in CloudWatch Logs (p. 186)
• Add the CreateLogGroup permission to your Amazon MQ user (p. 186)
• Conﬁgure a resource-based policy for Amazon MQ (p. 187)
• Cross-service confused deputy prevention (p. 188)
• Troubleshooting CloudWatch Logs Conﬁguration (p. 189)

Understanding the structure of logging in CloudWatch Logs

You can enable general and audit logging when you conﬁgure advanced broker settings (p. 85) 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. 45) or an active/standby broker (p. 46),
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 suﬃxes 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 IAM 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 for users to
whom this policy is attached.

186
Amazon MQ Developer Guide
Conﬁguring Amazon MQ for ActiveMQ logs

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:*:*:log-group:/aws/amazonmq/*"
}
]
}

Note
Here, the term user refers to IAM Users and not Amazon MQ users, which are created when a
new broker is conﬁgured. For more information regarding setting up IAM users and conﬁguring
IAM policies, please refer to the Identity Management Overview section of the IAM User Guide.

For more information, see CreateLogGroup in the Amazon CloudWatch Logs API Reference.

Conﬁgure a resource-based policy for Amazon MQ

Important
If you don't conﬁgure a resource-based policy for Amazon MQ, the broker can't publish the logs
to CloudWatch Logs.

To allow Amazon MQ to publish logs to your CloudWatch Logs log group, conﬁgure 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 speciﬁed log group.
• PutLogEvents – Delivers events to the speciﬁed CloudWatch Logs log stream.

The following resource-based policy grants permission for logs:CreateLogStream and

logs:PutLogEvents to AWS.

This resource-based policy must be conﬁgured by using the AWS CLI as shown by the following
command. In the example, replace us-east-1 with your own information.

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\"], \"Resource\":
\"arn:aws:logs:*:*:log-group:\/aws\/amazonmq\/*\" }]}"

Note
Because this example uses the /aws/amazonmq/ preﬁx, you need to conﬁgure the resource-
based policy only once per AWS account, per region.

187
Amazon MQ Developer Guide
Conﬁguring Amazon MQ for ActiveMQ logs

Cross-service confused deputy prevention

The confused deputy problem is a security issue where an entity that doesn't have permission to perform
an action can coerce a more-privileged entity to perform the action. In AWS, cross-service impersonation
can result in the confused deputy problem. Cross-service impersonation can occur when one service (the
calling service) calls another service (the called service). The calling service can be manipulated to use its
permissions to act on another customer's resources in a way it should not otherwise have permission to
access. To prevent this, AWS provides tools that help you protect your data for all services with service
principals that have been given access to resources in your account.

We recommend using the aws:SourceArn and aws:SourceAccount global condition context keys
in your Amazon MQ resource-based policy to limit CloudWatch Logs access to one or more speciﬁed
brokers.
Note
If you use both global condition context keys, the aws:SourceAccount value and the account
in the aws:SourceArn value must use the same account ID when used in the same policy
statement.

The following example demonstrates a resource-based policy that limits CloudWatch Logs access to a
single Amazon MQ broker.

{
"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/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012",
"aws:SourceArn": "arn:aws:mq:us-
east-2:123456789012:broker:MyBroker:b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9"
}
}
}
]
}

You can also conﬁgure your resource-based policy to limit CloudWatch Logs access to all brokers in an
account, as shown in the following.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"mq.amazonaws.com"
]
},
"Action": [
"logs:CreateLogStream",

188
Amazon MQ Developer Guide
Conﬁguring Amazon MQ for RabbitMQ logs

"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:*:*:log-group:/aws/amazonmq/*",
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:mq:*:123456789012:broker:*"
},
"StringEquals": {
"aws:SourceAccount": "123456789012"
}
}
}
]
}

For more information about the confused deputy security issue, see The confused deputy problem in the
IAM User Guide.

Troubleshooting CloudWatch Logs Conﬁguration

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. 186) and reboot the broker. This
allows Amazon MQ to create the log group.

Log Streams Don't Appear in CloudWatch Log Groups

Conﬁgure a resource-based policy for Amazon MQ (p. 187). This allows your broker to publish its logs.

Conﬁguring Amazon MQ for RabbitMQ logs

When you enable CloudWatch logging for your RabbitMQ brokers, Amazon MQ uses a service-linked role
to publish general logs to CloudWatch. If no Amazon MQ service-linked role exists when you ﬁrst create
a broker, Amazon MQ will automatically create one. All subsequent RabbitMQ brokers will use the same
service-linked role to publish logs to CloudWatch.

For more information about service-linked roles, see Using service-linked roles in the AWS Identity and
Access Management User Guide. For more information about how Amazon MQ uses service-linked roles,
see the section called “Using service-linked roles” (p. 162).
Note
Audit logging is not supported for RabbitMQ brokers.

189
Amazon MQ Developer Guide
Brokers

Quotas in Amazon MQ
This topic lists quotas within Amazon MQ. Many of the following quotas can be changed for speciﬁc AWS
accounts. To request an increase for a limit, see AWS Service Quotas in the Amazon Web Services General
Reference.

Topics
• Brokers (p. 190)
• Conﬁgurations (p. 190)
• Users (p. 191)
• Data Storage (p. 191)
• API Throttling (p. 192)

Brokers
The following table lists quotas 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 speciﬁed in the
ASCII Printable Character Set.
• Can contain only alphanumeric characters,
dashes, periods, underscores, and tildes (- . _
~).

Number of brokers, per region 50

Wire-level connections per protocol for smaller Important

broker Does not apply to RabbitMQ brokers.
100 for mq.*.micro instance type brokers.

Wire-level connections per protocol for larger Important

broker Does not apply to RabbitMQ brokers.
1,000 for mq.*.*large instance type brokers.

Security groups per broker 5

ActiveMQ destinations (queues, and topics) CloudWatch monitors only the ﬁrst 200
monitored in CloudWatch destinations.

RabbitMQ destinations (queues) monitored in CloudWatch monitors only the ﬁrst 500
CloudWatch destinations, ordered by number of consumers.

Tags per broker 50

Conﬁgurations
The following table lists quotas related to Amazon MQ conﬁgurations.

190
Amazon MQ Developer Guide
Users

Important
Does not apply to RabbitMQ brokers.

Limit Description

Conﬁguration name • Must be 1-150 characters long.

• Must contain only characters speciﬁed in the
ASCII Printable Character Set.
• Can contain only alphanumeric characters,
dashes, periods, underscores, and tildes (- . _
~).

Revisions per conﬁguration 300

Users
The following table lists quotas related to Amazon MQ ActiveMQ broker users.
Important
Does not apply to RabbitMQ brokers.

Limit Description

Username • Must be 1-100 characters long.

• Must contain only characters speciﬁed in the
ASCII Printable Character Set.
• Can contain only alphanumeric characters,
dashes, periods, underscores, and tildes (- . _
~).
• Must not contain commas (,).

Password • Must be 12-250 characters long.

• Must contain only characters speciﬁed in the
ASCII Printable Character Set.
• Must contain at least 4 unique characters.
• Must not contain commas (,).

Users per broker (simple auth) 250

Groups per user (simple auth) 20

Data Storage
The following table lists quotas related to Amazon MQ data storage.

Limit Description

Storage capacity per smaller broker 20 GB for mq.*.micro instance type brokers. For
more information regarding Amazon MQ instance
types, see Broker instance types (p. 30).

191
Amazon MQ Developer Guide
API Throttling

Limit Description

Storage capacity per larger broker 200 GB for mq.*.*large instance type brokers.
For more information regarding Amazon MQ
instance types, see Broker instance types (p. 30).

Job scheduler usage limit per broker backed by Important

Amazon EBS (p. 43) Does not apply to RabbitMQ brokers.
50 GB. For more information about job scheduler
usage, see JobSchedulerUsage in the Apache
ActiveMQ API Documentation.

Temporary storage capacity per smaller broker. Important

Does not apply to RabbitMQ brokers.
5 GB for mq.*.micro instance type brokers.

Temporary storage capacity per larger broker. Important

Does not apply to RabbitMQ brokers.
50 GB for mq.*.*large instance type brokers.

API Throttling
The following throttling quotas 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.
Important
These quotas don't apply to Amazon MQ for ActiveMQ or Amazon MQ for RabbitMQ broker
messaging APIs. For example, Amazon MQ doesn't throttle the sending or receiving of
messages.

API burst limit API rate limit

100 15

192
Amazon MQ Developer Guide
Troubleshooting: General

Troubleshooting Amazon MQ
This section describes common issues you might encounter when using Amazon MQ brokers, and the
steps you can take to resolve them.

Contents
• Troubleshooting: General (p. 193)
• I can't connect to my broker web console or endpoints. (p. 194)
• My broker is running, and I can verify connectivity using telnet, but my clients are unable to
connect and are returning SSL exceptions. (p. 197)
• I created a broker but broker creation failed. (p. 197)
• My broker restarted and I'm not sure why. (p. 197)
• Troubleshooting: Amazon MQ for ActiveMQ (p. 198)
• I can't see general or audit logs for my broker in CloudWatch Logs even though I’ve
activated logging. (p. 198)
• After broker restart or maintenance window, I can't connect to my broker even though the
status is RUNNING. Why? (p. 199)
• I see some of my clients connecting to the broker, while others are unable to
connect. (p. 199)
• I'm seeing exception org.apache.jasper.JasperException: An exception occurred processing
JSP page on the ActiveMQ console when performing operations. (p. 200)
• Troubleshooting: Amazon MQ for RabbitMQ (p. 200)
• I can’t see metrics for my queues or virtual hosts in CloudWatch. (p. 200)
• How do I enable plugins in Amazon MQ for RabbitMQ? (p. 201)
• I'm unable to change Amazon VPC conﬁguration for the broker. (p. 201)
• Troubleshooting: Amazon MQ action required codes (p. 201)
• Amazon MQ for RabbitMQ: High memory alarm (p. 201)
• Diagnosing high memory alarm using the RabbitMQ web console (p. 202)
• Diagnosing high memory alarm using Amazon MQ metrics (p. 202)
• Addressing high memory alarm (p. 203)
• Reducing the number of connections and channels (p. 204)
• Addressing paused queue synchronizations in cluster deployments (p. 204)
• Addressing restart loops in single-instance brokers (p. 205)
• Preventing high memory alarms (p. 205)

Troubleshooting: General
Use the information in this section to help you diagnose common issues you might encounter when
working with Amazon MQ brokers, such as issues connecting to your broker, and broker reboots.

Contents
• I can't connect to my broker web console or endpoints. (p. 194)
• My broker is running, and I can verify connectivity using telnet, but my clients are unable to connect
and are returning SSL exceptions. (p. 197)
• I created a broker but broker creation failed. (p. 197)

193
Amazon MQ Developer Guide
I can't connect to my broker web console or endpoints.

• My broker restarted and I'm not sure why. (p. 197)

I can't connect to my broker web console or

endpoints.
If you're experiencing issues connecting to your broker using the web console or wire-level endpoints, we
recommend the following steps.

1. Check whether you're attempting to connect to your broker from behind a firewall. You might need to
configure the firewall to allow access to your broker.
2. Check whether you're trying to connect to your broker using a FIPS endpoint. Amazon MQ only
supports FIPS endpoints when using API operations, and not for wire-level connections to the broker
instance itself.
3. Check if the Public Accessibility option for your broker is set to Yes. If this is set to No, check your
subnet's network Access Control List (ACL) rules. If you've created custom network ACLs, you might
need to change the network ACL rules to provide access to your broker. For more information about
Amazon VPC networking, see Enabling internet access in the Amazon VPC User Guide
4. Check your broker's Security Group rules. Make sure that you are allowing connections to the
following ports:
Note
The following ports are grouped according to engine types because Amazon MQ for
ActiveMQ and Amazon MQ for RabbitMQ use different ports for connections.

Amazon MQ for ActiveMQ

• Web console – Port 8162
• OpenWire – Port 61617
• AMQP – Port 5671
• STOMP – Port 61614
• MQTT – Port 8883
• WSS – Port 61619

Amazon MQ for RabbitMQ

• Web console and management API – Port 443 and 15671
• AMQP – Port 5671
5. Run the following network connectivity tests for your broker engine type.
Note
For brokers without public accessibility, run the tests from an Amazon EC2 instance within the
same Amazon VPC as your Amazon MQ broker and evaluate the responses.
Amazon MQ for ActiveMQ

To test your Amazon MQ for ActiveMQ broker's network connectivity

1. Open a new terminal or command line window.

2. Run the following nslookup command to query your broker DNS record. For active/
standby (p. 46) deployments, test both the active and standby endpoints. The active/standby
endpoints are identiﬁed with a suﬃx, -1 or -2 added to the unique broker ID. Replace the
endpoint with your information.

$ nslookup b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com

194
Amazon MQ Developer Guide
I can't connect to my broker web console or endpoints.

If the query succeeds, you will see an output similar to the following.

Non-authoritative answer:
Server: dns-resolver-corp-sfo-1.sfo.corp.amazon.com
Address: 172.10.123.456

Name: ec2-12-345-123-45.us-west-2.compute.amazonaws.com
Address: 12.345.123.45
Aliases: b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com

The resolved IP address should match the IP addresses provided in the Amazon MQ console.
This indicates that the domain name is resolving correctly on the DNS server, and you can
move on to the next step.
3. Run the following telnet command to test the network path for your broker. Replace the
endpoint with your information. Replace port with port number 8162 for the web console,
or other wire-level ports to test additional protocols as needed.
Note
For active/standby deployments, you will receive a Connect failed error message
if you run telnet with the standby endpoint. This is expected, as the standby
instance itself is running, but the ActiveMQ process is not running and does not have
access to the broker's Amazon EFS storage volume. Run the command for both -1
and -2 endpoints to ensure you test both the active and the standby instances.

$ telnet b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com port

For the active instance, you will see an output similar to the following.

Connected to b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com.
Escape character is '^]'.

4. Do one of the following.

• If the telnet command succeeds, check the EstablishedConnectionsCount (p. 173)
metric and confirm that the broker has not reached the maximum Wire-level connection
limit (p. 190). You can also confirm if the limit has been reached by reviewing the broker
General logs. If this metric is greater than zero, then there is at least one client currently
connected to the broker. If the metric shows zero connections, then perform the telnet
path test again and wait at least one minute before disconnecting, as broker metrics are
published every minute.
• If the telnet command fails, check the status of your broker's elastic network interface,
and confirm that the status is in-use. Create an Amazon VPC flow log for each instance's
network interface, and review the generated flow logs. Look for the broker's IP addresses
when you ran the telnet command, and confirm the connection packets are ACCEPTED,
including a return packet. For more information, and to see a flow log example, see Flow
log record examples in the Amazon VPC Developer Guide.
5. Run the following curl command to check connectivity to the ActiveMQ admin web console.

$ curl https://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
west-2.amazonaws.com:8162/index.html

If the command succeeds, the output should be an HTML document similar to the following.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://

www.w3.org/TR/html4/loose.dtd">
<html>

195
Amazon MQ Developer Guide
I can't connect to my broker web console or endpoints.

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /
>
<title>Apache ActiveMQ</title>
...

Amazon MQ for RabbitMQ

To test your Amazon MQ for RabbitMQ broker's network connectivity

1. Open a new terminal or command line window.

2. Run the following nslookup command to query your broker DNS record. Replace the
endpoint with your information.

$ nslookup b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com

If the query succeeds, you will see an output similar to the following.

Non-authoritative answer:
Server: dns-resolver-corp-sfo-1.sfo.corp.amazon.com
Address: 172.10.123.456

Name: rabbit-broker-1c23e456ca78-b9000123b4ebbab5.elb.us-west-2.amazonaws.com
Addresses: 52.12.345.678
52.23.234.56
41.234.567.890
54.123.45.678
Aliases: b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com

3. Run the following telnet command to test the network path for your broker. Replace the
endpoint with your information. You can replace port with port 443 for the web console,
and 5671 to test the wire-level AMQP connection.

$ telnet b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com port

If the command succeeds, you'll see an output similar to the following.

Connected to b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-west-2.amazonaws.com.
Escape character is '^]'.

Note
The telnet connection will close automatically after a few seconds.
4. Do one of the following.
• If the telnet command succeeds, check the ConnectionCount (p. 178) metric and
confirm that the broker has not reached the value set in the max-connections (p. 122)
default policy. You can also confirm if the limit has been reached by reviewing the broker
Connection.log log group. If this metric is greater than zero, there is at least one client
currently connected to the broker. If the metric shows zero connections, then perform
the telnet path test again. You may need to repeat this process if the connection closes
before your broker has published new connection metrics to CloudWatch. Metrics are
published every minute.
• For brokers without public accessibility, if the telnet command fails, check the status
of your broker's elastic network interfaces, and confirm that the status is in-use. Create
an Amazon VPC flow log for each network interface, and review the generated flow logs.
Look for the broker's private IP addresses when you the telnet command was invoked,
196
Amazon MQ Developer Guide
SSL exceptions

and conﬁrm the connection packets are ACCEPTED, including a return packet. For more
information, and to see a ﬂow log example, see Flow log record examples in the Amazon
VPC Developer Guide.
Note
This step does not apply to Amazon MQ for RabbitMQ brokers with public
accessibility.
5. Run the following curl command to check connectivity to the RabbitMQ admin web console.

$ curl https://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-
west-2.amazonaws.com:443/index.html

If the command succeeds, the output should be an HTML document similar to the following.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>RabbitMQ Management</title>
...

My broker is running, and I can verify connectivity

using telnet, but my clients are unable to connect
and are returning SSL exceptions.
Your broker endpoint certiﬁcate may have been updated during the broker maintenance window (p. 19).
Amazon MQ broker certiﬁcates are rotated periodically to ensure continued availability and security of
brokers.

We recommend using the Amazon root certificate authority (CA) in Amazon Trust Services to
authenticate against in your clients' trust store. All Amazon MQ broker certificates are signed with this
root CA. By using an Amazon root CA, you will no longer need to download the new Amazon MQ broker
certificate every time there is a certificate update on the broker.

I created a broker but broker creation failed.

If your broker is in a CREATION_FAILED status, do the following.

• Check your IAM permissions. To create a broker must either use the AWS managed IAM policy
AmazonMQFullAccess or have the correct set of Amazon EC2 permissions in your custom IAM policy.
To learn more about the required Amazon EC2 permissions you need, see IAM permissions required to
create an Amazon MQ broker (p. 158).
• Check if the subnet you are choosing for your broker is in a shared Amazon Virtual Private Cloud (VPC).
To create an Amazon MQ broker in a shared Amazon VPC, you must create it in the account that owns
the Amazon VPC.

My broker restarted and I'm not sure why.

If your broker has restarted automatically, it may be due to one of the following reasons.

197
Amazon MQ Developer Guide
Troubleshooting: Amazon MQ for ActiveMQ

• Your broker may have restarted because of a scheduled weekly maintenance window. Periodically,
Amazon MQ performs maintenance to the hardware, operating system, or the engine software of a
message broker. The duration of the maintenance varies, but can last up to two hours, depending on
the operations that are scheduled for your message broker. Brokers might restart at any point during
the two hour maintenance window. For more information about broker maintenance windows, see the
section called “Maintaining a broker” (p. 19).
• Your broker instance type might not be suitable to your application workload. For example, running
a production workload on a mq.t2.micro might result in the broker running out of resources. High
CPU utilization, or high broker memory usage can cause a broker to unexpectedly restart. To see how
much CPU and memory is being utilized by your broker, use the following CloudWatch metrics for your
engine type.
• Amazon MQ for ActiveMQ – Check CpuUtilization for the percentage of allocated Amazon EC2
compute units that the broker currently uses. Check HeapUsagefor the percentage of the ActiveMQ
JVM memory limit that the broker currently uses.
• Amazon MQ for RabbitMQ – Check SystemCpuUtilization for the percentage of allocated
Amazon EC2 compute units that the broker currently uses. Check RabbitMQMemUsed for the volume
of RAM used in Bytes, and divide by RabbitMQMemLimit for the percentage of memory used by the
RabbitMQ node.

For more information about broker instance types and how to choose the right instance type for your
workload, see Broker instance types (p. 30).

Troubleshooting: Amazon MQ for ActiveMQ

Use the information in this section to help you diagnose and resolve common issues you might
encounter when working with Amazon MQ for ActiveMQ brokers.

Contents
• I can't see general or audit logs for my broker in CloudWatch Logs even though I’ve activated
logging. (p. 198)
• After broker restart or maintenance window, I can't connect to my broker even though the status is
RUNNING. Why? (p. 199)
• I see some of my clients connecting to the broker, while others are unable to connect. (p. 199)
• I'm seeing exception org.apache.jasper.JasperException: An exception occurred processing JSP page
on the ActiveMQ console when performing operations. (p. 200)

I can't see general or audit logs for my broker in

CloudWatch Logs even though I’ve activated logging.
If you’re unable to view logs for your broker in CloudWatch Logs, do the following.

1. Check if the IAM user who creates or reboots the broker has the logs:CreateLogGroup permission.
If you don't add the CreateLogGroup permission to a user before the user creates or reboots the
broker, Amazon MQ will not create the log group.
2. Check if you have configured a resource-based policy to allow Amazon MQ to publish logs to
CloudWatch Logs. 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.

198
Amazon MQ Developer Guide
Connecting to broker after a restart

For more information about conﬁguring Amazon MQ for ActiveMQ to publish logs to CloudWatch Logs,
see Conﬁguring logging.

After broker restart or maintenance window, I can't

connect to my broker even though the status is
RUNNING. Why?
You might be encountering connection issues after a broker restart you initiated, after a scheduled
maintenance window is completed, or in a failure event, where the standby instance is activated. In
either case, connection issues following a broker restart are most likely caused by unusually large
numbers of messages persisted in your broker's Amazon EFS or Amazon EBS storage volume. During
a restart, Amazon MQ moves persisted messages from storage to broker memory. To conﬁrm this
diagnosis, you can monitor the following metrics on CloudWatch for your Amazon MQ for ActiveMQ
broker:

• StoragePercentUsage — Large percentages at or close to 100 percent can cause the broker to
refuse connections.
• JournalFilesForFullRecovery — Indicates the number of of journal ﬁles that will be replayed
following an unclean shutdown and restart. An increasing, or consistently higher than one, value
indicates unresolved transactions that can cause connection issues after restart.
• OpenTransactionCount — A number larger than zero following a restart indicates that the broker
will attempt to store previously consumed messages, as a result causing connection issues.

To resolve this issue, we recommend resolving your XA transactions with either a rollback() or
a commid(). For more information, and to see a code example of resolving XA transactions using
rollback(), see recovering XA transactions (p. 117).

I see some of my clients connecting to the broker,

while others are unable to connect.
If your broker is in the RUNNING status and some clients are able to connect to the broker successfully,
while others are unable to do so, you may have reached the wire-level connections (p. 190) limit for the
broker. To verify that you've reached the wire-level connections limit, do the following:

• Check the general broker logs for your Amazon MQ for ActiveMQ broker in CloudWatch Logs. If
the limit has been reached, you will see Reached Maximum Connections in the broker logs. For
more information on CloudWatch Logs for Amazon MQ for ActiveMQ brokers, see the section called
“Understanding the structure of logging in CloudWatch Logs” (p. 186).

Once the wire-level connections limit is reached, the broker will actively refuse additional incoming
connections. To resolve this issue, we recommend upgrading your broker instance type. For more
information on choosing the best instance type for your workload, see Broker instance types (p. 30).

If you've conﬁrmed that the number of your wire-level connections is less than the broker connection
limit, the issue might be related to rebooting clients. Check your broker logs for numerous and frequent
entries of ... Inactive for longer than 600000 ms - removing .... The log entry is
indicative of rebooting clients or connectivity issues. This eﬀect is more evident when clients connect to
the broker via a Network Load Balancer (NLB) with clients that frequently disconnect and reconnect to
the broker. This is more typically observed in container based clients.

Check your client-side logs for further details. The broker will clean up inactive TCP connections after
600000 ms, and free up the connection socket.

199
Amazon MQ Developer Guide
JSP exception on the web console

I'm seeing exception

org.apache.jasper.JasperException: An
exception occurred processing JSP page on
the ActiveMQ console when performing operations.
If you are using simple authentication and configuring AuthorizationPlugin for queue and topic
authorization, make sure to use the AuthorizationEntries element in your XML configuration file,
and allow the activemq-webconsole group permission to all queues and topics. This ensures that the
ActiveMQ web console can communicate with the ActiveMQ broker.

The following example AuthorizationEntry grants read and write permissions for all queues and
topics to the activemq-webconsole group.

<authorizationEntries>
<authorizationEntry admin="activemq-webconsole,admins,users" topic=">" read="activemq-
webconsole,admins,users" write="activemq-webconsole,admins,users" />
<authorizationEntry admin="activemq-webconsole,admins,users" queue=">" read="activemq-
webconsole,admins,users" write="activemq-webconsole,admins,users" />
</authorizationEntries>

Similarly when integrating your broker with LDAP, make sure to grant permission for the amazonmq-
console-admins group. For more information about LDAP integration, see the section called “How
LDAP integration works” (p. 104).

Troubleshooting: Amazon MQ for RabbitMQ

Use the information in this section to help you diagnose and resolve common issues you might
encounter when working with Amazon MQ for RabbitMQ brokers.

Contents
• I can’t see metrics for my queues or virtual hosts in CloudWatch. (p. 200)
• How do I enable plugins in Amazon MQ for RabbitMQ? (p. 201)
• I'm unable to change Amazon VPC conﬁguration for the broker. (p. 201)

I can’t see metrics for my queues or virtual hosts in

CloudWatch.
If you’re unable to view metrics for your queues or virtual hosts in CloudWatch, check if your queue or
virtual host names contain any blank spaces, tabs, or other non-ASCII characters.

Amazon MQ cannot publish metrics for virtual hosts and queues with names containing blank spaces,
tabs or other non-ASCII characters.

For more information about dimension names, see Dimension in the Amazon CloudWatch API Reference.

200
Amazon MQ Developer Guide
How do I enable plugins in Amazon MQ for RabbitMQ?

How do I enable plugins in Amazon MQ for

RabbitMQ?
Amazon MQ for RabbitMQ currently only supports the RabbitMQ management, shovel, federation,
consistent-hash exchange plugin, which are enabled by default. For more information on using
supported plugins, see the section called “Plugins” (p. 126).

I'm unable to change Amazon VPC conﬁguration for

the broker.
Amazon MQ does not support changing Amazon VPC conﬁguration after your broker is created. Please
note that you will need to create a new broker with the new Amazon VPC conﬁguration and update the
client connection URL with the new broker connection URL.

Troubleshooting: Amazon MQ action required

codes
Amazon MQ returns an exception for certain API operations, such as RebootBroker, if your broker is
in an unhealthy state and requires a set of actions to return to a healthy state. The exceptions include
speciﬁc action required codes that help you to identify a root cause, and address the issue and recover
your broker.

Use the following list of topics to identify the action required code you have received, and learn more
about the steps we recommend to resolve your issue.

Action required codes

• Amazon MQ for RabbitMQ: High memory alarm (p. 201)

Amazon MQ for RabbitMQ: High memory alarm

RabbitMQ will raise a high memory alarm when the broker's memory usage, identified by CloudWatch
metric RabbitMQMemUsed, exceeds the memory limit, identified by RabbitMQMemLimit.
RabbitMQMemLimit is set by Amazon MQ and has been specifically tuned considering the memory
available for each host instance type.

An Amazon MQ for RabbitMQ broker that has raised a high memory alarm will block all clients that are
publishing messages. Due to high memory usage, your broker might also experience other issues that
complicate diagnosis and resolution of the alarm.

Single-instance brokers that can't complete start-up due to high memory usage might enter a restart
loop, during which, interactions with the broker are limited. In cluster deployments, queues might
experience paused synchronization of messages between replicas on diﬀerent nodes. Paused queue
syncs prevent consumption of messages from queues and must be addressed separately while resolving
the memory alarm.

Amazon MQ will not restart a broker experiencing a high memory alarm and will return an exception for
RebootBroker API operations as long as the broker continues to raise the alarm.

Use the information in this section to help you diagnose and resolve RabbitMQ high memory alarms
raised by your broker.

Topics

201
Amazon MQ Developer Guide
RABBITMQ_MEMORY_ALARM

• Diagnosing high memory alarm using the RabbitMQ web console (p. 202)
• Diagnosing high memory alarm using Amazon MQ metrics (p. 202)
• Addressing high memory alarm (p. 203)
• Reducing the number of connections and channels (p. 204)
• Addressing paused queue synchronizations in cluster deployments (p. 204)
• Addressing restart loops in single-instance brokers (p. 205)
• Preventing high memory alarms (p. 205)

Diagnosing high memory alarm using the RabbitMQ web

console
The RabbitMQ web console can generate and display detailed memory usage information for each node.
You can ﬁnd this information by doing the following:

1. Sign in to AWS Management Console and open your broker's RabbitMQ web console.
2. On the RabbitMQ console, on the Overview page, choose the name of a node from the Nodes list.
3. On the node detail page, choose Memory details to expand the section to view the node's memory
usage information.

The memory usage information that RabbitMQ provides in the web console can help you determine
which resources might be consuming too much memory and contributing to the high memory alarm.
For more information about the memory usage details available via the RabbitMQ web console, see
Reasoning About Memory Use on the RabbitMQ Server Documentation website.

Diagnosing high memory alarm using Amazon MQ metrics

Amazon MQ enables metrics for your broker by default. You can view your broker metrics (p. 170) by
accessing the CloudWatch console, or by using the CloudWatch API. The following metrics are useful
when diagnosing the RabbitMQ high memory alarm.

Amazon MQ CloudWatch Reason for high memory use

metric

MessageCount Messages are stored in memory

until they are consumed or
discarded. A high message count
might indicate overutilization of
resources and can lead to a high
memory alarm.

QueueCount Queues are stored in memory,

and a high number of queues
can lead to a high memory
alarm.

ConnectionCount Client connections utilize

memory, and too many
simultaneous connections can
lead to a high memory alarm.

ChannelCount Similar to connections,

channels established using
each connection are also stored

202
Amazon MQ Developer Guide
RABBITMQ_MEMORY_ALARM

Amazon MQ CloudWatch Reason for high memory use

metric
in node memory, and a high
number of channels can lead to
a high memory alarm.

ConsumerCount For every consumer connected

to the broker, a set number
of messages are loaded from
storage into memory before
they are delivered to the
consumer. A large number of
consumer connections might
cause high memory usage and
lead to a high memory alarm.

PublishRate Publishing messages utilizes

the broker' memory. If the
rate at which messages are
published to the broker is too
high and signiﬁcantly outpaces
the rate at which the broker
delivers messages to consumers,
the broker might raise a high
memory alarm.

Addressing high memory alarm

For each contributor that you identify, we recommended the following set of actions to mitigate and
resolve the broker's high memory alarm.

Reason for high memory use Amazon MQ recommendation

The number of messages in the Do any of the following:

queues is too high.
• Consume messages published
to the queues.
• Purge messages from queues.
• Delete the queues from your
broker.

The number of queues Reduce the number of queues.

conﬁgured on the broker is too
high.

The number of connections Reduce the number of

established on the broker is too connections. For more
high. information, see the section
called “Reducing the
number of connections and
channels” (p. 204).

The number of channels Reduce the number of channels.

established on the broker is too For more information see, the
high. section called “Reducing the

203
Amazon MQ Developer Guide
RABBITMQ_MEMORY_ALARM

Reason for high memory use Amazon MQ recommendation

number of connections and
channels” (p. 204).

The number of consumers Reduce the number of

connected to the broker is too consumers connected to the
high. broker.

The message publishing rate is Reduce the rate at which

too high. publishers send messages to the
broker.

The client connection attempt Reduce the frequency at which

rate is too high. clients attempt to connect to
the broker in order to publish or
consume messages, or conﬁgure
the broker.

Reducing the number of connections and channels

Connections to your Amazon MQ for RabbitMQ broker can be closed either by your client applications, or
by manually closing them using the RabbitMQ web console. To close a connection using the RabbitMQ
web console do the following.

1. Sign in to AWS Management Console and open your broker's RabbitMQ web console.
2. On the RabbitMQ console, choose the Connections tab.
3. On the Connections page, under All connections, choose the name of the connection you want to
close from the list.
4. On the connection details page, choose Close this connection to expand the section, then choose
Force Close. Optionally, you can replace the default text for Reason with your own description.
Amazon MQ for RabbitMQ will return the reason you specify to the client when you close the
connection.
5. Choose OK on the dialog box to conﬁrm and close the connection.

When you close a connection, any channels associated with closed connection will also be closed.
Note
Your client applications may be conﬁgured to automatically re-establish connections to the
broker after they are closed. In this case, closing connections from the broker web console will
not be suﬃcient for reducing connection or channel counts.

For brokers without public access, you can temporarily block connections by denying inbound traﬃc on
the appropriate message protocol port, for example, port 5671 for AMQP connections. You can block
the port in the security group that you provided to Amazon MQ when creating the broker. For more
information on modifying your security group, see Adding rules to a security group in the Amazon VPC
User Guide.

Addressing paused queue synchronizations in cluster

deployments
While addressing RabbitMQ's high memory alarms, you may ﬁnd that messages on one or multiple
queues cannot be consumed. These queues may be in the process of synchronizing messages between
nodes, during which the respective queues become unavailable for publishing and consuming. Queue

204
Amazon MQ Developer Guide
RABBITMQ_MEMORY_ALARM

synchronizations might become paused due to the high memory alarm, and even contribute to the
memory alarm.

For information about stopping and retrying paused queue syncs, see the section called “Resolving
paused queue sync” (p. 137).

Addressing restart loops in single-instance brokers

An Amazon MQ for RabbitMQ single-instance broker that raises a high memory alarm is at risk of
becoming unavailable if it restarts and does not have enough memory to start up. This can cause
RabbitMQ to enter a restart loop and prevent any further interactions with the broker until the issue is
resolved. If your broker is in a restart loop, you will not be able to apply the Amazon MQ recommended
actions previously described in this section to resolve the high memory alarm.

To recover your broker, we recommend upgrading to a larger instance type with more memory. Unlike
in cluster deployments, you can upgrade a single-instance broker while it is experiencing a high memory
alarm because there are no queue synchronizations to perform between nodes during a restart.

Preventing high memory alarms

For each contributing factor you identify, we recommends the following set of actions for preventing and
reducing the occurrence of RabbitMQ high memory alarms.

Reason high memory use Amazon MQ recommendation

The number of messages in the Do the following:

queues is too high.
• Enable lazy queues (p. 141).
• Set, or reduce the queue
depth limit (p. 121).

The number of queues Set, or reduce the queue count

conﬁgured on the broker is too limit (p. 121).
high.

The number of connections Set, or reduce the connection

established on the broker is too count limit (p. 121).
high.

The number of channels Set a maximum number of

established on the broker is too channels per connection on
high. client applications.

The number of consumers Set a small consumer pre-fetch

connected to the broker is too limit (p. 121).
high.

The client connection attempt Use longer-lived connections

rate is too high. to reduce the number and
frequency of connection
attempts.

After your broker's memory alarm has been resolved, you can upgrade your host instance type to an
instance with additional resources. For information on how to update your broker's instance type see
UpdateBrokerInput in the Amazon MQ REST API Reference.

For a complete listing of broker instance types, see the section called “Amazon MQ for RabbitMQ
instance types” (p. 33).

205
Amazon MQ Developer Guide
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

Amazon MQ for ActiveMQ resources

The following table lists useful resources for working with Apache ActiveMQ.

Resource Description

Apache ActiveMQ Getting Started Guide The oﬃcial documentation of Apache ActiveMQ.

206
Amazon MQ Developer Guide
Amazon MQ for RabbitMQ resources

Resource Description

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.

Amazon MQ for RabbitMQ resources

The following table lists useful resources for working with RabbitMQ.

Resource Description

The RabbitMQ Getting Started Guide The oﬃcial documentation of RabbitMQ.

RabbitMQ Client Libraries and Developer Tools A guide to the oﬃcially supported client libraries
and devloper tools for working with RabbitMQ
using a variety of programming languages and
platforms.

RabbitMQ Best Practices CloudAMQP's guide on best practices and

recommendations for working with RabbitMQ.

207
Amazon MQ Developer Guide

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. 220).

Date Documentation Update

August 17, 2022 Amazon MQ now supports ActiveMQ 5.17.1, a new major engine version release.
This update and all further updates will no longer support TLS 1.0 and 1.1. For
more information, see the following:

• ActiveMQ 5.17.1 Release Page

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Upgrading an Amazon MQ broker engine version (p. 21)
• Working with Spring XML conﬁguration ﬁles (p. 57)

May 4, 2022 Amazon MQ adds inclusive language for networkConnector element in broker
conﬁguration.

• Creating and conﬁguring an Amazon MQ network of brokers

April 25, 2022 Amazon MQ This release adds the CRITICAL_ACTION_REQUIRED broker state
and the ActionRequired API property. CRITICAL_ACTION_REQUIRED informs
you when your broker is degraded. ActionRequired provides you with a code
which you can use to ﬁnd instructions in the Developer Guide on how to resolve
the issue.

• the section called “Troubleshooting: Amazon MQ action required

codes” (p. 201)
• ActionRequired documentation in the Amazon MQ API Reference.

April 20, 2022 Amazon MQ now supports ActiveMQ 5.16.4, a minor engine version release. For
more information, see the following:

• ActiveMQ 5.16.4 Release Page

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working with Spring XML conﬁguration ﬁles (p. 57)
• Upgrading an Amazon MQ broker engine version (p. 21)

March 1, 2022 Amazon MQ is now available in the Asia Paciﬁc (Jakarta) Region. For information
on available regions, see AWS Regions and Endpoints in the AWS General
Reference guide.

February 25, 2022 Amazon MQ for RabbitMQ now supports RabbitMQ version 3.8.27.

For more information about the ﬁxes and features in this release, see the
following:

• RabbitMQ 3.8.27 release notes on the RabbitMQ server GitHub repository

• RabbitMQ changelog

For more information about supported Amazon MQ for RabbitMQ versions

and broker upgrades, see Managing Amazon MQ for RabbitMQ engine
versions (p. 130).

208
Amazon MQ Developer Guide

Date Documentation Update

February 16, 2022 Amazon MQ is now available in the Africa (Cape Town) Region. For information on
available regions, see AWS Regions and Endpoints in the AWS General Reference
guide.

February 14, 2022 Amazon MQ for RabbitMQ now supports RabbitMQ version 3.9.13. Automatic
minor version upgrades (p. 24) cannot be used to upgrade from Rabbit 3.8 to 3.9.
To do so, manually upgrade your broker (p. 24).

For more information on new features introduced in RabbitMQ 3.9, see the
release notes page for version 3.9.0 on the GitHub website.
Note
Currently, Amazon MQ does not support streams, or using structured
logging in JSON, introduced in RabbitMQ 3.9.

For more information about the ﬁxes and features in this release, see the
following:

• RabbitMQ 3.9.13 release notes on the RabbitMQ server GitHub repository

• RabbitMQ changelog

For more information about supported Amazon MQ for RabbitMQ versions

and broker upgrades, see Managing Amazon MQ for RabbitMQ engine
versions (p. 130).

February 07, 2022 Amazon MQ for RabbitMQ introduces new broker metrics, allowing you
to monitor average resource utilization across all three nodes in a cluster
deployment.

For more information, see the following:

• the section called “Logging and monitoring Amazon MQ for RabbitMQ

brokers” (p. 178)

January 18, 2022 Amazon MQ for RabbitMQ now supports RabbitMQ version 3.8.26.

For more information about the ﬁxes and features in this release, see the
following:

• RabbitMQ 3.8.26 release notes on the RabbitMQ server GitHub repository

• RabbitMQ changelog

For more information about supported Amazon MQ for RabbitMQ versions

and broker upgrades, see Managing Amazon MQ for RabbitMQ engine
versions (p. 130).

January 13, 2022 Amazon MQ introduces the RABBITMQ_MEMORY_ALARM status code to inform you
when your broker has raised a high memory alarm and is in an unhealthy state.
Amazon MQ provides detailed information and recommendations to help you
diagnose, resolve and prevent high memory alarms. For more information, see
the following.

• the section called “ RABBITMQ_MEMORY_ALARM ” (p. 201)

209
Amazon MQ Developer Guide

Date Documentation Update

January 6, 2022 When you conﬁgure CloudWatch Logs for Amazon MQ for ActiveMQ brokers,
Amazon MQ supports using the aws:SourceArn and aws:SourceAccount
global condition context keys in IAM resource-based policies to prevent the
confused deputy problem. For more information, see the following.

• the section called “Cross-service confused deputy prevention” (p. 188)

December 20, Amazon MQ for ActiveMQ introduces a set of new metrics, allowing you to
2021 monitor the maximum number of connections you can make to your broker using
diﬀerent supported transport protocols, as well as an additional new metric
that allows you to monitor the number of nodes connected to your broker in a
network of brokers (p. 46). For more information, see the following.

• the section called “Logging and monitoring Amazon MQ for ActiveMQ

brokers” (p. 173)

November 16, Amazon MQ for RabbitMQ now supports RabbitMQ version 3.8.23.
2021
For more information about the ﬁxes and features in this release, see the
following:

• RabbitMQ 3.8.23 release notes on the RabbitMQ server GitHub repository

• RabbitMQ changelog

For more information about supported Amazon MQ for RabbitMQ versions

and broker upgrades, see Managing Amazon MQ for RabbitMQ engine
versions (p. 130).

October 12, 2021 Amazon MQ now supports ActiveMQ 5.16.3, a minor engine version release. For
more information, see the following:

• ActiveMQ 5.16.3 Release Page

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Upgrading an Amazon MQ broker engine version (p. 21)
• Working with Spring XML conﬁguration ﬁles (p. 57)

September 8, Amazon MQ for RabbitMQ now supports RabbitMQ version 3.8.22.

2021
This release includes a ﬁx for an issue with queues using per-message TTL (time
to live), identiﬁed in the previously supported version, RabbitMQ 3.8.17. We
recommend upgrading your existing brokers to version 3.8.22.

For more information about the ﬁxes and features in this release, see the
following:

• RabbitMQ 3.8.22 release notes on the RabbitMQ server GitHub repository

• RabbitMQ changelog

For more information about supported Amazon MQ for RabbitMQ versions

and broker upgrades, see Managing Amazon MQ for RabbitMQ engine
versions (p. 130)

210
Amazon MQ Developer Guide

Date Documentation Update

August 25, 2021 Amazon MQ for RabbitMQ has temporarily disabled RabbitMQ engine version
3.8.17 due to an issue identiﬁed with queues using per-message time-to-live
(TTL). We recommend using version 3.8.11.

July 29, 2021 Amazon MQ for RabbitMQ now supports RabbitMQ version 3.8.17. For more
information about the ﬁxes and features contained in this update, see the
following:

• RabbitMQ 3.8.17 release notes on the RabbitMQ server GitHub repository

• RabbitMQ changelog
• Managing Amazon MQ for RabbitMQ engine versions (p. 130)

July 16, 2021 You can now adjust the maintenance window of an Amazon MQ broker using the
AWS Management Console, AWS CLI, or the Amazon MQ API. To learn more about
broker maintenance windows, see the following.

• Maintaining an Amazon MQ broker (p. 19)

July 6, 2021 Amazon MQ for RabbitMQ introduces support for the Consistent Hash exchange
type. Consistent Hash exchanges route messages to queues based on a hash value
calculated from the routing key of a message. For more information, see the
following:

• Consistent Hash exchange plugin (p. 128)

• RabbitMQ Consistent Hash Exchange Type on the RabbitMQ GitHub repository

June 7, 2021 Amazon MQ now supports ActiveMQ 5.16.2, a new major engine version release.
For more information, see the following:

• ActiveMQ 5.16.2 Release Page

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Upgrading an Amazon MQ broker engine version (p. 21)
• Working with Spring XML conﬁguration ﬁles (p. 57)

May 26, 2021 Amazon MQ for RabbitMQ is now available in the China (Beijing) and China
(Ningxia) Regions. For information on available regions, see AWS Regions and
Endpoints.

May 18, 2021 Amazon MQ for RabbitMQ implements broker defaults.

When you ﬁrst create a broker, Amazon MQ creates a set of broker policies and
vhost limits based on the instance type and deployment mode you choose,
in order to optimize the broker's performance. For more information, see the
following:

• Amazon MQ for RabbitMQ broker defaults (p. 121)

May 5, 2021 Amazon MQ now supports ActiveMQ 5.15.15. For more information, see the
following:

• ActiveMQ 5.15.15 Release Page

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working with Spring XML conﬁguration ﬁles (p. 57)

211
Amazon MQ Developer Guide

Date Documentation Update

May 5, 2021 Amazon MQ started tracking changes to AWS managed policies. For more
information, see the following:

• the section called “AWS managed policies” (p. 161)

April 14, 2021 Amazon MQ is now available in the China (Beijing) and China (Ningxia) Regions.
For information on available regions, see AWS Regions and Endpoints.

April 7, 2021 Amazon MQ now supports RabbitMQ 3.8.11. For more information about the
ﬁxes and features contained in this update, see the following:

• RabbitMQ 3.8.11 release notes on the RabbitMQ server GitHub repository

• RabbitMQ changelog
• Managing Amazon MQ for RabbitMQ engine versions (p. 130)

April 1, 2021 Amazon MQ is now available in the Asia Paciﬁc (Osaka) Region. For information
about available regions, see Amazon MQ regions and endpoints.

December 21, Amazon MQ now supports ActiveMQ 5.15.14. For more information, see the
2020 following:

• ActiveMQ 5.15.14 Release Notes

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working with Spring XML conﬁguration ﬁles (p. 57)
• Important
Due to a known Apache ActiveMQ issue in this release, the new Pause
Queue button in the ActiveMQ web console cannot be used with
Amazon MQ for ActiveMQ brokers. For more information about this
issue, see AMQ-8104.

November 4, 2020 Amazon MQ now supports RabbitMQ, a popular open source message broker. This
enables you to migrate your existing RabbitMQ message brokers to AWS without
having to rewrite code.

Amazon MQ for RabbitMQ manages both individual and clustered message

brokers and handles tasks like provisioning the infrastructure, setting up the
broker, and updating the software.

• Amazon MQ supports RabbitMQ 3.8.6. For more information about supported

engine versions, see the section called “Version management” (p. 130).
• The AWS Free Tier includes up to 750 hours of a single-instance mq.t3.micro
broker and up to 20GB of storage per month for one year. For more
information about supported instance types, see Broker instance types (p. 30).
• With Amazon MQ for RabbitMQ, you can access your brokers using AMQP
0-9-1, and with any language supported by the RabbitMQ client libraries. For
more information about supported protocols and cipher suites, see the section
called “Amazon MQ for RabbitMQ protocols” (p. 148).
• Amazon MQ for RabbitMQ is available in all regions that Amazon MQ is
currently available. To learn more about all of the available regions, see the
AWS Region Table.

To get started with using Amazon MQ, create a broker, and connect a JVM-
based application to your RabbitMQ broker, see the section called “Creating and
connecting to a RabbitMQ broker” (p. 11).

212
Amazon MQ Developer Guide

Date Documentation Update

October 22, 2020 Amazon MQ supports ActiveMQ 5.15.13. For more information, see the following:

• ActiveMQ 5.15.13 Release Notes

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working with Spring XML conﬁguration ﬁles (p. 57)

September 30, Amazon MQ is now available in the Europe (Milan) Region. For information about
2020 available regions, see Amazon MQ regions and endpoints.

July 27, 2020 You can authenticate Amazon MQ users using the credentials stored in your
Active Directory or other LDAP server. You can also add, delete, and modify
Amazon MQ users and assign permissions to topics and queues. For more
information, see Integrate LDAP with ActiveMQ (p. 101).

July 17, 2020 Amazon MQ now supports the mq.t3.micro instance type. For more
information, see Broker instance types (p. 30).

June 30, 2020 Amazon MQ supports ActiveMQ 5.15.12. For more information, see the following:

• ActiveMQ 5.15.12 Release Notes

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working with Spring XML conﬁguration ﬁles (p. 57)

April 30, 2020 Amazon MQ supports a new child collection element, systemUsage, on the
broker element. For more information, see systemUsage (p. 74).

Amazon MQ also supports three new attributes on the kahaDB child element.

• journalDiskSyncInterval - Interval (ms) for when to perform a disk sync if

journalDiskSyncStrategy=periodic.
• journalDiskSyncStrategy - configures the disk sync policy.
• preallocationStrategy - configures how the broker will try to preallocate
the journal files when a new journal file is needed.

For more information, see Attributes (p. 73).

March 3, 2020 Amazon MQ supports two new CloudWatch metrics

• TempPercentUsage - The percentage of available temporary storage used by

non-persistent messages.
• JobSchedulerStorePercentUsage - The percentage of disk space used by
the job scheduler store.

For more information, see Monitoring Amazon MQ using CloudWatch (p. 173).

February 4, 2020 Amazon MQ is available in the Asia Paciﬁc (Hong Kong) and Middle East (Bahrain)
regions. For information on available regions, see AWS Regions and Endpoints.

January 22, 2020 Amazon MQ supports ActiveMQ 5.15.10. For more information, see the following:

• ActiveMQ 5.15.10 Release Notes

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working with Spring XML conﬁguration ﬁles (p. 57)

213
Amazon MQ Developer Guide

Date Documentation Update

December 19, Amazon MQ is available in the Europe (Stockholm) and South America (São Paulo)
2019 regions. For information on available regions, see AWS Regions and Endpoints.

December 16, Amazon MQ supports creating throughput-optimized brokers by using Amazon

2019 Elastic Block Store (EBS)—instead of the default Amazon Elastic File System
(Amazon EFS)—for broker storage. To take advantage of high durability and
replication across multiple Availability Zones, use Amazon EFS. To take advantage
of low latency and high throughput, use Amazon EBS.
Important

• You can use Amazon EBS only with the mq.m5 broker instance type
family.
• Although you can change the broker instance type, you can't change
the broker storage type after you create the broker.
• Amazon EBS replicates data within a single Availability Zone and
doesn't support the ActiveMQ active/standby (p. 46) deployment
mode.

For more information, see the following:

• Storage (p. 43)

• Choose the correct broker storage type for the best throughput (p. 117)
• The storageType property of the broker-instance-options resource in
the Amazon MQ REST API Reference
• The BurstBalance, VolumeReadOps, and VolumeWriteOps metrics in the
Amazon MQ for ActiveMQ metrics (p. 173) section.

October 18, 2019 Two Amazon CloudWatch metrics are available: TotalEnqueueCount and
TotalDequeueCount. For more information, see ActiveMQ destination (queue
and topic) metrics (p. 176).

October 11, 2019 Amazon MQ now supports Federal Information Processing Standard 140-2 (FIPS)
compliant endpoints in U.S. commercial regions.

For more information see the following:

• Federal Information Processing Standard (FIPS) 140-2

• Amazon MQ Regions and Endpoints

September 30, Amazon MQ now includes the ability to scale your brokers by changing the host
2019 instance type. For more information, see the hostInstanceType property
of UpdateBrokerInput, and the pendingHostInstanceType property of
DescribeBrokerOutput.

August 30, 2019 You can now update the security groups associated with a broker, both in the
console and with UpdateBrokerInput.

214
Amazon MQ Developer Guide

Date Documentation Update

July 22, 2019 Amazon MQ integrates with AWS Key Management Service (KMS) to oﬀer server-
side encryption. You can now select your own customer managed CMK, or use
an AWS managed KMS key in your AWS KMS account. For more information, see
Encryption at rest (p. 146).

Amazon MQ supports using AWS KMS keys in the following ways.

• AWS owned KMS key — The key is owned Amazon MQ and is not in your
account.
• AWS managed KMS key — The AWS managed KMS key (aws/mq) is a KMS key
in your account that is created, managed, and used on your behalf by Amazon
MQ.
• Select existing customer managed CMK — Customer managed CMKs are
created and managed by you in AWS Key Management Service (KMS).

June 19, 2019 Amazon MQ is available in the Europe (Paris) and Asia Paciﬁc (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. For
more information, see the following:

• Monitoring Amazon MQ using CloudWatch (p. 173)

• Amazon MQ for ActiveMQ metrics (p. 173)

May 10, 2019 Data storage for new mq.t2.micro instance types is limited to 20 GB. For more
information, see the following:

• the section called “Data Storage” (p. 191)

• Broker instance types (p. 30)

April 29, 2019 You can now use tag-based policies and resource-level permissions. For more
information, see the following:

• How Amazon MQ works with IAM (p. 152)

• Resource-level permissions for Amazon MQ API actions (p. 160)

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

• Broker instance options

• Broker engine types

April 8, 2019 Amazon MQ supports ActiveMQ 5.15.9. For more information, see the following:

• ActiveMQ 5.15.9 Release Notes

• Managing Amazon MQ for ActiveMQ engine versions (p. 75)
• Working with Spring XML conﬁguration ﬁles (p. 57)

215
Amazon MQ Developer Guide

Date Documentation Update

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 the following:

• Dynamic Failover With Transport Connectors (p. 55)

• Amazon MQ Network of brokers (p. 46)
• Amazon MQ Broker Conﬁguration Parameters (p. 57)

February 27, 2019 Amazon MQ is available in the Europe (London) Region in addition to the
following regions:

• Asia Paciﬁc (Singapore)

• US East (Ohio)
• US East (N. Virginia)
• US West (N. California)
• US West (Oregon)
• Asia Pacific (Tokyo)
• Asia Pacific (Seoul)
• Asia Pacific (Sydney)
• Europe (Frankfurt)
• Europe (Ireland)

January 24, 2019 The default conﬁguration 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. For more information, see, Quotas in Amazon MQ (p. 190).

December 19, You can conﬁgure a series of Amazon MQ brokers in a network of brokers. For
2018 more information, see the following sections:

• Amazon MQ Network of brokers (p. 46)

• Creating and Conﬁguring a Network of Brokers (p. 88)
• Conﬁgure Your Network of Brokers Correctly (p. 117)
• networkConnector (p. 71)
• networkConnectionStartAsync (p. 67)

December 11, Amazon MQ supports ActiveMQ 5.15.8, 5.15.6, and 5.15.0.

2018
• Resolved bugs and improvements in ActiveMQ:
• ActiveMQ 5.15.8 Release Notes
• ActiveMQ 5.15.7 Release Notes

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. For
more information, see Tagging resources.

November 19, AWS has expanded its SOC compliance program to include Amazon MQ as an SOC
2018 compliant service.

216
Amazon MQ Developer Guide

Date Documentation Update

October 15, 2018 • The maximum number of groups per user is 20. For more information, see
Users (p. 191).
• The maximum number of connections per broker, per wire-level protocol is
1,000. For more information, see Brokers (p. 190).

October 2, 2018 AWS has expanded its HIPAA compliance program to include Amazon MQ as a
HIPAA Eligible Service.

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, Amazon CloudWatch Logs, and maintenance

preferences (p. 87)
• Resolved bugs and improvements in the ActiveMQ documentation:
• ActiveMQ 5.15.6 Release Notes
• ActiveMQ 5.15.5 Release Notes
• ActiveMQ 5.15.4 Release Notes
• ActiveMQ 5.15.3 Release Notes
• ActiveMQ 5.15.2 Release Notes
• ActiveMQ 5.15.1 Release Notes
• ActiveMQ Client 5.15.6

August 31, 2018 • The following metrics are available:

• CurrentConnectionsCount
• TotalConsumerCount
• TotalProducerCount

For more information, see the Amazon MQ for ActiveMQ metrics (p. 173)
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 Paciﬁc (Singapore) Region in addition to the
following regions:

July 30, 2018 You can conﬁgure Amazon MQ to publish general and audit logs to Amazon
CloudWatch Logs. For more information, see Conﬁguring Amazon MQ to publish
logs to Amazon CloudWatch Logs (p. 185).

217
Amazon MQ Developer Guide

Date Documentation Update

July 25, 2018 Amazon MQ is available in the Asia Paciﬁc (Tokyo) and Asia Paciﬁc (Seoul) Regions
in addition to the following regions:

• US East (Ohio)
• US East (N. Virginia)
• US West (N. California)
• US West (Oregon)
• Asia Paciﬁc (Sydney)
• Europe (Frankfurt)
• Europe (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. 182).

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. 30).

June 27, 2018 Amazon MQ is available in the US West (N. California) Region in addition to the
following regions:

• US East (Ohio)
• US East (N. Virginia)
• US West (Oregon)
• Asia Paciﬁc (Sydney)
• Europe (Frankfurt)
• Europe (Ireland)

218
Amazon MQ Developer Guide

Date Documentation Update

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
Users (p. 191).

March 13, 2018 Creating a broker takes about 15 minutes. For more information, see Finish
creating the broker (p. 86).

March 1, 2018 • You can conﬁgure the concurrent store and dispatch (p. 116) for Apache
KahaDB using the concurrentStoreAndDispatchQueues (p. 73) attribute.
• The CpuCreditBalance CloudWatch metric (p. 173) is available for
mq.t2.micro broker instance type.

January 10, 2018 The following changes aﬀect 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 conﬁguration of inbound and outbound
rules. For more information, see the updated Enable inbound connections (p. 6)
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.

219
Amazon MQ Developer Guide
Document History

Date Documentation Update

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)
• US East (N. Virginia)
• US West (Oregon)
• Asia Paciﬁc (Sydney)
• Europe (Frankfurt)
• Europe (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. 173) metric). If your application
requires ﬁxed 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
• MQTT over WebSocket
• OpenWire
• STOMP
• STOMP over WebSocket
• 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. 97).
• 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. 208).

Date Documentation Update

August 22, 2022 Created separate parent chapters for Amazon MQ for ActiveMQ and Amazon
MQ for RabbitMQ engines. These parent chapters now contain engine details,
tutorials, and best practices:

• Working with Amazon MQ for ActiveMQ (p. 37)

220
Amazon MQ Developer Guide
Document History

Date Documentation Update

• Working with Amazon MQ for RabbitMQ (p. 119)

January 13, 2022 Added a new troubleshooting section that lists the status codes that Amazon MQ
returns when a broker is in an unhealthy state, along with detailed information
about diagnosing, and recovering the broker.

• the section called “Troubleshooting: Amazon MQ action required

codes” (p. 201)

November 8, 2021 Added new tutorial that describes setting up a Python Pika client with Amazon
MQ for RabbitMQ brokers.

• the section called “Using Python Pika with Amazon MQ for RabbitMQ” (p. 132)

October 8, 2021 Added the following troubleshooting topics for both Amazon MQ for ActiveMQ
and Amazon MQ for RabbitMQ broker engines:

• Some clients unable to connect (p. 199)

• the section called “How do I enable plugins in Amazon MQ for
RabbitMQ?” (p. 201)
• the section called “I'm unable to change Amazon VPC conﬁguration for the
broker.” (p. 201)

September 22, Added the following topics for troubleshooting common connection, and
2021 authorization issues with Amazon MQ for ActiveMQ brokers:

• Connecting to broker after a restart (p. 199)

• JSP exception on the web console (p. 200)

August 12, 2021 Added the following section to describe troubleshooting common issues when
working with Amazon MQ brokers.

• Troubleshooting (p. 193)

July 29, 2021 Added the following sections to describe Amazon MQ for RabbitMQ version
management and upgrading Amazon MQ brokers to new minor and major engine
versions as they are supported.

• the section called “Version management” (p. 130)

July 21, 2021 Added the following sections to describe connecting an Amazon MQ broker to
AWS Lambda as an event source.

• Connect your Amazon MQ for ActiveMQ broker to Lambda (p. 9)

• Connect your Amazon MQ for RabbitMQ broker to Lambda (p. 16)

July 16, 2021 Added the following sections to describe Amazon MQ broker maintenance
windows, and how to adjust a maintenance window using the AWS Management
Console, AWS CLI, or the Amazon MQ API.

• the section called “Maintaining a broker” (p. 19)

221
Amazon MQ Developer Guide
Document History

Date Documentation Update

June 7, 2021 Added the following sections to describe Amazon MQ for ActiveMQ version
management and upgrading Amazon MQ brokers to new minor and major engine
versions as they are supported.

• the section called “Version management” (p. 75)

• the section called “Upgrading the engine version” (p. 21)

May 18, 2021 Added the following section to describe Amazon MQ for RabbitMQ broker
defaults

• the section called “Broker defaults” (p. 121)

May 5, 2021 Added the following section for describing AWS managed policies for Amazon
MQ and updates to these policies:

• the section called “AWS managed policies” (p. 161)

February 16, 2021 Added the following tutorial section for Amazon MQ for RabbitMQ:

• the section called “Resolving paused queue sync” (p. 137)

November 4, 2020 • Added the following sections to document Amazon MQ for RabbitMQ support:
• the section called “Creating and connecting to a RabbitMQ broker” (p. 11)
• the section called “RabbitMQ tutorials” (p. 132)
• the section called “Amazon MQ for RabbitMQ best practices” (p. 141)
• the section called “RabbitMQ engine” (p. 119)
• the section called “Conﬁguring Amazon MQ for RabbitMQ logs” (p. 189)
• the section called “Using service-linked roles” (p. 162)
• Additional revisions to existing chapters and sections of the guide were made to
accurately document Amazon MQ for RabbitMQ support.

December 16, • Added the following sections:

2019 • Storage (p. 43)
• Choose the correct broker storage type for the best throughput (p. 117)
• Revised the information in the following sections:
• Broker (p. 37)
• Broker instance types (p. 30)
• Amazon MQ single-instance broker (p. 45)
• Amazon MQ active/standby broker for high availability (p. 46)
• Create an ActiveMQ broker (p. 4)
• Creating and conﬁguring a broker (p. 84)

July 19, 2019 Modiﬁed and added content on encryption management in the following
sections:

• Data protection in Amazon MQ (p. 145)

• Encryption at rest (p. 146)
• Encryption in transit (p. 147)
• EncryptionOptions

222
Amazon MQ Developer Guide
Document History

Date Documentation Update

April 22, 2019 Added the following sections for tag-based policies and resource-level
permissions:

• How Amazon MQ works with IAM (p. 152)

• Resource-level permissions for Amazon MQ API actions (p. 160)

• Dynamic Failover With Transport Connectors (p. 55)

• Amazon MQ Network of brokers (p. 46)
• Amazon MQ Broker Conﬁguration Parameters (p. 57)

January 5, 2019 Improved documentation on some per-minute metrics. For more information, see
the following: ActiveMQ destination (queue and topic) metrics (p. 176).

December 19, • Added the following sections:

2018 • Amazon MQ Network of brokers (p. 46)
• Creating and Configuring a Network of Brokers (p. 88)
• Configure Your Network of Brokers Correctly (p. 117)
• networkConnector (p. 71)
• networkConnectionStartAsync (p. 67)
• Added the networkConnectors child collection element to the Elements,
Child Collection Elements, and Their Child Elements Permitted in Amazon MQ
Configurations (p. 68) section.

December 11, Updated documentation to reﬂect availability of ActiveMQ version 5.15.8.

2018

December 5, 2018 Added the Tagging resources (p. 34) section.

October 26, 2018 Added the Avoid slow restarts by recovering prepared XA transactions (p. 117)
section.

October 15, 2018 Updated the Quotas in Amazon MQ (p. 190) section.

October 1, 2018 Corrected the information in the Next steps (p. 11) section.

September 27, • Added the Editing broker engine version, Amazon CloudWatch Logs, and
2018 maintenance preferences (p. 87) section.
• Updated the following sections:
• Create an ActiveMQ broker (p. 4)
• Conﬁgure Basic Broker Settings (p. 84)

September 18, Added the following note to the Creating and managing ActiveMQ broker
2018 users (p. 111) section: You can't conﬁgure 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.

223
Amazon MQ Developer Guide
Document History

Date Documentation Update

August 31, 2018 • Clarified the terminology for active/standby brokers. For more information, see
Amazon MQ active/standby broker for high availability (p. 46).
• Simplified the terminology for the maintenance window. For more information,
see Amazon MQ Broker Configuration Lifecycle (p. 56).
• Rewrote the Configure Additional Broker Settings (p. 85) section.
• Updated the Amazon MQ for ActiveMQ metrics (p. 173) and Listing brokers and
viewing broker details (p. 25) sections.

August 15, 2018 Corrected the information in the Create an ActiveMQ broker (p. 4) section.

August 13, 2018 Added the Accessing the broker web console without public accessibility (p. 28)
section.

August 2, 2018 • Added the Troubleshooting CloudWatch Logs Conﬁguration (p. 189) 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. 186)

• Connect a Java application to your broker (p. 6)

July 31, 2018 • Moved the 3-minute demo video to the Getting Started with Amazon MQ (p. 4)
section.
• Added the 3-minute getting started video to the What is Amazon MQ? (p. 1)
section.

July 30, 2018 • Added the Conﬁguring Amazon MQ to publish logs to Amazon CloudWatch
Logs (p. 185) section.
• Updated the Conﬁgure Additional Broker Settings (p. 85) section.

July 19, 2018 • Added the Logging Amazon MQ API calls using CloudTrail (p. 182) section.

July 5, 2018 • Added an authorizationEntry child element cross-reference to the Always

configure an authorization map (p. 169) section.
• Clarified the information in the Integrating ActiveMQ brokers with
LDAP (p. 100) section.
• Clarified the information in the API Throttling (p. 192) section.

June 29, 2018 • Updated the information in the Broker instance types (p. 30) section.
• Added the Choose the Correct Broker Instance Type for the Best
Throughput (p. 116) section.

224
Amazon MQ Developer Guide
Document History

Date Documentation Update

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. 76) 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. 76) section.

May 22, 2018 Corrected the information in all Java dependency sections.

May 17, 2018 Corrected the information in the Users (p. 191) section.

May 15, 2018 Corrected the information in the Ensuring eﬀective Amazon MQ
performance (p. 115) section.

May 8, 2018 • Placed the Amazon MQ REST API permissions reference (p. 159) in its own
section.
• Created the IAM Permissions Required to Create an Amazon MQ Broker (p. 158)
section with an example custom IAM policy.

May 7, 2018 • Clariﬁed throughout this guide that the broker maintenance window is 2
hours long. For more information, see Amazon MQ Broker Conﬁguration
Lifecycle (p. 56).
• 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. 158).

May 1, 2018 Clariﬁed the information about the maintenance window for active/standby
brokers in the following sections:

• Amazon MQ active/standby broker for high availability (p. 46)

• Creating and configuring a broker (p. 84)
• Creating and applying broker configurations (p. 92)
• Editing and Managing Broker Configurations (p. 94)

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:

• Always Use Connection Pooling (p. 114)

• Create a message producer and send a message (p. 7)
• Create a message consumer and receive the message (p. 8)
• AmazonMQExample.java (p. 79)

225
Amazon MQ Developer Guide
Document History

Date Documentation Update

April 26, 2018 Added an MQTT Java example to the Working Java Example (p. 76) section. The
MQTT example Java code connects to a broker, creates a topic, and publishes and
receives a message.

April 4, 2018 Renamed the Communicating with Amazon MQ section to Connecting to Amazon
MQ (p. 113).

April 3, 2018 Clariﬁed and corrected the information in the Disable Concurrent Store and
Dispatch for Queues with Slow Consumers (p. 116) 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. 116) 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.
• Restructured the following sections:
• Broker Architecture (p. 44)
• How Amazon MQ Works.
• Moved Amazon MQ Broker Conﬁguration Lifecycle (p. 56) under the Broker
Architecture (p. 44) section.

March 22, 2018 Clariﬁed 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 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 Amazon EFS.

March 15, 2018 • Restructured the Amazon MQ Basic elements (p. 37) section.

March 12, 2018 • Clariﬁed and corrected the information in the Security best practices for
Amazon MQ (p. 168) and Connecting to Amazon MQ (p. 113) sections.
• Added the Disable Concurrent Store and Dispatch for Queues with Slow
Consumers (p. 116) section.
• Grouped admonitions into a preface for the Conﬁgure advanced broker
settings (p. 85) section.

March 9, 2018 • Clariﬁed and corrected the information in the Always conﬁgure an
authorization map (p. 169) section.
• Added the authorizationEntry (p. 71) section and updated the kahaDB (p. 73)
section.

March 8, 2018 • Added the Always conﬁgure an authorization map (p. 169) section.
• Added notes about broker suﬃxes to the Monitoring Amazon MQ using
CloudWatch (p. 173) section.

226
Amazon MQ Developer Guide
Document History

Date Documentation Update

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. 173)
metric). If your application requires ﬁxed performance, consider using an
mq.m5.large instance type.

March 1, 2018 • Added the CpuCreditBalance metric to the Amazon MQ for ActiveMQ
metrics (p. 173) section.
• Added the Amazon MQ Child Element Attributes (p. 71) section.
• Added links from elements in the the section called “Permitted
Elements” (p. 58) 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.

February 22, 2018 Clariﬁed and corrected the information in the following sections:

• Prefer brokers without public accessibility (p. 169)

• Always Use the Failover Transport to Connect to Multiple Broker
Endpoints (p. 115)
• API authentication and authorization for Amazon MQ (p. 158)
• Integrating ActiveMQ brokers with LDAP (p. 100)

February 21, 2018 Corrected the Java code in the following sections:

• Working Java Example (p. 76)

• Connect a Java application to your broker (p. 6)
• Always Use Connection Pooling (p. 114)

February 20, 2018 Clariﬁed and corrected the information in the Security in Amazon MQ (p. 145) and
Best Practices sections.

February 19, 2018 • Corrected the Java code in the Always Use Connection Pooling (p. 114) section.
• Restructured and expanded the Best Practices sections and Security in Amazon
MQ (p. 145) sections.

227
Amazon MQ Developer Guide
Document History

Date Documentation Update

February 16, 2018 • Added the Security best practices for Amazon MQ (p. 168) section.
• Updated the Connecting to Amazon MQ (p. 113) section.
• Corrected the Java code in the following sections:
• Getting Started with Amazon MQ (p. 4)
• AmazonMQExample.java (p. 79)

February 15, 2018 • Restructured and expanded the Best Practices sections section.
• Updated the following sections:
• How can I get started with Amazon MQ? (p. 1)
• Next steps (p. 11) (Getting Started)
• Related resources (p. 206)

February 14, 2018 Updated the following sections:

• Quotas in Amazon MQ (p. 190)

• API Throttling (p. 192)
• Security in Amazon MQ (p. 145)

February 13, 2018 • Updated the Related resources (p. 206) section.
• Updated the Quotas in Amazon MQ (p. 190) section.
• Added the We want to hear from you (p. 1) section.

January 25, 2018 • Fixed an error in the Add Java dependencies (p. 77) subsection of the Working
Java Example (p. 76) 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. 113) section.
• Updated all diagrams throughout this guide.
• Added links to the Amazon MQ REST API Reference throughout this guide and
links to speciﬁc REST APIs to the API authentication and authorization for
Amazon MQ (p. 158) section.

January 19, 2018 Updated the information in the Amazon MQ for ActiveMQ resources (p. 206)
section.

January 18, 2018 Clariﬁed and corrected the information in the Quotas in Amazon MQ (p. 190)
section.

January 17, 2018 Reinstated the recommendation to prefer virtual destinations over durable
subscriptions (p. 115), with an improved explanation.

January 11, 2018 • The Amazon MQ Developer Guide is available in Kindle format, in addition to
HTML and PDF.
• Clariﬁed and corrected information in the API authentication and authorization
for Amazon MQ (p. 158) and Step 2: create an IAM user and get your AWS
credentials (p. 2) sections.

January 3, 2018 Added DescribeConfigurationRevision to the API authentication and

authorization for Amazon MQ (p. 158) section.

228
Amazon MQ Developer Guide
Document History

Date Documentation Update

December 15, Removed the recommendation against durable subscriptions from the Best
2017 Practices sections section.

December 8, 2017 • Added the Enable inbound connections (p. 6) prerequisite to the Connecting
a Java application to your broker (p. 97) and Working Java Example (p. 76)
sections.
• Added the following note throughout this guide: Currently, you can't delete a
conﬁguration.

December 7, 2017 • Improved the code in the AmazonMQExample.java (p. 79).

• Added the API authentication and authorization for Amazon MQ (p. 158)
section.

December 5, 2017 • Clariﬁed and corrected information in the Monitoring Amazon MQ using
CloudWatch (p. 173) section:
• Improved the metric descriptions.
• Added the Amazon MQ for ActiveMQ metrics (p. 173) and Dimensions for
ActiveMQ broker metrics (p. 176) sub-sections.
• Added the "Introducing Amazon MQ" video to the What is Amazon MQ? (p. 1)
section.

December 4, 2017 • Clariﬁed the following information in the Data Storage (p. 191) section: Storage
capacity per broker is 200 GB.
• Added the Prerequisites (p. 77) to the Working Java Example (p. 76) 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. 97)).

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. 96) or reboot the broker (p. 29). For more information, see Amazon
MQ Broker Configuration Lifecycle (p. 56).

229
Amazon MQ Developer Guide

AWS glossary
For the latest AWS terminology, see the AWS glossary in the AWS General Reference.

230

Intrusion Detection Honeypots
From Everand
Intrusion Detection Honeypots
Chris Sanders
3/5 (2)
Builder.ai - Corporate Deck (1)
No ratings yet
Builder.ai - Corporate Deck (1)
24 pages
How to Sell on Amazon and Product Research: Product Research Tips and Practical Guide on How to Find a Winning Product to Sell on Amazon Fba
From Everand
How to Sell on Amazon and Product Research: Product Research Tips and Practical Guide on How to Find a Winning Product to Sell on Amazon Fba
David L. Ross
No ratings yet
Audio, Video, and Media in the Ministry
From Everand
Audio, Video, and Media in the Ministry
Clarence Floyd Richmond
No ratings yet
Amazon MQ: Developer Guide
No ratings yet
Amazon MQ: Developer Guide
126 pages
Amazon MQ DG
No ratings yet
Amazon MQ DG
132 pages
Sqs DG PDF
No ratings yet
Sqs DG PDF
199 pages
Sqs DG
No ratings yet
Sqs DG
192 pages
sqs-dg
No ratings yet
sqs-dg
191 pages
10K Blueprint
From Everand
10K Blueprint
Cian O Farrell
5/5 (2)
ChatGPT for Business: Strategies for Success
From Everand
ChatGPT for Business: Strategies for Success
Matthew C. Smith
1/5 (1)
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
From Everand
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
Jay Nans
No ratings yet
Sqs DG
No ratings yet
Sqs DG
109 pages
Gray Hat Hacking the Ethical Hacker's
From Everand
Gray Hat Hacking the Ethical Hacker's
Çağatay Şanlı
5/5 (1)
CAN Bus for Beginners: A Practical Guide to Automotive Networking
From Everand
CAN Bus for Beginners: A Practical Guide to Automotive Networking
Mohamad Charara
No ratings yet
Cybersecurity for Executives: A Guide to Protecting Your Business
From Everand
Cybersecurity for Executives: A Guide to Protecting Your Business
Matthew C. Smith
No ratings yet
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet
Red Hat AMQ-7.5-Managing AMQ Broker-en-US
No ratings yet
Red Hat AMQ-7.5-Managing AMQ Broker-en-US
72 pages
How to Sell on Amazon Fba
From Everand
How to Sell on Amazon Fba
David L. Ross
No ratings yet
A To Z of Internet: Everything You Wanted to Know
From Everand
A To Z of Internet: Everything You Wanted to Know
Bittu Kumar
No ratings yet
Breaking Barriers: S.T.E.M Mentorship in Business
From Everand
Breaking Barriers: S.T.E.M Mentorship in Business
Matthew C. Smith
No ratings yet
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
From Everand
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
Matthew C. Smith
No ratings yet
Amazon Simple Queue Service: Developer Guide API Version 2009-02-01
No ratings yet
Amazon Simple Queue Service: Developer Guide API Version 2009-02-01
82 pages
Apache Active
0% (1)
Apache Active
140 pages
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
From Everand
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
Michael Basler
No ratings yet
Aws SDK Documentation
No ratings yet
Aws SDK Documentation
160 pages
BlockChain for Beginners
From Everand
BlockChain for Beginners
Matthew Smith
No ratings yet
Active MQ
No ratings yet
Active MQ
18 pages
Content Creation Revolution with chatGPT
From Everand
Content Creation Revolution with chatGPT
Maria Cowen
No ratings yet
Apache Activemq: Create and Modify Brokers and Who Can Send Messages To and Receive Messages From
No ratings yet
Apache Activemq: Create and Modify Brokers and Who Can Send Messages To and Receive Messages From
1 page
Aquaponics for Profit
From Everand
Aquaponics for Profit
David H Dudley
No ratings yet
Plain JavaScript: Learning the Front-End
From Everand
Plain JavaScript: Learning the Front-End
Roger Beans-Rivet
No ratings yet
AI-Driven Digital Transformation: A Proven Blueprint for Responsible AI Scaling
From Everand
AI-Driven Digital Transformation: A Proven Blueprint for Responsible AI Scaling
Srikanth Victory
No ratings yet
(Ebook) ActiveMQ in Action by Bruce Snyder, Dejan Bosanac, Rob Davies ISBN 9781933988948, 1933988940 download
100% (1)
(Ebook) ActiveMQ in Action by Bruce Snyder, Dejan Bosanac, Rob Davies ISBN 9781933988948, 1933988940 download
61 pages
Apache ActiveMQ Artemis DOcumentation
No ratings yet
Apache ActiveMQ Artemis DOcumentation
458 pages
ESB Usage Guide
No ratings yet
ESB Usage Guide
23 pages
Business English Writing: Effective Business Writing Tips and Will Help You Write Better and More Effectively at Work
From Everand
Business English Writing: Effective Business Writing Tips and Will Help You Write Better and More Effectively at Work
Mary G. Lewis
No ratings yet
Cloud Computing : Beginners And Intermediate User Guide
From Everand
Cloud Computing : Beginners And Intermediate User Guide
David comer
No ratings yet
Web Video Business
From Everand
Web Video Business
MUHAMMAD NUR WAHID ANUAR
No ratings yet
Amazon MQ: REST API Reference
No ratings yet
Amazon MQ: REST API Reference
56 pages
Amazon Aws Lambda-Dg PDF
No ratings yet
Amazon Aws Lambda-Dg PDF
733 pages
Craftsman Creative: How Five-Figure Creators Can Build Six-Figure Businesses
From Everand
Craftsman Creative: How Five-Figure Creators Can Build Six-Figure Businesses
Daren Smith
No ratings yet
Mastering RabbitMQ - Sample Chapter
No ratings yet
Mastering RabbitMQ - Sample Chapter
24 pages
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
From Everand
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
Vladimir Kiselev
No ratings yet
Mazon (Rabbit) MQ
No ratings yet
Mazon (Rabbit) MQ
9 pages
Enterprise Messaging With Apache Activemq: James Strachan
No ratings yet
Enterprise Messaging With Apache Activemq: James Strachan
46 pages
Aws Cloud9 Ug
No ratings yet
Aws Cloud9 Ug
362 pages
The Ai Advantage: How To Use Ai To Transform Your Business
From Everand
The Ai Advantage: How To Use Ai To Transform Your Business
Marvin Roberts
No ratings yet
MQ Admin Program
No ratings yet
MQ Admin Program
124 pages
Powerpack For Websphere MQ v8 1userguide
No ratings yet
Powerpack For Websphere MQ v8 1userguide
248 pages
RabbitMQ Urbiotica
No ratings yet
RabbitMQ Urbiotica
5 pages
Lambda DG
No ratings yet
Lambda DG
553 pages
Queue (Which Stores Messages Across Multiple Amazon SQS Servers), and Consumers (Other Components That
No ratings yet
Queue (Which Stores Messages Across Multiple Amazon SQS Servers), and Consumers (Other Components That
6 pages
12 - CT071!3!3-DDAC - Message Queue Solutions in Cloud
No ratings yet
12 - CT071!3!3-DDAC - Message Queue Solutions in Cloud
62 pages
Aquaponics Design Plans, Construction, Operation, and Income: Organic Food
From Everand
Aquaponics Design Plans, Construction, Operation, and Income: Organic Food
David H Dudley
No ratings yet
RabbitMQ A Comprehensive Guide
No ratings yet
RabbitMQ A Comprehensive Guide
3 pages
Mastering Python Advanced Concepts and Practical Applications
From Everand
Mastering Python Advanced Concepts and Practical Applications
Aissa Younes
No ratings yet
Conquering the Competition: Strategies for Standing Out in the Gaming Content Landscape
From Everand
Conquering the Competition: Strategies for Standing Out in the Gaming Content Landscape
Rian McCullen
No ratings yet
AWS Lambda DG
No ratings yet
AWS Lambda DG
440 pages
ISO 26262 Made Simple: A Beginner’s Guide to Automotive Safety
From Everand
ISO 26262 Made Simple: A Beginner’s Guide to Automotive Safety
Mohamad Charara
No ratings yet
Lambda DG
No ratings yet
Lambda DG
487 pages
TAFJ-DB2-Install
No ratings yet
TAFJ-DB2-Install
13 pages
TAFJ-DB-Performance
No ratings yet
TAFJ-DB-Performance
15 pages
TAFJ-CALLJEE
No ratings yet
TAFJ-CALLJEE
7 pages
TAFJ-Kerberos Setup
No ratings yet
TAFJ-Kerberos Setup
8 pages
Component Framework Deploying Component Service
No ratings yet
Component Framework Deploying Component Service
14 pages
AWS Stack8 R21 Runbook Customer
100% (1)
AWS Stack8 R21 Runbook Customer
106 pages
IRIS Integration User Guide
No ratings yet
IRIS Integration User Guide
18 pages
Stack1 AWS Red Hat JBoss Runbook Multitier R18
No ratings yet
Stack1 AWS Red Hat JBoss Runbook Multitier R18
86 pages
How To Generate CRF Report
No ratings yet
How To Generate CRF Report
5 pages
AWS Re Invent
No ratings yet
AWS Re Invent
34 pages
Frequently Asked Questions (FAQ)
No ratings yet
Frequently Asked Questions (FAQ)
3 pages
Public-Private-Hybrid CC
No ratings yet
Public-Private-Hybrid CC
28 pages
AWS Solution Architect Associate Cheat Sheat
No ratings yet
AWS Solution Architect Associate Cheat Sheat
24 pages
I2k2 Profile
No ratings yet
I2k2 Profile
22 pages
Final_ASD
No ratings yet
Final_ASD
46 pages
Nithyasree
No ratings yet
Nithyasree
1 page
Praful Resume Devops
No ratings yet
Praful Resume Devops
3 pages
Start Cloud Career
No ratings yet
Start Cloud Career
12 pages
Gautam Prajapati - Updated-Resume
No ratings yet
Gautam Prajapati - Updated-Resume
3 pages
2019 APN Program Tier Requirement Guide (English)
100% (1)
2019 APN Program Tier Requirement Guide (English)
21 pages
Get started - AWS Amplify Gen 2 Documentation
No ratings yet
Get started - AWS Amplify Gen 2 Documentation
2 pages
Ansible EC2 Example - Create EC2 Instance With
No ratings yet
Ansible EC2 Example - Create EC2 Instance With
27 pages
Caltech PGP in DevOps Brochure 17-04-2024 - CTME
No ratings yet
Caltech PGP in DevOps Brochure 17-04-2024 - CTME
28 pages
Frontend Engineer II - AWS Ressource Management: Description
No ratings yet
Frontend Engineer II - AWS Ressource Management: Description
2 pages
Natalie Li Burgher - Recruiter
No ratings yet
Natalie Li Burgher - Recruiter
1 page
Barclays PDF
No ratings yet
Barclays PDF
1 page
Cloud Computing Questions-1
No ratings yet
Cloud Computing Questions-1
38 pages
Eks Ultimate Guide
0% (1)
Eks Ultimate Guide
298 pages
AWS IOT Services
No ratings yet
AWS IOT Services
8 pages
AWS Certified Solutions Architect Official Study Guide: Associate Exam 1st Edition by Joe Baron (eBook PDF) All Chapters Instant Download
100% (1)
AWS Certified Solutions Architect Official Study Guide: Associate Exam 1st Edition by Joe Baron (eBook PDF) All Chapters Instant Download
55 pages
Cloud Computing Services
No ratings yet
Cloud Computing Services
17 pages
C2 Deutsch Cloud Ingenieur in München
No ratings yet
C2 Deutsch Cloud Ingenieur in München
2 pages
DEVIKA.V ML
No ratings yet
DEVIKA.V ML
7 pages
CC Unit3 Overview
No ratings yet
CC Unit3 Overview
2 pages
Sankalp_Chintalwar_Resume
No ratings yet
Sankalp_Chintalwar_Resume
2 pages
Sponsor Symposia AWS Healthcare Strategy and Generative AI Machine Learning DHC Halifax - Vfinal
No ratings yet
Sponsor Symposia AWS Healthcare Strategy and Generative AI Machine Learning DHC Halifax - Vfinal
38 pages
Amazon
No ratings yet
Amazon
15 pages
Solved Big Data and Data Science Projects
100% (1)
Solved Big Data and Data Science Projects
85 pages