JBoss Community Archive (Read Only)

RHQ 4.9

RHQ Control Script

Overview

This documents 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.

Windows

On Windows, there is a rhqctl.bat which should work analogously to rhqctl on UNIX-based platforms. There are a couple of important notes regarding Windows Services:

  • On Windows the RHQ Server, RHQ Storage Node, and RHQ Agent will be installed as Windows Services when RHQ is installed, by the "rhqctl install" command.

  • Start the command window with "Run as Administrator". This is required for manipulating Windows services (just as has been required in the past when running the RHQ Server and RHQ Agent as a service).

  • The Windows services will run by default as the local system account (known as "Default" or ".\LocalSystem"). To install the services as a different user set the following properties prior to installation:

  • RHQ Server Service

    • RHQ_SERVER_RUN_AS=.\<username> or RHQ_SERVER_RUN_AS_ME=true

    • RHQ_SERVER_PASSWORD=<password>

    • RHQ_SERVER_PASSWORD_PROMPT=false

  • RHQ Storage Service

    • RHQ_STORAGE_RUN_AS=.\<username> or RHQ_STORAGE_RUN_AS_ME=true

    • RHQ_STORAGE_PASSWORD=<password>

    • RHQ_STORAGE_PASSWORD_PROMPT=false

  • RHQ Agent Service

    • RHQ_AGENT_RUN_AS=.\<username> or RHQ_AGENT_RUN_AS_ME=true

    • RHQ_AGENT_PASSWORD=<password>

    • RHQ_AGENT_PASSWORD_PROMPT=false

  • To remove services use rhqctl. For example: "rhqctl remove".

    • Note that removing Windows services does not uninstall the RHQ component. In general it should not be necessary to remove the Windows services.

  • By default the RHQ Storage Node data will be persisted under "HOMEDRIVE:\rhq\storage" on Windows.

Running the Agent from the Command Line

In general it is recommended to just run the agent as a Windows service. But if you plan to stop the service and run the agent interactively (typically this is done for development or debugging purposes) it is recommended not to install the agent service with the local system account. It will be necessary to run the agent as the same user both as the service and interactively to ensure the same agent configuration is applied in both scenarios. The agent service can be installed to run as a different user by setting the following environment variables before running "rhqctl install":

  • RHQ_AGENT_RUN_AS=.\<username> or RHQ_AGENT_RUN_AS_ME=true

  • RHQ_AGENT_PASSWORD_PROMPT=false

  • RHQ_AGENT_PASSWORD=<password>

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

* 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]
    --agent-auto-start <arg>        If an agent is to be installed it
                                    will, by default, also be started.
                                    However, if this option is set to
                                    false, the agent will not be started
                                    after it gets installed.
    --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.
    --server-config <arg>           An alternate properties file to use in
                                    place of the default
                                    rhq-server.properties
    --storage                       Install RHQ storage node. The install
                                    directory will be
                                    [/home/bob/rhq-storage]. Note
                                    that this option implies --agent which
                                    means an agent will also be installed,
                                    if one is not yet installed.
    --storage-config <arg>          A properties file with keys that
                                    correspond to option names of the
                                    storage installer. Each property will
                                    be translated into an option that is
                                    passed to the  storage installer.
    --storage-data-root-dir <arg>   The root directory under which all
                                    storage data directories will be
                                    placed.

When no options are specified rhqctl installs all 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

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

--server

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

--storage

When the --storage option is supplied, rhqctl 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.

--server-config

Specifies an alternative properties file to use in place of the default rhq-server.properties. This properties file will replace the default rhq-server.properties.

--storage-config

