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:
| Windows | bin\amq.bat |
| *NIX | bin/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>helpCOMMANDS 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 --helpDESCRIPTION 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 instanceJBossA-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.
| Command Group | Description |
|---|---|
| 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 fooValueJBossA-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}
rootAbout 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 123JBossA-MQ:karaf@root>echo 00.123 0.123JBossA-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.
