red hat jboss a-mq 7.0-beta using a-mq broker resources, minimizing the number of threads blocking...

Red Hat Customer ContentServices

Red Hat JBoss A-MQ 7.0-BetaUsing A-MQ Broker

For use with A-MQ Broker 7.0

Red Hat JBoss A-MQ 7.0-Beta Using A-MQ Broker

For use with A-MQ Broker 7.0

Legal Notice

Copyright 2016 Red Hat, Inc.

The text of and illustrations in this document are licensed by Red Hat under a Creative CommonsAttributionShare Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA isavailable athttp://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you mustprovide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinitylogo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and othercountries.

Linux is the registered trademark of Linus Torvalds in the United States and other countries.

Java is a registered trademark of Oracle and/or its affiliates.

XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United Statesand/or other countries.

MySQL is a registered trademark of MySQL AB in the United States, the European Union andother countries.

Node.js is an official trademark of Joyent. Red Hat Software Collections is not formally related toor endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack Word Mark and OpenStack logo are either registered trademarks/service marksor trademarks/service marks of the OpenStack Foundation, in the United States and other countriesand are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed orsponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

AbstractThis guide describes how to install, configure, monitor, and manage the broker.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Table of Contents

CHAPTER 1. OVERVIEW1.1. KEY FEATURES1.2. KEY CONCEPTS1.3. SUPPORTED CONFIGURATIONS

CHAPTER 2. INSTALLATION2.1. PREREQUISITES2.2. DOWNLOAD AN A-MQ BROKER ARCHIVE2.3. EXTRACT THE .ZIP ARCHIVE2.4. EXTRACT THE .TAR.GZ ARCHIVE2.5. ARCHIVE CONTENTS

CHAPTER 3. GETTING STARTED3.1. CREATE A BROKER INSTANCE3.2. START A BROKER INSTANCE3.3. RUN THE EXAMPLES3.4. REVIEW DEFAULT CONFIGURATION

CHAPTER 4. CONFIGURING NETWORK CONNECTIONS4.1. ACCEPTORS4.2. CONNECTORS4.3. IN VM AND NETTY CONNECTIONS4.4. CONFIGURING IN VM CONNECTIONS4.5. CONFIGURING NETTY TCP CONNECTIONS4.6. CONFIGURING NETTY HTTP CONNECTIONS4.7. CONFIGURING NETTY TLS/SSL CONNECTIONS4.8. CONFIGURING CONNECTIONS ON THE CLIENT SIDE

CHAPTER 5. CONFIGURING PROTOCOLS5.1. AMQP5.2. MQTT5.3. OPENWIRE5.4. STOMP

CHAPTER 6. CONFIGURING DESTINATIONS6.1. QUEUES6.2. TOPICS6.3. ADDRESS SETTINGS

CHAPTER 7. CONFIGURING SECURITY7.1. CONFIGURING AUTHENTICATION7.2. CONFIGURING AUTHORIZATION7.3. CONFIGURING TRANSPORT LAYER SECURITY

CHAPTER 8. CONFIGURING PERSISTENCE8.1. A-MQ BROKER 7.0.0 FILE JOURNAL (DEFAULT)8.2. CONFIGURING THE BINDINGS JOURNAL8.3. CONFIGURING THE JMS JOURNAL8.4. CONFIGURING THE MESSAGE JOURNAL8.5. AN IMPORTANT NOTE ON DISABLING DISK WRITE CACHE.8.6. INSTALLING AIO8.7. CONFIGURING FOR JDBC PERSISTENCE8.8. CONFIGURING FOR ZERO PERSISTENCE

4445

666677

99

101213

171717181818191919

2121232425

28282929

31313944

474749494952535354

Table of Contents

1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CHAPTER 9. CONFIGURING RESOURCE LIMITS9.1. CONFIGURING CONNECTION AND QUEUE LIMITS

CHAPTER 10. CONFIGURING CLUSTERING10.1. CLUSTER TOPOLOGIES10.2. BROKER DISCOVERY10.3. BROKER-SIDE MESSAGE LOAD BALANCING10.4. CLIENT-SIDE LOAD BALANCING10.5. SPECIFYING MEMBERS OF A CLUSTER EXPLICITLY10.6. MESSAGE REDISTRIBUTION

CHAPTER 11. CONFIGURING HIGH AVAILABILITY AND FAILOVER11.1. LIVE - BACKUP GROUPS11.2. FAILOVER

CHAPTER 12. CONFIGURING LOGGING12.1. CHANGING THE LOGGING LEVEL12.2. CONFIGURING CONSOLE LOGGING12.3. CONFIGURING FILE LOGGING12.4. CONFIGURING THE LOGGING FORMAT12.5. CLIENT OR EMBEDDED SERVER LOGGING

CHAPTER 13. MANAGING A-MQ BROKER13.1. USING A-MQ CONSOLE13.2. MANAGEMENT API

CHAPTER 14. TROUBLESHOOTING A-MQ BROKER14.1. TUNING JMS14.2. TUNING PERSISTENCE14.3. OTHER TUNINGS14.4. AVOIDING ANTI-PATTERNS14.5. HANDLING SLOW CONSUMERS

APPENDIX A. REFERENCE MATERIALA.1. ACCEPTOR AND CONNECTOR CONFIGURATION PARAMETERSA.2. ADDRESS SETTING ATTRIBUTESA.3. USING YOUR SUBSCRIPTION

5555

56565766717373

757589

949496979898

101101109

125125125126126127

128128132134


2

Table of Contents

3

CHAPTER 1. OVERVIEW

A-MQ Broker is a full-featured, message-oriented middleware broker. It offers specialized queueingbehaviors, message persistence, and manageability. Core messaging is provided by ApacheActiveMQ with support for different messaging styles such as publish-subscribe, point-to-point, andstore-and-forward. It supports multiple protocols and client languages, freeing you to use many ifnot all of your application assets. Lastly, A-MQ Broker is supported to work with Red Hat JBossEnterprise Application Platform.

A-MQ Broker is based on Apache ActiveMQ Artemis.

1.1. KEY FEATURES

Supports multiple wire protocols

AMQP

Artemis Core Protocol

HornetQ Core Protocol

MQTT

OpenWire (Used by A-MQ 6 clients)

STOMP

Supports JMS 2.0

Clustering and high availability options

Fast, native-IO persistence

Fully transactional (including XA support)

Written in Java for broad platform support

Choice of Management Interfaces: A-MQ Console and/or API

1.2. KEY CONCEPTS

Messaging brokers allow you to loosely couple heterogeneous systems together, while typicallyproviding reliability, transactions, and many other features.

Unlike systems based on a Remote Procedure Call (RPC) pattern, messaging systems primarilyuse an asynchronous message-passing pattern with no tight relationship between requests andresponses. Most messaging systems also support a request-response mode, but this is not aprimary feature of messaging systems.

Designing systems to be asynchronous from end to end allows you to really take advantage of yourhardware resources, minimizing the number of threads blocking on IO operations, and to use yournetwork bandwidth to its full capacity. With an RPC approach you have to wait for a response foreach request you make so are limited by the network round-trip time, or latency, of your network.With an asynchronous system you can pipeline flows of messages in different directions, so you arelimited by the network bandwidth, not the latency. This typically allows you to create much higherperformance applications.


4

http://activemq.apache.org/artemis/

Messaging systems decouple the senders of messages from the consumers of messages. Thesenders and consumers of messages are completely independent and know nothing of each other.This allows you to create flexible, loosely coupled systems.

1.3. SUPPORTED CONFIGURATIONS

In order to be running in a supported configuration, A-MQ Broker must be running on an appropriatecombination of operating system and certified JDK implementation. The table below provides amatrix of supported JDK implementations by the version of Red Hat Enterprise Linux (RHEL)operating system.

Table 1.1. Supported RHEL and JDK combinations

Operating System OpenJDK 8 Oracle JDK 8 IBM JDK 8

RHEL 6 x86 Yes Yes -

RHEL 6 x86-64 Yes Yes Yes

RHEL 7 x86-64 Yes Yes Yes

