LibraryPrintFeedback

Installing Fuse HQ

Version 4.4

April 2011
Legal Notices

Updated: 15 Apr 2011

Table of Contents

1. Installation Prerequisites
Planning your installation
Fuse HQ Server Requirements
Fuse HQ Agent Requirements
Fuse HQ Repository Requirements
2. Preparing the Fuse HQ Repository
Preparing an Oracle Database
Preparing a PostgreSQL Database
Preparing a MySQL Database
3. Installing the Fuse HQ Server
Downloading a Fuse HQ Server Installation Package
Running the Fuse HQ Server Installer
Fuse HQ Server Configuration Settings
Installing the Fuse HQ Server License
4. Installing Fuse HQ Agents
Downloading a Fuse HQ Agent Installation Package
Fuse HQ Agent Installations
5. Running the Fuse HQ Server and the Fuse HQ Agent
Starting and Stopping the Fuse HQ Server
Starting and Stopping the Fuse HQ Agent
6. Upgrading Fuse HQ
Upgrading the Fuse HQ Server
Upgrading the Fuse HQ Agent
7. Uninstalling Fuse HQ Components
Uninstalling the Fuse HQ Server
Uninstalling a Fuse HQ Agent

List of Tables

3.1. Installation Mode Arguments for the setup Command
3.2. Configuration Settings for the Fuse HQ Server
5.1. Configuration Settings for the Fuse HQ Agent

Before you begin installation of Fuse HQ, you must decide where you will install the following Fuse HQ functional components:

ComponentDescription
Fuse HQ Server

The central component that controls agents, manages data, and provides a browser-based GUI.

See Fuse HQ Server Requirements.

Fuse HQ Agent

The component that finds resources, gathers data, controls software, and communicates with the server.

Agents are installed on the systems in a network that you want to monitor or control. See Fuse HQ Agent Requirements Note that agents cannot function remotely; they can only monitor resources on the system where they are installed.

Fuse HQ Repository

A database, managed by the Server. It stores Fuse HQ data and is responsible for ensuring data integrity and access.

See Fuse HQ Repository Requirements

Check this section before you install HQ Server on the machine that will be the central control and management system for Fuse HQ.

Fuse HQ server is supported on the following operating systems:

Fuse HQ supports the following Web browsers:

[Warning]Warning

The Skype plugin for Firefox causes unexpected behavior in the HQ user interface. Disable the plugin to work around this problem.

The Fuse HQ Server is bundled with a JRE and its use is recommended. However, if you prefer to use a JRE (or JDK) that may already be installed on the system, the JRE or JDK should be version 1.5 or 1.6. We recommend Java 1.6.

[Warning]Windows 64-bit JRE

HQ Server does not support 64-bit JREs under Windows. Use the 32-bit installer package for Windows, or the platform-independent installer if you prefer to use a pre-existing JRE in your environment.

Before installing Fuse HQ you will need to obtain the Oracle JDBC driver. To obtain the driver:

  1. Go to http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html.

  2. In the JDBC Driver Downloads section, select the link for your version of Oracle.

  3. On the drivers download page, select the driver for your JDK version.

    • JDK 5.0 — ojdbc5.jar

    • JDK 6.0 — ojdbc6.jar

    [Note]Note

    JDeveloper 11g JDBC drivers support JDBC 4.0 features. Use ojdbc6.jar with JDK 6.0 for JDBC 4.0 features.

  4. On the page that appears accept the licensing agreement.

  5. Download the jar file.

  6. Copy the driver jar file to hyperic-hq-installer/installer-4.x.y/lib.

Preparing a PostgreSQL database for the Fuse HQ repository is relatively complicated and can vary depending on the operating system and other factors. PostgreSQL usually requires a DBA or someone with DBA knowledge for setup and maintenance. You can also find help by consulting the PostgreSQL documentation.

[Note]Note

Fuse HQ automatically creates a language in the PostgreSQL database, but not in PostgreSQL 8.0. You must run the following command on a PostgreSQL 8.0 database:

createlang plpgsql <DATABASE NAME>

The createlang executable is located in the bin directory of your PostgreSQL installation.

You configure the MySQL database by editing the settings in its configuration file. On Unix and Linux, the file is /etc/my.cnf. On Windows the file is MySQLInstallDir\my.ini.

