Skip to end of metadata
Go to start of metadata

Running The Installer

If you are upgrading from a previous version of RHQ, please follow the [Upgrade guide].
Please review all of the information at Windows Installation prior to installing on Windows.
If you plan on using an Oracle database for the RHQ backend datastore, you must download and install its driver. See Oracle Driver for more details.
Before you begin, make sure you download the RHQ server distribution file (which is packaged as a .zip file).


Installing the RHQ Server basically involves three steps. To start quickly follow the quick-install steps. If you have questions then read the details found further down on this page.

Unlike previous RHQ versions, there is no web installer.
It is recommended you have one common file system area where you install the RHQ Server and its related components. For example, /opt/rhq. Under here, the RHQ installation procedures will be able to install the RHQ Server, RHQ Storage Node and RHQ Agent in separate child directories. Having a common parent directory will assist in upgrading the software in the future. See [Windows Installations] for more on path length limitations.

Quick Installation Steps

These steps will install an RHQ Server, RHQ Storage Node (with default settings), and an RHQ Agent.

  1. Unzip the RHQ Server in some directory (to be referenced as <rhq-install-dir>)
  2. Edit <rhq-install-dir>/bin/ so all settings match your environment. See Server Properties for more information on these settings.
    • Make sure rhq.autoinstall.enabled=true in This is pre-set and should not be changed for typical installations.
    • Do not put plain text passwords in! To generate encoded password values use <rhq-install-dir>/bin/rhq-encode-value.[sh,bat]. This command will prompt for your plain text password and provide the encoded property value for use in It will not update the file. The following properties require encoded password values:
      • rhq.server.database.password
  3. Edit <rhq-install-dir>/bin/ so all settings match your environment. See Storage Properties for more information on these settings.
    • It is not required to edit any storage properties but is recommended to review the options.
  4. Install and Start RHQ
    • Install and start RHQ via <rhq-install-dir>/bin/rhqctl install --start
    • The default username / password after installation are rhqadmin/rhqadmin.

Detailed Installation Steps