Specifies a properties file where each property corresponds to a storage installer option. You can find the names of the storage options that are valid (as well as a description of them), run the rhq-storage-installer script with the -help option. All options (minus the "-" prefix, are the names of the storage options.

If a relative path is specified with the agent-config, server-config, and storage-config options, it will be resolved relative to <rhq-server-dir>.

A few options are not relevant for the properties file and have been omitted from the list. Specifically --dir, --start, --upgrade. 

$ ./rhq-storage-installer.sh --help
Starting RHQ Storage Installer ...
15:47:13,049 INFO  [org.jboss.modules] JBoss Modules version 1.2.0.CR1
15:47:13,172 INFO  [org.rhq.storage.installer.StorageInstaller] Running RHQ Storage Node installer...
usage: rhq-storage-installer.sh|bat [options]
 -c,--client-port <PORT>          The port on which to listen for client
                                  requests. Defaults to 9142
    --check-status <true|false>   Check the node status to verify that it
                                  is up after starting it. This option is
                                  ignored if the start option is not set.
                                  Defaults to true.
    --commitlog <DIR>             The directory where the storage node
                                  keeps commit log files. Defaults to
                                  /var/lib/rhq/storage/commitlog (on Linux)
                                  or %HOMEDRIVE%\rhq\storage\commitlog
                                  (on Windows).
    --data <DIR>                  The directory where the storage node
                                  keeps data files. Defaults to
                                  /var/lib/rhq/storage/data  (on Linux)
                                  or %HOMEDRIVE%\rhq\storage\data
                                  (on Windows).
 -h,--help                        Show this message.
    --heap-new-size <arg>         The value to use for the new generation
                                  of the heap. This value is passed
                                  directly to the -Xmn option of the Java
                                  executable
    --heap-size <arg>             The value to use for both the min and
                                  max heap. This value is passed directly
                                  to the -Xms and -Xmx options of the Java
                                  executable.
 -j,--jmx-port <PORT>             The port on which to listen for JMX
                                  connections. Defaults to 7299.
 -n,--hostname <HOSTNAME>         The hostname or IP address on which the
                                  node will listen for requests. If not
                                  specified, defaults to the hostname for
                                  localhost.
 -s,--seeds <SEEDS>               A comma-delimited list of hostnames or
                                  IP addresses that serve as contact
                                  points. Nodes use this list to find each
                                  other and to learn the cluster topology.
                                  It does not need to specify all nodes in
                                  the cluster. Defaults to this node's
                                  hostname.
    --saved-caches <DIR>          The directory where the storage node
                                  keeps saved cache files. Defaults to
                                  /var/lib/rhq/storage/saved_caches (on Linux)
                                  or %HOMEDRIVE%\rhq\storage\saved_caches
                                  (on Windows).
    --ssl-storage-port <PORT>     The port on which to listen for
                                  encrypted requests from other nodes.
                                  Only used when encryption is enabled.
                                  Defaults to 7101
    --stack-size <arg>            The value to use for the thread stack
                                  size. This value is passed directly to
                                  the -Xss option of the Java executable.
    --storage-port <PORT>         The port on which to listen for requests
                                  from other nodes. Defaults to 7100

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.

If using non-default settings for the data, commitlog, and/or saved-caches directories, each directory should be unique. Do not share the same directory.

See Storage Node Installer for more information about the storage installer.

--storage-data-root-dir

By default, the RHQ Storage Node will persist its data on the filesystem under /var/lib. However, this requires root access; if you do not wish to allow the RHQ Storage Node to run as root, you must specify a different root directory that the RHQ Storage Node will have read-write access to.

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

Install an RHQ Storage Node with non-default options. Note this does not install an RHQ Server but does install an RHQ Agent along with the RHQ Storage Node: 

$ rhqctl install --storage --storage-config=/tmp/storage.properties

where storage.properties looks like, 

commitlog=/tmp/rhq/storage/commit_log
data=/tmp/rhq/storage/data
saved-caches=/tmp/rhq/storage/saved_caches

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
    --agent-auto-start <arg>          If an agent is to be upgraded it
                                      will, by default, also be started.
                                      However, if this option is set to
                                      false, the agent will not be started
                                      after it gets upgraded.
    --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.
    --run-data-migrator <arg>         This option is valid only when
                                      upgrading from older systems that
                                      did not have storage nodes. The
                                      existing metric data needs to
                                      migrate to the metric storage.  The
                                      upgrade process can trigger this or
                                      give you an estimate on the
                                      duration. If you want to have fine
                                      control over the process, please run
                                      the migrator on the command line.
                                      Options are none (do nothing),
                                      estimate (estimate the migration
                                      time only), print-command (print the
                                      command line for a manual run),
                                      do-it (run the migration)
    --storage-config <arg>            This option is valid only when
                                      upgrading from older systems that
                                      did not have storage nodes. Use this
                                      option to specify non-default
                                      storage installer options. It is the
                                      path to a properties file with keys
                                      that correspond to option names of
                                      the storage installer. Each property
                                      will be translated into an option
                                      that is passed to the storage
                                      installer.
    --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.
    --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

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 08:49:11 UTC, last content change 2013-09-18 19:43:38 UTC.