This document describes how to set up Hyperic HQ on Ubuntu 7.04. The resulting system provides an awesome, web-based “Systems-Management-Software”. It’s the next stage of classical monitoring and able to manage all kinds of operating systems, web servers, application servers and database servers.
I can’t list all the features in here, so please take a look at http://www.hyperic.com/products/hq_oss.html. Hyperic HQ is licensed under the GPL.
This howto is meant as a practical guide; it does not cover the theoretical backgrounds. They are treated in a lot of other documents in the web.
This document comes without warranty of any kind! I want to say that this is not the only way of setting up such a system. There are many ways of achieving this goal but this is the way I take. I do not issue any guarantee that this will work for you!
Set up a basic Ubuntu 7.04 system and update it.
2 Get Hyperic HQ
tar xvfz hyperic-hq-installer-3.1.0-439-x86-linux.tgz
3 Install Hyperic HQ
You are not allowed to install Hyperic HQ as root, and the installer does not auto-create the installdir. So you have to create it yourself and change the owner to your username:
sudo mkdir /home/hyperic
sudo chown %yourusername%:%yourusername% /home/hyperic
Note: The installdir can be any directory you want, however be sure that you are permitted to write to it.
3.1 Start Installation
Run the installer:
3.2 Select Software
You will be asked which software you want to install – select server and agent:
Note: If you have a running HQ Server and want to monitor other machines, you only need to install the HQ Agent on them. It is available for all kinds of operating systems. Have a look at http://sourceforge.net/projects/hyperic-hq.
3.3 HQ Server Installdir
Next step we choose the default installation path for the HQ server – so hit enter.
3.4 SMTP Server
At this point you are asked to enter the name or ip of the smtp-server that HQ will
use to send email messages – choose your local machine:
Note: You can insert any other name or ip of an existing smtp-server of course.
3.5 HQ Agent Installdir
Now you are asked for an installation path again – this time for the HQ agent. Once more we choose the default – so hit enter.
Note: HQ server and HQ agent will be installed isolated from each other in one’s subdirectorys.
3.6 During Installation
At a point the Installation will be paused, and you are asked to open a second terminal and log in as root to execute a special script.
So open a second terminal and execute the script:
After that close the second terminal, return to the first terminal with the paused installation and hit enter to continue the installation process.
After the installation finished, the install-log has been saved to /tmp/hyperic-hq-installer/installer-3.1.0/hq-install.log
Keep in mind that /tmp/ will be deleted if you shut down or reboot the system. So if you want to cast a glance on it later you have to copy it to another directory.
4 Start The HQ Server
First you have to start the HQ server:
The initial startup should look like this:
Starting HQ server…
Initializing HQ server configuration…
Checking jboss jndi port…
Checking jboss mbean port…
Starting HQ built-in database…
HQ built-in database started.
Booting the HQ server…
HQ server booted.
Login to HQ at: http://127.0.0.1:7080/
Note: The first start will take more time as usual.
5 Start The HQ Agent
After the HQ server booted you have to start the agent:
The initial startup should look like this:
– Unable to load agent token file. Generating a new one … Done
– Invoking agent
– Starting agent process
Agent successfully started
6 Configure The HQ Agent
The HQ agent needs some information for the cooperation with the HQ server. You will be asked for it straight after the HQ agent started for the first time.
6.1 HQ Server IP Address
You will be asked to enter the ip adress for the HQ server. In this case, where the HQ server and the HQ agent are installed on the same machine, it’s localhost:
6.2 SSL Communication
You will be asked if you want encrypted communication between the HQ Agent and the HQ server. In this case it’s not needed, but remember to enable the SSL communication if you set up an HQ agent that will communicate to the HQ server across the internet.
So hit enter to choose default=no.
6.3 HQ Server Port
You will be asked for the port that the HQ agent has to use to communicate with the HQ server. If you haven’t changed it, it is the default port 7080 (tcp).
So hit enter to choose default=7080.
Be sure, that the firewall on the HQ server host, or a special device that is connected to the host, is not blocking port 7080 (tcp) or 7443 (tcp). Otherwise you’ll have to open them.
6.4 Access Data
You will be asked to enter the proper username and password that the HQ agent will need to communicate with the HQ server. We use the default values for this setup.
So hit enter to choose the default username (hqadmin) and next enter the default password:
Be sure that you change these settings if you use this system in a production environment and have HQ agents communicating across the internet.
6.5 HQ Agent IP Address
You will be asked to enter the ip address that the HQ server has to use to communicate with the HQ agent. In this case it’s localhost:
So hit enter to choose the default.
6.6 HQ Agent Port
You will be asked for the port that the HQ server has to use to communicate with the HQ agent. If you haven’t changed it, it is the default port 2144 (tcp).
So hit enter to choose default=2144.
Be sure, that the firewall on the HQ agent host, or a special device that is connected to the host, is not blocking port 2144 (tcp) for incomming traffic. Otherwise you’ll have to open it.
6.7 Configuration Completion
Now, after you entered all needed information, the HQ agent will register itself at the host.
It should look like this:
– Received temporary auth token from agent
– Registering agent with HQ
– HQ gave us the following agent token 1187275261550-13485140805726178-3666098505737167114
– Informing agent of new HQ server
– Successfully setup agent
7 Access The HQ Server
The HQ Server provides an eye candy, easy-to-use, web-based interface.
You can access it with a browser of your choice at http://127.0.0.1:7080 on the host-system, or using another computer, at http://%hostip%:7080 .
Keep in mind the essential commands:
Start the HQ Server:
Start the HQ Agent:
Stop the HQ Agent:
Stop the HQ Server:
To give you a slight foretaste, I made a few screenshots.
Server1 memory overview (indicators):
Server1 memory overview (metric data):
Server1 configuration (only a small proportion):
Hyperic at sourceforge: http://sourceforge.net/projects/hyperic-hq/