A-MQ Broker also supports configurations using operating systems other than RHEL. Below is a listof combinations by JDK version.

Other Supported JDK and OS Combinations

Oracle JDK 8Solaris 10 (x86, x86-64, and SPARC)Solaris 11 (x86, x86-64, and SPARC)Windows Server 2012 R2 (x86-64 only)

IBM JDK 8AIX 7.1

HP JVM 1.8HP-UX 11i

A-MQ Broker also includes the A-MQ Console, a GUI-based management tool. The table below liststhe supported web browsers when using A-MQ Console.

Supported Versions of Web Browsers

Chrome 44

Firefox 40

Internet Explorer 10 and 11

CHAPTER 1. OVERVIEW

5

CHAPTER 2. INSTALLATION

2.1. PREREQUISITES

A-MQ Broker requires the following components.

JRE 1.8 (for running A-MQ Broker)

JDK 1.8 (for running the examples)

Maven 3.2 (for running the examples)

Note that the broker runtime requires only a JRE. However, running the included examples requiresa full JDK as well as Maven.

If you are installing A-MQ Broker on a supported version of Red Hat Enterprise Linux, you can usethe yum command to install any needed pre-requisites. For example, the command below will installOpenJDK 1.8 and Maven.

$ sudo yum install java-1.8.0-openjdk maven

You can also download supported versions of a JDK and Maven from their respective websites,OpenJDK and Apache Maven for example. Consult Supported Configurations to ensure you areusing a supported version of Java.

2.2. DOWNLOAD AN A-MQ BROKER ARCHIVE

A platform-independent, archived distribution of A-MQ Broker is available for download from the RedHat Customer Portal. See Using Your Subscription for more information on how to access thecustomer portal using your Red Hat subscription. You can download a copy of the distribution byfollowing the steps below.

1. Open a browser and log in to the Red Hat Customer Portal at https://access.redhat.com.

2. Click Downloads.

3. Click Red Hat JBoss A-MQ in the Product Downloads list.

4. Select the correct A-MQ Broker version from the Version drop-down menu.

5. Select your preferred archive for Red Hat JBoss 7.x.x Broker:

a. An archive in .zip format (for any supported OS: Linux, Unix, or Windows) or

b. An archive in .tar.gz format (for any supported OS with the tar and gunzipcommands, typically *nix)

6. Click the Download link of your preferred archive.

2.3. EXTRACT THE .ZIP ARCHIVE

Once the zip file has been downloaded, you can install A-MQ Broker by extracting the zip filecontents, as done in the steps below.


6

http://openjdk.java.net/https://maven.apache.org/https://access.redhat.com

1. If necessary, move the zip file to the server and location where A-MQ Broker should beinstalled.

Note

The user who will be running A-MQ Broker must have read and write access tothis directory.

2. Extract the zip archive.

$ unzip jboss-amq-7.x.x.zip

Note

For Windows Server, right-click the zip file and select Extract All.

The directory created by extracting the archive is the top-level directory for the A-MQ Brokerinstallation. This is referred to as .

2.4. EXTRACT THE .TAR.GZ ARCHIVE

Once the tar.gz file has been downloaded, you can install A-MQ Broker by first de-compressing thecontents of the tar archive and then extracting A-MQ Broker from the tar archive itself. The steps arecaptured below.

1. If necessary, move the tar.gz file to the server and location where A-MQ Broker should beinstalled.

Note

The user who will be running A-MQ Broker must have read and write access tothis directory.

2. Decompress the tar archive

$ gunzip jboss-amq-7.x.x.tar.gz

3. Extract A-MQ Broker from the decompressed tar archive

$ tar -xvf jboss-amq-7.x.x.tar

2.5. ARCHIVE CONTENTS

The directory created by extracting the archive is the top-level directory for the A-MQ Brokerinstallation. This directory is referred to as and includes a number of importantdirectories noted in the table below.

CHAPTER 2. INSTALLATION

7

1. Archive Contents of

If you want to find Look here

API documentation /web/api

Binaries and scripts needed to run A-MQ Broker /bin

Configuration files /etc

JMS and Java EE examples /examples

Jars and libraries needed to run A-MQ Broker /lib

XML Schemas used to validate A-MQ Broker configuration files /schema

Web context loaded when A-MQ Broker runs. /web


8

CHAPTER 3. GETTING STARTED

This chapter lets you get started with A-MQ Broker right away by creating your first broker instanceand by running one of the examples included as part of the installation. Next, this chapter willprovide an overview of the basic configuration elements and concepts. Later chapters will providedetails for the topics introduced here.

3.1. CREATE A BROKER INSTANCE

To A-MQ Brokera broker instance is a directory containing all the configuration and runtime data,such as logs and data files. The runtime data is associated with a unique broker process,

To create a broker instance, follow the steps below.

1. Determine a directory location for the broker instance. For example /var/lib/amq7

Note

On Unix systems, it is recommended that you store the runtime data under the /var/lib directory.

2. Use the artemis create command to create the broker under the location used in Step1. For example, to create the broker instance mybroker under the /var/lib/amq7directory, run the following commands.

$ sudo mkdir /var/lib/amq7$ cd /var/lib/amq7$ sudo /bin/artemis create mybroker

The artemis create command will ask a series of questions in order to configure thebroker instance.

The following example shows the command-line interactive process when creating a brokerinstance.

Creating ActiveMQ Artemis instance at: /var/lib/amq7/mybroker

--user: is mandatory with this configuration:Please provide the default username:

--password: is mandatory with this configuration:Please provide the default password:

--role: is mandatory with this configuration:Please provide the default role:amq

--allow-anonymous | --require-login: is mandatory with this configuration:Allow anonymous access? (Y/N):


9

Y

Auto tuning journal ...done! Your system can make 19.23 writes per millisecond, your journal-buffer-timeout will be 52000

You can now start the broker by executing:

"/var/lib/amq7/mybroker/bin/artemis" run

Or you can run the broker in the background using:

"/var/lib/amq7/mybroker/bin/artemis-service" start

Note

The artemis create command will prompt for mandatory property values only. For thefull list of properties available when creating an instance, run the artemis help createcommand.

The broker instance created by artemis create will have the directory structure detailed in thetable below. The location of the broker instance is known as the .

1. Contents of a broker instance directory

If you want to find Look here

Scripts that launch and manage the instance /bin

Configuration files /etc

Storage for persistent messages /data

Log files /log

Temporary files /tmp

3.2. START A BROKER INSTANCE

Once the broker is created, use the artemis script in the /bindirectory to start it. For example, to start a broker instance installed at /var/lib/amq7/mybroker,use the following command.


10

$ /var/lib/amq7/mybroker/bin/artemis run

The broker will produce output similar to the following.

