Chapter 4. Getting Started

This chapter introduces you to AMQ Broker by showing you how to perform the following basic but important tasks:

Create a broker instance.
Start a broker instance.
Stop a broker instance.
Run the examples included with the installation of AMQ Broker.

4.1. Creating a Broker Instance

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

Creating a Broker Instance on Linux

Procedure

Create a directory location for the broker instance, for example /var/opt/amq-broker, and assign the user you created during installation as its owner:
```
$ sudo mkdir /var/opt/amq-broker
$ sudo chown -R amq-broker:amq-broker /var/opt/amq-broker
```
Move to the new directory and use the artemis create command to create a broker. For example, to create the broker instance mybroker under the /var/opt/amq-broker directory, run the following commands. Note that in the following example the user that was created during installation is the one to run the create command:
```
$ su - amq-broker
$ cd /var/opt/amq-broker
$ INSTALL_DIR/bin/artemis create mybroker
```

Creating a Broker Instance on Windows

Procedure

Using Windows Explorer create a new folder to serve as the location for the broker instance.
Open a Windows command prompt from the location you just created and use the artemis.cmd create command to create a broker. For example, to create the broker instance mybroker, run the following command:
```
> INSTALL_DIR\bin\artemis.cmd create mybroker
```

Responding to Questions Asked During the Creation Process

The create command will ask a series of questions to configure the broker instance. It will prompt for mandatory property value only. For the full list of properties available when creating an instance, run the artemis help create command.

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

Creating ActiveMQ Artemis instance at: /var/opt/amq-broker/mybroker

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

--password: is mandatory with this configuration:
Please provide the default password:
<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):
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/opt/amq-broker/mybroker/bin/artemis" run

Or you can run the broker in the background using:

"/var/opt/amq-broker/mybroker/bin/artemis-service" start

Broker Instance Directory Contents

The process creates a top level directory and several subdirectories containing configuration and runtime data. In the preceding examples, the top level directory is named mybroker. The documentation refers to the top level location as the BROKER_INSTANCE_DIR. The table below details its structure and contents.

Table 4.1. Contents of a broker instance directory
If you want to find…	Look here…
Scripts that launch and manage the instance	`BROKER_INSTANCE_DIR/bin`
Configuration files	`BROKER_INSTANCE_DIR/etc`
Storage for persistent messages	`BROKER_INSTANCE_DIR/data`
Log files	`BROKER_INSTANCE_DIR/log`
Temporary files	`BROKER_INSTANCE_DIR/tmp`

4.2. Starting a Broker Instance

After the broker is created, use the artemis script in the BROKER_INSTANCE_DIR/bin directory to start it. For instance, to start a broker created at /var/opt/amq-broker/mybroker, use the following command as the user you created during installation. In the following example, the user amq-broker starts the broker:

$ su - amq-broker
$ /var/opt/amq-broker/mybroker/bin/artemis run

The artemis command has other other options available. Provide the help parameter to learn more:

$ /var/opt/amq-broker/mybroker/bin/artemis help

When started, the broker will produce output similar to the following:

          __  __  ____    ____            _
    /\   |  \/  |/ __ \  |  _ \          | |
   /  \  | \  / | |  | | | |_) |_ __ ___ | | _____ _ __
  / /\ \ | |\/| | |  | | |  _ <| '__/ _ \| |/ / _ \ '__|
 / ____ \| |  | | |__| | | |_) | | | (_) |   <  __/ |
/_/    \_\_|  |_|\___\_\ |____/|_|  \___/|_|\_\___|_|

Red Hat JBoss AMQ 7.1.0.GA