For more information about InnoDB startup options and system variables, see http://dev.mysql.com/doc/refman/5.0/en/innodb-parameters.html.

Configure MySQL as follows:

  1. Enable the full query log.

    [mysqld]
    log-error = /home/mysql/log/mysqld.err
    log = /home/mysql/log/mysql_general.log

    Every query (even ones with incorrect syntax) that the database server receives will be logged. This is useful for debugging, but it is usually disabled in production use. Be sure to change the paths given here to match your environment.

  2. Print warnings to the error log file.

    log_warnings
    server-id       = 1

    If you have any problem with MySQL, you should enable logging of warnings and examine the error log for possible explanations.

  3. Configure buffer pool size.

    innodb_buffer_pool_size = 256M

    The size of the MySQL buffer pool is has a significant impact on MySQL performance. If your database is on a dedicated machine, make the buffer pool about 80% of total memory.

  4. Configure the frequency with which the log buffer is written to the log, and the log is flushed to the disk.

    innodb_flush_log_at_trx_commit = 2
    innodb_log_buffer_size = 64M
    innodb_log_file_size = 256M

    Setting this value to 0 dramatically increases MySQL performance, but with this setting, you are likely to lose data in the event of a server crash. If loss of data is unacceptable, use a value of 2 instead. We do not recommend setting the value to 1.

  5. Configure innodb as the default storage engine.

    default-storage_engine=innodb
    bulk_insert_buffer_size = 32M
    join_buffer_size = 8M
    max_heap_table_size = 256M
    tmp_table_size = 256M
    max_tmp_tables = 48
    myisam_sort_buffer_size = 256M
  6. Configure the sort buffer size.

    sort_buffer_size = 64K

    MySQL recommends a sort_buffer_size larger than 64K.

    An article on experimenting with sort buffer size is available at http://www.mysqlperformanceblog.com/2007/08/18/how-fast-can-you-sort-data-with-mysql.

  7. Configure the read buffer size.

    read_buffer_size = 1M
    read_rnd_buffer_size = 10M
    table_cache = 2048
    set-variable = max_connections=400
    key_buffer_size = 256M
    thread_cache_size = 32

    Because Fuse HQ does a significant volume of sequential reads, a large read buffer improve performance.

  8. Configure the number of threads that can run in the InnoDB kernel.

    innodb_thread_concurrency = 8

    A starting point for setting this value is to to set a value equal to twice the number of CPUs times the number of disks.

  9. Set the method that is used to flush data and log files.

    innodb_flush_method=O_DIRECT
    innodb_rollback_on_timeout=1

    For battery-backed-up storage with write-back cache mode on Linux, the O_DIRECT flush method is good.

  10. Set the size of the query cache.

    query_cache_size = 0

    Generally, the higher this value, the better the performance. However, in MySQL versions older than 5.0.50, beware of setting this variable too high, as it may cause the database to pause. For more information, see the bug description at http://bugs.mysql.com/bug.php?id=21074.

  11. Set the query cache limit.

    The default value here is 1M. If the qcache_hits-to-qcache_inserts ratio is low, raise this value.

    query_cache_limit = 8M
  12. Set the character encoding to utf-8.

    default-character-set=utf8
    collation_server=utf8_bin

Go to the Fuse HQ download web page to obtain an installation package for Fuse HQ Server. If you do not already have an account on the fusesource.com Web site, you will be prompted to create an account before you proceed with the download.

Select the installation package that matches the system where you intend to install Fuse HQ Server. See Hardware for details of supported platforms.

[Note]Note

If you already have a JRE that you want to use, download the No JRE package. However, be sure that your JAVA_HOME environment variable is set to point to the particular JRE you want Fuse HQ to run on.

Save the file (a .zip or a.tar.gz file) to a directory where you can unpack it. Unpack the file using the appropriate utility ( WinZip, tar, gunzip, etc.).

[Note]Note

On some Solaris systems, the default version of tar is incompatible with Fuse HQ installation packages. When tar is incompatible, unpacking will be incomplete and you may see checksum errors. The solution is to install GNU tar. See the instructions for installing GNU tar for more information.

