This document describes how to set up Hyperic HQ on Fedora 8. The resulting system provides an awesome, web-based “System ManagementSoftware”. 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 a practical guide without any warranty – it doesn’t cover the theoretical backgrounds. There are many ways to set up such a system – this is the way I chose.
1 Preliminary Note
I used a standard Fedora 8 installation for this howto. It’s also possible to use a Fedora 8 server setup (minimal installation without gui etc).
Note: If you want to set up a virtual machine with VMware-Server you should install the VMware Tools – otherwise the VM’s system time will run too fast and the HQ server might get problems with the collection of data from the HQ agents.
2.1 Up To Date
I recommend to install a few plugins for yum to speed it up a bit and prevent problems with packages.
Use your preferred yum frontend or a terminal:
yum -y install yum-fastestmirror yum-skip-broken yum-fedorakmod yum-kernel-module
Now you should update your system (if not already done). Use your preferred yum frontend or a terminal:
yum -y update
It’s highly recommended that you synchronize the system time on the HQ server and all HQ agents via NTP (Network Time Protocol). Otherwise the HQ server will get problems with the collection of metrics from the HQ agents.
2.2.1 Standard Setup With Gui
The NTP-settings are available in the gnome-system menu.
Enter the root password.
Select “Runlevel All” in the menu.
The service “ntpd” should be activated in runlevels 3 and 5. If not, mark the corresponding checkboxes, start the service and save the settings.
2.2.2 Server Setup Without Gui
First switch to the rootaccount …
… and check if NTP is activated for runlevel 3.
chkconfig –list ntpd
If it is deactivated, activate it in runlevel 3 and start it.
chkconfig –level 3 ntpd on
If you haven’t set up a DNS-server for your network it would be a good idea to edit the hosts file on the HQ server’s host and all workstations from which you want to access the HQ server’s webinterface. So let’s edit the settings:
It should look like this. Replace the hostname and the IP with the settings you chose.
# Do not remove the following line, or various programs # that require network functionality will fail. 127.0.0.1 localhost.localdomain localhost 192.168.0.100 server1.example.com server1 ::1 localhost6.localdomain6 localhost6
Afterwards switch back to your useraccount.
On Windows workstations you’ll find the hosts-file in C:\Windows\System32\drivers\etc\.
SELinux should be disabled. If you’re not sure if it is, enter:
cat /etc/selinux/config | grep ^SELINUX=
If it is not disabled edit the config file:
After that you have to reboot the system.
You have to open a few ports in the firewall to make the HQ server accessible for HQ agents that are running on other machines and to access the HQ server’s webinterface from outside.
If you want to use the standard ports you’ll have to open port 7080 (tcp) and 7443 (tcp). Otherwise configure the firewall-settings later when you’ve reached step 3.4/3.5 .
2.5.1 Standard Setup With Gui
If you chose a standard setup, the firewall settings are available in the gnome system-menu.
Enter the root password.
Click on “Other Ports” on the left and afterwards on “Add” on the right. Now mark the checkbox next to “User Defined“, enter the http port and click on “OK“. Repeat these steps for the https port.
After that click on “Apply” so that the changes can take effect.
2.5.2 Server Setup Without Gui
If you chose a minimal setup without gui you can edit the firewall settings via:
Select “Customize” and hit enter.
Insert the http and https port, separated by a space, into the field next to “Other Ports“. Afterwards select “OK” and hit enter.
Select “OK” and hit enter.
2.6 X Libraries
Because the HQ server needs some of the X libraries to create charts and other graphics within the webinterface, we need to install the corresponding package.
Use your preferred yum frontend or a terminal:
yum -y install libXp
2.7 HQ Directory
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 ownership to your useraccount.
chown %yourusername%:%yourusername% /home/hyperic/
Note: The installdir can be any directory you want, however be sure that you are allowed to write to it.
2.8 Get Hyperic HQ
When I was writing this howto the newest version available (x86) was 3.1.4-504. Maybe there’s already a newer version out when you’re reading this – so please have a look at http://www.hyperic.com/downloads/dl-hq-oss.html#installer to find out which is the latest version.
Download and unpack Hyperic HQ.
tar xvfz hyperic-hq-installer-3.1.4-504-x86-linux.tgz
Now, after we’ve prepared the system, it’s time to start the installation.
First switch to the temporary folder.
You have the choice between a standard setup with default settings…
…standard setups with usage of another database (PostgreSQL, Oracle or MySQL v4.x) than the built-in PostgreSQL database…
(Note: If you want to set up Hyperic HQ with usage of another database have a look at http://support.hyperic.com/confluence/display/DOCSHQ30/Database+Preparation first! Support for MySQL v5.x is beta at the moment and will probably be fully supported in Hyperic HQ v3.2.x.)
…and a custom installation where you can adjust all and everything – that I chose for this setup (with default settings) to show you all available options.
3.2 Software Selection
You’ll 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://www.hyperic.com/downloads/dl-hq-oss.html#installer.
3.3 HQ Server Installdir
Next step we choose the default installation path for the HQ server (/home/hyperic/) – simply hit enter.
3.4 HQ Server / Webinterface HTTP Port
You’ll be asked what port shall be used to access the webinterface (HTTP) – this port will also be used to communicate with the HQ agents. I chose the default port 7080 (simply hit enter).
Note: Have a look at step 2.5 if you haven’t adjusted your firewall-settings yet.
3.5 HQ Server / Webinterface HTTPS Port
You’ll be asked what port shall be used to access the webinterface (HTTPS) – this port will also be used to communicate with the HQ agents (encrypted). I chose the default port 7443 (simply hit enter).
Note: Have a look at step 2.5 if you haven’t adjusted your firewall settings yet.
3.6 JNP Service
You’ll be asked what port shall be used for the JNP service. I chose the default port 2099 (simply hit enter).
3.7 MBean Server
You’ll be asked what port shall be used for the MBean server. I chose the default port 9093 (simply hit enter).
3.8 Webinterface Base URL
You’ll be asked which URL shall be used to access the webinterface. I chose the default http://server1.example.com:7080/ (simply hit enter).
3.9 Email Address
You’ll be asked for the email address that HQ will use as the sender. I chose the default email@example.com (simply hit enter).
At this point you have to choose the backend database that the HQ server shall use. If you want to use another database than the built-in it’s highly recommended that you read http://support.hyperic.com/confluence/display/DOCSHQ30/Database+Preparation first! I chose the default – the built-in PostgreSQL database (1).
3.11 Database Port
You’ll be asked what port shall be used for the database. I chose the default port 9432 (simply hit enter).
3.12 Admin User Username
Choose a username for the admin user. I chose the default hqadmin (simply hit enter).
3.13 Admin User Password
Choose a password for the admin user – I chose hqadmin.
Keep in mind that you should choose a secure password in a production environment.
3.14 Admin User Email Address
You’ll be asked to enter an email address for the admin user. I chose the default firstname.lastname@example.org (simply hit enter).
3.15 HQ Agent Installdir
Now we choose the default installation path for the HQ agent (/home/hyperic/) – simply hit enter.
Note: HQ server and HQ agent will be installed isolated from each other in one’s subdirectories.
3.16 During The Installation
Now the HQ server and HQ agent are being installed with the settings you chose in the steps before. At a point the installation will be paused, and you are asked to open a second terminal, log in as root and execute a special script. So open a second terminal and enter:
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.4/hq-install.log.
4 HQ server Initial Start-Up
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 HQ Agent Initial Start-Up
After the HQ server has 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 HQ Agent Configuration
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
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. Hit enter if you want to choose the default (no encryption).
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. Enter the port that you chose in step 3.4 – I chose the default port 7080 (simply hit enter).
Be sure, that the firewall on the HQ server’s host, or a special firewall-device that is connected to it, is not blocking the ports that you chose in the steps 3.4 and 3.5 (the defaults are 7080 (tcp) and 7443 (tcp)). Otherwise you’ll have to open them.
6.4 Access Data
You will be asked to enter the username (step 3.12) and password (step 3.13) that the HQ agent will need to communicate with the HQ server. I chose the default username and password (both hqadmin).
6.5 HQ Agent IP
You will be asked to enter the ip adress that the HQ server shall use to contact the HQ agent. In this case, where the HQ server and the HQ agent are installed on the same machine, it’s the local IP. Simply hit enter to choose the default (in my case 192.168.0.100).
6.6 HQ Agent Port
You will be asked to enter the port that the HQ server shall use to contact the HQ agent. I chose the default 2144 (simply hit enter).
Be sure, that the firewall on the HQ agent’s host, or a special firewall device that is connected to it, is not blocking the port that you chose in this step (the default is 2144 (tcp)). Otherwise you’ll have to open it.
6.7 Configuration Completition
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 1196949488716-2984445946072380062-7407104339127655563
– Informing agent of new HQ server
– Successfully setup agent
7 The Webinterface
The HQ Server provides an eye-candy, easy-to-use webinterface. You can access it with a browser of your choice at http://127.0.0.1:%http_port% on the host-system, or using another computer, at http://%hostip_or_hostname%:%http_port% (the default http-port is 7080) – or if you want an encrypted connection, at https://%hostip_or_hostname%:%https_port% (the default https-port is 7443).
8 Essential Commands
8.1 HQ Server
8.2 HQ Agent
9.6 Server1 Memory Overview
9.7 Server1 HQ JBoss Configuration
- Hyperic HQ: http://www.hyperic.com/products/hq_oss.html
- Fedora: http://fedoraproject.org/