The setup script in the HQ installation package is the way to start the installer. Executing the setup script with no arguments 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. The setup script will also accept a single argument that causes it to behave in different ways. Those arguments are detailed below.
If you already have an HQ Server installed, skip to HQ Agent installation.
 | Windows users, run the installer on the command line and substitute setup.sh with setup.bat. Also, if an older version of HQ is already installed and running, please stop HQ Server, HQ Database, and HQ Agent from the Services control panel, an Administrative Tool. |
setup.sh -full
The installer will prompt for almost everything. Ports to use, HQ Administrator username and password, The 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. This will just ask for database connection information and take defaults for everything else.
 | Note for PostgreSQL 8.0 HQ creates a language in the PostgreSQL database. HQ is not able to create the language automatically in PostgreSQL 8.0, so if you plan to use this version, you must run the following command on the HQ database before starting the HQ Server. createlang plpgsql [DATABASE NAME] The createlang executable is located in the bin directory of your PostgreSQL installation. |
setup.sh -oracle
Quick install mode for Oracle. 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. 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 yet supported by Hyperic HQ and is currently in Beta. Support is expected for Hyperic HQ 3.2.
| Database Required These last 3 flags (-postgresql, -oracle, and -mysql) require a database other than the HQ Built-in database. See the HQ Database Preparation Guide for details on setting up your database. |
Components
The first thing the HQ installer will ask in all modes except upgrade will be which components you wish to install. Select at least one of the following choices.
| 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. |
| 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. |
HQ Server Installation
When installing the HQ Server using the -full option, all aspects of the HQ Server can be configured. These aspects are detailed below.
| Configuration | Description | Default | ||
|---|---|---|---|---|
| HQ Server HTTP Port | Configuration for the port HQ Server will listen for HTTP traffic | 7080 |
||
| HQ Server HTTPS Port | Configuration for the port HQ Server will listen for HTTPS traffic | 7443 |
||
| HQ Server JNP Port | Allows for specification of an alternate JNP port | 2099 |
||
| HQ Server MBean Port | Allows for specification of an alternate MBean server port | 9093 |
||
| HQ Server Base URL | Allows for specification of the URL used to access the HQ Server. This value is used in alert notification emails. This value can also be changed from the HQ Server Administration page by an HQ administrator 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 will be skipped. If no SMTP server is found, it will ask you to specify one that it can use to send outbound alert notifications | localhost |
||
| HQ Server Alert Notification Sender | This is 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 | Select the backend database HQ Server will use. Options are the HQ built-in database (PostgreSQL 8.0), Oracle 8, Oracle 9i/10g, PostgreSQL, and MySQL. Depending on the selection of the database, the next questions will be about how to connect to that database. Any selection except HQ Buit-in Database will require JDBC URL, username and password | HQ Built-in Database |
||
| HQ Administrator Username | Allows for specification of the username of the original HQ administrator (HQ root user) | hqadmin |
||
| HQ Administrator Password | Specify a password for the HQ administrator. The installer will not echo the password and 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 | This is the email address assigned to the HQ administrator. This is the address alert notifications will be sent to if the administrator user is ever configured to receive alert notifications | hqadmin@hostname |
||
| HQ Server Authentication Data Source | This allows specification of an alternate LDAP data source for the HQ user authentication. If LDAP is selected, there will be further questions specific to the LDAP connection. For details on how to configure HQ for LDAP authentication, see the HQ LDAP Configuration documentation
|
HQ Database |
| High Availability The High Availability option has been removed from the installer in HQ 3.0. High Availability is now configured post install. See the HQ High Availability Guide for details on HA configuration. |
HQ Agent Installation
The only question the agent installer will ask is where to install the agent. If an agent installation exists in that location, the installer will ask if you want to overwrite it. However, the first time the HQ Agent is started, there are some questions to be answered. The agent needs to know how to contact the HQ Server, so that information must be supplied to it. After starting the HQ Server, see the HQ Agent Startup section for details.
| Agent-only Installation It is not necessary to use the full installer to install an agent. Separate agent-only installation bundles are available for download. To use these simply, unpack the bundle and start up the agent (go through the same initial agent startup process as a normal install). |
HQ Shell Installation
The only question the shell installation will ask is the location to install.
Installation Completion
After all questions have been correctly answered, the installer will install the selected HQ components. If a server was installed, see the HQ Server Startup section. If an agent was installed, see the HQ Agent Startup section. For more details on the HQ Shell, see the CLI Reference section of the documentation.
HQ Server Startup
Once the installer successfully installs the HQ Server, it needs no post-installation tasks, it can immediately be started. On Windows platforms, The Hyperic HQ Server gets installed as a Windows Service, so starting and stopping can be managed from the Windows Service Manager.
Unix users start the server by executing
server-3.x.x/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-3.x.x/logs/server.log) will have detailed startup information.
HQ Agent Startup
This section will cover the questions to be answered during the first start of an agent. But be aware that the HQ Server must already be running before starting an agent for the first time. If the server is not running yet, see the HQ Server Startup section above.
| HQ Agent on Windows Windows users will use the following command from a Command Prompt (not double-clicking) to start the agent: hq-agent.exe After the first start process has been completed, it is recommended that the HQ Agent be installed as a Windows Service by executing 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 |
Start the HQ Agent by executing the following command:
agent-3.x.x/hq-agent.sh start
When the HQ Agent starts up for the first time, a series of questions are given to establish network communications with the HQ Server. These are detailed below:
| 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 |
The HQ Agent can be shutdown by executing
agent-3.x.x/hq-agent.sh stop
Connection information can be displayed from a running agent by executing
agent-3.x.x/hq-agent.sh status
Next Steps
- See Getting Started With HQ for a walk through of the first steps to managing your IT infrastructure.
- Find out what's new in HQ by reading the Release Notes.
- Learn how Hyperic HQ monitors your resources with the Monitoring Basics document.
- Enhance your performance by tweaking HQ's configurations.
- See how to develop your own custom plugins for HQ in the Plugin Development Center.
- Configure Hyperic HQ to deliver email alerts via an SMTP server.
- Learn how to manually configure HQ's Cache Settings.
