Installing Hyperic HQ: The Complete Guide
Available in HQ Open Source unless marked by * for HQ Enterprise only
This page provides complete instructions for installing and starting Hyperic HQ. It describes every step and every installation-configuration option. For quick-installation instructions, consult the instructions for a Windows environment or a non-Windows environment.
 | Recommended for Experienced Users This complete installation guide is recommended for experienced HQ users and for users who find the quick-installation instructions (for Windows or non-Windows) insufficient. |
Procedural Overview of a complete installation of HQ:
- Run the setup script.
- Select components to install.
- Configure the HQ Server installation. (-full installation mode only)
- Install the HQ Agent. Start with this step if an HQ Server is already installed.
- Install the HQ Shell.
Installation complete! - Start the HQ Server.
- Start the HQ Agent.
| Attention: Windows Installations If installing Hyperic HQ in a Windows environment, you will need to change this page's instructions in a few ways:
|
Step 1. Run the setup script with the appropriate argument to start the installer.
The setup script is in the HQ installation package. The script accepts either no argument or a single argument: the choice determines the installation "mode." Choose the one appropriate for your installation.
- Run setup.sh. This can take several minutes.
hyperic@hq$ .hyperic-hq-installer/setup.sh -full Initializing Hyperic HQ Installation... Loading taskdefs... Taskdefs loaded Choose which software to install: 1: Hyperic HQ Server 2: Hyperic HQ Shell 3: Hyperic HQ Agent You may enter multiple choices, separated by commas.
Setup Script Arguments that Determine Installation "Mode"
| Argument | Associated Installation "Mode" | ||
|---|---|---|---|
| <no argument> | Invokes the installer in quick install mode: It will install the selected HQ components with all the default settings. This is the quickest and easiest way to install HQ. | ||
| setup.sh -full | The installer will prompt for almost everything: ports to use, HQ Administrator username and password, database to use, etc. | ||
| setup.sh -upgrade | Start the installer in upgrade mode. The installer will ask for the full path to the HQ Server to be upgraded. Upgrade to HQ 3.0 is supported from 2.6 and previous 2.7.x releases. This option will only upgrade an HQ Server. To upgrade agents, either use the agent installer in the HQ Shell or re-run the HQ installer to install a new agent and configure it to connect to the new server. | ||
| setup.sh -postgresql | Quick install mode for a standalone (not the HQ built-in) PostgreSQL. See instructions for using a PostgreSQL database. This will just ask for database connection information and take defaults for everything else.
|
||
| setup.sh -oracle | Quick install mode for Oracle. See instructions for using an Oracle database. As with PostgreSQL install, this will just ask for Oracle connection information and everything else will be defaults. | ||
| setup.sh -mysql | Quick install mode for MySQL. See [instructions for using a MySQL database]. As with PostgreSQL install, this will just ask for MySQL connection information and everything else will be defaults. MySQL 5.0 or higher is not supported by Hyperic HQ. |
| Database Required These last 3 flags (-postgresql, -oracle, and -mysql) require a database other than the HQ Built-in database. See Preparing HQ's Database for details on setting up your database. |
Step 2. Select components to install.
Not applicable to upgrade mode
- Select the HQ Server, Agent, and/or Shell for installation. Below only the Server and Agent are selected.
1,3
- Specify where to install the HQ Server:
HQ server installation path [default '/home/hyperic']:
Install the HQ Server to any location you wish. You must have write access to that location, of course. The Agent and Shell install paths can be the same as the Server install path (they install themselves to different subdirectories).
The first thing the HQ installer will ask is which components you wish to install. Select at least one of the following components:
Components to Be Installed
| Component | Description |
|---|---|
| HQ Server | The HQ Server is the heart of HQ and must be installed in one location. |
| HQ Agent | The HQ Agent is an agent that sits on a platform and reports to the Server. The HQ Agent is installed in at least one location, and Agents can be installed in many. |
| HQ Shell | The HQ Shell is a command line interface to HQ. It is useful for scripting multiple operations and general HQ access from a command line environment. The HQ Shell does not need to be installed for HQ to run, it is purely to facilitate access to the HQ Server. It is capable of connecting to the server remotely and can therefore be installed anywhere. |
Step 3. Configure the HQ Server installation.
Applies only to full mode
After selecting the Server for installation, the installer will prompt you for the following configuration options. Either accept the default values or specify different ones, according to the needs of your installation.
Configuration Options for the HQ Server
| Configuration | Description | Default |
|---|---|---|
| HQ Server HTTP Port | The port HQ Server will listen for HTTP traffic | 7080 |
| HQ Server HTTPS Port | The port HQ Server will listen for HTTPS traffic | 7443 |
| HQ Server JNP Port | An alternate JNP port | 2099 |
| HQ Server MBean Port | An alternate MBean server port | 9093 |
| HQ Server Base URL | The URL used to access the HQ Server. This value is used in alert notification emails. This value can also be changed on the "HQ Server Administration" screen after the product is installed. | http://hostname:http_port/ |
| SMTP Server | The installer will attempt to detect if there is an SMTP server running on the localhost. If it finds one, this question is skipped. If no SMTP server is found, it will ask you to specify one that it can use to send outbound alert notification emails | localhost |
| HQ Server Alert Notification Sender | The "From" address on alert notification emails sent from HQ. Note that most mail servers will not deliver mail without a valid domain name in the From field | hqadmin@hostname |
| HQ Backend Database | The backend database HQ Server will use. Your options are: the HQ built-in database (PostgreSQL 8.0), Oracle 8, Oracle 9i/10g, PostgreSQL, and MySQL. The ensuing questions will focus on how to connect to the selected database. Any selection except HQ Buit-in Database will require JDBC URL, username, and password | HQ Built-in Database |
| HQ Administrator Username | The username of the original HQ Administrator (HQ root user) | hqadmin |
| HQ Administrator Password | The password for the HQ Administrator. The installer will not echo the password but will prompt for it twice so it can be verified. If -full is used, there is no default and a password must be entered | hqadmin |
| HQ Administrator email address | The email address assigned to the HQ Administrator. Alert notifications will be sent to this address if the Administrator user is ever configured to receive alert notifications | hqadmin@hostname |
| HQ Server Authentication Data Source | An alternate LDAP data source for the HQ-user authentication. If LDAP is selected, there will be more questions specific to the LDAP connection. For details on how to configure HQ for LDAP authentication, see the HQ LDAP Configuration documentation. LDAP authentication can also be configured after HQ is installed. | HQ Database |
| High Availability The installer does not contain a High Availability option. See the HQ High Availability Guide for details on HA configuration. |
Step 4. Install the HQ Agent.
After you specify all the Server configuration options, the installer asks for the Agent's installation location. If an agent installation exists in that location, the installer will ask if you want to overwrite it.
HQ agent installation path [default '/home/hyperic']:
When starting the Agent for the first time, however, you will have to provide more information, as explained in the instructions for starting the Agent.
Agent-Only Installations
It is not necessary to do a complete installation in order to install just an Agent. Separate Agent-only installation bundles are available for download. To use these simply, unpack the bundle and start up the Agent, as described in the instructions for starting the Agent, just as you would in a complete installation.
Step 5. Install the HQ Shell.
After you specify the Agent installation directory, the installer asks for the Shell's installation location.
HQ shell installation path [default '/home/hyperic']:
Installation Complete!
After all the installer's questions have been correctly answered, it will install the selected HQ components. If a Server was installed, go on to starting the Server. If an Agent was installed, go on to starting the Agent. For more details on the HQ Shell, see the CLI Reference.
Step 6. Start the HQ Server.
For Windows installations
The Server can be started right after installing it as a service.
- Install the Server as a service:
<Server Installation directory>\bin\hq-server.exe -i
This takes only a few seconds.
Now you can start (and stop) the Server via the Windows Service control panel.
For non-Windows installations
The Server can be started immediately after installation.
- Start the server with this command:
<Server Installation Directory>/bin/hq-server.sh start
The script will display some startup information on stdout, then it will detach and run in the background.
The URL that HQ is configured to listen on will display startup progress information until it is completely started. Then it will redirect to the login page.
Additionally, the Server log (located at <Server installation directory>/logs/server.log) will have detailed startup information.
Step 7. Start the HQ Agent.
This section addresses the questions asked the first time an Agent is started. The HQ Server must already be running before starting an Agent for the first time. If the server is not running yet, see these instructions.
For Windows installations
- Run the following command from a command prompt (not by double-clicking) :
hq-agent.exe
- After the first start process has been completed, we recommended installing the HQ Agent as a Windows Service. Run this command:
hq-agent.exe -i
After the Windows Service has been installed, starting and stopping the HQ Agent can be managed from the Windows Service Manager
For non-Windows installations
To start the HQ Agent:
- Run the following command:
<Agent Installation Directory>/hq-agent.sh start
When the HQ Agent starts for the first time, it asks you for information so that it can establish network communications with the HQ Server:
| Configuration Question | Description | Default |
|---|---|---|
| HQ Server IP Address | Supply the IP address of the running HQ Server. If the agent is on the same host as the server, the answer can be 127.0.0.1 to communicate on the loopback interface | none |
| HQ Server <-> HQ Agent secure communication | This option tells the HQ Agent to communicate with the HQ Server over HTTPS. If secure communication is not necessary (for instance, if the agent and server are on a private network), saying 'no' here will increase the performance of agent/server communication | no |
| HQ Server Port | Supply the port the HQ Agent will communicate to the HQ Server on. If the answer of the previous question was 'yes' to communicate securely, the HTTPS port must be supplied. If the answer was 'no' not to communicate securely, the HTTP port must be supplied | 7080 or 7443 |
| HQ Login | Supply the username of an HQ user with sufficient permissions to create resources in HQ. The HQ administrator has such permissions | hqadmin |
| HQ Password | Supply the password for the username entered above | none |
| HQ Agent IP Address | Supply the IP address the HQ Server will use to contact this agent. If the agent is on the same host as the server, the answer can be 127.0.0.1 to communicate on the loopback interface. If there is a firewall between the HQ Server and agent, this would be the IP address of the firewall and the firewall must be configured to forward traffic intended for the HQ Agent to the correct location | Detected IP Address |
| HQ Agent Port | Similar to the previous question, this is the port the HQ Server will communicate to the agent on. Note that changing this value will not change the port the agent binds to on the machine. The port the agent binds to is set in the agent.properties properties file. The property to set is agent.listenPort. There is no agent.listenPort specified by default, so the agent listens on 2144 by default. If the agent.listenPort is changed, this question must be answered accordingly. Additionally, if there is a firewall between the HQ Agent and the HQ Server, this value should be the port the firewall is forwarding to the HQ Agent | 2144 |
To shut down the HQ Agent:
- Run the following command (be sure to provide the correct version number):
agent-3.x.x/hq-agent.sh stop
To display connection information for a running Agent:
- Run the following command (be sure to provide the correct version number):
agent-3.x.x/hq-agent.sh status
|
Next Steps Get a quick start to basic management of your IT infrastructure |
Related Information |
