Securing the Apache ActiveMQ Artemis REST Interface

215 Pages·2015·1.27 MB·English

Table of Contents
1. Introduction
2. Legal Notice
3. Preface
4. Project Info
5. Running the Server
6. Messaging Concepts
7. Architecture
8. Using the Server
9. Using JMS
10. Using Core
11. Mapping JMS Concepts to the Core API
12. The Client Classpath
13. Examples
14. Routing Messages With Wild Cards
15. Understanding the Apache ActiveMQ Artemis Wildcard Syntax
16. Filter Expressions
17. Persistence
18. Configuring Transports
19. Detecting Dead Connections
20. Detecting Slow Consumers
21. Resource Manager Configuration
22. Flow Control
23. Guarantees of sends and commits
24. Message Redelivery and Undelivered Messages
25. Message Expiry
26. Large Messages
27. Paging
28. Queue Attributes
29. Scheduled Messages
30. Last-Value Queues
31. Message Grouping
32. Extra Acknowledge Modes
33. Management
34. Security
35. Resource Limits
36. The JMS Bridge
37. Client Reconnection and Session Reattachment
38. Diverting and Splitting Message Flows
39. Core Bridges
40. Duplicate Message Detection
41. Clusters
42. High Availability and Failover
43. Graceful Server Shutdown
44. Libaio Native Libraries
45. Thread management
46. Logging
47. REST Interface
48. Embedding Apache ActiveMQ Artemis
49. Spring Integration
50. AeroGear Integration
51. VertX Integration
52. Intercepting Operations
53. Interoperability
54. Tools
55. Performance Tuning
56. Configuration Reference
Apache ActiveMQ Artemis User Manual
The User manual is an in depth manual on all aspects of Apache ActiveMQ Artemis
Legal Notice
Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You
under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License 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.
Preface
What is Apache ActiveMQ Artemis?
Apache ActiveMQ Artemis is an open source project to build a multi-protocol, embeddable, very high performance,
clustered, asynchronous messaging system.
Apache ActiveMQ Artemis is an example of Message Oriented Middleware (MoM). For a description of MoMs and
other messaging concepts please see the Messaging Concepts.
For answers to more questions about what Apache ActiveMQ Artemis is and what it isn't please visit the FAQs wiki
page.
Why use Apache ActiveMQ Artemis? Here are just a few of the reasons:
100% open source software. Apache ActiveMQ Artemis is licensed using the Apache Software License v 2.0 to
minimise barriers to adoption.
Apache ActiveMQ Artemis is designed with usability in mind.
Written in Java. Runs on any platform with a Java 8+ runtime, that's everything from Windows desktops to IBM
mainframes.
Amazing performance. Our ground-breaking high performance journal provides persistent messaging performance
at rates normally seen for non-persistent messaging, our non-persistent messaging performance rocks the boat
too.
Full feature set. All the features you'd expect in any serious messaging system, and others you won't find anywhere
else.
Elegant, clean-cut design with minimal third party dependencies. Run ActiveMQ Artemis stand-alone, run it in
integrated in your favourite JEE application server, or run it embedded inside your own product. It's up to you.
Seamless high availability. We provide a HA solution with automatic client failover so you can guarantee zero
message loss or duplication in event of server failure.
Hugely flexible clustering. Create clusters of servers that know how to load balance messages. Link geographically
distributed clusters over unreliable connections to form a global network. Configure routing of messages in a highly
flexible way.
Project Information
The official Apache ActiveMQ Artemis project page is http://activemq.apache.org//.
Software Download
The software can be download from the Download page:http://activemq.apache.org/download.html
Project Information
If you have any user questions please use our user forum
If you have development related questions, please use our developer forum
Pop in and chat to us in our IRC channel
Follow us on twitter
Apache ActiveMQ Artemis Git repository is https://github.com/apache/activemq-artemis
All release tags are available from https://github.com/apache/activemq-artemis/releases
And many thanks to all our contributors, both old and new who helped create Apache ActiveMQ Artemis.
Prerequisites
Note
ActiveMQ Artemis only runs on Java 7 or later.
By default, ActiveMQ Artemis server runs with 1GiB of memory. If your computer has less memory, or you want to run it
with more available RAM, modify the value in bin/run.sh accordingly.
If you are on Linux you may want to enable libaio For persistence, ActiveMQ Artemis uses its own fast journal, which you
can configure to use libaio (which is the default when running on Linux) or Java NIO. In order to use the libaio module on
Linux, you'll need to install libaio, if it's not already installed.
If you're not running on Linux then you don't need to worry about this.
You can install libaio using the following steps as the root user:
Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
yum install libaio
Using aptitude, (e.g. on Ubuntu or Debian system):
apt-get install libaio
Installation
After downloading the distribution, the following highlights some important folders on the distribution:
|___ bin
|
|___ web
| |___ user-manual
| |___ api
|
|___ examples
| |___ core
| |___ javaee
| |___ jms
|
|___ lib
|
|___ schema
bin -- binaries and scripts needed to run ActiveMQ Artemis.
web -- The folder where the web context is loaded when ActiveMQ Artemis runs.
user-manual -- The user manual is placed under the web folder.
api -- The api documentation is placed under the web folder
examples -- JMS and Java EE examples. Please refer to the 'running examples' chapter for details on how to run
them.
lib -- jars and libraries needed to run ActiveMQ Artemis
licenses -- licenses for ActiveMQ Artemis
schemas -- XML Schemas used to validate ActiveMQ Artemis configuration files
Creating a Broker Instance
A broker instance is the directory containing all the configuration and runtime data, such as logs and data files,
associated with a broker process. It is recommended that you do not create the instance directory under ${ARTEMIS_HOME} .
This separation is encouraged so that you can more easily upgrade when the next version of ActiveMQ Artemis is
released.
On Unix systems, it is a common convention to store this kind of runtime data under the /var/lib directory. For example,
to create an instance at '/var/lib/mybroker', run the following commands in your command line shell:
cd /var/lib
${ARTEMIS_HOME}/bin/activemq create mybroker
A broker instance directory will contain the following sub directories:
bin : holds execution scripts associated with this instance.
etc : hold the instance configuration files
data : holds the data files used for storing persistent messages
log : holds rotating log files
tmp : holds temporary files that are safe to delete between broker runs
At this point you may want to adjust the default configuration located in the etc directory.
Environment variables are used to provide ease of changing ports, hosts and data directories used and can be found in
etc/activemq.profile on linux and etc\activemq.profile.cmd on Windows.
Options
There are several options you can use when creating an instance.
For a full list of updated properties always use:
$./artemis help create
NAME
artemis create - creates a new broker instance
SYNOPSIS
artemis create [--allow-anonymous]
[--cluster-password <clusterPassword>] [--cluster-user <clusterUser>]
[--clustered] [--data <data>] [--encoding <encoding>] [--force]
[--home <home>] [--host <host>] [--java-options <javaOptions>]
[--password <password>] [--port-offset <portOffset>] [--replicated]
[--role <role>] [--shared-store] [--silent-input] [--user <user>] [--]
<directory>
OPTIONS
--allow-anonymous
Enables anonymous configuration on security (Default: input)
--cluster-password <clusterPassword>
The cluster password to use for clustering. (Default: input)
--cluster-user <clusterUser>
The cluster user to use for clustering. (Default: input)
--clustered
Enable clustering
--data <data>
Directory where ActiveMQ Data is used. Path are relative to
artemis.instance/bin
--encoding <encoding>
The encoding that text files should use
--force
Overwrite configuration at destination directory
--home <home>
Directory where ActiveMQ Artemis is installed
--host <host>
The host name of the broker (Default: 0.0.0.0 or input if clustered)
--java-options <javaOptions>
Extra java options to be passed to the profile
--password <password>
The user's password (Default: input)
--port-offset <portOffset>
Off sets the default ports
--replicated
Enable broker replication
--role <role>
The name for the role created (Default: amq)
--shared-store
Enable broker shared store
--silent-input
It will disable all the inputs, and it would make a best guess for
any required input
--user <user>
The username (Default: input)
--
This option can be used to separate command-line options from the
list of argument, (useful when arguments might be mistaken for
command-line options
<directory>
The instance directory to hold the broker's configuration and data
Some of these properties may be mandatory in certain configurations and the system may ask you for additional input.
./artemis create /usr/server
Creating ActiveMQ Artemis instance at: /user/server
--user: is mandatory with this configuration:
Please provide the default username:
admin
--password: is mandatory with this configuration:
Please provide the default password:
--allow-anonymous: is mandatory with this configuration:
Allow anonymous access? (Y/N):
y
You can now start the broker by executing:
"/user/server/bin/artemis" run
Or you can run the broker in the background using:
"/user/server/bin/artemis-service" start
Starting and Stopping a Broker Instance
Assuming you created the broker instance under /var/lib/mybroker all you need to do start running the broker instance is
execute:
/var/lib/mybroker/bin/activemq run
Now that the broker is running, you can optionally run some of the included examples to verify the the broker is running
properly.
To stop the Apache ActiveMQ Artemis instance you will use the same activemq script, but with the stop argument . Example:
/var/lib/mybroker/bin/activemq stop
By default the etc/bootstrap.xml configuration is used. The configuration can be changed e.g. by running ./activemq run --
xml:path/to/bootstrap.xml or another config of your choosing.
Windows Server
On windows you will have the option to run ActiveMQ Artemis as a service. Just use the following command to install it:
$ ./artemis-service.exe install
The create process should give you a hint of the available commands available for the artemis-service.exe