unzip rhq-server-*.zip
This page is for installing a new RHQ Server. If you already have a RHQ Server installed and wish to re-install it or upgrade it, go to Upgrading the Server.
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 these 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.
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.
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.
These steps will install an RHQ Server, RHQ Storage Node (with default settings), and an RHQ Agent.
Unzip the RHQ Server in some directory (to be referenced as <rhq-install-dir>)
Edit <rhq-install-dir>/bin/rhq-server.properties so all settings match your environment. See Startup Properties for more information on these settings.
Make sure rhq.autoinstall.enabled=true in rhq-server.properties. This is pre-set and should not be changed for typical installations.
Do not put the actual plain text passwords in rhq-server.properties! To generate obfuscated password values use <rhq-install-dir>/bin/rhq-installer.[sh,bat] --encodepassword=<your password>. This command will not edit your rhq-server.properties - it only outputs the property values you should use when editing rhq-server.properties prior to installation. The following properties require obfuscated password values:
rhq.storage.password
rhq.server.database.password
rhq.server.management.password
Install and Start RHQ
On Windows the RHQ Server, RHQ Storage Node, and RHQ Agent will be installed as Windows Services. See more here before installing.
Install and start RHQ via <rhq-install-dir>/bin/rhqctl install
To install RHQ:
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.9.0. The /opt/rhq/rhq-server-4.9.0 directory should not exist prior to the unzip operation.
Do not install the RHQ Server into a directory with a path longer than about 19 characters (e.g. use C:\rhq rather than C:\Documents and Settings\myusername). Excessively long pathnames may cause errors during execution of the server - see this Microsoft MSDN article for more information. It has also been seen that unzipping the distribution using 7-Zip may also help avoid the long-pathname problem.
Load <rhq-install-dir>/bin/rhq-server.properties 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 Startup Properties for more information on these settings. Some values must be explicitly set prior to installation!
Do not put the actual plain text passwords in rhq-server.properties! To generate obfuscated password values use <rhq-install-dir>/bin/rhq-installer.[sh,bat] --encodepassword=<your password>. This command will not edit your rhq-server.properties - it only outputs the property values you should use when editing rhq-server.properties prior to installation. The following properties require obfuscated password values:
rhq.storage.password
rhq.server.database.password
rhq.server.management.password
Make sure rhq.autoinstall.enabled=true in rhq-server.properties. This is pre-set and should not be changed for typical installations.
You must set the rhq.storage.nodes property if all of the following are true:
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)
In this case set rhq.storage.nodes with an entry for each of your pre-installed, remote, RHQ Storage Nodes.
To alter any defaults for the RHQ Storage Node create a <rhq-install-dir>/bin/rhq-storage.properties file. In this file you can specify any of the RHQ Storage Node --storage-config options. These include the directories for data storage, host and port information, and several other options.
Ignore this step if this is a server-only install.
Decide which other rhqctl install options may be applicable to your installation and prepare the options as needed, based on their descriptions.
Install and Run RHQ
On Windows the RHQ Server, RHQ Storage Node, and RHQ Agent will be installed as Windows Services. See more here before installing.
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 lower the memory requirements of the RHQ Server by editing bin/rhq-server.sh (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 via <rhq-install-dir>/bin/rhqctl install [options]
Once the installation completes, your RHQ Server will soon be ready. No further work needs to be done.
The single configuration file <rhq-install-dir>/bin/rhq-server.properties 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 (rhq.server.tomcat.security.keystore.file and rhq.server.tomcat.security.truststore.file). 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>.
You can install the RHQ Server to run when your computer boots up. On Windows, this means installing the RHQ Server to start as a Windows Service. On UNIX, it means installing the RHQ Server startup script as an init.d startup script. To install as a boot-time service on either Windows or UNIX, refer to Running the RHQ Server. Note that, on Windows, rhqctl will install the software components as services for you.
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.
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 rhq-server.properties 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];
Type=[java.sql.SQLException]
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.
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. You also must make sure the name of the jar 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.
The RHQ Server's rhq.server.high-availability.name 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:
<rhq-install-dir>/bin/rhq-installer.[sh,bat] --listservers
Avoid using generic names such as server, localhost or s1 for the value of rhq.server.high-availability.name. Use more explicit names that easily identify the RHQ Server - IP addresses, FQDN hostnames or simply more descriptive names are more appropriate.
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.
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.
RHQ no longer has a GUI installer application. You install via the command line only using the script rhqctl. See rhqctl control script.
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.