To install RHQ:

  1. Unzip the RHQ Server distribution file to the directory within which it will be executed from (to be referenced as <rhq-install-dir>). For example, if you want to install the RHQ Server under the /opt/rhq directory, place the RHQ Server distribution file in /opt/rhq and execute:
    unzip rhq-server-*.zip

    The directory structure within the zip file ensures that the RHQ Server has a version-specific installation directory name. For example, the above command will create a directory named /opt/rhq/rhq-server-4.10.0. The /opt/rhq/rhq-server-4.9.0 directory should not exist prior to the unzip operation.

  2. Load <rhq-install-dir>/bin/ in a text editor and change all the settings so they are correct for your environment. You can leave many of the values as is, but you must ensure things such as the database settings, host and port settings are all correct for your environment. You can read the comments found in the properties file itself for more documentation or you can refer to Server Properties for more information on these settings. Some values must be explicitly set prior to installation!
    • Do not put plain text passwords in! To generate encoded password values use <rhq-install-dir>/bin/rhq-encode-value.[sh,bat]. This command will prompt for your plain text password and provide the encoded property value for use in It will not update the file. The following properties require encoded password values:
      • rhq.server.database.password
    • Make sure rhq.autoinstall.enabled=true in This is pre-set and should not be changed for typical installations.
    • You must set the property if all of the following are true. If necessary, set with an entry for each of your pre-installed, remote, RHQ Storage Nodes:
      • This is a server-only install (meaning you plan to use the rhqctl --server option to avoid an RHQ Storage Node install)
      • This is the initial RHQ Server install (not an additional HA server)
  3. Load <rhq-install-dir>/bin/ in a text editor and change all the settings so they are correct for your environment. See Storage Properties for more information on these settings.
    • It is not required to edit any storage properties but is recommended to review the options. Options include the directories for data storage, host and port information, and several other options.
      Ignore this step if this is a server-only install.
  4. Decide which other rhqctl install options may be applicable to your installation and prepare the options as needed, based on their descriptions.
  5. Install and Run RHQ
    The RHQ Server will allocate a large amount of memory to its JVM when it starts up. This is to ensure it can support a fairly large environment. If your machine does not have enough memory and you don't plan on managing a large environment, you can adjust the memory requirements of the RHQ Server by editing bin/internal/ (for UNIX/Linux) or bin/wrapper/rhq-server-wrapper.conf (for Windows) and adjusting the -Xms, -Xmx, -XX:PermSize, -XX:MaxPermSize VM settings. Note that if you lower the memory requirements, you may cause the RHQ Server to hit OutOfMemoryErrors - change these settings at your own risk. See Running the RHQ Server#Setting Environment Variables and Running the RHQ Server#Optional Wrapper Configuration Files
    You can validate your setup without actually installing. If you pass in the command line option --test (or -t) to the {{rhq-installer.[sh,bat] script, it will perform some validation and output information to the console indicating if everything is ready for performing the installation.
    • Install and start RHQ
      • Install via <rhq-install-dir>/bin/rhqctl install [options]
        • Or optionally install and start in one command via <rhq-install-dir>/bin/rhqctl install --start [options]
      • Start via <rhq-install-dir>/bin/rhqctl start [options]

Once the installation completes, your RHQ Server will soon be ready. No further work needs to be done.

Reconfiguring the Server

The single configuration file <rhq-install-dir>/bin/ that was used during installation is also the one you can use to reconfigure the RHQ Server after you've initially run the installation steps above. To change the configuration of the RHQ Server, you edit that file with the new values you want, shutdown the RHQ Server, then restart it.

Due to some limitations within the app server, there are two RHQ settings that will not take effect immediately upon restart if you change their values after the initial installation. These are settings for the web connector's keystore and truststore file locations ( and If you ever need to change those values after you've installed RHQ, you will need to change them in the app server's standalone/configuration/standalone-full.xml file in the <ssl> node of the https <connector>.

Installing as a Boot Time Service

You can install the RHQ Server to run when your computer boots up. On Windows the installed Windows services are set to automatic and will start automatically at system start. On UNIX, it means installing the RHQ Server startup script as an init.d startup script. To install as a boot-time service refer to Running the RHQ Server.

Some Things To Know Before You Start

You should read through the notes below before you install RHQ. They provide information that you should know beforehand and some may be relevant to your situation.

Storage Node

There is a new component needed by the RHQ Server called the RHQ Storage Node. This did not exist in RHQ versions 4.7 and earlier. The RHQ Storage Node is, by default, installed for you by rhqctl. In order for RHQ to manage its own storage component, it requires that an RHQ Agent now also be installed on the same machine as the RHQ Storage Node. So rhqctl install will now install three things - the RHQ Server itself, an RHQ Storage Node, and an RHQ Agent. An RHQ Server must have access to at least one RHQ Storage Node, but if you don't want the storage node running on the same machine as the RHQ Server, you can do so. Just realize that what ever machine is running an RHQ Storage Node must also have an RHQ Agent running along side of it. rhqctl install --help provides more information on the RHQ Control Script options to allow you to install only the RHQ Server.


  • If you have not installed your database server or did not create the necessary database or role for use with RHQ, you must do so first before continuing. See Prerequisites#Database.
  • You can test your database settings without actually installing RHQ by using the --test command line argument to the rhq-installer script. The installer will tell you if the settings are correct or not. If this test fails, check your connection settings in and ensure your database server is running.
  • The username that RHQ will use to connect to the database must be the owner of the RHQ tables.
  • If you are using an Oracle DB and you are installing for the first time (or you elected to "overwrite" the database schema but there is nothing to overwrite because this is a first-time installation) then you may see error messages in the RHQ logs that look like the following - these can be safely ignored:
    ERROR [DBSetup] {DBSetup.dropped-table-error}Failed to drop
    table [SOME_RHQ_TABLE] or one of its sequences. Cause: ErrorCode=[2289];
    SQLState=[42000]; Message=[ORA-02289: sequence does not exist];
  • If you are using a PostgreSQL DB, note that there have been some cases where the RHQ installation failed with an error "Relation RHQ_Principal does not exist". Refer to PostgreSQL for a workaround.

Oracle Driver

If you plan on installing with Oracle as the backend DB, you need to acquire the Oracle JDBC driver from an external source (due to licensing restrictions, RHQ cannot ship with the Oracle JDBC driver). One such place to obtain this driver is Oracle's website. Once you obtain the Oracle JDBC driver jar file, you must copy it to the <rhq-install-dir>/modules/org/rhq/oracle/main directory. Note that, by default, a "dummy" file exists here. This isn't a real Oracle driver that RHQ ships out-of-box. You will want to overwrite that dummy driver file with a real one. You also must make sure the name of the Oracle driver jar file matches that in the module.xml file located in the same directory (see the <resource-root> element's "path" attribute). Do this before running the server or installer.

If you do not plan on having an Oracle database, you don't have to do anything. A valid Postgres JDBC driver is included with RHQ out-of-box - Postgres should work without any customizations.

Server Name

The RHQ Server's property uniquely identifies the RHQ Server being installed. It defaults to the resolved hostname of the machine but can be set to a different value if necessary (it actually doesn't have to be a hostname or IP address at all). If you provide a new name that is different from any other server name registered in your RHQ environment, this will result in a new RHQ Server registration. In other words, the installer treats this as an additional server being added to the RHQ HA Cloud. You can find out all the server names currently registered in your RHQ environment by running:

Avoid using generic names such as server, localhost or s1 for the value of Use more explicit names that easily identify the RHQ Server - IP addresses, FQDN hostnames or simply more descriptive names are more appropriate.

Server's Public Endpoint

The server's public endpoint (rhq.autoinstall.public-endpoint-address) is used for the Server-Agent communication. After installation, you can update the Server Endpoint information via the RHQ GUI Administration pages (specifically, Administration>Servers).

The Server Endpoint Address must be public so that all RHQ Agents are able to resolve the supplied value. This is particularly important in High Availability (multi-Server) environments where RHQ Agents are connecting to various RHQ Servers in the cloud.

SMTP Settings

If you plan on using RHQ's feature of alert email notifications (most people do), you must ensure your SMTP settings are set correctly. Without providing RHQ with a valid SMTP server, it will be unable to send emails. To test your email settings once the RHQ Server is running, log in as the "rhqadmin" user and go to the email test page here: http://localhost:7080/coregui/CoreGUI.html#Test/ServerAccess/EmailTest.

Command-line Installer Only

RHQ no longer has a GUI installer application. You install via the command line only using the script rhqctl. See rhqctl control script.

Developer Builds

You will also notice that the RHQ EAR is not hot deployed by the deployment scanner (that is, the EAR is not located in the app server's deployments/ directory). Rather, the EAR is deployed by a custom AS startup extension and the EAR itself is found under <rhq-install-dir>/modules, not deployments/ (specifically, the EAR is found in the startup extension module).

If developers wish to hot-deploy changes to code, they can build the RHQ maven modules with the -Pdev profile which will copy the new artifacts to the new startup extension modules location. You can then ask the app server to reload.

l l Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Feb 17, 2014

    I removed a long comment here - the "--start" option exists in newer versions of RHQ. If you have a question as to the rhqctl options, make sure you are looking at the latest version of the software when comparing it to these docs. There are additional RHQ spaces in the wiki for older versions (such as the RHQ 4.9 space).

  2. Mar 22, 2014

    after installation default User / Username / login is rhqadmin and default password is rhqadmin , thx Heiko

  3. May 15, 2015

    Hi All,

    I installed rhq-server-4.13.0 on ubuntu 12.04 without any errors. I configured agent in another machine through server application URL administration -> agent -> connection information I got it's done successfully.  Same thing I checked in agent node it's running. But I'm not able to list the agent node in my server. Even I replaced the agent-configuration.xml to rhq-server IP address. Same status please any one help in this issue.