Chapter 1. Using the Command Console

Overview

The Red Hat JBoss A-MQ command console is a tool for both managing the JBoss A-MQ environment and interacting with a fabric. When you start JBoss A-MQ you can launch into a mode that displays the command console. You can also use a remote command console to connect to a broker.
The console provides commands that you can use to perform basic management of your JBoss A-MQ environment, including managing destinations, connections and other administrative objects in the broker.
The console uses prefixes to group commands relating to the same functionality. For example commands related to configuration are prefixed config:, and logging-related commands are prefixed log:.

Starting the command console

To start JBoss A-MQ open a console at the installation directory and enter:
Windowsbin\amq.bat
*NIXbin/amq.sh
JBoss A-MQ starts and the console is ready. You should see the prompt shown in Example 1.1, “The Red Hat JBoss A-MQ Console”.

Example 1.1. The Red Hat JBoss A-MQ Console

 _ ____ __ __ ____ | | _ \ /\ | \/ |/ __ \ | | |_) | ___ ___ ___ / \ ______| \ / | | | | _ | | _ < / _ \/ __/ __| / /\ \______| |\/| | | | | | |__| | |_) | (_) \__ \__ \ / ____ \ | | | | |__| | \____/|____/ \___/|___/___/ /_/ \_\ |_| |_|\___\_\ JBoss A-MQ (6.0.0.redhat-012) http://www.redhat.com/products/jbossenterprisemiddleware/amq/ Hit '<tab>' for a list of available commands and '[cmd] --help' for help on a specific command. Hit '<ctrl-d>' or 'osgi:shutdown' to shutdown JBoss A-MQ. JBossA-MQ:karaf@root>

Getting help

The console provides two levels of help:
  • console help—list all of the commands along with a brief summary of the commands function
  • command help—a detailed description of a command and its arguments
To access the console help you use the help command from the console prompt (or the equivalent man command alias). It will display a grouped list of all the commands available in the console. Each command in the list will be followed by a description of the command as shown in Example 1.2, “Console Help”.

Example 1.2. Console Help

JBossA-MQ:karaf@root> help
COMMANDS activemq:browse activemq:bstat activemq:list activemq:purge activemq:query admin:change-opts Changes the Java options of an existing container instance. admin:change-rmi-registry-port Changes the RMI registry port (used by management layer) of an existing container instance.
    ...
JBossA-MQ:karaf@root>
The help for each command includes the definition, the syntax, and the arguments and any options. To display the help for a command, type the command with the --help option. As shown in Example 1.3, “Help for a Command”, entering admin:start --help displays the help for that command.

Example 1.3. Help for a Command

JBossA-MQ:karaf@root> admin:start --help
DESCRIPTION admin:start Starts an existing container instance. SYNTAX admin:start [options] name ARGUMENTS name The name of the container instance OPTIONS --help Display this help message -o, --java-opts Java options when launching the instance 
JBossA-MQ:karaf@root>

Command completion

Pressing Tab at anytime will provide you with a list of commands that can complete what you have already entered at the prompt. For example if you entered active followed by Tab a list similar to Example 1.4, “Console Commands” will be shown.

Example 1.4. Console Commands

activemq:browse activemq:bstat activemq:list activemq:purge activemq:query JBossA-MQ:karaf@root>
If you press Tab without entering anything at the prompt, the console will list all of the possible commands.

Command groups

Commands are grouped under prefixes according to functionality. Table 1.1, “Command Groups” summarizes the command groups available in the console. Click on a command group name for more information.

Table 1.1. Command Groups

Command GroupDescription
activemq Views and manages brokers and messages.
admin Creates, manages, and destroys containers.
config Manages configuration.
dev Utilities that are useful for a developer while testing bundles in the container.
fab Manages the dependency resolution mechanism used by Fuse Application Bundles.
fabric Performs provisioning and configuration using Fuse Fabric.
features Performs provisioning based on Apache Karaf feature specs.
jaas Manages the console's security settings.
log Displays and configures logging.
osgi Manages the OSGi bundle repository.
patch Manages patches.
packages Lists imported and exported packages.
shell Performs basic console functions
ssh Creates and connects to a remote SSH server
web Lists the WARs deployed in the container.
zk Accesses and modifies entries in the Zookeeper registry.

Short version

Many of the console commands allow you to omit the group prefix.
If the command is only in one command groups, you can omit the group prefix. For example, you can enter bstat in place of activemq:bstat because it only exists in the activemq command group.
If the command exists in multiple command groups, you can still drop the prefix and the console will default to using the version of the command from one of the following command groups:
  • shell
  • osgi
  • admin
For example, info is equivalent to shell:info. If you wanted to use osgi:info, you need to enter the full command.

Properties and system properties

The console allows you to define custom properties, which can be useful when writing shell scripts for the console. Define properties using a simple assignment expression, PropertyName = Value, and access the property value with the syntax $PropertyName or ${PropertyName}. For example, to define the foo property: 
JBossA-MQ:karaf@root> foo = fooValue
fooValue
JBossA-MQ:karaf@root> echo $foo
fooValue
You can also use this syntax to access JVM System Properties. For example: 
JBossA-MQ:karaf@root> echo ${karaf.name}
root

About console input

In console input, the Karaf shell drops leading zeros when the input appears to be a number. For example: 
JBossA-MQ:karaf@root> echo 0123
123
JBossA-MQ:karaf@root> echo 00.123
0.123
JBossA-MQ:karaf@root>
This is a problem if you define a numeric username with a leading zero. The shell drops the leading zero and login attempts fail. To avoid this, do not use a zero as the first character in a numeric username. Alternatively, include at least one alphabetic character in a username.