What happens next, depends on which installation mode you chose:

  • If you chose to do a quick install, the installation completes with all the default configuration settings. You can view the installation log, hq-install.log in fuse-hq-installer/installer-4.4.0.0-fuse/logs/hq-install.log.

  • If you chose to do a quick install with one of the external repository options (-postgresql, -oracle, or -mysql), the installer will prompt you to enter a JDBC connection URL, a user name, and a password. Then, the installation completes with all the default configuration settings.

    The installer offers a default JDBC connection URL, which you can use if you installed the repository on the same system as the Fuse HQ Server.

    The user name and password should refer to an account that has administrative privileges. The instructions in Preparing the Fuse HQ Repository describe how to create administrative accounts in all three types of repository.

  • If you chose a full install, the installer prompts you for configuration settings.

If you run the installer using the -full option, the installer prompts you for configuration settings in the order shown in Table 3.2.

Table 3.2. Configuration Settings for the Fuse HQ Server

SettingDefaultDescription
HTTP port7080The port the Fuse HQ Server's web-based GUI uses for HTTP communications.
HTTPS port7443The port the Fuse HQ Server's web-based GUI uses for secure HTTPS communications.
JNP port2099The port the Fuse HQ Server uses for the JNP service.
Mbean port9093 The port the Fuse HQ Server uses for the Mbean Server .
GUI URLhttp://hostname:_http_portThe URL Fuse HQ Agents will use to send alert notifications to the web-based GUI. (You can change this value on the Fuse HQ Server Administration screen.)
Fuse HQ Server's email addresshqadmin@hostname The From address on alert notification emails sent by the Fuse HQ Server. Note that most email servers will not deliver mail without a valid domain name in the From field.
Backend databaseHQ Built-in DatabaseThe type of database that the Fuse HQ Server will use as a repository. If you choose anything other than the default built-in database, the installer will prompt you for a JDBC connection URL, a user name, and a password. If you choose the built-in database, the installer will prompt you for a port number. The default is 9432.
Administrator's user namehqadminThe user name of the original Fuse HQ administrator.
Administrator's passwordhqadminThe password of the original Fuse HQ administrator.
Administrator's addresshqadmin@hostname The email address assigned to the initial Fuse HQ administrator. Alert notifications are sent to this address if the Administrator is configured to receive alert notifications.

The installer saves your settings in a file named hq-server-install.conf in the ServerInstallDir/data directory. You can open and view this file in a text editor after the installation completes.

Go to the Fuse HQ download web page to obtain an installation package for Fuse HQ Agent. If you do not already have an account on the fusesource.com Web site, you will be prompted to create an account before you proceed with the download.

If you intend to install both a Fuse HQ Server and Agent, choose a package for one of the platforms described in Fuse HQ Server Requirements and follow the instructions in Running the Fuse HQ Server Installer.

Select the installation package that matches the system where you intend to install Fuse HQ Agent (see Fuse HQ Agent Requirements for details of supported platforms).

[Note]Note

If you already have a JRE that you want to use, download the No JRE package. However, be sure that your JAVA_HOME environment variable is set to point to the particular JRE you want Fuse HQ to run on. If you have a particular JRE you want Fuse HQ to run on, you can set the HQ_JAVA_HOME environment variable.

Save the file to the directory where you want to install the Fuse HQ Agent. On Windows, for example, Agents are often installed in a folder created under C:\Program Files, but there is no requirement to use any particular installation directory. However, you must install the Fuse HQ Agent on the system that you want to monitor. Agents cannot monitor remote systems.

To start the Fuse HQ Agent for the first time on Windows:

Do not run hq-agent.bat by double-clicking on it in Windows Explorer.

When you start a Fuse HQ Agent for the first time, the startup process prompts you for the configuration settings shown in Table 5.1.

Table 5.1. Configuration Settings for the Fuse HQ Agent

SettingDefaultDescription
Server IP Address none

The IP address of the system running the Fuse HQ Server.

If the Fuse HQAgent is on the same host as the Server, you can use 127.0.0.1 which allows communication on the loopback interface. If the Server is running on a remote host you can run ping to get the IP address.

Secure communicationsnoSpecify if HTTPS should be used for secure communications between Fuse HQ Server and Agent. Saying no improves performance. Secure communication is not always necessary (for example, when the Fuse HQ Agent and Server are on a private network).
Server port7080 or 7443