10:53:43,959 INFO  [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server
10:53:44,076 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)
10:53:44,099 INFO  [org.apache.activemq.artemis.core.server] AMQ221012: Using AIO Journal
10:53:44,158 INFO  [org.apache.activemq.artemis.core.server] AMQ221057: Global Max Size is being adjusted to 1/2 of the JVM max size (-Xmx). being defined as 1,073,741,824
10:53:44,176 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-server]. Adding protocol support for: CORE
10:53:44,176 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-amqp-protocol]. Adding protocol support for: AMQP
10:53:44,177 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-hornetq-protocol]. Adding protocol support for: HORNETQ
10:53:44,177 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-mqtt-protocol]. Adding protocol support for: MQTT
10:53:44,177 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-openwire-protocol]. Adding protocol support for: OPENWIRE
10:53:44,177 INFO  [org.apache.activemq.artemis.core.server] AMQ221043: Protocol module found: [artemis-stomp-protocol]. Adding protocol support for: STOMP
10:53:44,250 INFO  [org.apache.activemq.artemis.core.server] AMQ221034: Waiting indefinitely to obtain live lock
10:53:44,250 INFO  [org.apache.activemq.artemis.core.server] AMQ221035: Live Server Obtained live lock
10:53:44,348 INFO  [org.apache.activemq.artemis.core.server] AMQ221003: Deploying queue DLQ on address DLQ
10:53:44,458 INFO  [org.apache.activemq.artemis.core.server] AMQ221003: Deploying queue ExpiryQueue on address ExpiryQueue
10:53:44,767 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started EPOLL Acceptor at 0.0.0.0:61616 for protocols [CORE,MQTT,AMQP,STOMP,HORNETQ,OPENWIRE]
10:53:44,772 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started EPOLL Acceptor at 0.0.0.0:5445 for protocols [HORNETQ,STOMP]
10:53:44,775 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started EPOLL Acceptor at 0.0.0.0:5672 for protocols [AMQP]
10:53:44,778 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started EPOLL Acceptor at 0.0.0.0:1883 for protocols [MQTT]
10:53:44,780 INFO  [org.apache.activemq.artemis.core.server] AMQ221020: Started EPOLL Acceptor at 0.0.0.0:61613 for protocols [STOMP]
10:53:44,787 INFO  [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live
10:53:44,787 INFO  [org.apache.activemq.artemis.core.server] AMQ221001: Apache ActiveMQ Artemis Message Broker version 2.4.0.amq-710001-redhat-1 [0.0.0.0, nodeID=036f2ead-df5d-11e7-a02f-0800274e493d]
10:53:45,041 INFO  [io.hawt.branding.plugin.PluginContextListener] Initialized hawtio-redhat-fuse-branding plugin
10:53:45,107 INFO  [org.apache.activemq.hawtio.plugin.PluginContextListener] Initialized artemis-plugin plugin
10:53:45,552 INFO  [io.hawt.system.ConfigManager] Configuration will be discovered via system properties
10:53:45,556 INFO  [io.hawt.jmx.JmxTreeWatcher] Welcome to hawtio 1.4.0.redhat-630310 : http://hawt.io/ : Don't cha wish your console was hawt like me? ;-)
10:53:45,558 INFO  [io.hawt.jmx.UploadManager] Using file upload directory: /var/opt/amq-broker/broker-7.1/tmp/uploads
10:53:45,572 INFO  [io.hawt.web.AuthenticationFilter] Starting hawtio authentication filter, JAAS realm: "activemq" authorized role(s): "amq" role principal classes: "org.apache.activemq.artemis.spi.core.security.jaas.RolePrincipal"
10:53:45,599 INFO  [io.hawt.web.JolokiaConfiguredAgentServlet] Jolokia overridden property: [key=policyLocation, value=file:/var/opt/amq-broker/broker-7.1//etc/jolokia-access.xml]
10:53:45,624 INFO  [io.hawt.web.RBACMBeanInvoker] Using MBean [hawtio:type=security,area=jmx,rank=0,name=HawtioDummyJMXSecurity] for role based access control
10:53:45,782 INFO  [io.hawt.system.ProxyWhitelist] Initial proxy whitelist: [localhost, 127.0.0.1, 192.168.99.101, rhel7-1, 10.0.3.15]
10:53:46,040 INFO  [org.apache.activemq.artemis] AMQ241001: HTTP Server started at http://localhost:8161
10:53:46,041 INFO  [org.apache.activemq.artemis] AMQ241002: Artemis Jolokia REST API available at http://localhost:8161/console/jolokia
10:53:46,041 INFO  [org.apache.activemq.artemis] AMQ241004: Artemis Console available at http://localhost:8161/console

4.2.1. Starting a Broker as a Linux Service

If the broker is installed on Linux, you can run it as a service.

Procedure

Create a new amq-broker.service file in the /etc/systemd/system/ directory.

Copy the following text into the file.

Modify the path and user fields according to the information provided during the broker instance creation. In the example below, the user amq-broker starts the broker service installed under the /var/opt/amq-broker/mybroker/ directory.

[Unit]
Description=AMQ Broker
After=syslog.target network.target

[Service]
ExecStart=/var/opt/amq-broker/mybroker/bin/artemis run
Restart=on-failure
User=amq-broker
Group=amq-broker

# A workaround for Java signal handling
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

Open a terminal.
Enable the broker service using the following command:
```
sudo systemctl enable amq-broker
```
Run the broker service using the following command:
```
sudo systemctl start amq-broker
```

4.2.2. Starting a Broker as a Windows Service

If the broker is installed on Windows, you can run it as a service.

Procedure

The following steps require that you open a command prompt to enter the commands.

Install the broker as a service with the following command:
```
BROKER_INSTANCE_DIR\bin\artemis-service.exe install
```

Start the service by using the following command:

BROKER_INSTANCE_DIR\bin\artemis-service.exe start

(Optional) Uninstall the service:

BROKER_INSTANCE_DIR\bin\artemis-service.exe uninstall

4.3. Stopping a Broker Instance

You can stop the broker manually by issuing the stop command. Immediately after the command is entered, all connections to the broker are forcefully stopped and the shutdown process begins.

Procedure

Stop the broker.
1. If you are running the broker on Linux, issue the following command:
```
BROKER_INSTANCE_DIR\bin\artemis stop
```
2. If you are running the broker on Windows as a service, issue the following command:
```
BROKER_INSTANCE_DIR\bin\artemis-service.exe stop
```

4.3.1. Stopping a Broker Instance Gracefully

A manual shutdown forcefully disconnects all clients after a stop command is entered. As an alternative, configure the broker to shutdown gracefully by using the graceful-shutdown-enabled configuration element.

When graceful-shutdown-enabled is set to true, no new client connections are allowed after a stop command is entered. However, existing connections are allowed to close on the client-side before the shutdown process is started. The default value for graceful-shutdown-enabled is false.

Use the graceful-shutdown-timeout configuration element to set a length of time, in milliseconds, for clients to disconnect before connections are forcefully closed from the broker side. After all connections are closed, the shutdown process is started. One advantage of using graceful-shutdown-timeout is that it prevents client connections from delaying a shutdown. The default value for graceful-shutdown-timeout is -1, meaning the broker waits indefinitely for clients to disconnect.

The following procedure demonstrates how to configure a graceful shutdown that uses a timeout.

Procedure

Open the configuration file BROKER_INSTANCE_DIR\etc\broker.xml.

Add the graceful-shutdown-enabled configuration element and set the value to true.

<configuration>
     <core>
          ...
          <graceful-shutdown-enabled>
              true
          </graceful-shutdown-enabled>
          ...
     </core>
</configuration>

Add the graceful-shutdown-timeout configuration element and set a value for the timeout in milliseconds. In the following example, client connections are forcefully closed 30 seconds (30000 milliseconds) after the stop command is issued.

<configuration>
     <core>
          ...
          <graceful-shutdown-enabled>
              true
          </graceful-shutdown-enabled>
          <graceful-shutdown-timeout>
              30000
          </graceful-shutdown-timeout>
          ...
     </core>
</configuration>

4.4. Running the Included Examples

AMQ Broker ships with many example programs that highlight various basic and advanced features of the product. They can be found under INSTALL_DIR/examples.

The examples require a supported release of the Java Development Kit (JDK) and Maven version 3.2 or greater to build and run. Consult Supported Configurations for details about JDK support. The next section shows you how to install and configure Maven, enabling you to run the examples.

Downloading Maven and the AMQ Repository

Running the examples requires that both Maven and the Red Hat AMQ Broker Maven repository are installed locally. The steps below show you how to download, install, and configure both. For more information about Maven refer to the appendix.

Downloading and Installing Maven

Go to Apache Maven Project - Download Maven and download the latest distribution for your operating system.
Install Maven for your operating system.
For more information, see Installing Apache Maven.

Downloading and Installing the AMQ Maven Repository

Open a browser and log in to the Red Hat Customer Portal at https://access.redhat.com.
Click Downloads.
Find Red Hat AMQ in the Product Downloads list.
Select Download Latest Broker from the drop-down list located on the same row to go to the Software Downloads page for AMQ Broker.
From the Software Downloads page, select the correct AMQ Broker version from the Version drop-down menu.
Click the Download link for the Maven Repository to download a .zip file containing the repository.
Unzip the file on the local file system into a directory of your choosing.
This creates a new directory, which contains the Maven repository in a subdirectory named maven-repository/.

Important

If you want to continue to use an older local repository, you must configure it separately in the Maven settings.xml configuration file. Each local repository must be configured within its own <repository> element.

Important

Remove the cached repository/ subdirectory located under the .m2/ directory before attempting to use a new Maven repository.

Configuring the Maven Settings File

Locate the Maven settings.xml file for your operating system. It is usually located in the ${user.home}/.m2/ directory.
- For Linux or Mac, this is ~/.m2/
- For Windows, this is \Documents and Settings\.m2\ or \Users\.m2\
(Optional) If you do not find a settings.xml file in ${user.home}/.m2/, there is a default version located in the conf/ directory of your Maven installation. Copy the default settings.xml file into the ${user.home}/.m2/ directory.

Copy the following XML into the <profiles> element of the settings.xml file.

<!-- Configure the JBoss AMQ Maven repository -->
<profile>
  <id>jboss-amq-maven-repository</id>
  <repositories>
    <repository>
      <id>jboss-amq-maven-repository</id>
      <url>file://JBOSS_AMQ_REPOSITORY_PATH</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>jboss-amq-maven-repository</id>
      <url>file://JBOSS_AMQ_REPOSITORY_PATH</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>
</profile>

Replace JBOSS_AMQ_REPOSITORY_PATH within the url element with the location of the maven repository on the local file system. If you followed the installation steps above, the location should end with /maven-repository.
Copy the following XML into the <activeProfiles> element of the settings.xml file.
```
<activeProfile>jboss-amq-maven-repository</activeProfile>
```
(Optional) If you copied the default settings.xml from your Maven installation, uncomment the <active-profiles> section if it was commented out by default.

Important

If your Maven repository contains outdated artifacts, you may encounter one of the following Maven error messages when you build or deploy your project:

Missing artifact ARTIFACT_NAME
[ERROR] Failed to execute goal on project PROJECT_NAME; Could not resolve dependencies for PROJECT_NAME

To resolve the issue, delete the cached version of your local repository to force a download of the latest Maven artifacts. The cached repository is located here: ${user.home}/.m2/repository/

Several of the examples use UDP clustering, which may not work in your environment when you first attempt to run them. On Linux, you can issue a command to provide the appropriate environment. The following command redirects any traffic directed to 224.0.0.0 to the loopback interface, allowing examples that use UDP clustering to run successfully:

sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev lo

Running the `queue` Example to Test Your Installation

To run any example, change directories to the desired example and type mvn clean verify. You can also use the profile -P examples to run multiple examples under any example directory tree. For details on each example, read the readme.html file in each example directory. An excellent example to use as a "sanity test" of your broker installation is the queue example. The example creates a producer to send a message to the broker and a consumer that receives the same message.

Procedure

To build and run the example, navigate to the INSTALL_DIR/examples/features/standard/queue directory:
```
$ cd INSTALL_DIR/examples/features/standard/queue
```
Run the mvn clean verify command:
```
$ mvn clean verify
```

Maven will start the broker and run the example. When completed the output should look something like the following example. Note that the example may take a long time to run the first 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 message
server-out:11:30:46,545 INFO  [org.apache.activemq.artemis.core.server] AMQ221003: Trying to deploy queue jms.queue.exampleQueue
Received message: This is a text message
[INFO]
[INFO] --- artemis-maven-plugin:1.2.0.amq-700:cli (stop) @ queue ---
[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] ------------------------------------------------------------------------

Chapter 4. Getting Started

4.1. Creating a Broker Instance

Creating a Broker Instance on Linux

Creating a Broker Instance on Windows

Responding to Questions Asked During the Creation Process

Broker Instance Directory Contents

4.2. Starting a Broker Instance

4.2.1. Starting a Broker as a Linux Service

4.2.2. Starting a Broker as a Windows Service

4.3. Stopping a Broker Instance

4.3.1. Stopping a Broker Instance Gracefully

4.4. Running the Included Examples

Downloading Maven and the AMQ Repository

Running the `queue` Example to Test Your Installation

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 4. Getting Started

4.1. Creating a Broker Instance

Creating a Broker Instance on Linux

Creating a Broker Instance on Windows

Responding to Questions Asked During the Creation Process

Broker Instance Directory Contents

4.2. Starting a Broker Instance

4.2.1. Starting a Broker as a Linux Service

4.2.2. Starting a Broker as a Windows Service

4.3. Stopping a Broker Instance

4.3.1. Stopping a Broker Instance Gracefully

4.4. Running the Included Examples

Downloading Maven and the AMQ Repository

Running the queue Example to Test Your Installation

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

Running the `queue` Example to Test Your Installation