このコンテンツは選択した言語では利用できません。
Chapter 3. Using command line interface
The command line interface (CLI) allows interaction with the message broker by use of an interactive terminal. Manage broker actions, configure messages, and enter useful commands by using the CLI.
The command line interface (CLI) allows users and roles to be added to files, by using an interactive process.
3.1. Starting broker instances
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
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
Use the
artemis run
command to start the broker instance.$ /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 ...
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
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
3.1.3. Starting a broker as a Windows service
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
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
3.2. Stopping broker instances
Stop the broker instance manually or configure the broker to shutdown gracefully.
3.2.1. Stopping a broker instance
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.
If you are running the broker on Linux, issue the following command:
<broker-instance-dir>\bin\artemis stop
If you are running the broker on Windows as a service, issue the following command:
<broker-instance-dir>\bin\artemis-service.exe stop
3.2.2. 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 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 totrue
.<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 thestop
command is issued.<configuration> <core> ... <graceful-shutdown-enabled> true </graceful-shutdown-enabled> <graceful-shutdown-timeout> 30000 </graceful-shutdown-timeout> ... </core> </configuration>
3.3. Auditing messages by intercepting packets
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
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.
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; } }
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; } }
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; } }
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; } }
3.3.2. Configuring the broker to use interceptors
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 ofremoting-incoming-interceptors
.<configuration> <core> ... <remoting-incoming-interceptors> <class-name>org.example.MyIncomingInterceptor</class-name> </remoting-incoming-interceptors> ... </core> </configuration>
If the interceptor is intended for outgoing messages, add its
class-name
to the list ofremoting-outgoing-interceptors
.<configuration> <core> ... <remoting-outgoing-interceptors> <class-name>org.example.MyOutgoingInterceptor</class-name> </remoting-outgoing-interceptors> </core> </configuration>
3.3.3. Interceptors on the client side
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
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.
Tool | Description |
---|---|
address |
Addresses tool groups (create/delete/update/show) (example |
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 |
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 |
run | Runs the broker instance. |
stop | Stops the broker instance. |
user |
Default file-based user managament (add/rm/list/reset) (example |
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 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) ...
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 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)