The port the Fuse HQ Agent uses to communicate with the Server.

If secure communication was specified, an HTTPS port (default 7443) must be supplied. Otherwise, an HTTP port (default 7080) must be supplied.

HQ loginhqadminThe username of an HQ user. The default, hqadmin, is based on the assumption that you used that username for the administrative account when you configured the Fuse HQ Server. However, the hqadmin account has permissions to create platforms, servers, and services on the Server. For security reasons, you may want to use a more restrictive account.
HQ password noneThe password for the specified username.
Agent IP Address Detected IP Address

The IP address of the system running the Fuse HQ Agent.

If the Fuse HQAgent is on the same host as the Server, you can use 127.0.0.1 which allows communication on the loopback interface.

If there is a firewall between the Fuse HQ Server and Agent, use the IP address of the firewall. Note that the firewall must be configured to forward Fuse HQ Agent traffic to the correct location.

Also note that IP addresses must be static for systems running a Fuse HQ Server or an Agent. In Fuse HQ, IP addresses are referenced in configuration files. If the IP address was dynamic and it changed, the configuration file would not be updated to reference the new address.

Agent Port 2144

The port the Fuse HQ Server uses to communicate with the Agent.

Note that this port number is the value of the agent.setup.agentPort configuration parameter, which is passed to the Server at startup and which the Server will use to communicate with the Agent. However, there is another configuration parameter, agent.listenPort, which is not passed to the Server. It is the port that the Agent actually uses to receive communications.

By default, the value of agentPort is identical to the value of listenPort (2144). So the Server is sending to the same port that the Agent is using to receive.

You might set agentPort and listenPort to different values if a firewall or proxy intervenes between the Server and Agent. In that case, the firewall or proxy must be configured to receive messages on agentPort and forward them to listenPort.

You can set these Fuse HQ Agent configuration parameters in the agent.properties file, which is located in the Agent's installation directory.


An alternative to configuring each Agent during initial startup is to create and copy an agent.properties file to each install location. See Automatic Fuse HQ Agent configuration for more information.

When you run the Fuse HQ Server installer in upgrade mode, you install a new Fuse HQ Server and use the configuration information from the previously installed Server.

To upgrade the Fuse HQ Server, perform the following steps:

  1. Stop the existing Fuse HQ Server if it is running.

    See Starting and stopping the Fuse HQ Server on Windows systems or Starting and stopping the Fuse HQ Server on non-Windows systems for more information.

  2. Back up the repository

    This step is not necessary if you are using the built-in database. See Backing up the repository ) for more information.

  3. Stop the database server for the repository.

  4. Download and unpack the installation package.

    See Downloading a Fuse HQ Server Installation Package for more information.

  5. Run the installer in upgrade mode.

    On Windows, you run setup.bat -upgrade. On non-Windows systems, you run setup.sh -upgrade.

  6. When prompted by the installer enter the full pathname of the current Fuse HQ Server and the location where the new Server should be installed. Note that you should not install the new Server in the same directory that contains the old Server.

  7. Archive the old Fuse HQ Server directory (using tar or zip), in case you need to revert to the older version.

After successfully completing the upgrade, you should be able to start the repository and run the new Fuse HQ Server.

To upgrade a Fuse HQ Agent:

  1. Stop the Fuse HQ Agent service. See Stopping the Fuse HQ Agent on Windows or Stopping the Fuse HQ Agent on non-Windows systems.

  2. On Windows platforms, uninstall the Agent service by running the following command:

    hq-agent.bat remove
  3. Back up the agent.properties file from the previous Agent installation.

  4. Download and unpack the Agent-only package into its installation directory. See Downloading a Fuse HQ Agent Installation Package for more information..

  5. Restore the backed up properties from the agent.properties file.

    • If upgrading between 4.x releases, you can just over-write the existing AgentInstallDir/conf/agent.properties file with the backed up agent.properties file.

    • If upgrading from a 3.x to a 4.x release, however, you must edit the new AgentInstallDir/conf/agent.properties file and manually copy property settings from the backed up agent.properties file (this is because the 4.x agent.properties file contains some properties not present in the older version).

  6. On Windows, install the new Agent service by running the following command:

    hq-agent.bat install
  7. Start the new Agent. See Starting and Stopping the Fuse HQ Agent for more information.