____ _ _ _ _ _ __ __ ___ _____| _ \ ___ __| | | | | | __ _| |_ / \ | \/ |/ _ \|___ || |_) / _ \/ _` | | |_| |/ _` | __| / _ \ _____| |\/| | | | | / /| _ < __/ (_| | | _ | (_| | |_ / ___ \_____| | | | |_| | / /|_| \_\___|\__,_| |_| |_|\__,_|\__| /_/ \_\ |_| |_|\__\_\/_/

Red Hat A-MQ7 7.0.0.ER12-redhat-1

14:46:15,468 INFO [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server14:46:15,479 INFO [org.apache.activemq.artemis.core.server] AMQ221000: live Message Broker is starting with configuration Broker Configuration (clustered=false,journalDirectory=./data/journal,bindingsDirectory=./data/bindings,largeMessagesDirectory=./data/large-messages,pagingDirectory=./data/paging)14:46:15,497 INFO [org.apache.activemq.artemis.core.server] AMQ221012: Using AIO Journal14:46:15,525 INFO [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-server]. Adding protocol support for: CORE14:46:15,527 INFO [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-amqp-protocol]. Adding protocol support for: AMQP14:46:15,527 INFO [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-hornetq-protocol]. Adding protocol support for: HORNETQ14:46:15,528 INFO [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-mqtt-protocol]. Adding protocol support for: MQTT14:46:15,529 INFO [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-openwire-protocol]. Adding protocol support for: OPENWIRE14:46:15,530 INFO [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-stomp-protocol]. Adding protocol support for: STOMP14:46:15,825 INFO [org.apache.activemq.artemis.core.server] AMQ221052: trying to deploy topic jms.topic.myTopic14:46:15,828 INFO [org.apache.activemq.artemis.core.server] AMQ221003: Trying to deploy queue jms.queue.DLQ14:46:15,833 INFO [org.apache.activemq.artemis.core.server] AMQ221003: Trying to deploy queue jms.queue.ExpiryQueue14:46:16,062 INFO [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:61616 for protocols [CORE,MQTT,AMQP,HORNETQ,STOMP,OPENWIRE]14:46:16,065 INFO [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:5445 for protocols [HORNETQ,STOMP]14:46:16,069 INFO [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:5672 for protocols [AMQP]14:46:16,071 INFO [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at localhost:1883 for protocols [MQTT]14:46:16,073 INFO [org.apache.activemq.artemis.core.server] AMQ221020:


11

Started Acceptor at localhost:61613 for protocols [STOMP]14:46:16,073 INFO [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live14:46:16,073 INFO [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 1.2.0.amq-700006 [amq, nodeID=71ecbb84-176e-11e6-be67-54ee7531eccb]SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".SLF4J: Defaulting to no-operation (NOP) logger implementationSLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.INFO | main | Initialized artemis-plugin plugin14:46:17,116 INFO [org.apache.activemq.artemis] AMQ241001: HTTP Server started at http://localhost:816114:46:17,116 INFO [org.apache.activemq.artemis] AMQ241002: Artemis Jolokia REST API available at http://localhost:8161/jolokia

3.3. RUN THE EXAMPLES

A-MQ Broker ships with many example programs that highlight various basic and advanced featuresof the product. They can be found under /examples. The examples require asupported release of the Java Development Kit (JDK) and Maven version 3.2 to build and execute.Consult Supported Configurations for details about JDK support.

An excellent example to use as a "sanity test" of your installation is the queue example. To buildand run the example, navigate to the /examples/features/standard/queuedirectory and run the mvn verify command.

$ cd /examples/features/standard/queue$ mvn verify

Maven will then start the broker and run the example program. Once completed the output shouldlook something like the below example. Note that the example may take a long time to complete thefirst time since Maven will download any missing dependencies required to run the example.

[INFO] Scanning for projects...[INFO][INFO] ------------------------------------------------------------------------[INFO] Building ActiveMQ Artemis JMS Queue Example 1.2.0.amq-700[INFO] ------------------------------------------------------------------------ ...server-out:11:30:45,534 INFO [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 1.2.0.amq-700 [0.0.0.0, nodeID=e748cdbd-232c-11e6-b145-54ee7531eccb][INFO] Server started[INFO][INFO] --- artemis-maven-plugin:1.2.0.amq-700:runClient (runClient) @ queue ---Sent message: This is a text messageserver-out:11:30:46,545 INFO [org.apache.activemq.artemis.core.server] AMQ221003: Trying to deploy queue jms.queue.exampleQueueReceived message: This is a text message[INFO][INFO] --- artemis-maven-plugin:1.2.0.amq-700:cli (stop) @ queue ---


12

[INFO] ------------------------------------------------------------------------[INFO] BUILD SUCCESS[INFO] ------------------------------------------------------------------------[INFO] Total time: 6.368 s[INFO] Finished at: 2016-05-26T11:30:47+01:00[INFO] Final Memory: 44M/553M[INFO] ------------------------------------------------------------------------

3.4. REVIEW DEFAULT CONFIGURATION

Now that you have an instance of a broker running, it is time to walk through common configurationelements and the default options that are included when the A-MQ Broker is started "out of the box".Most of the configuration discussed here is found in /etc/broker.xml, but the last section is dedicated to another configuration file /etc/bootstrap.xml which as its name implies is used by A-MQ Broker as itfirst begins execution and so is the first configuration file read.

3.4.1. broker.xml

3.4.1.1. Network Connections

Brokers listen for incoming client connections by using an acceptor configuration element to definethe port and protocols a client can use to make connections. Be default A-MQ Broker includesconfiguration for several acceptors.

Default Acceptor Configuration in broker.xml

... ... tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576

tcp://0.0.0.0:5672?protocols=AMQP

tcp://0.0.0.0:61613?protocols=STOMP

tcp://0.0.0.0:5445?protocols=HORNETQ,STOMP


13

A connector works as the counterpart to an acceptor. Out of the box, does not have any pre-configured connectors. Connectors are used when the broker needs to communicate to otherbrokers in its cluster or when remote clients establish connections to the server by using JNDI.

See Configuring Transports for details on acceptors and connectors configuration. For moreinformation on the protocols supported by the broker, refer to Configuring Protocols.

3.4.1.2. Addresses and Queues

A-MQ Broker includes a JMS wrapper for what is known as its Core API, which allows you to defineyour messaging destinations as either JMS or Core based. For example, the default broker.xmldefines two JMS queues, one to handle messages that arrive with no known destination, a DeadLetter Queue (DLQ); and a queue to place messages that have live passed their expiration andtherefore should not be routed to a destination.

Default JMS Queues in broker.xml

The default configuration also uses the concept of an address-setting to establish a default, or catchall, set of configuration that will be applied to any created queue or topic.

Default Address Setting in broker.xml

tcp://0.0.0.0:1883?protocols=MQTT ...

...

... ... jms.queue.DLQ jms.queue.ExpiryQueue 0 10485760 10 BLOCK


14

Note how the address-setting uses a wildcard syntax to dictate which queues and topics are to havethe configuration applied. In this case the single # symbol tells A-MQ Broker to apply theconfiguration to all queues and topics.

3.4.1.3. Security

A-MQ Broker contains a flexible role-based security model for applying security to queues, based ontheir addresses. Also, just like an address setting, you can use a wildcard syntax, as does thedefault configuration.

Default Security Configuration in broker.xml

Note the seven types of permission that can be used as part security setting. See ConfiguringSecurity for more details on permission types and the rest of security topics.

3.4.1.4. Persistence

By default A-MQ Broker persistence uses an append only file journal that consists of a set of fileson disk that are used to save messages, transactions, and other state.

There are several elements that are needed to configure the broker to persist to a message journal.These include the following.

Default Persistence Configuration in broker.xml

... ...

When persistence-enabled is true the journal persists to the directories specified and usingthe specified journal type of NIO. Alternative journal types are ASYNCIO and JDBC.

For more details on configuring persistence, refer to Configuring Persistence.

3.4.2. bootstrap.xml

The bootstrap configuration file, /etc/bootstrap.xml, is read whenthe broker first starts. It is used to configure the web server, security, and the broker configurationfile.

Default Contents of bootstrap.xml

Note that you can change the location for the broker.xml configuration file and for the bound url ofthe web server and its applications, including A-MQ Console.

For more details on the console persistence, see Using A-MQ 7 Console.

... true NIO ./data/paging ./data/bindings ./data/journal ./data/large-messages 2 -1 ...


16

persistence

CHAPTER 4. CONFIGURING NETWORK CONNECTIONS

This chapter provides information about A-MQ Broker network connections and how you configurethem. The two primary configuration elements to configure network connection, Acceptors andConnectors, are discussed first. The chapter then turns to the topic of Netty and the role it plays inproviding the underlying network connectivity. Lastly, these concepts come together whenconfiguration steps for TCP, HTTP, and TLS/SSL network connections are explained.

4.1. ACCEPTORS

One of the most important concepts in broker transports is the acceptor. Acceptors define the wayconnections are made to the broker. Below is a typical acceptor that might be in found inside theconfiguration file broker.xml.

Note that each acceptors is grouped inside an acceptors element. There is no upper limit to thenumber of acceptors you can list per server.

The acceptor can also be configured with a set of key, value pairs used to configure the specifictransport, the set of valid key-value pairs depends on the specific transport be used and are passedstraight through to the underlying transport. These are set on the URI as part of the query, like so:

For details on connector configuration parameters, see Acceptor and Connector ConfigurationParameters.

4.2. CONNECTORS

Whereas acceptors are used on the server to define how the server accepts connections,connectors are used by a client to define how it connects to a server.

Below is a typical connector as defined in a broker.xml configuration file:

Note that connectors are defined inside a connectors element. There is no upper limit to thenumber of connectors per server.

You typically define connectors on the server, as opposed to defining them on the client, for thefollowing reasons:

The server needs to know how to connect to other servers. For example, when one server isbridged to another or when a server takes part in a cluster.

tcp://localhost:61617

tcp://localhost:61617?sslEnabled=true;key-store-path=/path



17

The server is being used by a client to look up JMS connection factory instances. In thesecases, JNDI needs to know details of the connection factories used to create client connections.The information is configured on the server and provided to the client when a JNDI lookup isperformed. See Configure a Connection on the Client Side for more information.

Like acceptors, connectors have their configuration attached to the query string of their URI. Belowis an example of a connector that has the tcpNoDelay parameter set to false, which turns offNagles alogrithm for this connection.

For details on connector configuration parameters, see Acceptor and Connector ConfigurationParameters.

4.3. IN VM AND NETTY CONNECTIONS

Every acceptor and connector contains a URI that defines the type of connection to create.

Using vm in the URI schema will create an In VM connection, which is used when a broker needs tocommunicate with another broker running in the same virtual machine.

Using tcp in the URI schema will create a Netty connection. [Netty](http://netty.io/) is a highperformance low level network library that allows network connections to be configured in severaldifferent ways: using Java IO or NIO, TCP sockets, SSL/TLS, even tunneling over HTTP or HTTPS.Netty also allows for a single port to be used for all messaging protocols. The broker willautomatically detect which protocol is being used and direct the incoming message to theappropriate broker handler.

See Configuring Messaging Protocols for details on how to configure protocols for your networkconnections.

4.4. CONFIGURING IN VM CONNECTIONS

In-VM connections are used by local clients running in the same JVM as the server. The client canbe be an application or another broker. For an In VM connection, the authority part of the URIdefines a unique server id. In fact, no other part of the URI is needed, so the result is a typicallyshort URI as in the examples below:

The above acceptor is configured to accept connections from the server with the id of 0, which isrunning in the same virtual machine. As for the connector, it defines how to establish an in vmconnection to the same server 0.

An In Vm connection can be used when multiple brokers are co-located in the same virtual machine,as part of a high availability solution for example.

4.5. CONFIGURING NETTY TCP CONNECTIONS

For Netty connections the host and the port of the URI define what host and port the connection willbe used for the connection.

tcp://localhost:61616?tcpNoDelay=false

vm://0vm://0


18

http://netty.io/

Netty TCP is a basic, unencrypted, TCP-based transport. It can be configured to use blocking JavaIO or the newer, non blocking Java NIO. Java NIO is preferred for better scalability with manyconcurrent connections. However, using the old IO can sometimes give you better latency than NIOwhen you are less worried about supporting many thousands of concurrent connections.

If you are running connections across an untrusted network, please bear in mind this networkconnection is unencrypted. You may want to consider using an SSL or HTTPS configuration toencrypt messages sent over this connection if encryption is a priority. Please refer to ConfiguringTransport Layer Security for details.

When using the Netty TCP transport, all connections are initiated from the client side. In otherwords, the server does not initiate any connections to the client, which works well with firewallpolicies that force connections to be initiated from one direction.

All the valid Netty transport keys are defined in the class org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants.Most parameters can be used either with acceptors or connectors, some only work with acceptors.

For details on configuration parameters, see Acceptor and Connector Configuration Parameters.

4.6. CONFIGURING NETTY HTTP CONNECTIONS

Netty HTTP tunnels packets over the HTTP protocol. It can be useful in scenarios where firewallsonly allow HTTP traffic to pass.

To enable a connection for HTTP set the httpEnabled parameter to true on the connectors URI.There are no changes needed or an acceptor, simply use the same URI configuration as any non-HTTP connection. The configuration below is a basic example of an HTTP-enabled acceptor andconnector.

For a full working example showing how to use Netty HTTP, see the http-transport example,located under /examples/standard.

Netty HTTP uses the same properties as Netty TCP but also has its own configuration properties.For details on HTTP-related and other configuration parameters, see Acceptor and ConnectorConfiguration Parameters.

4.7. CONFIGURING NETTY TLS/SSL CONNECTIONS

You can also configure connections to use TLS/SSL. Please refer to Configuring Transport LayerSecurity for details.

4.8. CONFIGURING CONNECTIONS ON THE CLIENT SIDE

Connectors are also used indirectly in client applications. For example, a connector is created whenclient code programmatically configures a core ClientSessionFactory to communicate with abroker. In this case there is no need to define a connector in the server side configuration. Instead,

tcp://localhost:61617tcp://localhost:61617

tcp://localhost:8080?httpEnabled=truetcp://localhost:8080


19

configuration is defined programmatically in the client code and tells the ClientSessionFactorywhich connection to use.

Below is an example of creating a ClientSessionFactory which will connect directly to anacceptor. It uses the standard Netty TCP transport and will connect on port 61617 of localhost, thedefault host location.

Map connectionParams = new HashMap();

connectionParams.put(org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 61617);

TransportConfiguration transportConfiguration = new TransportConfiguration( "org.apache.activemq.artemis.core.remoting.impl.netty.NettyConnectorFactory", connectionParams);

ServerLocator locator = ActiveMQClient.createServerLocatorWithoutHA(transportConfiguration);

ClientSessionFactory sessionFactory = locator.createClientSessionFactory();

ClientSession session = sessionFactory.createSession(...);

Similarly, if you are using JMS, you can configure the JMS connection factory directly on the clientside without having to define a connector on the server side.

Map connectionParams = new HashMap();

connectionParams.put(org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants.PORT_PROP_NAME, 61617);

TransportConfiguration transportConfiguration = new TransportConfiguration( "org.apache.activemq.artemis.core.remoting.impl.netty.NettyConnectorFactory", connectionParams);

ConnectionFactory connectionFactory = ActiveMQJMSClient.createConnectionFactoryWithoutHA(JMSFactoryType.CF, transportConfiguration);

Connection jmsConnection = connectionFactory.createConnection();


20

CHAPTER 5. CONFIGURING PROTOCOLS

A-MQ Broker has a pluggable protocol architecture and supports several wire protocols. Eachprotocol is shipped as its own module (or jar) and will be available if the jar is available on theclasspath.

The broker ships with support for the following protocols:

AMQP

HornetQ

MQTT

OpenWire

STOMP

In addition to the protocols above, the broker also offers support for its own highly performant nativeprotocol "Core".

In order to make use of a particular protocol, a transport must be configured with the desiredprotocol enabled. See [Configure Network Connections] for more information.

The default configuration shipped with the broker distribution comes with a number of acceptorsalready defined, one for each of the above protocols plus a generic acceptor that supports allprotocols. To enable a protocol on a particular acceptor simply add a url parameter"protocol=AMQP,STOMP" to the acceptor url. Where the value of the parameter is a commaseparated list of protocol names. If the protocol parameter is omitted from the url all protocols areenabled.

5.1. AMQP

The broker supports the [AMQP 1.0](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp) specification. To enable AMQP configure a Netty Acceptor to receive AMQPclients, like so:

tcp://localhost:5672?protocols=AMQP

The broker will then accept AMQP 1.0 clients on port 5672 which is the default AMQP port.

tcp://localhost:1883?protocols=MQTT

tcp://localhost:1883?protocols=MQTT,AMQP



21

https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp

5.1.1. Security

The broker accepts AMQP SASL Authentication and will use this to map onto the underlying sessioncreated for the connection so you can use the normal broker security configuration.

5.1.2. Links

An AMQP link is a uni-directional transport for messages between a source and a target, i.e. a clientand the broker. A link will have an endpoint of which there are two kinds, a sender and a receiver. Atthe broker, a sender will have its messages converted into a broker message and forwarded to itsdestination or target. A receiver will map onto a brokers consumer and convert broker messagesback into AMQP messages before being delivered.

5.1.3. Destinations

If an AMQP link is dynamic, a temporary queue will be created and either the remote source or theremote target address will be set to the name of the temporary queue. If the link is not dynamic, theaddress of the remote target or source will be used for the queue. If the remote target or sourcedoes not exist, an exception will be sent.

Note

For the next version we will add a flag to automatically create durable queue but fornow you will have to add them via the configuration

5.1.4. Topics

Although AMQP has no notion of topics it is still possible to treat AMQP consumers or receivers assubscriptions rather than just consumers on a queue. By default any receiving link that attaches toan address with the prefix jms.topic. will be treated as a subscription and a subscription queuewill be created. If the Terminus Durability is either UNSETTLED_STATE or CONFIGURATION thenthe queue will be made durable, similar to a JMS durable subscription and given a name made upfrom the container ID and the link name, something like my-container-id:my-link-name. if theTerminus Durability is configured as NONE then a volatile queue will be created.

The prefix can be changed by configuring the Acceptor and setting the pubSubPrefix like so

tcp://0.0.0.0:5672?protocols=AMQP;pubSubPrefix=foo.bar.

A-MQ Broker also supports the qpid-jms client and will respect its use of topics regardless of theprefix used for the address.

5.1.5. Coordinators and Handling Transactions

An AMQP links target can also be a Coordinator, the Coordinator is used to handle transactions. If acoordinator is used the underlying HormetQ session will be transacted and will be either rolled backor committed via the coordinator.

Note

AMQP allows the use of multiple transactions per session, amqp:multi-txns-per-ssn, however in this version the broker will only support single transactions


22

per session

5.2. MQTT

MQTT is a light weight, client to server, publish / subscribe messaging protocol. MQTT has beenspecifically designed to reduce transport overhead (and thus network traffic) and code footprint onclient devices. For this reason MQTT is ideally suited to constrained devices such as sensors andactuators and is quickly becoming the defacto standard communication protocol for Internet ofThings(IoT).

The broker supports MQTT v3.1.1 (and also the older v3.1 code message format). To enable MQTT,simply add an appropriate acceptor with the MQTT protocol enabled. For example:

tcp://localhost:1883?protocols=MQTT

By default the configuration created for the broker has the above acceptor already defined, MQTT isalso active by default on the generic acceptor defined on port 61616 (where all protocols areenabled), in the out of the box configuration.

The best source of information on the MQTT protocol is in the specification. The MQTT v3.1.1specification can be downloaded from the OASIS website here: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html

Some note worthy features of MQTT are explained below:

5.2.1. Quality of Service

MQTT offers 3 quality of service levels.

Each message (or topic subscription) can define a quality of service that is associated with it. Thequality of service level defined on a topic is the maximum level a client is willing to accept. Thequality of service level on a message is the desired quality of service level for this message. Thebroker will attempt to deliver messages to subscribers at the highest quality of service level based onwhat is defined on the message and topic subscription.

Each quality of service level offers a level of guarantee by which a message is sent or received:

Quality of Service(QoS) 0: AT MOST ONCE: Guarantees that a particular message is only everreceived by the subscriber a maximum of one time. This does mean that the message maynever arrive. The sender and the receiver will attempt to deliver the message, but if somethingfails and the message does not reach its destination (say due to a network connection) themessage may be lost. This QoS has the least network traffic overhead and the least burden onthe client and the broker and is often useful for telemetry data where it does not matter if some ofthe data is lost.

QoS 1: AT LEAST ONCE: Guarantees that a message will reach its intended recipient one ormore times. The sender will continue to send the message until it receives an acknowledgmentfrom the recipient, confirming it has received the message. The result of this QoS is that therecipient may receive the message multiple times, and also increases the network overhead thanQoS 0, (due to acks). In addition more burden is placed on the sender as it needs to store themessage and retry should it fail to receive an ack in a reasonable time.

QoS 2: EXACTLY ONCE: The most costly of the QoS (in terms of network traffic and burden onsender and receiver) this QoS will ensure that the message is received by a recipient exactlyone time. This ensures that the receiver never gets any duplicate copies of the message and willeventually get it, but at the extra cost of network overhead and complexity required on the sender


23

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html

and receiver.

5.2.2. Retained Messages

MQTT has an interesting feature in which messages can be "retained" for a particular address. Thismeans that once a retain message has been sent to an address, any new subscribers to thataddress will receive the last sent retain message before any others messages, this happens even ifthe retained message was sent before a client has connected or subscribed. An example of wherethis feature might be useful is in environments such as IoT where devices need to quickly get thecurrent state of a system when they are on boarded into a system.

5.2.3. Will Messages

A will message can be sent when a client initially connects to a broker. Clients are able to set a "willmessage" as part of the connect packet. If the client abnormally disconnects, say due to a device ornetwork failure the broker will proceed to publish the will message to the specified address (asdefined also in the connect packet). Other subscribers to the will topic receive the will message andcan react to it saccordingly. This feature can be useful in an IoT style scenario to detect errorsacross a potentially large scale deployment of devices.

5.2.4. Wild card subscriptions

MQTT addresses are hierarchical much like a file system, and use "/" character to separatehierarchical levels. Subscribers are able to subscribe to specific topics or to whole branches of ahierarchy.

To subscribe to branches of an address hierarchy a subscriber can use wild cards.

There are 2 types of wild card in MQTT:

# Multi level wild card. Adding this wild card to an address would match all branches of theaddress hierarchy under a specified node. For example: /uk/# Would match /uk/cities,/uk/cities/newcastle and also /uk/rivers/tyne. Subscribing to an address "#" would result insubscribing to all topics in the broker. This can be useful, but should be done so with care sinceit has significant performance implications.

+ Single level wild card. Matches a single level in the address hierarchy. For example/uk/+/stores would match /uk/newcastle/stores but not /uk/cities/newcastle/stores.

5.3. OPENWIRE

The broker supports the [OpenWire](http://activemq..org/openwire.html) protocol so that a brokerJMS client can talk directly to a broker. To enable OpenWire support configure a Netty Acceptor likeso:

tcp://localhost:61616?protocols=OPENWIRE

The broker will then listens on port 61616 for incoming openwire commands. Please note the"protocols" option is not mandatory here. The openwire configuration conforms to the brokers"Single Port" feature. Please refer to [Configuring Single Port](#configuring-transports.single-port)for details.

Please refer to the openwire example for more coding details.


24

http:/openwire.html

Currently we support OpenWire clients that are using standard JMS APIs. In the future we will getmore support for some advanced, OpenWire specific features into the broker.

5.4. STOMP

Stomp is a text-orientated wire protocol that allows Stomp clients to communicate with StompBrokers. The broker supports Stomp 1.0, 1.1 and 1.2.

Stomp clients are available for several languages and platforms making it a good choice forinteroperability.

5.4.1. Native Stomp support

The broker provides native support for Stomp. To be able to send and receive Stomp messages,configure a NettyAcceptor with a protocols parameter set to have stomp:

tcp://localhost:61613?protocols=STOMP

With this configuration, the broker will accept Stomp connections on the port 61613 (which is thedefault port of the Stomp brokers).

See the stomp example located under /examples/protocols which showshow to configure a broker with Stomp.

5.4.2. Limitations

The broker currently does not support virtual hosting, which means the 'host' header in CONNECTframe will be ignored.

Message acknowledgements are not transactional. The ACK frame can not be part of a transaction(it will be ignored if its transaction header is set).

5.4.3. Message IDs

When receiving Stomp messages via a JMS consumer or a QueueBrowser, the messages bydefault will not contain any JMS properties, such as JMSMessageID. Because this mayinconvenience clients who want to use an ID, the broker provides a parameter to set a message IDon each incoming Stomp message. If you want each Stomp message to have a unique ID, just setthe stompEnableMessageId to true, as in the example below:

tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true

When the server starts with the above setting, each stomp message sent through this acceptor willhave an extra property added. The property key is amq-message-id and the value is a Stringrepresentation of a long type internal message id prefixed with STOMP, like:

amq-message-id : STOMP12345

If stomp-enable-message-id is not specified in the configuration, the default is false.


25

http://stomp.github.com/

5.4.4. Handling Large Messages

Stomp clients may send very large bodies of frames which can exceed the size of the brokersservers internal buffer, causing unexpected errors. To prevent this situation from happening, thebroker provides a Stomp configuration attribute stompMinLargeMessageSize. This attribute canbe configured inside a stomp acceptor, as a parameter. For example:

tcp://localhost:61613?protocols=STOMP;stompMinLargeMessageSize=10240

The type of this attribute is integer. When this attributed is configured, the broker will check the sizeof the body of each Stomp frame coming from connections established with this acceptor. If the sizeof the body is equal to or greater than the value of stompMinLargeMessageSize, the messagewill be persisted as a large message. When a large message is delivered to a stomp consumer, theHorentQ server will automatically handle the conversion from a large message to a normalmessage, before sending it to the client.

If a large message is compressed, the server will uncompressed it before sending it to stompclients. The default value of stompMinLargeMessageSize is the same as the default value of[min-large-message-size](#large-messages.core.config).

5.4.5. Heart-beating

The broker specifies a minimum value for both client and server heart-beat intervals. The minimuminterval for both client and server heartbeats is 500 milliseconds. That means if a client sends aCONNECT frame with heartbeat values lower than 500, the server will default the value to 500milliseconds regardless of the values of the heart-beat header in the frame.

5.4.5.1. Connection-ttl

STOMP clients should always send a DISCONNECT frame before closing their connections. In thiscase the server will clear up any server side resources such as sessions and consumerssynchronously. However if STOMP clients exit without sending a DISCONNECT frame or if theycrash the server will have no way of knowing immediately whether the client is still alive or not.STOMP connections therefore default to a connection-ttl value of 1 minute. This value can beoverridden using connection-ttl-override.

If you need a specific connectionTtl for your stomp connections without affecting the connectionTtlOverride setting, you can configure your stomp acceptor with the connectionTtl property, which is used to set the ttl for connections that are created from thatacceptor. For example:

tcp://localhost:61613?protocols=STOMP;connectionTtl=20000

The above configuration will make sure that any stomp connection that is created from that acceptorwill have its connection-ttl set to 20 seconds.

Note

Please note that the STOMP protocol version 1.0 does not contain any heartbeatframe. It is therefore the users responsibility to make sure data is sent withinconnection-ttl or the server will assume the client is dead and clean up server sideresources. With Stomp 1.1 users can use heart-beats to maintain the life cycle of


26

stomp connections.

5.4.6. Sending and Consuming Stomp Messages from JMS or A-MQ BrokerCore API

Stomp is mainly a text-orientated protocol. To make it simpler to interoperate with JMS and brokerCore API, our Stomp implementation checks for presence of the content-length header todecide how to map a Stomp message to a JMS message or a Core message.

If the Stomp message does not have a content-length header, it will be mapped to a JMSTextMessage or a Core message with a single nullable SimpleString in the body buffer.

Alternatively, if the Stomp message has a content-length header, it will be mapped to a JMSBytesMessage or a Core message with a byte[] in the body buffer.

The same logic applies when mapping a JMS message or a Core message to Stomp. A Stompclient can check the presence of the content-length header to determine the type of themessage body (String or bytes).

5.4.7. Mapping Destinations to A-MQ Broker Addresses and Queues

Stomp clients deal with destinations when sending messages and subscribing. Destination namesare string values which are mapped to some form of destination on the server - how the servertranslates these is left to the server implementation.

In brokers, these destinations are mapped to addresses and queues. When a Stomp client sends amessage (using a SEND frame), the specified destination is mapped to an address. When a Stompclient subscribes (or unsubscribes) for a destination (using a SUBSCRIBE or UNSUBSCRIBE frame),the destination is mapped to a broker queue.

5.4.8. JMS Destinations

JMS destinations are also mapped to broker addresses and queues. If you want to use Stomp tosend messages to JMS destinations, the Stomp destinations must follow the same convention:

Send or subscribe to a JMS Queue by prepending the queue name by jms.queue.. Forexample, to send a message to the orders JMS Queue, the Stomp client must send the frame:

SENDdestination:jms.queue.ordershello queue orders^@

Send or subscribe to a JMS Topic by prepending the topic name by jms.topic.. For exampleto subscribe to the stocks JMS Topic, the Stomp client must send the frame:

SUBSCRIBEdestination:jms.topic.stocks^@


27

CHAPTER 6. CONFIGURING DESTINATIONS

A-MQ Broker implements its own messaging API known as the Core API. Because many users willbe more comfortable using JMS, A-MQ Broker provides a JMS-based wrapper around the Core API.Including both the Core API and the JMS wrapper gives you the option to build agnostic messagingapplications or to build JMS-based applications. This chapter will show you both methods, Core andJMS, and will introduce you to the A-MQ Broker concept of address settings. As youll see anyqueue and topic is ultimately bound to an address setting.

6.1. QUEUES

There are two types of queues that can be configured in the broker: a JMS queue and a Corequeue. If you want a queue that is exposed to a JMS client and is also manageable via the JMSManagement resources, then you should configure a JMS queue. This is configured in the jms rootelement in the /etc/broker.xml configuration file.

Example JMS Queue Configuration

This example creates a durable JMS queue called myQueue. There are two optional parametersthat can also be configured on a JMS queue.

Table 6.1. Optional JMS Queue Parameters

Parameter Description Default Value

durable Whether the queue and itsmessages are persisted

True

selector A message selector to filtermessages arriving on the queue

null

Note

A JMS queue creates a Core queue under the covers using the jms.queue. prefix forthe queue name and address.

If you do not want to expose the queue to a JMS client or manage it using the JMS managementresources, you can use a Core queue. This is configured in the queues element within the coreroot element found in the /etc/broker.xml configuration file.

Example Core Queue Configuration


28

This will create a Core queue named myQueue with the address myAddress. Messages sent to theaddress myAddress will be forwarded to the queue myQueue. Consumers that consume from myQueue will receive the messages. Note that the optional parameters durable and filter servethe same purpose as durable and selector for JMS queues.

Note

If you are using any other client apart from the A-MQ Core JMS client you can interactwith JMS queues by adding the prefix jms.queue..

For more details on how queues interoperate with different protocols, refer to Configuring Protocols.

6.2. TOPICS

JMS Topics are fully supported and are implemented as facades that wrap A-MQ Broker queuesand addresses. Like queues, topics are configured in the jms root element found in the /etc/broker.xml configuration file.

Example JMS Topic Configuration

This example creates a JMS topic called myTopic which can be used with a JMS client.

Note

If you are using any other client apart from the A-MQ Core JMS client you can interactwith a JMS topic by adding the prefix jms.topic.. Messages sent to this address will beforwarded to any Core queues with this address. For receivers, this differs depending onthe protocol.

For a details on how JMS topics interoperate with different protocols, refer to Configuring Protocols.

6.3. ADDRESS SETTINGS

A-MQ Broker has several configurable options which control aspects of how and when a message isdelivered, how many attempts should be made, and when the message expires. Theseconfiguration options all exist within the configuration element. You can haveA-MQ Broker apply a single to multiple destinations by using a wildcard

myAddress

CHAPTER 6. CONFIGURING DESTINATIONS

29

syntax.

The A-MQ Broker Wildcard Syntax

Apache ActiveMQ Artemis uses a specific syntax for representing wildcards in security settings,address settings and when creating consumers.

The syntax is similar to that used by AMQP.

An Apache ActiveMQ Artemis wildcard expression contains words delimited by the character . (fullstop).

The special characters = and * also have special meaning and can take the place of a word.

The character = means 'match any sequence of zero or more words'.

The character * means 'match a single word'.

The examples in the table below illustrate how wildcards are used to match a set of addresses.

Table 6.2. Wildcard Examples

Example Description

news.europe.# Matches news.europe, news.europe.sport, news.europe.politics.fr, but not news.usa or europe.

news.* Matches news.europe and news.usa, but not news.europe.sport.

news.*.sport Matches news.europe.sport and news.usa.sport, but not news.europe.fr.sport.

Note

The use of a single # for the name attribute makes this default address-setting theconfiguration to be used for all destinations since # matches any address. You cancontinue to apply this catch-all configuration to all of your addresses, or you can add anew address-setting for each address or group of addresses that requires its ownconfiguration set.


30

http://www.amqp.org

CHAPTER 7. CONFIGURING SECURITY

Security across the broker can be enabled or disabled via in the element of the broker.xml configuration file.

To disable security specify false for .

To enable security specify true for . Security is enabled by default.

For performance reasons security is cached and invalidated every so often. To change this periodset the property security-invalidation-interval, which is in milliseconds. The default is 10000.

7.1. CONFIGURING AUTHENTICATION

Support for authentication is provided by pluggable "login modules" based on the JavaAuthentication and Authorization Service (JAAS) specification. A-MQ Broker includes login modulesto cover most use cases. Per JAAS, login modules are configured in a configuration file called login.config. In short, the file defines:

An alias for a configuration (e.g. activemq).

The implementation class (e.g., org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule).

A flag which indicates whether the success of the LoginModule is required, requisite, sufficient, or optional.

A list of configuration options specific to the login module implementation.

By default, the location and name of login.config is specified on the command line which is setby etc/artemis.profile on linux and etc\artemis.profile.cmd on Windows.

See Oracles tutorial for more information on how to use login.config.

Below are some of the most common use cases addressed by the login modules that are includedwith A-MQ Broker.

7.1.1. Configuring Guest Authentication

Aside from having no authentication at all, "anonymous access" is the most basic configuration. Inthis configuration, any user who connects without credentials or with the wrong credentials will beauthenticated automatically and assigned a specific user and role. This functionality is provided bythe "Guest" login module.

Example Guest Login Configuration

activemq { org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule required org.apache.activemq.jaas.guest.user="guest" org.apache.activemq.jaas.guest.role="guest";};


31

https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/LoginConfigFile.html

In this configuration the "Guest" login module will assign users the username "guest" and the role"guest". This is relevant for role-based authorization which is discussed in a subsequent section.

The "entry" is "activemq" and that name would be referenced in bootstrap.xml like so:

Guest Login Module Details

The guest login module allows users without credentials (and, depending on how it is configured,possibly also users with invalid credentials) to access the broker. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule.

org.apache.activemq.jaas.guest.user - the user name to assign; default is "guest"

org.apache.activemq.jaas.guest.role - the role name to assign; default is "guests"

credentialsInvalidate - boolean flag; if true, reject login requests that include apassword (i.e. guest login succeeds only when the user does not provide a password); default is false

debug - boolean flag; if true, enable debugging; this is used only for testing or debugging;normally, it should be set to false, or omitted; default is false

It is common for the guest login module to be chained with another login module, such as aproperties login module. Read more about that use-case in the Section 7.1.5, Configuring MultipleLogin Modules for Authentication section.

7.1.2. Configuring Basic User and Password Authentication

When basic username and password validation is required the simplest option is to use the"Properties" login module. This login module will check the users credentials against a set of localproperty files. Heres an example login.config:

Example Properties Login Configuration

activemq { org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required org.apache.activemq.jaas.properties.user="users.properties" org.apache.activemq.jaas.properties.role="roles.properties";};

The user properties file follows the pattern of user=password. For example:

user1=secretuser2=swordfishuser3=myPassword

There are 3 users defined here - user1, user2, and user3. The user1 user has a password of secret while user2 has a password of swordfish and user3 has a password of myPassword.

The role properties file follows the pattern of role=user where the user can be a comma delimitedlist of users in that particular role. For example:


32

admin=user1,user2developer=user3

There are 2 groups defined here - admin and developer. The users user1 and user2 belong tothe admin role and the user user3 belongs to the developer role.

The "entry" is "activemq" and that name would be referenced in bootstrap.xml like so:

Basic User and Password Login Module Details

The JAAS properties login module provides a simple store of authentication data, where the relevantuser data is stored in a pair of flat files. This is convenient for demonstrations and testing, but for anenterprise system, the integration with LDAP is preferable. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule.

org.apache.activemq.jaas.properties.user - the path to the file which contains userand password properties

org.apache.activemq.jaas.properties.role - the path to the file which contains userand role properties


In the context of the properties login module, the users.properties file consists of a list ofproperties of the form, UserName=Password. For example, to define the users system, user, andguest, you could create a file like the following:

system=manageruser=passwordguest=password

The roles.properties file consists of a list of properties of the form, Role=UserList, whereUserList is a comma-separated list of users. For example, to define the roles admins, users, and guests, you could create a file like the following:

admins=systemusers=system,userguests=guest

7.1.3. Configuring Certificate Based Authentication

The JAAS certificate authentication login module must be used in combination with SSL and theclients must be configured with their own certificate. In this scenario, authentication is actuallyperformed during the SSL/TLS handshake, not directly by the JAAS certificate authentication plug-in.

The role of the plug-in is as follows:

To further constrain the set of acceptable users, because only the user DNs explicitly listed inthe relevant properties file are eligible to be authenticated.

To associate a list of groups with the received user identity, facilitating integration with


33

authorization.

To require the presence of an incoming certificate (by default, the SSL/TLS layer is configured totreat the presence of a client certificate as optional).

The JAAS certificate login module stores a collection of certificate DNs in a pair of flat files. The filesassociate a username and a list of group IDs with each DN.

The certificate login module is implemented by org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule.

The following activemq login entry shows how to configure certificate login module in thelogin.config file:

activemq { org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule debug=true org.apache.activemq.jaas.textfiledn.user="users.properties" org.apache.activemq.jaas.textfiledn.role="roles.properties";};

In the preceding example, the JAAS realm is configured to use a single org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule login module. The options supported by this login module are as follows:


org.apache.activemq.jaas.textfiledn.user - specifies the location of the userproperties file (relative to the directory containing the login configuration file).

org.apache.activemq.jaas.textfiledn.role - specifies the location of the roleproperties file (relative to the directory containing the login configuration file).

In the context of the certificate login module, the users.properties file consists of a list ofproperties of the form, UserName=StringifiedSubjectDN. For example, to define the users,system, user, and guest, one could create a file like the following:

system=CN=system,O=Progress,C=USuser=CN=humble user,O=Progress,C=USguest=CN=anon,O=Progress,C=DE

Each username is mapped to a subject DN, encoded as a string (where the string encoding isspecified by RFC 2253). For example, the system username is mapped to the CN=system,O=Progress,C=US subject DN. When performing authentication, the plug-in extractsthe subject DN from the received certificate, converts it to the standard string format, and comparesit with the subject DNs in the users.properties file by testing for string equality. Consequently,you must be careful to ensure that the subject DNs appearing in the users.properties file arean exact match for the subject DNs extracted from the user certificates.

Note: Technically, there is some residual ambiguity in the DN string format. For example, the domainComponent attribute could be represented in a string either as the string, DC, or as the OID,0.9.2342.19200300.100.1.25. Normally, you do not need to worry about this ambiguity. But itcould potentially be a problem, if you changed the underlying implementation of the Java security


34

layer.

The easiest way to obtain the subject DNs from the user certificates is by invoking the keytoolutility to print the certificate contents. To print the contents of a certificate in a keystore, perform thefollowing steps:

1. Export the certificate from the keystore file into a temporary file. For example, to export thecertificate with alias broker-localhost from the broker.ks keystore file, enter thefollowing command:

keytool -export -file broker.export -alias broker-localhost -keystore broker.ks -storepass password

After running this command, the exported certificate is in the file, broker.export.

2. Print out the contents of the exported certificate. For example, to print out the contents of broker.export, enter the following command:

keytool -printcert -file broker.export

Which should produce output similar to that shown here:

Owner: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=UnknownIssuer: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=UnknownSerial number: 4537c82eValid from: Thu Oct 19 19:47:10 BST 2006 until: Wed Jan 17 18:47:10 GMT 2007Certificate fingerprints: MD5: 3F:6C:0C:89:A8:80:29:CC:F5:2D:DA:5C:D7:3F:AB:37 SHA1: F0:79:0D:04:38:5A:46:CE:86:E1:8A:20:1F:7B:AB:3A:46:E4:34:5C

The string following Owner: gives the subject DN. The format used to enter the subject DNdepends on your platform. The Owner: string above could be represented as either CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown or CN=localhost,OU=broker,O=Unknown,L=Unknown,ST=Unknown,C=Unknown.

The roles.properties file consists of a list of properties of the form, Role=UserList, where UserList is a comma-separated list of users. For example, to define the roles admins, users,and guests, you could create a file like the following:

admins=systemusers=system,userguests=guest

7.1.4. Configuring LDAP Authentication

The LDAP login module enables authentication and authorization by checking the incomingcredentials against user data stored in a central X.500 directory server. It is implemented by org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule.


35

Heres an example login.config:

activemq { org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule required debug=true initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory connectionURL="ldap://localhost:1024" connectionUsername="uid=admin,ou=system" connectionPassword=secret connectionProtocol=s authentication=simple userBase="ou=system" userSearchMatching="(uid={0})" userSearchSubtree=false roleBase="ou=system" roleName=cn roleSearchMatching="(member=uid={1},ou=system)" roleSearchSubtree=false ;};

initialContextFactory - must always be set to com.sun.jndi.ldap.LdapCtxFactory

connectionURL - specify the location of the directory server using an ldap URL,ldap://Host:Port. One can optionally qualify this URL, by adding a forward slash, /, followed bythe DN of a particular node in the directory tree. For example,ldap://ldapserver:10389/ou=system.

authentication - specifies the authentication method used when binding to the LDAP server.Can take either of the values, simple (username and password) or none (anonymous).

connectionUsername - the DN of the user that opens the connection to the directory server.For example, uid=admin,ou=system. Directory servers generally require clients to presentusername/password credentials in order to open a connection.

connectionPassword - the password that matches the DN from connectionUsername. Inthe directory server, in the DIT, the password is normally stored as a userPassword attribute inthe corresponding directory entry.

connectionProtocol - any value is supported but is effectively unused. In the future, thisoption may allow one to select the Secure Socket Layer (SSL) for the connection to the directoryserver. This option must be set explicitly because it has no default value.

userBase - selects a particular subtree of the DIT to search for user entries. The subtree isspecified by a DN, which specifies the base node of the subtree. For example, by setting thisoption to ou=User,ou=ActiveMQ,ou=system, the search for user entries is restricted to thesubtree beneath the ou=User,ou=ActiveMQ,ou=system node.

userSearchMatching - specifies an LDAP search filter, which is applied to the subtreeselected by userBase. Before passing to the LDAP search operation, the string value providedhere is subjected to string substitution, as implemented by the java.text.MessageFormatclass. Essentially, this means that the special string, {0}, is substituted by the username, asextracted from the incoming client credentials.

After substitution, the string is interpreted as an LDAP search filter, where the LDAP search filtersyntax is defined by the IETF standard, RFC 2254. A short introduction to the search filter syntax


36

is available from Oracles JNDI tutorial, Search Filters.

For example, if this option is set to (uid={0}) and the received username is jdoe, the searchfilter becomes (uid=jdoe) after string substitution. If the resulting search filter is applied to thesubtree selected by the user base, ou=User,ou=ActiveMQ,ou=system, it would match theentry, uid=jdoe,ou=User,ou=ActiveMQ,ou=system (and possibly more deeply nestedentries, depending on the specified search depthsee the userSearchSubtree option).

userSearchSubtree - specify the search depth for user entries, relative to the node specifiedby userBase. This option is a boolean. false indicates it will try to match one of the childentries of the userBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE). true indicates it will tryto match any entry belonging to the subtree of the userBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).

userRoleName - specifies the name of the multi-valued attribute of the user entry that containsa list of role names for the user (where the role names are interpreted as group names by thebrokers authorization plug-in). If this option is omitted, no role names are extracted from the userentry.

roleBase - if role data is stored directly in the directory server, one can use a combination ofrole options (roleBase, roleSearchMatching, roleSearchSubtree, and roleName) asan alternative to (or in addition to) specifying the userRoleName option. This option selects aparticular subtree of the DIT to search for role/group entries. The subtree is specified by a DN,which specifies the base node of the subtree. For example, by setting this option to ou=Group,ou=ActiveMQ,ou=system, the search for role/group entries is restricted to thesubtree beneath the ou=Group,ou=ActiveMQ,ou=system node.

roleName - specifies the attribute type of the role entry that contains the name of the role/group(e.g. C, O, OU, etc.). If this option is omitted the role search feature is effectively disabled.

roleSearchMatching - specifies an LDAP search filter, which is applied to the subtreeselected by roleBase. This works in a similar manner to the userSearchMatching option,except that it supports two substitution strings. The substitution string {0} substitutes the full DNof the matched user entry (that is, the result of the user search). For example, for the user, jdoe,the substituted string could be uid=jdoe,ou=User,ou=ActiveMQ,ou=system. Thesubstitution string {1} substitutes the received username. For example, jdoe.

If this option is set to (member=uid={1}) and the received username is jdoe, the search filterbecomes (member=uid=jdoe) after string substitution (assuming ApacheDS search filtersyntax). If the resulting search filter is applied to the subtree selected by the role base, ou=Group,ou=ActiveMQ,ou=system, it matches all role entries that have a member attributeequal to uid=jdoe (the value of a member attribute is a DN).

This option must always be set, even if role searching is disabled, because it has no defaultvalue.

If OpenLDAP is used, the syntax of the search filter is (member:=uid=jdoe).

roleSearchSubtree - specify the search depth for role entries, relative to the node specifiedby roleBase. This option can take boolean values, as follows:

false (default) - try to match one of the child entries of the roleBase node (maps to javax.naming.directory.SearchControls.ONELEVEL_SCOPE).


37

http://download.oracle.com/javase/jndi/tutorial/basics/directory/filter.html

true try to match any entry belonging to the subtree of the roleBase node (maps to javax.naming.directory.SearchControls.SUBTREE_SCOPE).


Add user entries under the node specified by the userBase option. When creating a new user entryin the directory, choose an object class that supports the userPassword attribute (for example, the person or inetOrgPerson object classes are typically suitable). After creating the user entry, addthe userPassword attribute, to hold the users password.

If role data must be stored in dedicated role entries (where each node represents a particular role),create a role entry as follows. Create a new child of the roleBase node, where the objectClassof the child is groupOfNames. Set the cn (or whatever attribute type is specified by roleName) ofthe new child node equal to the name of the role/group. Define a member attribute for each memberof the role/group, setting the member value to the DN of the corresponding user (where the DN isspecified either fully, uid=jdoe,ou=User,ou=ActiveMQ,ou=system, or partially, uid=jdoe).

If roles need to be added to user entries, that requires directory schema customization by adding asuitable attribute type to the user entrys object class. The chosen attribute type must be capable ofhandling multiple values.

7.1.5. Configuring Multiple Login Modules for Authentication

It is possible to combine login modules to accommodate more complex use-cases. The mostcommon reason to combine login modules is to support authentication for both anonymous usersand users who submit credentials.

The following snippet shows how to configure a JAAS login entry for the use case where users withno credentials or invalid credentials are logged in as guests (via the guest login module) and userswho submit valid credentials are logged in with the corresponding role/permissions (via theproperties login module).

activemq { org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient debug=true org.apache.activemq.jaas.properties.user="users.properties" org.apache.activemq.jaas.properties.role="roles.properties";

org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient debug=true org.apache.activemq.jaas.guest.user="guest" org.apache.activemq.jaas.guest.role="restricted";};

red hat jboss a-mq 7.0-beta using a-mq broker resources, minimizing the number of threads blocking...

Documents