Skip to end of metadata
Go to start of metadata

RHQ Control Script

Overview

This document provides details on the RHQ control script, rhqctl. The purpose of the control script is to provide basic lifecycle management of RHQ services installed on a server machine. Within the context of this document an RHQ service refers specifically to one of the RHQ Server, RHQ Agent, or RHQ Storage Node.

rhqctl is for managing the RHQ services necessary for running the RHQ Server. The RHQ Server needs at least one RHQ Storage Node (running locally or remotely) for persisting data. In order to be managed, RHQ Storage Node itself needs an RHQ Agent. Therefore, rhqctl can be used to manage the lifecycle of those components (RHQ Server, RHQ Storage Node and RHQ Agent).

Do not use rhqctl on your agent machines. On your machines where you only need an RHQ Agent, you only need to install and upgrade the agent using the normal agent install/upgrade mechanisms and run the agent using the normal start/stop mechanisms. rhqctl is only for use on your server machines where you have RHQ Servers and/or RHQ Storage Nodes (and their associated RHQ Agents) installed.

Basic lifecycle management includes,

  • Installing
  • Upgrading from older versions
  • Starting
  • Stopping
  • Checking status (to see whether or not services are running)
  • Starting in console mode (i.e., in the foreground)

A primary objective of the control script is usability. As such rhqctl has only a handful of commands and a limited number of options. To the greatest extent possible, the script should figure out what it needs to do without additional user input or configuration. For example, if you invoke the script with the "start" command and no options, it will determine what services are installed on the machine and for each service that is not running, the script will start the service.

Installation

As soon as you unzip your RHQ distribution, the rhqctl control script is available in the <rhq-install-dir>/bin directory. Although, there are steps to take prior to installation or upgrade. See RHQ Server Installation.

Windows

Windows
Please review all of the information at Windows Installation prior to installing on Windows.

Commands

The section gives an overview of basic usage and the commands that rhqctl supports. To see a list of supported commands along with basic help information run the script without any arguments.

$ ./rhqctl
15:39:00,629 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl <cmd> [options]

where <cmd> is one of:
 console <[options]>   Starts an RHQ service in the foreground. Only --server or --storage is supported.
                       To start the agent in the foreground, use the <RHQ_AGENT_HOME>/bin/rhq-agent.(sh|bat)
                       script.
 install <[options]>   Installs RHQ services.
 start <[options]>     Starts RHQ services.
 status <[options]>    Check status of RHQ services
 stop <[options]>      Stops RHQ services
 upgrade <[options]>   Upgrades RHQ services from an earlier installed version
 remove <[options]>    Windows only. Removes RHQ Windows services

* For help on a specific command: rhqctl <cmd> --help
* Limit commands to a single component with one of: --storage, --server,
--agent
If you run the RHQ Server on a UNIX-based operating system, you may want to use the bash autocompletion script for rhqctl. To make it work, all you have to do is to copy the rhqctl-completion.sh script to your /etc/bash_completion.d/ directory. Everytime you write rhqctl in the terminal and press the <TAB> key, you will get an advice what can follow in given context.

install

$ ./rhqctl install --help
15:40:50,087 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl install [options]

Installs RHQ services.
    --agent                         Install RHQ agent. The install directory will be [/home/bob/rhq-agent]
                                    specify --storage to install one.
    --start                         If specified then immediately start the services after installation.  Note that
                                    services may be started and shut down as part of the installation process, but
                                    will not be started or left running by default.
    --agent-config <arg>            An alternate XML file to use in place of the default agent-configuration.xml
    --agent-preference <arg>        An agent preference setting (whose argument is in the form 'name=value') to be
                                    set in the agent. More than one of these is allowed.
    --server                        Install RHQ server. If you have not yet installed an RHQ storage node somewhere
                                    in your network, you must specify --storage to install one.
                                    The rhq-server.properties file should be updated as desired, prior to install.
    --storage                       Install RHQ storage node. The install directory will be [/home/bob/rhq-storage]. 
                                    The rhq-storage.properties file should be updated as desired,
                                    prior to install. Note that this option implies --agent which means an agent will
                                    also be installed, if one is not yet installed.
    --storage-data-root-dir <arg>   The root directory under which all storage data directories will be placed.

