Chapter 3. Using the command line interface

3.1. Starting broker instances
Copia collegamento

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.

You can start a broker in the foreground by using the artemis script, as a Linux service, or as a Windows service.

3.1.1. Starting the broker instance
Copia collegamento

After the broker instance is created, you use the artemis run command to start it.

Procedure

Switch to the user account you created during installation.
```
su - amq-broker
```
```
$ su - amq-broker
```
Copy to Clipboard Toggle word wrap

Use the artemis run command to start the broker instance.

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

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

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

Red Hat JBoss AMQ 7.2.1.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
...

Copy to Clipboard

Toggle word wrap

The broker starts and displays log output with the following information:

The location of the transaction logs and cluster configuration.
The type of journal being used for message persistence (AIO in this case).
The URI(s) that can accept client connections.
By default, port 61616 can accept connections from any of the supported protocols (CORE, MQTT, AMQP, STOMP, HORNETQ, and OPENWIRE). There are separate, individual ports for each protocol as well.
The web console is available at http://localhost:8161.
The Jolokia service (JMX over REST) is available at http://localhost:8161/jolokia.

3.1.2. Starting a broker as a Linux service
Copia collegamento

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

[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

Copy to Clipboard

Toggle word wrap

Open a terminal.
Enable the broker service using the following command:
```
sudo systemctl enable amq-broker
```
```
sudo systemctl enable amq-broker
```
Copy to Clipboard Toggle word wrap
Run the broker service using the following command:
```
sudo systemctl start amq-broker
```
```
sudo systemctl start amq-broker
```
Copy to Clipboard Toggle word wrap

3.1.3. Starting a broker as a Windows service
Copia collegamento

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

Procedure

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
```
```
<broker-instance-dir>\bin\artemis-service.exe install
```
Copy to Clipboard Toggle word wrap
Start the service by using the following command:
```
<broker-instance-dir>\bin\artemis-service.exe start
```
```
<broker-instance-dir>\bin\artemis-service.exe start
```
Copy to Clipboard Toggle word wrap

(Optional) Uninstall the service:

<broker-instance-dir>\bin\artemis-service.exe uninstall

<broker-instance-dir>\bin\artemis-service.exe uninstall

Copy to Clipboard

Toggle word wrap

3.2. Stopping broker instances
Copia collegamento

Stop the broker instance manually or configure the broker to shutdown gracefully.

3.2.1. Stopping the broker instance
Copia collegamento

After creating the standalone broker and producing and consuming test messages, you can stop the broker instance.

This procedure manually stops the broker, which forcefully closes all client connections. In a production environment, you should configure the broker to stop gracefully so that client connections can be closed properly.

Procedure

Use the artemis stop command to stop the broker instance:

/var/opt/amq-broker/mybroker/bin/artemis stop

$ /var/opt/amq-broker/mybroker/bin/artemis stop
2018-12-03 14:37:30,630 INFO  [org.apache.activemq.artemis.core.server] AMQ221002: Apache ActiveMQ Artemis Message Broker version 2.6.1.amq-720004-redhat-1 [b6c244ef-f1cb-11e8-a2d7-0800271b03bd] stopped, uptime 35 minutes
Server stopped!

Copy to Clipboard

Toggle word wrap

3.2.2. Stopping a broker instance gracefully
Copia collegamento

A manual shutdown forcefully disconnects all clients after a stop command is entered. As an alternative, configure the broker to shut down 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>

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

Copy to Clipboard

Toggle word wrap

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>

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

Copy to Clipboard

Toggle word wrap

3.3. Auditing messages by intercepting packets
Copia collegamento

Intercept packets entering or exiting the broker, to audit packets or filter messages. Interceptors change the packets that they intercept. This makes interceptors powerful, but also potentially dangerous.

Develop interceptors to meet your business requirements. Interceptors are protocol specific and must implement the appropriate interface.

Interceptors must implement the intercept() method, which returns a boolean value. If the value is true, the message packet continues onward. If false, the process is aborted, no other interceptors are called, and the message packet is not processed further.

3.3.1. Creating interceptors
Copia collegamento

Interceptors can change the packets they intercept. You can create your own incoming and outgoing interceptors. All interceptors are protocol specific and are called for any packet entering or exiting the server respectively. This allows you to create interceptors to meet business requirements such as auditing packets.

Interceptors and their dependencies must be placed in the Java classpath of the broker. You can use the <broker-instance-dir>/lib directory because it is part of the classpath by default.

The following examples demonstrate how to create an interceptor that checks the size of each packet passed to it.

Note

The examples implement a specific interface for each protocol.

Procedure

Implement the appropriate interface and override its intercept() method.

If you are using the AMQP protocol, implement the org.apache.activemq.artemis.protocol.amqp.broker.AmqpInterceptor interface.

package com.example;

import org.apache.activemq.artemis.protocol.amqp.broker.AMQPMessage;
import org.apache.activemq.artemis.protocol.amqp.broker.AmqpInterceptor;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements AmqpInterceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  public boolean intercept(final AMQPMessage message, RemotingConnection connection)
  {
    int size = message.getEncodeSize();
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This AMQPMessage has an acceptable size.");
      return true;
    }
    return false;
  }
}

package com.example;

import org.apache.activemq.artemis.protocol.amqp.broker.AMQPMessage;
import org.apache.activemq.artemis.protocol.amqp.broker.AmqpInterceptor;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements AmqpInterceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  public boolean intercept(final AMQPMessage message, RemotingConnection connection)
  {
    int size = message.getEncodeSize();
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This AMQPMessage has an acceptable size.");
      return true;
    }
    return false;
  }
}

Copy to Clipboard

Toggle word wrap

If you are using the Core protocol, your interceptor must implement the org.apache.artemis.activemq.api.core.Interceptor interface.

package com.example;

import org.apache.artemis.activemq.api.core.Interceptor;
import org.apache.activemq.artemis.core.protocol.core.Packet;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements Interceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  boolean intercept(Packet packet, RemotingConnection connection)
  throws ActiveMQException
  {
    int size = packet.getPacketSize();
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This Packet has an acceptable size.");
      return true;
    }
    return false;
  }
}

package com.example;

import org.apache.artemis.activemq.api.core.Interceptor;
import org.apache.activemq.artemis.core.protocol.core.Packet;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements Interceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  boolean intercept(Packet packet, RemotingConnection connection)
  throws ActiveMQException
  {
    int size = packet.getPacketSize();
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This Packet has an acceptable size.");
      return true;
    }
    return false;
  }
}

Copy to Clipboard

Toggle word wrap

If you are using the MQTT protocol, implement the org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor interface.

package com.example;

import org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor;
import io.netty.handler.codec.mqtt.MqttMessage;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements Interceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  boolean intercept(MqttMessage mqttMessage, RemotingConnection connection)
  throws ActiveMQException
  {
    byte[] msg = (mqttMessage.toString()).getBytes();
    int size = msg.length;
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This MqttMessage has an acceptable size.");
      return true;
    }
    return false;
  }
}

package com.example;

import org.apache.activemq.artemis.core.protocol.mqtt.MQTTInterceptor;
import io.netty.handler.codec.mqtt.MqttMessage;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements Interceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  boolean intercept(MqttMessage mqttMessage, RemotingConnection connection)
  throws ActiveMQException
  {
    byte[] msg = (mqttMessage.toString()).getBytes();
    int size = msg.length;
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This MqttMessage has an acceptable size.");
      return true;
    }
    return false;
  }
}

Copy to Clipboard

Toggle word wrap

If you are using the Stomp protocol, implement the org.apache.activemq.artemis.core.protocol.stomp.StompFrameInterceptor interface.

package com.example;

import org.apache.activemq.artemis.core.protocol.stomp.StompFrameInterceptor;
import org.apache.activemq.artemis.core.protocol.stomp.StompFrame;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements Interceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  boolean intercept(StompFrame stompFrame, RemotingConnection connection)
  throws ActiveMQException
  {
    int size = stompFrame.getEncodedSize();
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This StompFrame has an acceptable size.");
      return true;
    }
    return false;
  }
}

package com.example;

import org.apache.activemq.artemis.core.protocol.stomp.StompFrameInterceptor;
import org.apache.activemq.artemis.core.protocol.stomp.StompFrame;
import org.apache.activemq.artemis.spi.core.protocol.RemotingConnection;

public class MyInterceptor implements Interceptor
{
  private final int ACCEPTABLE_SIZE = 1024;

  @Override
  boolean intercept(StompFrame stompFrame, RemotingConnection connection)
  throws ActiveMQException
  {
    int size = stompFrame.getEncodedSize();
    if (size <= ACCEPTABLE_SIZE) {
      System.out.println("This StompFrame has an acceptable size.");
      return true;
    }
    return false;
  }
}

Copy to Clipboard

Toggle word wrap

3.3.2. Configuring the broker to use interceptors
Copia collegamento

Prerequisites

Create an interceptor class and add it (and its dependencies) to the Java classpath of the broker. You can use the <broker-instance-dir>/lib directory since it is part of the classpath by default.

Procedure

Open <broker-instance-dir>/etc/broker.xml

Configure the broker to use an interceptor by adding configuration to _<broker-instance-dir>/etc/broker.xml

If the interceptor is intended for incoming messages, add its class-name to the list of remoting-incoming-interceptors.

<configuration>
  <core>
    ...
    <remoting-incoming-interceptors>
       <class-name>org.example.MyIncomingInterceptor</class-name>
    </remoting-incoming-interceptors>
    ...
  </core>
</configuration>

<configuration>
  <core>
    ...
    <remoting-incoming-interceptors>
       <class-name>org.example.MyIncomingInterceptor</class-name>
    </remoting-incoming-interceptors>
    ...
  </core>
</configuration>

Copy to Clipboard

Toggle word wrap

If the interceptor is intended for outgoing messages, add its class-name to the list of remoting-outgoing-interceptors.

<configuration>
  <core>
    ...
    <remoting-outgoing-interceptors>
       <class-name>org.example.MyOutgoingInterceptor</class-name>
    </remoting-outgoing-interceptors>
  </core>
</configuration>

<configuration>
  <core>
    ...
    <remoting-outgoing-interceptors>
       <class-name>org.example.MyOutgoingInterceptor</class-name>
    </remoting-outgoing-interceptors>
  </core>
</configuration>

Copy to Clipboard

Toggle word wrap

3.3.3. Interceptors on the client side
Copia collegamento

Clients can use interceptors to intercept packets either sent by the client to the server or by the server to the client. If the broker-side interceptor returns a false value, then no other interceptors are called and the client does not process the packet further. This process happens transparently, unless an outgoing packet is sent in a blocking fashion. In this case, an ActiveMQException is thrown to the caller. The ActiveMQException thrown contains the name of the interceptor that returned the false value.

On the server, the client interceptor classes and their dependencies must be added to the Java classpath of the client, to be properly instantiated and invoked.

3.4. Command line tools
Copia collegamento

AMQ Broker includes a set of command line interface (CLI) tools, so you can manage your messaging journal. The table below lists the name for each tool and its corresponding description.

Expand

Tool	Description
address	Addresses tool groups (create/delete/update/show) (example `./artemis address create`).
browser	Browses messages on an instance.
consumer	Consumes messages on an instance.
data	Prints reports about journal records and compacts the data.
decode	Imports the internal journal format from encode.
encode	Shows an internal format of the journal encoded to String.
exp	Exports the message data using a special and independent XML format.
help	Displays help information.
imp	Imports the journal to a running broker using the output provided by `exp`.
kill	Kills a broker instance started with --allow-kill.
mask	Masks a password and prints it out.
perf-journal	Calculates the journal-buffer timeout you should use with the current data folder.
queue	Queues tool groups (create/delete/update/stat) (example `./artemis queue create`).
run	Runs the broker instance.
stop	Stops the broker instance.
user	Default file-based user managament (add/rm/list/reset) (example `./artemis user list`)

For a full list of commands available for each tool, use the help parameter followed by the tool’s name. For instance, in the example below, the CLI output lists all the commands available to the data tool after the user enters the command ./artemis help data.

./artemis help data

$ ./artemis help data

NAME
        artemis data - data tools group
        (print|imp|exp|encode|decode|compact) (example ./artemis data print)

SYNOPSIS
        artemis data
        artemis data compact [--broker <brokerConfig>] [--verbose]
                [--paging <paging>] [--journal <journal>]
                [--large-messages <largeMessges>] [--bindings <binding>]
        artemis data decode [--broker <brokerConfig>] [--suffix <suffix>]
                [--verbose] [--paging <paging>] [--prefix <prefix>] [--file-size <size>]
                [--directory <directory>] --input <input> [--journal <journal>]
                [--large-messages <largeMessges>] [--bindings <binding>]
        artemis data encode [--directory <directory>] [--broker <brokerConfig>]
                [--suffix <suffix>] [--verbose] [--paging <paging>] [--prefix <prefix>]
                [--file-size <size>] [--journal <journal>]
                [--large-messages <largeMessges>] [--bindings <binding>]
        artemis data exp [--broker <brokerConfig>] [--verbose]
                [--paging <paging>] [--journal <journal>]
                [--large-messages <largeMessges>] [--bindings <binding>]
        artemis data imp [--host <host>] [--verbose] [--port <port>]
                [--password <password>] [--transaction] --input <input> [--user <user>]
        artemis data print [--broker <brokerConfig>] [--verbose]
                [--paging <paging>] [--journal <journal>]
                [--large-messages <largeMessges>] [--bindings <binding>]

COMMANDS
        With no arguments, Display help information

        print
            Print data records information (WARNING: don't use while a
            production server is running)

        ...

Copy to Clipboard

Toggle word wrap

You can use the help parameter for more information on how to execute each of the commands. For example, the CLI lists more information about the data print command after the user enters the ./artemis help data print.

./artemis help data print

$ ./artemis help data print

NAME
        artemis data print - Print data records information (WARNING: don't use
        while a production server is running)

SYNOPSIS
        artemis data print [--bindings <binding>] [--journal <journal>]
                [--paging <paging>]

OPTIONS
        --bindings <binding>
            The folder used for bindings (default ../data/bindings)

        --journal <journal>
            The folder used for messages journal (default ../data/journal)

        --paging <paging>
            The folder used for paging (default ../data/paging)

Copy to Clipboard

Toggle word wrap

Questo contenuto non è disponibile nella lingua selezionata.

3.1. Starting broker instances
Copia collegamento

3.1.1. Starting the broker instance
Copia collegamento

3.1.2. Starting a broker as a Linux service
Copia collegamento

3.1.3. Starting a broker as a Windows service
Copia collegamento

3.2. Stopping broker instances
Copia collegamento

3.2.1. Stopping the broker instance
Copia collegamento

3.2.2. Stopping a broker instance gracefully
Copia collegamento

3.3. Auditing messages by intercepting packets
Copia collegamento

3.3.1. Creating interceptors
Copia collegamento

3.3.2. Configuring the broker to use interceptors
Copia collegamento

3.3.3. Interceptors on the client side
Copia collegamento

3.4. Command line tools
Copia collegamento

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Rendiamo l’open source più inclusivo

Informazioni su Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Questo contenuto non è disponibile nella lingua selezionata.

Chapter 3. Using the command line interface

3.1. Starting broker instancesCopia collegamentoCollegamento copiato negli appunti!

3.1.1. Starting the broker instanceCopia collegamentoCollegamento copiato negli appunti!

3.1.2. Starting a broker as a Linux serviceCopia collegamentoCollegamento copiato negli appunti!

3.1.3. Starting a broker as a Windows serviceCopia collegamentoCollegamento copiato negli appunti!

3.2. Stopping broker instancesCopia collegamentoCollegamento copiato negli appunti!

3.2.1. Stopping the broker instanceCopia collegamentoCollegamento copiato negli appunti!

3.2.2. Stopping a broker instance gracefullyCopia collegamentoCollegamento copiato negli appunti!

3.3. Auditing messages by intercepting packetsCopia collegamentoCollegamento copiato negli appunti!

3.3.1. Creating interceptorsCopia collegamentoCollegamento copiato negli appunti!

3.3.2. Configuring the broker to use interceptorsCopia collegamentoCollegamento copiato negli appunti!

3.3.3. Interceptors on the client sideCopia collegamentoCollegamento copiato negli appunti!

3.4. Command line toolsCopia collegamentoCollegamento copiato negli appunti!

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Rendiamo l’open source più inclusivo

Informazioni su Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

3.1. Starting broker instances
Copia collegamento

3.1.1. Starting the broker instance
Copia collegamento

3.1.2. Starting a broker as a Linux service
Copia collegamento

3.1.3. Starting a broker as a Windows service
Copia collegamento

3.2. Stopping broker instances
Copia collegamento

3.2.1. Stopping the broker instance
Copia collegamento

3.2.2. Stopping a broker instance gracefully
Copia collegamento

3.3. Auditing messages by intercepting packets
Copia collegamento

3.3.1. Creating interceptors
Copia collegamento

3.3.2. Configuring the broker to use interceptors
Copia collegamento

3.3.3. Interceptors on the client side
Copia collegamento

3.4. Command line tools
Copia collegamento