Introduction to the HQE ServerTemplate
This page documents Hyperic's RightScale HQE Server w/ local MySQL backend ServerTemplate, referred to hereinafter as the "HQE ServerTemplate", and the RightScripts it contains.
The HQE ServerTemplate launches an EC2 instance that runs the HQ Server, an HQ Agent, and a local MySQL-hosted HQ database. You can launch using the built-in evaluation license or an existing HQ license. If you start with an evaluation license, you can convert to a fully licensed deployment later.
The HQE ServerTemplate provides an automated, repeatable method for deploying HQ components to AWS. HQ evaluators and customers can clone and modify the HQE ServerTemplate as desired to add or change functionality.
RightScript deployment of HQ is useful for:
- RightScale users that are interested in evaluating HQ.
- HQ customers who want to run HQ in the cloud and prefer the flexibility of subscription-based licensing over the HQ AMI available on Amazon DevPay.
Prerequisites and Assumptions
The following prerequisites and assumptions apply to the HQE ServerTemplate.
- RightScale subscription - You must have a premium RightScale subscription to use the HQE ServerTemplate; it uses several premium RightScripts.
- Supported AMI types - Currently, the HQ RightScripts are supported only for Linux AMIs.
- Using secure communications - The RightScript installations of HQ Server and HQ Agent do not setup firewall rules to open the ports on which the components communicate. You must create your own security groups to grant access to the ports used for agent-server communications and user access to the HQ Server user interface.
- On the HQ Server host, open ports 7080 and 7443, for plain and SSL communications with agents and user interface users.
- On each HQ Agent host, open port 2144 for communications with the HQ Server, unless you intend to use uni-directional communications, an agent configuration option that causes all communication with the server to be agent-initiated.
- Implementing database backup - This version of the HQE ServerTemplate does not include facilities for backing up the HQ database and configuration files to Elastic Block Storage (EBS), or restoring them from EBS. There are publicly available RightScripts for database backup and restore using EBS. Using these or similar RightScripts, a knowledgeable RightScale user can extend the HQE ServerTemplate to automate backup and restoration of the HQ database. Hyperic may provide this functionality in a future version of the HQE ServerTemplate.
Boot Scripts - Inventory and Sequence
This section lists the boot scripts in the HQE ServerTemplate in the order they are run when you use the template to deploy a machine instance. For each boot script, the table below lists the following information:
- Script type - The "Type" column indicates whether the script is public, premium, or Hyperic-provided. Note that Premium scripts are available only to RightScale customers.
- Description - The "Description" column contains a short description of what the script does. For public and premium scripts, see the provider's documentation for more detail. For more detailed information about the Hyperic-provided scripts, see Understanding Hyperic-Provided Boot Scripts.
| |
Script Name |
Type |
Description |
Inputs |
| 1. |
SYS REBOOT [rev 1] |
public |
|
|
| 2. |
MAIL Postfix Local Delivery v1 [rev 2] |
public |
Configures a mail transport agent (MTA). |
|
| 3. |
SYS Timezone set v1 [rev 2] |
premium |
Sets the timezone of the instance to the one specified by OPT_TZINFO. |
OPT_TZINFO |
| 4. |
SYS Syslog Remote Logging Client v6 [rev 5] |
public |
Configuring syslog-ng to maintain logs on the remote server identified by SYSLOG_SERVER. |
SYSLOG_SERVER |
| 5. |
RB rubygems 1.3.1 + quickinstall v4 [rev 1] |
public |
Patches RubyGems V 1.3.1 with a "quickinstall" option, which enables selection of a specific version and installation of multiple gems in a single command. |
|
| 6. |
SYS lvm on /mnt v8 [rev 5] |
premium |
Converts the available disks to LVM logical volumes. Volume size can be specified. |
OPT_LVM_SIZE
OPT_LVM_DRIVES |
| 7. |
DB RightScale tools install v10 [rev 5] |
premium |
Installs RightScale database tools in: /opt/rightscale/db. |
|
| 8. |
MISC ssh priv key install v2 [rev 2] |
public |
Copies a private key file specified by PRIVATE_SSH_KEY to ~root/.ssh/id_rsa |
PRIVATE_SSH_KEY |
| 9. |
SYS Monitoring install v7 [rev 4] |
public |
Installs and configures v4.1.1 or the collectd system statistics daemon (http://collectd.org/) to monitor RightScale.
Optionally, collectd will monitor processes listed in MON_PROCESSES. |
MON_PROCESSES
|
| 10. |
DB MySQL server install v7.1 [rev 1] |
Hyperic |
Installs MySQL with a default database.
For more information see DB MySQL server install v7.1. |
OPT_MYSQL_MAX_CONNECTIONS
DB_SERVER_USAGE
DB_BINLOG_PREFIX |
| 11. |
DB MySQL gem install v5 [rev 1] |
public |
Installs the C-native, fast MySQL gem. |
|
| 12. |
DB hqdb setup [rev 1] |
Hyperic |
Creates the HQ database in MySQL and sets (or resets) the passwords and privileges that the HQ database user requires.
Note: When using this script in another ServerTemplate, keep in mind it should be executed after installing an MySQL database server, and before installing the HQ Server. |
HQ_DB_USER_PWORD
HQ_DB_USER |
| 13. |
HQ Server Install [rev 1] |
Hyperic |
Installs and starts the HQ Server.
For more information, see HQ Server Install. |
HQ_DB_USER_PWORD
HQ_DB_USER
HQ_USE_EXISTING_LICENSE
HQ_UPGRADE
HQ_LICENSE_FILENAME
HQ_LICENSE_BUCKET_NAME
HQ_DB_JDBC_URL
HQADMIN_PWORD
HQADMIN_EMAIL
AWS_SECRET_ACCESS_KEY
AWS_ACCESS_KEY_ID
HQ_SERVER_SSL_PORT
HQ_SERVER_PORT |
| 14. |
HQ Agent Install [rev 1] |
Hyperic |
Installs and starts the HQ Agent.
For more information, see HQ Agent Install. |
HQ_USE_SSL
HQ_UNIDIRECTIONAL_AGENT
HQ_SERVER_DNSNAME
HQ_LOGIN_PWORD
HQ_LOGIN
HQ_AGENT_PORT
HQ_AGENT_DNSNAME
HQ_SERVER_SSL_PORT
HQ_SERVER_PORT |
Script Parameters - Definitions and Default Values
The following table defines the parameters used by RightScripts in the HQE ServerTemplate.
| Parameter |
Req |
Notes |
Default |
| AWS_ACCESS_KEY_ID |
n |
Required to use an existing HQ Server license stored on S3.
See Configuration Summary - Using an Existing HQ License. |
none
|
| AWS_SECRET_ACCESS_KEY |
n |
Required to use an existing HQ Server license stored on S3.
See Configuration Summary - Using an Existing HQ License. |
none |
| DB_BINLOG_PREFIX |
y |
The name prefix for binlog files (corresponding to the MySQL log-bin configuration parameter).
Specify an absolute path, or a path relative to the data directory. |
/mnt/mysql-binlogs/mysql-bin |
| DB_SERVER_USAGE |
y |
Specifies whether the machine instance is dedicated to MySQL, or will host additional processes. |
shared |
| HQ_AGENT_DNSNAME |
n |
Specifies the name shown in the HQ user interface for the agent.
By default, this is the hostname or IP address of the agent host. In EC2, this is typically the private DNS name.
You can use this parameter to provide a friendlier name. |
hq-server.ec2 |
| HQ_AGENT_PORT |
y |
The plain text listen port for the HQ Agent. |
2144 |
| HQ_DB_JDBC_URL |
y |
The JDBC URL the HQ Server uses to access the HQ database. The format is:
jdbc:mysql://db_hostname:port/db
where:
- db_hostname is the hostname of the database server
- port is the MySQL listen port
- db is the database name
|
jdbc:mysql://localhost:3306/hqdb |
| HQ_DB_USER |
y |
Username for database user with full privileges on the HQ database. |
hqadmin |
| HQ_DB_USER_PWORD |
y |
Password for database user with full privileges on the HQ database. |
none |
| HQ_LICENSE_BUCKET_NAME |
n |
Name of the S3 bucket that contains an HQ Server license.
See Configuration Summary - Using an Existing HQ License. |
none |
| HQ_LICENSE_FILENAME |
n |
To use an existing HQ Server license stored on S3, specify the name of the license file. The installer will download the license file and save it in:
/opt/hyperic/server/conf
as
license.xml
See Configuration Summary - Using an Existing HQ License. |
none |
| HQ_LOGIN |
y |
Specifies the username for the HQ user account with permissions to add new inventory.
Credentials are required when agent exchanges certificate information with the HQ Server at first startup. |
hqadmin |
| HQ_LOGIN_PWORD |
y |
Specifies the password for the HQ user account with permissions to add new inventory.
Credentials are required when agent exchanges certificate information with the HQ Server at first startup. |
none |
| HQ_SERVER_DNSNAME |
y |
The hostname or IP address of the HQ Server. |
localhost |
| HQ_SERVER_PORT |
y |
HQ Server plain text listen port, used for communication with HQ Agents and the web user interface. |
7080 |
| HQ_SERVER_SSL_PORT |
y |
HQ Server SSL listen port, used for SSL communication with HQ Agents and the web user interface. |
7443 |
| HQ_UNIDIRECTIONAL_AGENT |
y |
Controls whether communication between the HQ Server and HQ Agent is:
- bidirectional - agent initiates communicates to report metrics and the server initiates communications for control and scheduling data, or
- uni-directional - agent initiates all communications with the server.
|
no |
| HQ_UPGRADE |
y |
Indicates an upgrade, rather than a new installation. |
false |
| HQ_USE_EXISTING_LICENSE |
y |
Set to yes to use an HQ license file that resides on S3. Otherwise, HQ Server will be installed with an an evaluation license.
See Configuration Summary - Using an Existing HQ License. |
no |
| HQ_USE_SSL |
y |
Controls whether the agent to server communication is over SSL using the HQ_SERVER_SSL_PORT. (Server to agent communication is always SSL and cannot be configured otherwise.)
Note: A value of "no" is ignored if HQ_UNIDIRECTIONAL_AGENT=yes.
When unidirectional communications is configured all communications between agent and server is SSL. |
no |
| HQADMIN_EMAIL |
y |
The email address for the default HQ administrator account, hqadmin. HQ-generated status and messages will be sent to this email address. |
none |
| HQADMIN_PWORD |
y |
The password for the HQ Server's hqadmin user. |
none |
| MON_PROCESSES |
n |
A space delimited processes to be monitored by collectd. For example:
\"httpd mysqld\" |
alert |
| OPT_LVM_DRIVES |
n |
Converts the available disks to LVM logical volumes.
Value of "internal" causes all internal drives to be converted. |
internal |
| OPT_LVM_SIZE |
n |
Controls the size of LVM logical volumes, based on the available disk space.
|
max |
| OPT_MYSQL_MAX_CONNECTIONS |
n |
The maximum MySQL connections that can be established across the entire deployment. |
500 |
| OPT_TZINFO |
y |
|
US/Eastern |
| PRIVATE_SSH_KEY |
n |
Specifies a private SSH key. |
none |
| SYSLOG_SERVER |
y |
Hostname of remote server to host syslog-ng logs. |
syslog.rightscale.com |
Configuration Summary - Using an Existing HQ License
By default, the RightScript that installs the HQ Server installs it to use a built-in evaluation license.
If you wish to use an existing HQ license that resides on S3, set the following installation property values:
- AWS_ACCESS_KEY_ID to your AWS access key
- AWS_SECRET_ACCESS_KEY to your AWS access key
- HQ_USE_EXISTING_LICENSE to yes
- HQ_LICENSE_BUCKET_NAME to the name of the S3 bucket that contains your HQ license
- HQ_LICENSE_FILENAME to the name of your HQ license file
Understanding Hyperic-Provided Boot Scripts
Most of the RightScripts in the HQE ServerTemplate are public or premium RightScripts.
This section describes the RightScripts in the HQE ServerTemplate that are Hyperic-provided.
DB MySQL server install v7.1
The DB MySQL server install v7.1 RightScript is a boot script used in the HQE ServerTemplate. It runs the first time you launch the HQE ServerTemplate, but not upon a reboot of the machine instance.
The RightScript:
- Installs MySQL with a new default database. Any pre-existing MySQL configuration artifacts are replaced.
- Configures binlogs to reside in a directory different from the data directory.
Note: DB MySQL server install v7.1 is based on the public RightScale script of the same name. The Hyperic version is identical to the the public version, except for modifications to the "shared" database instance attachments. The public version of the script configuration file attachments assume that MySQL will use TCP sockets for communication with a local application, HQ Server uses JDBC connections that require MySQL be listening on the standard network port.
HQ Server Install
The HQ Server Install RightScript is a boot script used in the HQE ServerTemplate. It installs and configures the HQ Server to work with an existing HQ database. The HQ Server connects to the the HQ database during installation, so the server installation cannot be successfully performed if you do not have an HQ database configured and running. The HQE ServerTemplate installs a local MySQL-hosted HQ database (using the DB MySQL server install v7.1 RightScript) before running the HQ Server Install RightScript. When you run the HQ Server Install RightScript you supply input parameters that provide the JDBC connection and authentication properties that HQ Server needs to connect to the HQ database.
Note: If you are going to use a different database server for the HQ database, or locate the database on a different machine instance, you can use the HQ Server Install RightScript as in your own ServerTemplate. The same script input parameters apply - you would simply supply the connection properties appropriate for the HQ database's location and database server type. The HQ Server Install RightScript performs these steps:
- Check to see if a reboot has just occurred. If so, start the HQ Server, and bypass the installation and configuration steps that follow.
- Checks for existence of a "hyperic" user and group. Create them if they do not exist.
- Downloads the latest version of the HQ Server from Hyperic's download site.
- Install HQ Server to /opt/hyperic/server, and configure HQ Server it using the inputs supplied to the RightScript.
- If the script parameter HQ_USE_EXISTING_LICENSE is set to "yes", download the license file from the S3 bucket specified by the HQ_LICENSE_BUCKET_NAME parameter to /opt/hyperic/server/conf as license.xml.
- Download an HQ Server init script and configures it to automatically start the HQ Server upon reboot of the machine instance. # Start the HQ Server.
HQ Agent Install
The HQ Agent Install RightScript is a boot script used in the HQE ServerTemplate. It installs and configures an HQ Agent for use with an previously installed HQ Server.
Like any other RightScript, you can use he HQ Agent Install RightScript in multiple of ServerTemplates, so as desired, you can add it as a boot script to existing RightScale ServerTemplates you use to manage your deployments.
The HQ Agent Install RightScript performs these steps:
- Check to see if a reboot has just occurred. If so, start the HQ Agent, and bypass the installation and configuration steps that follow.
- Check for the existence of a "hyperic" user and group. Create them if they do not exist.
- Download the latest version of the HQ Agent from Hyperic's download site.
- Install the HQ Agent to /opt/hyperic/agent, and configure it using the inputs supplied to the RightScript.
- Download an HQ Agent init script and configure it to automatically start the HQ Agent upon reboot of the machine instance.
- Start the HQ Agent.
Deploying HQ on RightScale