When no options are specified rhqctl install installs all previously uninstalled services - the storage node followed by the server and then the agent. Installation includes laying the bits down on disk, configuring the service, and then starting the service. When the install command finishes (and no options are supplied), the storage node, the server, and the agent should all be up and running.

--agent

rhqctl install --agent will install the agent. If the agent is already installed, a warning message will be displayed and agent installation will be skipped.

--server

rhqctl install --server will install the server. If the server is already installed, a warning message will be displayed and server installation will be skipped.

--storage

rhqctl install --storage will install the storage node. If the storage node is already installed, a warning message will be displayed and storage node installed will be skipped.

Executing rhqctl install --storage results in both the storage node and agent being installed even though the agent option is not specified. This is because RHQ requires an agent to be installed along side a storage node so that it can be fully managed.

--agent-config

Specifies an alternative XML file to use in place of the default agent-configuration.xml. You can use this if you want to preconfigure your agent with your own custom settings.

If a relative path is specified with the {{agent-config} option, it will be resolved relative to <rhq-server-dir>.
Values are treated like Java strings. So:
  • Use forward slashes where possible, especially in directory or file paths (including Windows!). For example: /var/lib or C:/my/folder.
  • If you need an explicit backslash, escape it using a double-backslash.

--storage-data-root-dir

By default, the RHQ Storage Node will persist its data on the filesystem under <rhq-home>/rhq-data. <rhq-home> is the parent of the <rhq-install-dir>. For example if you unzip the distribution as /opt/rhq/rhq-server-<version>, then /opt/rhq is the home directory, and the storage node will persist data under /opt/rhq/rhq-data. If you do not want data stored in that directory then specify a different root directory that the RHQ Storage Node will have read-write access to. It should not be placed under the server distribution for upgrade purposes.

Examples

This is the basic install command which will install all components (an RHQ Server, RHQ Storage Node, and RHQ Agent):

$ rhqctl install

To install only the server, you would run the following (which assumes you already have a RHQ Storage Node installed and configured elsewhere):

$ rhqctl install --server

upgrade

$ ./rhqctl upgrade --help
12:08:54,374 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl upgrade [options]

Upgrades RHQ services from an earlier installed version
    --from-agent-dir <arg>            Full path to install directory of the RHQ Agent to be upgraded. Required
                                      only if an existing agent exists and is not installed in the default
                                      location: <from-server-dir>/../rhq-agent
    --from-server-dir <arg>           Full path to install directory of the RHQ Server to be upgraded. Required.
    --list-versions                   This option prints the install versions for the Servers and Storage
                                      Nodes in the topology. This option must be run from an already installed
                                      or upgraded RHQ Server node. When specified, all other options are ignored.
    --start                           Deprecated as of RHQ 4.13, no effect and will be removed in a future version.
    --storage-data-root-dir <arg>     This option is valid only when upgrading from older systems that did not have
                                      storage nodes. Use this option to specify a non-default base directory for the
                                      data directories created by the storage node. For example, if the default
                                      directory is not writable for the current user (/var/lib on Linux) or if you
                                      simply prefer a different location.
    --storage-schema                  This option updates the storage cluster schema.  This option must be run from
                                      an RHQ Server node. The running time for the schema update will vary depending
                                      on the schema changes being made, the runtime may be long and should not be
                                      interrupted.  It requires that all servers and storage nodes have already been
                                      upgraded to the desired version and that all nodes in the storage cluster are
                                      running. The command will fail if these prerequisites are not met. Use
                                      'rhqctl upgrade --list-versions' to see the current upgrade status. When
                                      specified, all other options are ignored.  Not all upgrades will require this step.
    --use-remote-storage-node <arg>   By default a server is co-located with a storage node. However, if this option
                                      is set to true, no local storage node will be upgraded and it is assumed a
                                      remote storage node is configured in rhq-server.properties.

--from-server-dir

This points to the location of the old server installation - this is the server you want to upgrade.

--from-agent-dir

If you installed your agent in a place other than the directory "rhq-agent" which is a peer directory to the --from-server-dir, then you must specify --from-agent-dir in order to upgrade the old agent. If you have no agent to upgrade, this need not be specified.

Examples

Upgrade the server. If this was an older server that did not have a storage node, an RHQ Storage Node and RHQ Agent will be installed when upgrading that server.

$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server

Upgrade the server and the agent. If this was an older server that did not have a storage node, an RHQ Storage Node will be installed when upgrading that server.

$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server --from-agent-dir /home/rhq/rhq-agent

Upgrade the server and put the storage node's data directories under the given root directory:

$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server --storage-data-root-dir /home/rhq/storage-data

Upgrade the server but do not install or upgrade any storage node. This requires that you have already configured your rhq-server.properties to point to a remote storage node cluster. Without a storage node (either remote or local), the server will fail to operate correctly.

$ ./rhqctl upgrade --from-server-dir /opt/rhq/rhq-server --use-remote-storage-node true

start

$ ./rhqctl start --help
11:56:00,344 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl start [options]

Starts RHQ services.
    --agent     Start RHQ agent
    --server    Start RHQ server
    --storage   Start RHQ storage node

When no options are specified rhqctl will start all installed services that are not already running.

--storage

Start the storage node. If the storage node is already running, rhqctl will log a message to indicate that it is already running. A warning is logged if the storage node is not installed.

--server

Start the server. If the server is already running, rhqctl will log a message to indicate that it is already running. A warning is logged if the server is not installed.

--agent

Start the agent. If the agent is already running, rhqctl will log a message to indicate that it is already running. A warning is logged if the agent is not installed.

Examples

Start only the storage node.

$ ./rhqctl start --storage

Start the storage node and the server.

$ ./rhqctl.sh start --storage --server

Start only the agent.

$ ./rhqctl start --agent

stop

$ ./rhqctl stop --help
11:58:02,183 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl stop [options]

Stops RHQ services
    --agent     Stop RHQ agent
    --server    Stop RHQ server
    --storage   Stop RHQ storage node

When no options are specified, rhqctl will stop all installed services that are running.

--storage

Stop the storage node. Log a warning message if the storage node is not installed.

--server

Stop the server. Log a warning message if the server is not installed.

--agent

Stop the agent. Log a warning message if the agent is not installed.

Examples

Stops only the storage node. If there is a server running, you must have other RHQ Storage Nodes running that the server can access; otherwise, errors will occur when the server attempts to persist data to storage.

$ ./rhqctl stop --storage

Stop the storage node and the server.

$ ./rhqctl stop --storage --server

Stop only the agent.

$ ./rhqctl stop --agent

status

$ ./rhqctl status --help
12:00:06,518 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl status [options]

Check status of RHQ services
    --agent     Check status of RHQ agent
    --server    Check status of RHQ server
    --storage   Check status of RHQ storage node

When no options are are specified, rhqctl will report the status of all installed services, indicating whether or not they are running.

--storage

Report the status of the storage node. Log a warning if the storage node is not installed.

--server

Report the status of the server. Log a warning if the server is not installed.

--agent

Report the status of the agent. Log a warning if the agent is not installed.

Examples

Report the status of the storage node.

$ ./rhqctl status --storage

Report the status of the storage node and the server.

$ ./rhqctl status --storage --server

Report the status of the agent.

$ ./rhqctl status --agent

console

$ ./rhqctl console --help
12:00:55,501 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
usage: rhqctl console [options]

Starts an RHQ service in the foreground. Only --server or --storage is
supported. To start the agent in the foreground, use the
<RHQ_AGENT_HOME>/bin/rhq-agent.(sh|bat) script.
    --server    Start the RHQ server in the foreground
    --storage   Start the RHQ storage node in the foreground

The console command is different from the start command in that it requires you to specify one and only one component to start. When no options are specified or when multiple options are specified, rhqctl just displays the usage message shown above.

--storage

Start the storage node in the foreground. Log a warning if the storage node is not installed or if it is already running.

--server

Start the server in the foreground. Log a warning if the server is not installed or if it is already running.

--agent

The --agent option is not yet fully implemented and therefore not a valid option. See BZ 970953
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.