JBoss Operations Network 2.2

Installation Guide

Installation and Initial Setup of the JBoss Operations Network

Edition 1

Logo

JBoss Documentation

JBoss ON Team

Red Hat JBoss

Legal Notice

Copyright © 2009 Red Hat, Inc..
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.

Abstract

A guide to the download, installation and initial setup of the JBoss Operations Network 2.x product and management agent.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. We need feedback
1. Download JBoss ON
1.1. Red Hat Customers
1.2. Open Source Community
2. JON 2.x Prerequisites
2.1. Operating System
2.2. Java
2.3. Database
2.3.1. PostgresSQL preparation
2.3.2. PostgreSQL quick start installation
2.3.3. Oracle preparation
3. JON Server Installation
3.1. JON High Availability
3.2. Upgrade
3.3. Preparation
3.4. Running the installer
3.4.1. Advanced settings
3.4.2. Database Settings
3.4.3. Installation settings
3.4.4. Server settings
3.5. Install JON Server
3.6. Installing as a boot-time service
3.7. Upgrading the JON Server
3.7.1. Remove obsolete alert definitions
3.7.2. Remove unwanted platforms from inventory
3.7.3. Stop the Server and all Agents
3.7.4. Unzip the new version of the JON Server
3.7.5. Install the new versions of JON Agent Plugin Packs
3.7.6. Setup the JON Server
3.7.7. Install the new version of the JON Agent to each Agent machine
3.7.8. Start up the new Server and Agents
3.7.9. Open the JON GUI
3.8. Startup properties
3.8.1. Database
3.8.2. Server bindings
3.8.3. High Availability bindings
3.8.4. Cluster bindings
3.8.5. RHQ Console transport security
3.8.6. Incoming Agent communication bindings
3.8.7. Incoming Agent communications transport security
3.8.8. Outgoing Agent communications transport security
3.8.9. Embedded RHQ Agent
3.8.10. Outgoing email
3.8.11. Operation invocation default timeout
3.8.12. Concurrency limits
4. JON Agent Installation
4.1. Overview
4.2. Obtaining the Agent
4.3. Agent configuration
4.4. Running on Windows
4.4.1. Running in a Windows Console
4.4.2. Installing and running as a Windows service
4.5. Running on UNIX®
4.5.1. Running in a console
4.5.2. Running as a daemon
4.5.3. Running with init.d
4.6. Command line options
4.7. Running embedded in a JON Server
4.8. Upgrading JON Agents
4.8.1. Upgrade the Server
4.8.2. Install the new Agents
5. Initial auto-discovery and import
5.1. Login
5.2. Installing a license
5.3. Initial auto-discovery and import
6. High Availability configurations
6.1. When should I define an HA configuration?
6.2. HA infrastructure impact
6.2.1. Database impact
6.2.2. Server and Agent endpoints
6.3. When should I use Affinity?
6.3.1. Physical efficiency
6.3.2. Logical efficiency
6.3.3. Warm backup
6.3.4. Affinity behavior
6.4. How do I move to an HA installation?
6.4.1. Moving to HA from JON 2.0.0/2.0.1
6.4.2. Server requirements
6.4.3. Agent requirements
6.5. How do I manage my HA installation?
Index

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. We need feedback

To see all outstanding issues regarding this guide, please visit: https://jira.jboss.org/jira/browse/JOPR
If you find a typographical error in the Installation Guide, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in JIRA: https://jira.jboss.org/jira/browse/JOPR against the component Documentation.
If you do have a suggestion for improving the documentation, try and be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Chapter 1. Download JBoss ON

1.1. Red Hat Customers

JBoss Operations Network 2.0 is available for download from the Customer Support Portal.
There are three types of licenses available.
  • License With Monitoring - this license gives you access to all features of JBoss ON (Monitoring, Inventory, Configuration, Alerts, Control Operations and Software feeds)
  • License Without Monitoring - this license gives you limited access to JBoss ON (Inventory, Configuration, Control Operations and Software Feeds)
  • Evaluation License With Monitoring - this is a 30-day evaluation that gives you access to all features of JBoss ON.

Procedure 1.1. Download JBoss Operations Network 2.0 and the License

  1. Log in to the Customer Support Portal, click on the Software section and look under Operations Network.
    If you do not have access to the Operations Network downloads section contact your sales representative.
  2. Download the following two files to run JBoss ON:
    • The JBoss ON 2.0 Server
    • JBoss ON 2.0 Agent
    Unlike previous releases of JBoss ON, there are no operating system specific versions of the distribution.
  3. Right click on the license and save the file to your desktop. After JBoss ON installation is complete, you will be prompted to upload the license.
    If you do not have access to the correct license, contact your sales representative.

1.2. Open Source Community

Jopr is the open source and unsupported release of the JBoss Operations Network. The RHQ project located at http://support.rhq-project.org/display/RHQ/Home also provides an open source release of JBoss ON. The license file for RHQ and Jopr is either located in the SVN repository, or is generated by the code.

Procedure 1.2. Download Jopr 2.1

  1. Navigate to the Jopr homepage located at http://www.jboss.org/jopr/. Click on the Downloads tab. Click on the Jopr link located under the Management section.
  2. Download the Jopr Server and Jopr Agent.

Chapter 2. JON 2.x Prerequisites

2.1. Operating System

JBoss ON 2.0 Server and Agent are supported on Linux and Windows with the amd64, i686 and ia64 architectures. We support other platforms that support Java 5, but native support must be disabled. This impacts upon the functionality of the JON Agent.

Note

All 64-bit platforms, with the exception of Linux on x64, are only supported by JBoss ON when the OS is in 32-bit compatibility mode.

2.2. Java

JBoss ON 2.0 requires Java 5 in order to run both the Server and the Agent; either a JRE or a JDK can be used. Java 5 must be installed on all machines monitored with an Agent, as well as on the machine hosting the JON Server. Download Java 5 from http://java.sun.com/javase/downloads/index_jdk5.jsp.

Note

JBoss ON 2.1 requires Java 5 or Java 6

Important

GNU libgcj is not supported.

Important

After downloading and installing the latest JRE or JDK 5, ensure that you set the JAVA_HOME environment variable to the installation directory. This environment variable will tells the JON Server and the JON Agent where to locate the JVM.

2.3. Database

In order to run JBoss ON 2.0, an external database must be installed. The supported databases are:
  • Postgres: To download and install Postgres, navigate to the Postgres website.
  • Oracle: To download and install Oracle, navigate to the Oracle website.
After installing the database, make note of the JDBC URL, username and password for the database. This information is required during the JBoss ON Server installation.

2.3.1. PostgresSQL preparation

PostgreSQL version

JBoss ON currently supports versions 8.2.4 or later of PostgreSQL. Earlier 8.2 versions are not recommended. Postgres 8.1 is not supported.

Important information for users of PostgreSQL version 8.4

Users of PostgreSQL 8.4 should ignore the suggested fsm_max_pages setting in the database configuration section below. The FSM pages setting no longer appears in the postgresql.conf file in versions 8.4 and onwards as this is now managed by PostgreSQL itself. If you try to add this setting, PostgreSQL 8.4 will fail to start. See the PostgreSQL 8.4 release notes for more information.

Note

If you do not have PostgreSQL installed, refer to Procedure 2.1, “Download and install PostgreSQL” for steps on how to install PostgreSQL.

postgresql.conf

PostgreSQL requires minor changes to the database configuration. Make the following changes to the postgresql.conf file:
## not necessary  if the database is started with the -i flag
listen_addresses = '*' 

## performance changes  for JBoss ON
shared_buffers = 80MB 		#  default is 32MB 
work_mem = 2048 		#  default is 1MB 
statement_timeout = 30s 	#  default is 0s
checkpoint_segments = 10	#  default is 3
max_fsm_pages = 100000          #  default is 204800
JBoss ON can use up to 55 database connections for the server (prior to JON 2.1, this number was 110). PostgreSQL also allows for connections reserved for administrators. These connections are counted in the pool of max_connections and therefore need to be added to the total number of max_connections. Assuming we have 5 connections reserved for the administrator, edit the postgresql.conf file as follows:
max_connections = 60	   #  default is 100
superuser_reserved_connections = 5 #  default is 3
If you are using the Postgres plugin to monitor this database instance, add one more connection per (logical) database you have setup in PostgreSQL. For further information about this plugin refer to the Postgres Server section of the Managed Resources Guide.

Kernel parameters

Depending on the OS you are using, you may need to adjust some kernel parameters. Refer to http://www.postgresql.org/docs/8.2/interactive/kernel-resources.html for more information.

pg_hba.conf

Update the pg_hba.conf file to allow the newly created role to connect from the machine the JBoss ON Server is installed on, (for example localhost). For details on how to do this refer to http://www.postgresql.org/docs/8.2/interactive/client-authentication.html.
After completing the above step, restart PostgreSQL for the changes to take effect. If no errors are displayed, the database is now ready to support a JBoss ON installation.
For more information on tuning Postgres, see http://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server.
Fixes for "Relation RHQ_Principal does not exist" error
Sometimes the database connection is marked as valid but the install still fails with the Relation RHQ_Principal does not exist error. This occurs when a new database is created by running initdb in a non-C locale through PostgreSQL instances.
To fix this error:
  1. Using a database explorer, create an empty table called RHQ_Principal in the database used for JBoss ON.
  2. Click on Install server
    The installer displays a warning about an existing schema. Overwrite the existing schema as it only consists of one empty table.
Another option is to specify the encoding of the created database as SQL-ASCII at creation time. For example:
initdb -D /my/test/data -E SQL_ASCII --locale en_US.UTF-8
Replace the directory after -D with your target directory for the database.

2.3.2. PostgreSQL quick start installation

Procedure 2.1. Download and install PostgreSQL

  1. Download the latest release of PostgreSQL.
    For UNIX®: Download the source from http://www.postgresql.org/ftp/source/.
    For Windows: Download the installer from http://www.postgresql.org/ftp/binary/.
  2. Install postgres.
    For UNIX: Build and install it as described here: http://www.postgresql.org/docs/8.3/static/install-short.html
    For Windows: Follow the installations instructions described at: http://pginstaller.projects.postgresql.org/
    Postgres can also be installed via a package installer such as yum on Fedora.
  3. You must ensure that the Postgres authentication mechanism is properly configured for the following commands to work. To give all users on the computer access to the database, add the following lines to the data/pg_hba.conf configuration file.
    local all all              trust
    host  all all 127.0.0.1/32 trust
    
    To change the postgres user's password:
    sudo passwd postgres
    
  4. Initialize the database.
    The database must be initialized before starting the server.
    service postgresql initdb
    
  5. Start Postgres.
    For UNIX:
    service postgresql start
    
    For Windows:
    If Postgres is installed as a service then it may already be running. Otherwise:
    net start pgsql-8.3
    
  6. Create a PostgreSQL role named rhqadmin with password rhqadmin. Do this via pgAdmin or from the command line as follows:
    cd <postgres-install-dir>
    createuser -h 127.0.0.1 -p 5432 -U postgres -S -D -R rhqadmin
    
  7. Create a PostgreSQL database named rhq, specifying the rhqadmin role as the owner. Do this via pgAdmin or from the command line as follows:
    cd <postgres-install-dir>
    createdb -h 127.0.0.1 -p 5432 -U postgres -O rhqadmin rhq
    
  8. If you are using this PostgreSQL installation for more than just demonstration or testing purposes, refer to Section 2.3.1, “PostgresSQL preparation” to configure your machine for production use with JON.

2.3.3. Oracle preparation

To use Oracle with JBoss ON, you will need to follow the following three steps. More preparation is required if the advanced Oracle setup will be used. Please refer to Section 2.3.3.3, “Advanced Oracle configuration”.
  1. Create or determine an Oracle instance to be used for the JBoss ON database.
    It is recommended that the Oracle server to be used by JBoss ON runs on its own hardware. Install Oracle on the machine to be used, and create a database. You can choose any name for the database. The Oracle instance is now ready for the next step.
  2. Create a user that JBoss ON will use to access Oracle.
    There are several ways to create a user in Oracle. One way is with SQL*Plus. First, log into the Oracle instance via as the system user with SQL*Plus, then issue the CREATE USER command:
    SQL> CREATE USER jon IDENTIFIED BY jon;
    
    Create a user named jon with a password of jon.
  3. Grant the required permissions to the Oracle user.
    The Oracle user must possess the connect and resource roles. This can be easily done in SQL*Plus with the GRANT command:
    SQL> GRANT connect, resource TO jon;
    
  4. Make sure DB_BLOCK_SIZE is at least 8k
    SQL> show parameter db_block_size;
    NAME                                 TYPE        VALUE
    ------------------------------------ ----------- ------------------------------
    db_block_size                        integer     8192
    
Oracle is now ready to accept a JBoss ON installation.

2.3.3.1. JON user requirements for XA

JBoss ON uses internally two phase commit for some of its database actions. To be able to recover from two phase commit failures, it is required to grant special privileges to the 'jon' datasource user . If you do not do this, XAException.XAER_RMERR errors will occur. The privileges you need to grant include:
GRANT SELECT ON sys.dba_pending_transactions TO jon;
GRANT SELECT ON sys.pending_trans$ TO jon;
GRANT SELECT ON sys.dba_2pc_pending TO jon;
GRANT EXECUTE ON sys.dbms_system TO jon;
GRANT SELECT ON v$xatrans$ TO jon;

2.3.3.2. Sessions and Processes

Currently the recommended algorithm for determining the maximum number of Oracle processes (as kept in v$resource_limit) which JON 2.1 should use is the following:
Take the maximum of:
  1. 1.5 * total number of JON Agents in the environment, and;
  2. 60 * total number of JON Servers in the environment
then add 40 if you are also using Oracle Enterprise Manager (EM).
For example if you had 100 JON Agents and 2 JON Servers, and you were using Oracle EM, you would have:
  1. 1.5 * 100 = 150
  2. 60 * 2 = 120
So the max is 150, add 40 to give 190 processes. The number of sessions (as kept in v$resource_limit) should be 1.1 * number of processes, so in this example a maximum of 209 sessions should be sufficient. These settings should prevent you from seeing errors such as ORA-00018: maximum number of sessions exceeded.

2.3.3.3. Advanced Oracle configuration

There are optional configurations that can help Oracle perform effectively with large JBoss ON environments. This configuration is not necessary for small to medium environments. An example of an environment where this type of configuration would help performance is an environment with hundreds of JON Agents.

Procedure 2.2. Advanced Oracle configuration

  1. Create a new database using the Oracle Database Configuration Assistant. Select New Database (Includes datafiles = No). Decline to install the Example Schemas to save space.
  2. If an advanced configuration is being used, Oracle should be installed on a dedicated host. So select Typical Memory configuration. Select OLTP as the type of database sizing to use. Allocate the highest percentage of system resources that you can afford. This should be set between 70-90%, ideally in the higher range.

    Warning

    Locally manage all tablespaces.
    Redo Logging should be turned OFF for all tablespaces by specifying the NOLOGGING clause when creating the tablespaces. In fact, Redo Logging should be turned off for all the tablespaces in the same database. This is a major bottleneck for the database, and, in our scenario, we need high throughput, which comes at the expense of recoverability. In other words, export data and back it up when you want to recover.
  3. Create the JBoss ON user.
    CREATE USER jon IDENTIFIED BY jon;
    
  4. Grant permissions to the new user.
    GRANT CONNECT, RESOURCE TO jon;
    

Chapter 3. JON Server Installation

This chapter describes the JBoss Operations Network 2.2 Server installation process. We recommended that you also read the JON Server Guide for more information about the JON Server.

3.1. JON High Availability

Starting with version 2.1.0 JON supports a multi-server environment. Running multiple JON servers provides a High Availability (HA) environment. A multi-server HA environment allows JON Agent failover and distribution of load.
HA is integrated into the standard installation process. There is no separate HA installer. The important points to understand are:
  • Multiple Servers can be configured against the same database.
  • Each Server requires a unique name for identification.
  • Each server requires a publicly accessible endpoint (public to the population of Agents).
Upgrading an existing server, or installing a new server will result in a single-server environment. To add more servers to the HA "Server Cloud" run the installer on the target server machines, each time configuring for the same database, endpoint information and selecting a unique Server name. Servers can be added and removed from the cloud at any point in time.
To learn more about whether an HA environment is appropriate for your needs, and how to move to HA from an existing JON installation, see Chapter 6, High Availability configurations.

3.2. Upgrade

Follow the JON Server upgrade instructions if you are upgrading from an earlier JON 2.x GA release. Failure to do so could result in a loss of inventory or metric data.

Important

Upgrade is not supported for version JON 1.x or any other version of JON prior to JON 2.0.0.GA.

3.3. Preparation

Java and Database prerequisites
Before running the installer, ensure you have installed a supported external database and JDK 5 or JDK 6. For instructions on how to install a JDK refer to Section 2.2, “Java”.
The JDBC URL, database username and password are required during the installation process.
Synchronized machine clocks
All JBoss ON Servers and Agents must have synchronized clocks. Clock variations will cause issues in resource synchronization and availabilities, metric measurements, graphing, and importing resources into inventory. Refer to http://www.ntp.org/ for information on installing and configuring NTP to ensure your clocks are synchronized.
DNS setup
DNS forward and reverse mapping entries must be present for all hosts involved in monitoring. This includes all JBoss ON Servers and all machines running Agents.
Monitoring the JON Server
The JBoss ON server is capable of monitoring itself. If you intend to do this, choose one of the following two options:
  • Install a standalone agent like you would on any other machine in the network.
  • Use the embedded agent that runs inside the JON Server.
Using the embedded agent frees you from having to install and maintain a separate, standalone agent. The embedded agent starts when the JON Server starts and remains running as long as the JON Server is running. If you wish to use the embedded agent, indicate in the installer to start the Agent along with the Server. Refer to the Embedded JON Agent section in the JON Agent Guide for more information.

Important

The embedded agent is for monitoring the JBoss ON Server itself. If you have another JBoss Application Server instance that you would like to monitor on the same machine as the JON Server, select the standalone agent option.

3.4. Running the installer

Unlike JBoss ON 1.x, there is no longer a standalone installer. You should have a JON Server distribution file (jon-server-2.X.zip).

Procedure 3.1. Run the installer

  1. Unzip the Server distribution to the directory within which it will be executed from. For example:
    cd /opt
    unzip jon-server-2.2.0.GA.zip
    
    The directory structure within the zipfile ensures that the Server has a version-specific installation directory name. For example, the above commands will create a directory named /opt/jon-server-2.2.0.GA. The /opt/jon-server-2.2.0.GA directory should not exist prior to the unzip operation.

    Windows installation

    Do not install the JON Server into a directory with a path longer than 19 characters (e.g. use C:\Program Files\ rather than C:\Documents and Settings\myusername\ ). Excessively long pathnames may cause errors during execution of the server.
  2. Install Agent Plugin Packs:
    The JON server distribution includes the core agent plugins it requires for operation. Additional plugins are delivered via plugin packs specific to the needs of the installation (for example, EWS, EAP, SOA-P). Each plugin pack contains one or more plugins in a zip file. The plugin packs can be unzipped anywhere, the following example places them at the top of the server distribution. For each plugin pack:
    					
    cd [install-dir]
    unzip jon-plugin-pack-<name>-2.2.0.GA.zip
    
    Follow the instructions in the README.txt supplied with the plugin pack to install the agent plugins.

    Note

    In an HA environment it is only necessary to install the plugin packs to one HA server. Once installed all of the HA servers will have access to the agent plugins.
  3. Run the JON Server:
    For UNIX, execute the following from the command line:
    cd [install-dir]/bin
    ./rhq-server.sh start
    
    For Windows, execute the following from the command line:
    cd [install-dir]\bin
    rhq-server-console.bat start
    
  4. Point your browser to http://localhost:7080/. This will display the JON Server Installer web application.
  5. Clicking the Click here to continue the installation link brings you to the main installer page.

3.4.1. Advanced settings

By default the installer displays only the typical settings required for installation. If you have advanced requirements, click the Show Advanced Settings check box to display the advanced settings in the next two sections.

Important

Toggling the Show Advanced Settings check box initializes the values for displayed settings. Be careful not to toggle this setting after entering your installation data.

3.4.2. Database Settings

The main installer page appears somewhat differently depending on the database settings. You must configure the database for this server installation. The database settings area of the installer looks like this:

Procedure 3.2. Configure the database

  1. Set your database connection properties by updating the default values as necessary.
    If you have installed your database server but not yet created the necessary database or role for use with JON, click on the Create Database button. Do not perform this step if you have already created the RHQ database and rhqadmin role.
    On Oracle, if you select the 'overwrite tables' option but there is nothing to overwrite (Because this is a first-time installation), you may see an error message in your server log. These can be safely ignored: ERROR [DBSetup] {DBSetup.dropped-table-error}Failed to drop table [SOME_RHQ_TABLE] or one of its sequences. Cause: ErrorCode=[2289]; SQLState=[42000]; Message=[ORA-02289: sequence does not exist]; Type=[java.sql.SQLException]
  2. Test your database connection by clicking the Test Connection button. If this test fails check your connection properties and ensure your database server is running.
  3. Existing Database options: If an existing JON Server schema is discovered (e.g. from a previous JON installation) the installer will give you the choice of either upgrading it to the latest schema version or overwriting it and losing all existing data. Take the default (Keep (maintain existing data)) unless you are confident you want to lose all previous JON data. If any errors occur during the DB schema installation, check the logs.

Important

The JBoss ON 1.x database schema is incompatible with the JBoss ON 2.0 schema and you cannot upgrade a 1.x schema to a 2.0 schema.

3.4.3. Installation settings

The installation settings page will differ slightly depending on whether a server has previously been installed for the configured database. If this is a new database or an upgrade from a version prior to 2.1.0, the installer page will look like this:
If this is an upgrade, or reinstallation, of a 2.1.0 server, or the installation of a new server into a High Availability cloud, the installer page will look like this:
The only difference is an additional drop down list of existing registered servers.
Registered Servers
The Registered Servers drop down list does not appear unless a 2.1.0 server has been previously installed to the configured database.
This drop down displays the servers currently registered for the configured database. For single server environments, only one entry is displayed. For High Availability environments, the list contains an entry for each server in the server cloud. When upgrading or reinstalling an existing 2.1.0 server, select that server from the list.
Select the appropriate server from the list. The installation settings configured for that server are now displayed; ensure the values are correct.
Server Name
The Server Name uniquely identifies the JON Server being installed. It defaults to the resolved host name of the machine but can be set to a different value if necessary.
Selecting a Registered Server from the drop down and then modifying the Server Name will result in a new Server registration. The installer treats this as an additional server being added to the HA Server Cloud. When adding a new server it is not necessary to select from the drop down list.

Server Name

Avoid using generic names such as server, localhost or s1 in favor of explicit names that easily identify the JON Server.
Public server endpoint
The remaining fields define the public server endpoint information for the JON Server-JON Agent communication. After installation, you can update the Server Endpoint information via the JON GUI Administration pages.

Important

The Server Endpoint Address must be public so that all JON Agents are able to resolve the supplied value. This is particularly important in High Availability (multi-Server) environments where JON Agents are connecting to various JON Servers in the cloud.

3.4.4. Server settings

The settings displayed depend on whether the Show Advanced Settings option is enabled.
Standard settings
The standard installation process contains the typical settings required to install JON. The default values are usually appropriate for most standard and advanced settings. If necessary, the server settings can be modified at a later time by editing the jon-server-home/bin/rhq-server.properties file.
If you bind the server to an address other than 0.0.0.0 you must also edit the jon-server-home/bin/rhq-server.properties file. Enable the java.rmi.server.hostname property and set it to the same address to which the server is bound.
Ensure your SMTP settings are set correctly to enable e-mail notification of alerts. You can update these settings if your SMTP server is not on the same machine as the JON server.
Set the Embedded Agent Enabled field to No if you are not monitoring the JON Server, or Yes if you are using the standalone agent.
Advanced settings
All advanced settings are explained in detail on the Startup Properties page.

Important

If you change any startup properties that require a restart, restart the server immediately after the installation so the settings can take effect. The server will not correctly function until this is done.

3.5. Install JON Server

Click on Install JON Server. An intermediate page is displayed during the installation. Once the installation has completed the message Starting up, please wait... is displayed. Click the Done! Click here to get started. link to begin using your JON server.

Important

Some browsers such as Safari and Opera cannot display the login page, but instead show the last page. If this happens, press the refresh button on your browser and click on the link again.

Install errors on Postgres

There have been some cases where the installation of PostgreSQL failed with an error "Relation RHQ_Principal" does not exist. Refer to Section 2.3.1, “PostgresSQL preparation” for a workaround.

3.6. Installing as a boot-time service

You can install the JON Server to run when your computer boots up. On Windows, this means installing the JON Server to start as a Windows Service. On UNIX, it means installing the JON Server startup script as an init.d startup script. To install as a boot-time service on either Windows or UNIX, refer to the Running the JON Server section in the JON Server Guide.

3.7. Upgrading the JON Server

Supported upgrades

Upgrade is not supported for version JON 1.x or any other version of JON prior to JON 2.0.0.GA. Perform a fresh JON installation if moving from a pre-JON 2.0.0.GA version.

Loss of data

Loss of minimal monitoring data is inevitable given the down-time involved in shutting down instances of the Agents during the upgrade process. If you have a Resource in inventory corresponding to the JON Server itself, all monitoring data for that resource will be lost.
Follow the steps outlined below to upgrade your JON Server:

3.7.1. Remove obsolete alert definitions

Important

Applies to JON 2.0.0 only
Before upgrading JON you must remove alert definitions with conditions for obsolete metrics. This is because alert definitions are not easily removed after the upgrade. Remove alert definitions, including alert templates, for the following metrics:

Table 3.1. Metrics

ResourceType
Metric
Postgres Server
User Time
Kernel Time
Physical Memory
Virtual Memory

3.7.2. Remove unwanted platforms from inventory

Remove "out of service" platform resources prior to the upgrade.

3.7.3. Stop the Server and all Agents

The JON Server must be upgraded before any Agents are upgraded. Shut down all agents and wait until all agents show red availability in the GUI before shutting down the server.
  1. Stop all of the JON Agents
  2. Stop the JON Server after all agents are down
Do not stop the JON Database.

3.7.4. Unzip the new version of the JON Server

Unzip the Server distribution to the directory within which it will be executed from.
cd /opt 
unzip jon-server-2.2.0.GA.zip

Important

Do not copy the new server installation on top of a previous server installation.
The directory structure within the zipfile ensures that the new Server has a version-specific installation directory name. The above commands create a directory named /opt/jon-server-2.2.0.GA.
If you have made modifications to your original Server's Startup Properties (e.g. enabling SSL, SMTP), either when first installing or through the ./bin/rhq-server.properties file, merge these changes into the new Server's rhq-server.properties file.

Merging Startup Properties

If you prefer not to edit the new Server's ./bin/rhq-server.properties file, you can merge your changed values during installation via the Advanced Settings checkbox.
If you are running the Server on Windows and installed the original Server as a Windows service, uninstall the Windows service:
cd <old-server-install-dir>/bin
./rhq-server.bat remove
Install a Windows service for the new Server:
cd <new-server-install-dir>/bin
./rhq-server.bat install

3.7.5. Install the new versions of JON Agent Plugin Packs

The JON server distribution includes the core agent plugins it requires for operation. Additional plugins are delivered via plugin packs specific to the needs of the installation (for example, EWS, EAP, SOA-P). Each plugin pack contains one or more plugins in a zip file. The plugin packs can be unzipped anywhere, the following example places them at the top of the server distribution. For each plugin pack:
cd [install-dir]
unzip jon-plugin-pack-<name>-2.2.0.GA.zip
Follow the instructions in the README.txt supplied with the plugin pack to install the agent plugins.

Note

In an HA environment it is only necessary to install the plugin packs to one HA server. Once installed all of the HA servers will have access to the agent plugins.

3.7.6. Setup the JON Server

Backup Your Database

We recommend backing up your database prior to proceeding. If problems arise during the database upgrade, having a backup will allow you to restore to your previous state.

Locate Your License

Register your license with the new version of JON. Your existing license file is located in old-server-install-dir/jbossas/server/default/deploy/rhq.ear/license/license.xml. Copy this to a safe location and reuse it during the upgrade process.
Follow the instructions in Chapter 3, JON Server Installation to install the Server. Once you have entered your database connection info, the installer should detect that there is an existing JON database and display the following prompt:
A database schema already exists. What do you want to do?
Choose the default, Keep (maintain existing data). Do not choose Overwrite (lose existing data), otherwise all of the existing inventory, metric, and history data from your original JON installation will be lost.

Important

During the upgrade you may see error messages in the console similar to the following. These can be safely ignored.
14:19:36,540 ERROR [ClientCommandSenderTask] {ClientCommandSenderTask.send-failed}Failed to send
command [Command: type=[remotepojo]; cmd-in-response=[ false]; config=[{rhq.timeout=1000, 
rhq.send-throttle= true}]; params=[{targetInterfaceName=org.rhq.enterprise.communications.Ping, 
invocation=NameBasedInvocation[ping]}]]. Cause: org.jboss.remoting.CannotConnectException:[.....]

3.7.7. Install the new version of the JON Agent to each Agent machine

Follow the Agent upgrade instructions in Section 4.8, “Upgrading JON Agents”.

3.7.8. Start up the new Server and Agents

Start up the new Server and Agents

3.7.9. Open the JON GUI

  1. If a JON JBossAS Server Resource corresponding to your old Server installation is in the inventory, remove it from the inventory.
  2. (Optional) Import the new JON JBossAS Server Resource into the inventory. Configure its metric schedules and alert definitions.

3.8. Startup properties

When the JON Server starts, it will load in the properties defined in the bin/rhq-server.properties file. These startup properties provide settings that are necessary to bootstrap the JON Server (things like what host address to bind the web application to, or what ports the server will listen to for incoming agent requests). Note that these startup properties are different than the values stored in the database and modifiable via the JON Console's Administration page.
Startup properties are set when you first run the installer using the advanced installation checkbox". Refer to Section 3.4, “Running the installer”.
The startup parameters are documented below.

3.8.1. Database

These properties define the RHQ Server's database and how it can connect to it.

Database type

rhq.server.database.type-mapping
Defines the vendor of your database that will be used as RHQ's backend persistence store. The only supported values are PostgreSQL or Oracle.

Database connection URL

rhq.server.database.connection-url
The JDBC URL that the RHQ Server will use when connecting to the database. An example is jdbc:postgresql://localhost:5432/rhq or jdbc:oracle:oci:@localhost:1521:orcl.

Database JDBC driver class

rhq.server.database.driver-class
The fully qualified class name of the JDBC driver that the RHQ Server will use to communicate with the database. An example is org.postgresql.Driver or com.oracle.driver.Driver.

Database XA DataSource class

rhq.server.database.xa-datasource-class
The fully qualified class name of the JDBC driver that the RHQ Server will use to communicate with the database. An example is org.postgresql.Driver or com.oracle.driver.Driver.

Database user name

rhq.server.database.user-name
The name of the user that the RHQ Server will use when logging into the database.

Database password

rhq.server.database.password
The password of the database user that is used by the RHQ Server when logging into the database.

Database server name

rhq.server.database.server-name
The server name where the database is found. This must match the server in the connection URL. Currently only used when connecting to PostgreSQL.

Database the port

rhq.server.database.port
The port on which the database is listening. This must match the port in the connection URL. Currently only used when connecting to PostgreSQL.

Database DB name

rhq.server.database.db-name
The name of the database. This must match the name found in the connection URL. Currently only used when connecting to PostgreSQL.

3.8.2. Server bindings

These settings bind the RHQ Server to specific IP addresses and ports. You may need to change these properties if you have firewall issues that require specific addresses and ports to be used.

Server bind address

jboss.bind.address
The RHQ GUI Console (among other services) bind to this IP address. This is the host in the RHQ Console URLs; e.g. the myhost in http://myhost:7080.

Prior to JON 2.1

If you change this value while the Incoming Agent Communications Transport parameter (rhq.communications.connector.transport) is set to servlet, you must also change the value of the Incoming Agent Communications Bind Address parameter (rhq.communications.connector.bind-address) to match this address.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

HTTP the port

rhq.server.startup.web.http.port
The RHQ GUI Console listens to this port for unsecured HTTP requests coming in. This is the port number in the RHQ Console URLs; e.g. the 7080 in http://localhost:7080. This is also the unsecure port used when defining the server's HA endpoint.

Prior to 2.1

If you change this value while your Incoming Agent Communications Transport (rhq.communications.connector.transport) is set to servlet, you must change the value of the Incoming Agent Communications The port (rhq.communications.connector.transport) parameter to match this port number.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Secure HTTPS the port

rhq.server.startup.web.https.port
The RHQ GUI Console listens to this port for secured HTTPS requests coming in. This is the port number in the RHQ Console URLs; e.g. the 7443 in http://localhost:7443. This is also the secure port used when defining the server's HA endpoint.

Prior to 2.1

If you change this value, and your Incoming Agent Communications Transport (rhq.communications.connector.transport) is set to sslservlet, you must change the value of the Incoming Agent Communications The port (rhq.communications.connector.transport) parameter to match this port number.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Web service the port

rhq.server.startup.webservice.port
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Naming service the port

rhq.server.startup.namingservice.port
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Naming Service RMI the port

rhq.server.startup.namingservice.rmiport
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

JRMP Invoker RMI The port

rhq.server.startup.jrmpinvoker.rmiport
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Pooled Invoker RMI The port

rhq.server.startup.pooledinvoker.rmiport
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

AJP Port

rhq.server.startup.ajp.port
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Unified invoker port

rhq.server.startup.unifiedinvoker.port
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Aspect delpoyer port

rhq.server.startup.aspectdeployer.bind-port
The port used by an internal service.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

3.8.3. High Availability bindings

Since 2.1, these are settings that configure the RHQ Server to identify itself to, and communicate with, other RHQ Servers or server-side components. They are required for a single-server installation and also facilitate membership in a multi-server, High Availability, RHQ Server Cloud. Note that these settings can not be changed in the rhq-server.properties files but rather are managed via the RHQ GUI post-installation.

3.8.3.1. Server name

rhq.server.high-availability.name
Each RHQ Server is identified by a unique name. The installer will default this value to the localhost name although it does not need to be a resolvable machine name. The only restriction is that all server names be unique in the RHQ server cloud.
Although present in rhq-server.properties this setting is managed only via the RHQ HA Administration Console.

3.8.3.2. Server public address

The public server endpoint IP address. This is the address that must be recognized by all agents needing access to this server. The installer will default this value to the localhost address.
This setting is managed only via the RHQ RHQ HA Administration Console.
The server endpoint address is used in conjunction with the servlet and sslservlet transport over either the HTTP Port (rhq.server.startup.web.http.port) or the Secure HTTPS Port (rhq.server.startup.web.https.port) to provide High Availability server endpoints to agents..

3.8.3.3. Server Affinity Group

RHQ performs load balancing and agent fail-over when operating with a multi-server configuration (RHQ Server Cloud). In certain situations, regional datacenters for example, it may make sense for particular RHQ Agents to prefer (have affinity for) certain servers. RHQ Agents assigned to a particular Affinity Group will prefer RHQ Servers assigned to the same Affinity Group. Note that the pairing is not strict and RHQ can service any agent with any server depending on resource load and availability. By default a server is not assigned an Affinity Group. For larger Server Clouds Affinity Group management is performed via the RHQ GUI.

3.8.3.4. Registered servers

When installing or upgrading the RHQ server against an existing database the installer will present a list of previously installed RHQ Server Names. These Server Names represent the servers in the current RHQ Server Cloud. If you are performing an upgrade, or for some reason are re-installing an RHQ Server select the appropriate server name from the list. The installer will populate the other High Availability settings as previously configured for the server. The server name should not be changed (otherwise the installer will treat this as a new server installation) but the other HA settings can be updated at this time.
If you manually enter a new server name it is installed as a new server. If no other servers exist, this is called a single-server configuration. Otherwise, the new server is added to the existing High Availability Server Cloud.
This list is not presented if the database is new or there are no previously installed servers.

3.8.4. Cluster bindings

Prior to 2.1, these are settings that configure the RHQ Server to participate in a RHQ Server cluster setup. You will normally only need to change these if you have firewall issues that require specific addresses and ports to be used. For low-level details about these JBossAS cluster settings, see http://www.jboss.org/community/docs/DOC-12460.
If you change any of these cluster binding values, you must shutdown and restart the RHQ Server in order for the changes to take effect.

Partition name

jboss.partition.name
The name of the RHQ Server cluster partition. All RHQ Servers participating in the cluster must use the same name.

Partition bind address

jgroups.bind_addr
The bind address used by JGroups to support clustering communications. If you have a multi-homed machine, set this to the appropriate NIC IP address. If you do not plan on running the RHQ Server as part of a cluster of RHQ Servers, you may set this to 127.0.0.1 so it binds only to the local loopback interface.

Partition UDP multicast mroup IP address

jgroups.udp.mcast_addr
The multicast address used by the JGroups channel to broadcast messages to members of the cluster.

Partition UDP multicast the port

jboss.hapartition.mcast_port
Used by an internal clustering service.

Partition UDP EJB3 entity cache multicast the port

jboss.ejb3entitypartition.mcast_port
Used by an internal clustering service to support EJB3 entity caching.

Partition UDP alert cache multicast the port

jboss.alertcachepartition.mcast_port
Used by an internal clustering service to support alert caching.

Partition UDP loopback

rhq.server.startup.partition.udpLoopback
On UNIX, this can typically be left as false. On Windows machines, because of the media sense feature being broken with multicast (even after disabling media sense), set this UDP loopback setting to true.

HA JNDI the port

rhq.server.startup.hajndi.port
Used by an internal service to define the port on which the HA-JNDI stub is made available.

HA JNDI RMI the port

rhq.server.startup.hajndi.rmiport
Used by an internal service - to be used by the HA-JNDI service once bound.

HA JNDI auto discovery group the port

rhq.server.startup.hajndi.autodiscoverygroupport
Multicast port used for cluster auto-discovery.

HA JRMP invoker RMI the port

rhq.server.startup.hajrmpinvoker.rmiport
Used by an internal service.

HA pooled invoker the port

rhq.server.startup.hapooledinvoker.port
Used by an internal service.

JGroups UDP IP time to live

jgroups.udp.ip_ttl
Used by JGroups as a performance tuning parameter. See the JBossAS and JGroups documentation on the UDP protocol's "ip_ttl" setting for more information.

3.8.5. RHQ Console transport security

RHQ Console Keystore

rhq.server.startup.keystore.filename
The RHQ Console can accept browser requests over HTTPS. If you want to authenticate your RHQ Console to remote browsers, you need to put an SSL certificate in a keystore file. This setting points to the location of your keystore file. Note that this filename must be a relative file path relative to the <RHQ Server Install Dir>/jbossas/server/default/conf directory. The RHQ Server ships with a self-signed certificate in a default keystore file.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

RHQ Console keystore password

rhq.server.startup.keystore.password
The password of the keystore file so the RHQ Console can access the keystore file in order to be able to serve the certificate to browser clients.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

RHQ Console SSL protocol

rhq.server.startup.keystore.sslprotocol
The protocol that browser clients should use to communicate with the RHQ Console.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

3.8.6. Incoming Agent communication bindings

These settings define how the RHQ Server will accept incoming messages from the RHQ Agents. See Communications Configuration for more information on setting up the RHQ Server's agent communications subsystem.

Incoming Agent communications transport

rhq.communications.connector.transport
Defines how the RHQ Agents need to transport messages to the RHQ Server. Typical values are servlet, and sslservlet.

Important

Any other transports such as "socket" and "sslsocket" have not been tested for functionality and performance and therefore are not supported.
If you elect to use servlet or sslservlet (which are the only two currently supported transports), it means the agent requests will go through the RHQ Server web application layer (i.e. the secure Tomcat Connector).
If you elect to use sslservlet, not only will agent requests route through the web application layer, but it also is secured though the secure Tomcat Connector as well. What this means is that the keystore used for incoming agent message authentication will be the same as that which you set up as described in Section 3.8.5, “RHQ Console transport security”.
Note that this transport setting does not restrict agents from only going over that particular transport. By default, the RHQ Server always deploys the comm connector that allows for both servlet and sslservlet traffic. What this means is, ultimately, it is the agent that decides what transport is actually used when it sends messages to the server. If the server has its transport set to servlet, but the agent is configured to talk to the server via sslservlet, the messages the agent sends will be via sslservlet.

Incoming Agent communications bind address

rhq.communications.connector.bind-address
This is the address that gets placed in the server's JBoss/Remoting locator URL.
Prior to 2.1: the address that the RHQ Server will bind its connector to so it can receive RHQ Agent messages.
Since 2.1: it defines the endpoint that the RHQ Server will bind its connector to; but in the way RHQ uses it, it also represents the public endpoint address that all agents can use to connect to the server.

Incoming Agent communications the port

rhq.communications.connector.bind-port
Prior to 2.1: The port that the RHQ Server will listen to in order to accept RHQ Agent messages.
Since 2.1: it defines the endpoint that the RHQ Server will bind its connector to; but in the way RHQ uses it, it also represents the public endpoint address that all agents can use to connect to the server.
This will be hidden from view in the installer though still appears in the rhq-server.properties file. It can be left blank - in that case, the server will set this to either the HTTP port or HTTPS port depending on the transport you configured the server with (i.e. servlet or sslservlet). This port will be used in the JBoss/Remoting locator URL of the server and represents the public port that all agents can use to connect to the server. However, the agents are free to go over the HTTP or HTTPS port depending if the agent wants to use servlet or sslservlet.

Incoming Agent communications transport parameters

rhq.communications.connector.transport-params
Defines additional transport parameters the RHQ Server will set on its connector that will accept incoming messages from the RHQ Agents. See Communications Configuration - TransportParameters for full details on transport parameters.

Agent multicast detector enabled

rhq.communications.multicast-detector.enabled
If true, the RHQ Server will attempt to auto-detect RHQ Agents coming online and going offline using multicast detection. Your network must support multicast traffic for this to work.

Agent multicast detector bind address

rhq.communications.multicast-detector.bind-address
The address that the multicast detector will directly bind to. This is not needed nor used if you have not enabled multicast detection.

Agent multicast detector multicast address

rhq.communications.multicast-detector.multicast-address
The address that the multicast detector will broadcast messages to. This is not needed nor used if you have not enabled multicast detection.

Agent multicast detector the port

rhq.communications.multicast-detector.port
The port that the multicast detector will broadcast messages to. This is not needed nor used if you have not enabled multicast detection.

3.8.7. Incoming Agent communications transport security

These settings define how the server will secure its communications channel when accepting incoming messages from the RHQ Agents. See Securing Communications for more detailed information on setting up the Server-Agent communications security.
Note that if you are not using an Incoming Agent Communications Transport (rhq.communications.connector.transport), these settings are not used.
The other half of the communications channel (that is, the outgoing side) has analogous settings. You can share keystores, truststores and other settings for both sides, or you can customize your communications for either side independently.

Incoming secure socket protocol

rhq.communications.connector.security.secure-socket-protocol
The secure protocol that agents must use when communicating with this RHQ Server.

Incoming keystore file

rhq.communications.connector.security.keystore.file
The keystore file that contains a certificate that authenticates the RHQ Server to the agents.

Incoming keystore algorithm

rhq.communications.connector.security.keystore.algorithm

Incoming keystore type

rhq.communications.connector.security.keystore.type
The file format of the keystore.

Incoming keystore password

rhq.communications.connector.security.keystore.password
The password that is used to gain access to the keystore file.

Incoming keystore key password

rhq.communications.connector.security.keystore.key-password
The password that is used to gain access to the key inside the keystore.

Incoming keystore alias

rhq.communications.connector.security.keystore.alias
The alias that identifies the RHQ Server's key within its keystore.

Incoming truststore file

rhq.communications.connector.security.truststore.file
The truststore file that contains certificates that this RHQ Server trusts. If you want or need the RHQ Server to authenticate RHQ Agents, you must set this; otherwise it is not needed. This truststore will contain certificates for all RHQ Agents that need to communicate with this RHQ Server. Refer to the Incoming Client Authentication Mode.

Incoming truststore algorithm

rhq.communications.connector.security.truststore.file

Incoming truststore type

rhq.communications.connector.security.truststore.type
The file format of the truststore file.

Incoming truststore password

rhq.communications.connector.security.truststore.type
The password that is used to gain access to the truststore file.

Incoming client authentication mode

rhq.communications.connector.security.client-auth-mode
Indicates if you want or need the RHQ Server to authenticate the RHQ Agents that are sending it messages. If you are using a secured transport but do not have trusted certificates for all of your RHQ Agents in a truststore, you must set this to none.
Valid values are: none, want or need

3.8.8. Outgoing Agent communications transport security

These settings define how the server will secure its communications channel when sending outgoing messages to the RHQ Agents. Refer to Securing Communications in the JON Agent Guide for more detailed information on setting up the Server-Agent communications security.
The other half of the communications channel (that is, the incoming side) has analogous settings. You can share keystores, truststores and other settings for both sides, or you can customize your communications for either side independently.
Note that if your RHQ Agents are not using a secure transport, these settings are not used.

Outgoing secure socket protocol

rhq.server.client.security.secure-socket-protocol
The secure protocol that the server must use when sending outgoing messages to agents. The agents must be expecting to use this protocol for messages that it receives.

Outgoing keystore file

rhq.server.client.security.keystore.file

Outgoing keystore algorithm

rhq.server.client.security.keystore.algorithm

Outgoing keystore type

rhq.server.client.security.keystore.type

Outgoing keystore password

rhq.server.client.security.keystore.password

Outgoing keystore key password

rhq.server.client.security.keystore.key-password

Outgoing keystore alias

rhq.server.client.security.keystore.alias

Outgoing truststore file

rhq.server.client.security.truststore.file

Outgoing truststore algorithm

rhq.server.client.security.truststore.algorithm

Outgoing truststore type

rhq.server.client.security.truststore.type

Outgoing truststore password

rhq.server.client.security.truststore.password

Outgoing Server authentication mode enabled

rhq.server.client.security.server-auth-mode-enabled
Indicates if you want or need the RHQ Server to authenticate the RHQ Agents that are sending it messages. If you are using a secured transport but do not have trusted certificates for all of your RHQ Agents in a truststore, you must set this to none.

3.8.9. Embedded RHQ Agent

You have the option of installing the RHQ Agent embedded directly in the RHQ Server, as opposed to installing and running a separate process for the RHQ Agent. The embedded agent operates just like its standalone counterpart, the only difference is it is running in the same Java virtual machine as the RHQ Server. Note that if you do this, you will not have the option of a command line interface to the agent, as you would have with a standalone RHQ Agent.

Embedded RHQ Agent Enabled

rhq.server.embedded-agent.enabled
Set this to true if you want to run the embedded RHQ Agent inside this RHQ Server. Set this to false if you want to run the RHQ Agent as a separate process or if you do not want a RHQ Agent running on the same machine as your RHQ Server.

Embedded RHQ Agent name

rhq.server.embedded-agent.name
The name that the embedded RHQ Agent will register itself as.

Embedded RHQ Agent disable native system

rhq.server.embedded-agent.disable-native-system
The RHQ Agent has JNI native components that is used to perform some tasks. If you are having problems with the native components, you can completely disable their usage by setting this to true. Typically, you can leave this as false under normal conditions.
If you change this value, you must shutdown and restart the RHQ Server in order for the change to take effect.

Embedded RHQ Agent reset configuration

rhq.server.embedded-agent.reset-configuration
If this is set to true, the embedded agent will reset its configuration at startup. Resetting the configuration means it will clear out any configuration settings currently persisted in the preferences store and reload the configuration from its built-in configuration file (i.e. the defaults it shipped with out-of-box). If false, the embedded agent will retain the configuration it had when it last was running - which may be different from its original configuration if a user changed those configuration settings from the RHQ Console. Note that this setting will not effect those configuration settings that are explicitly defined in or are derived from the rhq-server.properties startup properties file. This includes things like the Embedded RHQ Agent Disable Native System (rhq.server.embedded-agent.disable-native-system) and Incoming Agent Communications Transport (rhq.communications.connector.transport) (which tells the embedded agent how to talk to the server) and the like.

3.8.10. Outgoing email

Email SMTP hostname

rhq.server.email.smtp-host
The hostname of the SMTP server that is used when the RHQ Server sends emails.

Email SMTP the port

rhq.server.email.smtp-port
The port that the RHQ Server will send emails over when communicating with the SMTP server.

Email from address

rhq.server.email.from-address
The "From:" header of all emails sent by the RHQ Server.

3.8.11. Operation invocation default timeout

rhq.server.operation-timeout
One of the features of RHQ is the ability to invoke operations (aka control actions) on a resource. The RHQ Server will be able to ask an agent to invoke a particular operation on a particular resource managed by that agent. Because of the remote, asynchronous nature of operation invocations, a lot of things can go wrong (the network goes down, the resource crashes, etc.). This operation timeout is the default number of seconds that the RHQ Server will wait for an operation to complete and an agent to provide the results. If this timeout expires, the operation will be considered to have failed. Note that this is only a fallback default value - individual operations can define their own timeouts (in the plugin descriptor) or individual operation invocations can themselves specify a timeout. Those override this default rhq.operation-timeout setting.

3.8.12. Concurrency limits

RHQ is designed to scale to large numbers of agents. The RHQ Server must, therefore, take into account the possibility that it could get flooded with messages if many or all agents attempt to communicate with the server simultaneously (as will be the case if the RHQ Server is restarted after being down for a while; RHQ Agents will detect the RHQ Server has come back up and will attempt to immediately send it a backlog of messages).
To help alleviate problems that could occur during high load, the RHQ Server is configured to limit the number of concurrent messages allowed to be processed by different subsystems within the RHQ Server. If more messages arrive concurrently, such that the limit is exceeded, those additional messages will be dropped and the agent will be asked to send them later. The following configuration settings define types of messages that have concurrency limits associated with them.

Web connections

rhq.server.startup.web.max-connections
RHQ limits the number of web connections that can be concurrently created. This includes GUI connections made by browsers. It may also include connections made by agents, if agent connections are made via the servlet transport (Refer to Incoming Agent Communications Transport). Note that if agent requests are routed over web connections, you should ensure that the Global Concurrency Limit (rhq.communications.global-concurrency-limit) is slightly lower than this Web Connections limit so as not to lock out GUI users from accessing the user interface during times of high agent load.
This limit on web connections is the same for both non-secured http requests and secured https requests, so the total max connections allowed is actually twice what this setting is. For example, if the max web connections is set to 300, then 300 http requests will be allowed and 300 https requests will be allowed, for a possible total of 600 concurrent web connections.

Global concurrency limit

rhq.communications.global-concurrency-limit
Aside from the Web Connections (rhq.server.startup.web.max-connections) limit, all other concurrency limits will only affect incoming agent messages (not GUI/browser requests). This global concurrency limit will limit the total number of agent messages coming into the server, regardless of the type of message. In other words, if this global concurrency limit is set to 300, no more than 300 total agent messages can be processed at any one time, no matter what kinds of messages are coming in. The rest of the concurrency limit settings will put a limit on the number of messages of particular message types. Keep in mind that if other concurrency limits are set higher than this global limit, they are effectively capped at this global limit since you can never have more than this global limit number of messages concurrently being processed.

Inventory report

rhq.server.concurrency-limit.inventory-report
Inventory reports are sent from the agent when the agent starts up and periodically thereafter. Inventory reports can be large, depending on the number of resources on the agent machine.

Availability report

rhq.server.concurrency-limit.availability-report
Availability reports are sent from the agent very often (typically every 60 seconds). Availability reports are usually very small, but occur in large numbers due to the high frequency of their transmission.

Inventory synchronization

rhq.server.concurrency-limit.inventory-sync
Inventory synchronizations occur when the agent needs to synchronize its inventory with that of the server. Agents typically synchronize at startup. Traffic that flows as part of inventory synchronizations is usually large, depending upon the number of resources managed by the agent.

Content report

rhq.server.concurrency-limit.content-report
Content reports are similar to inventory reports except they contain information about discovered content (i.e. installed packages of software). These reports can be large depending on the number of installed software the agent has discovered and is managing.

Content download

rhq.server.concurrency-limit.content-download
Content downloads occur when a resource on an agent needs to ask for the content of a package version, usually for the purpose of installing the package.

Measurement report

rhq.server.concurrency-limit.measurement-report
Measurement reports are sent to the server periodically whenever the agent completes measurement collections. The number of measurement reports vary as do their size, depending on the number and frequency of measurements that are scheduled to be collected. The greater the number of schedule measurements the agent needs to collect, the more frequently measurement reports are sent and the larger they are.

Measurement schedule request

rhq.server.concurrency-limit.measurement-schedule-request
Similar to inventory synchronization, measurement schedule requests are sent to the agent when the agent wants to ask the server for its up-to-date set of measurement schedules that have to be collected.

Chapter 4. JON Agent Installation

4.1. Overview

The JON Agent can run on either a Windows or UNIX platform and does not require the execution of a special installer program. By default, the agent is not fully configured out-of-the-box. The first time you start the agent, or anytime that the agent's configuration has been cleaned, you must answer a series of setup questions. This can be done via a console window or by specifying a valid configuration file. After the agent has been configured you can run it as a Windows service, from a console, or run it as a daemon or init.d script in a UNIX environment.

4.2. Obtaining the Agent

In JON 2.2, the JON Agent is bundled along with the JON Server and is not available as a separate download. If there is a JON Server currently running in your environment, you can pull down an agent update binary .jar directly from the server using the following instructions.
  1. Simply point your browser to http://<your-server-hostname>:7080/agentupdate/download and save the agent binary update jar in a directory where you want to install the agent. The file you save should have a .jar extension. <your-server-hostname> should be the hostname or IP address of the server that is running and 7080 is the port on which that the server is accepting HTTP requests.
  2. Unpack the JON Agent distribution to a chosen directory.
  3. Copy the agent update binary .jar you downloaded from the JON Server to your chosen directory and run java -jar <agent-update-binary.jar> --install where <agent-update-binary.jar> is the name of the file you downloaded from the server.

4.3. Agent configuration

When the JON Agent is first executed, it enters into setup mode. In order for the JON Agent to contact the JON Server, you must enter values for the following parameters.

Table 4.1. The JON Agent setup mode parameters

Parameter Description
Agent Name
A unique name for the agent. The default is the fully qualified domain name (FQDN) of the host system. However, you can specify any name you want, as long as it is unique among all other agents in the system.
Agent Hostname or IP Address
The IP address the agent will bind to in order to listen for incoming messages. Refer to the JON Agent Communcation Services section in the JON Agent Guide for more information.
Agent Port
The port that the agent listens to for incoming messages.
RHQ Server Hostname or IP Address
The hostname or IP address the Server is listening to for incoming messages from agents. This is the address that the agent connects to when sending its initial registration request. If you are running in a RHQ High Availability (HA) environment (that is, you have multiple RHQ Servers running), this will not necessarily be this agent's primary Server. If you only have a single RHQ Server running in your environment, this address is the one the agent will always use when it needs to send messages to the Server.
RHQ Server Port
The port that the Server listens to for the incoming message registration message from the agent. Again, if you are running in RHQ HA environment, this isn't necessarily the port that all of your RHQ Servers are listening to. However, it should be set to the port that your "registration" Server is listening to.

Procedure 4.1. JON Agent Windows configuration

  1. Configure the agent by following one of the options below; option 1 is the default method. The rhq-agent.bat script is located in the <agent-install-dir>\bin\ directory.
    Option 1
    Run the rhq-agent.bat script in a console and follow the prompts, entering the appropriate values. If you need help on a particular preference setting, enter !? at the setup prompt for a description of that preference.
    C:\rhq-agent-2.2.0.GA\bin> rhq-agent.bat
    
    Option 2
    Edit the agent-configuration.xml and ensure to enter the correct settings. Run the rhq-agent.bat script and specifiy the agent-configuration.xml. For example:
    C:\rhq-agent-2.2.0.GA\bin> rhq-agent.bat --config ..\conf\agent-configuration.xml
    
    Option 3
    Run the rhq-agent.bat script and specify a valid file containing the values of all the setup parameters. For example, the command below uses a file called myAnswers.txt.
    C:\rhq-agent-2.2.0.GA\bin> rhq-agent.bat --input myAnswers.txt --nonative
    
    The --nonative temporarily disables the native system to allow reading input from a file. The contents of the myAnswers.txt file used in the example above is shown below. Each answer must be on its own line. To enable reading from standard input again, the last line must read native enable.
    [Agent Name] agentdomain.example.com
    [Agent Hostname or IP Address] agentdomain.example.com
    [Agent Port] 16163
    [RHQ Server Hostname or IP Address] serverdomain.example.com
    [RHQ Server Port] 7080
    native enable
    
  2. After the agent has connected to the server, the agent command prompt appears. Enter the command identify to identify the RHQ Server.
Reconfiguring the JON Agent
If you have previously installed a JON Agent on a machine and need to wipe all of its old persistent configuration data, start with a clean JON Agent by passing in the command line option -l, or --cleanconfig. This forces the agent to enter setup mode. If at any time, you need to start the JON Agent in setup mode, specify the -s, or --setup, command line option.
Debug mode
If you need to run the agent and its launcher scripts in debug mode so that the scripts and the agent itself log debug messages, define the environment variable RHQ_AGENT_DEBUG to "true". To disable debug mode, unset the RHQ_AGENT_DEBUG environment variable or set it to "false". You can alternatively use the agent's debug prompt command, in order to toggle the debug mode while the agent is running (specifically debug --file - execute help debug from the agent prompt for more information on this command).

4.4. Running on Windows

4.4.1. Running in a Windows Console

To run the JON Agent in a console, execute the rhq-agent.bat script found in the <agent-install-dir>\bin directory of the distribution. You can pass in any of the command line options that are described in Section 4.6, “Command line options”.
The rhq-server.bat script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the JON Server at a new JVM or you can define VM options. The comments at the top of the rhq-server.bat file contain a detailed list of these environment variables. You do not have to set any specific variables to get the JON Server to run; sensible defaults are used.
Do not edit the rhq-agent.bat file. If you need to customize the launch parameters of the Agent, either set the environment variables at the command prompt, or edit the values in the rhq-agent-env.bat.

4.4.2. Installing and running as a Windows service

Important

The agent will not ask for the configuration when installing as a Windows service. This means that you need to either pre-configure the agent, which means you pass all required information to the agent via the agent's configuration file, or you can run the agent in standard (non-service) mode once (as the user the service will run as) in order to answer all the setup questions prior to installing it as service.
If you wish to run the JON Agent at boot time, you can install the JON Agent as a Windows Service. To do so, you use the rhq-agent-wrapper.bat file. This script file accepts any of the following command line options:
  • install - this will install the JON Agent as a Windows Service. When you do this, you will be prompted for the password of the user that the service will run as. Information on how to define what user the service will run as is outlined below. The Windows Service will be installed to automatically start at boot time. You can change this behavior by modifying the wrapper configuration file as described below.
  • start - this will start the Windows Service, effectively starting the JON Agent. You must have installed the Windows Service first in order to be able to start it. Note that you can also start the JON Agent by using the Windows Services Administrative Tool instead.
  • stop - this will stop the Windows Service, effectively stopping the JON Agent. You need to have the Windows Service installed and started to stop it. Note that you can also stop the JON Agent by using the Windows Services Administrative Tool instead.
  • remove - this will remove the Windows Service from your Windows operating system. If the service was running, it will first be stopped. Once the service is removed, it will no longer be started at boot time and you can no longer start it with this wrapper script.
  • status - this simply tells you if the service is installed or not; if it is installed, it will tell you if it is currently running or not.
Two environment variables need to be explicitly mentioned here since they are important and have security implications.
  • RHQ_AGENT_RUN_AS - if this variable is set, its value will be the domain\username of the user account that the JON Agent Windows Service will be run as. The format of this variable's value must match that which Windows expects for a user account - specifically the Windows domain name followed by a backslash followed by the username. An example would be MYDOMAIN\john. This variable is used when you install the service via rhq-agent-wrapper.bat install.
  • RHQ_AGENT_RUN_AS_ME - if this variable is defined, it forces the user account to be that of the current user (specifically ".\ %USERNAME%)". The variable's value does not have to be anything in particular; as long as it is defined to something, it will take effect. If this variable is defined, it will override the RHQ_AGENT_RUN_AS environment variable. This variable is used when you install the service via rhq-agent-wrapper.bat install.
Refer to the comments at the top of the rhq-agent-wrapper.bat script file for the full list of variables you can set and the documentation on what they control.

Important

If you do not pass the agent a file containing its required configuration then you must specify one of the two environment variables mentioned above in order for the agent to properly initialize itself. If you specify RHQ_AGENT_RUN_AS_ME then you must have previously run the agent at least once in standard (interactive) mode as the current user before installing it as a service.
If you specify RHQ_AGENT_RUN_AS then you must have previously run the agent at least once in standard (interactive) mode as the user specified by RHQ_AGENT_RUN_AS before installing it as a service.
If neither of the above two environment variables are set, the JON Agent Windows Service will run as the System account. In this scenario the information the agent needs must be specified in its configuration file.

Important

If you specify either RHQ_AGENT_RUN_AS_ME or RHQ_AGENT_RUN_AS then you need to make sure that the selected user can actually start services in Windows. Do this by setting the "Logon as Service" right. Go to the Administrative Tools folder in your control panel. Open the Local Security Policy applet. Expand Local Policy and then click on User Rights Assignment. On the right side of your page, there is a logon as service policy where you can add the selected user.
In addition to setting the wrapper script file's environment variables, you can also further configure the JON Agent Windows Service by modifying the service wrapper configuration file - this file is located in the agent's distribution, specifically at bin\wrapper\rhq-agent-wrapper.conf. This configuration file sets some Java Service Wrapper configuration items (Java Service Wrapper is the utility that rhq-agent-wrapper.bat script uses to install and control the Windows Service). If you wish to add, remove or modify some wrapper.* settings, it is recommended that you read the Java Service Wrapper's configuration properties documentation.

Warning

In JON 2.0.1 it is necessary to add the following to the '# Additional JVM parameters' section of bin\wrapper\rhq-agent-wrapper.conf in order for the agent to run correctly as a windows service. This will be fixed in the JON 2.1 release.
wrapper.java.additional.6=-Djava.endorsed.dirs=%RHQ_AGENT_HOME%/lib/endorsed
A few common settings you may wish to modify are:
  • wrapper.app.parameter.# - these are command line options you can pass to the JON Agent itself. Refer to the JON Agent Guide for information on agent command line options. Note that each individual option and their values must be given their own wrapper configuration property and each property must be placed in numerical order. You cannot change the wrapper.app.parameter.1 or wrapper.app.parameter.2 properties - start with wrapper.app.parameter.3 and increment up from there. The option numbers must not contain holes! Example:
    wrapper.app.parameter.3=--config
    wrapper.app.parameter.4=C:\my-configs\my-agent-config.xml
    
  • wrapper.java.additional.# - these are additional VM options you can pass directly to the VM (such as -Xmx or -D). As with the wrapper.app.parameter.# properties, you must increment each option in numerical order. You should leave wrapper.java.additional.1 alone unless you want to point to your own log configuration file. You can add, remove or modify others, but make sure you know what you are doing. Example:
    wrapper.java.additional.2=-Xms256m
    wrapper.java.additional.3=-Xmx800m
    wrapper.java.additional.4=-XX:+DisableExplicitGC
    
  • wrapper.ntservice.starttype - by default, this is set to AUTO_START, meaning the JON Agent's service will be started automatically at boot time. If you prefer to force a manual start of the service, you can set this to DEMAND_START.
There are many other Java Service Wrapper configuration properties you can set. For more information, please refer to the Java Service Wrapper documentation.

4.5. Running on UNIX®

The JON Agent can be run directly from a console window or it can be installed as an init.d process such that it starts up when the computer boots up.

4.5.1. Running in a console

To run the JON Agent in a console, please execute the rhq-agent.sh script found in the /bin directory of the distribution. You can pass in any of the command line options that are described in the JON Agent Guide. There are a few environment variables that this rhq-agent.sh script looks for to allow you to run custom operations such as explicitly pointing to a specific JVM that you want the agent to run with or defining what VM options you would like to pass in. Please refer to the comments in rhq-agent-env.sh for the list of these environment variables. You do not have to set any specific environment variables to get the JON Agent to run under most circumstances; sensible defaults will be used. You should not edit rhq-agent.sh - if you need to customize the launch parameters of the Agent, either set the environment variables in your shell that you use to run rhq-agent.sh or edit the values in rhq-agent-env.sh.

4.5.2. Running as a daemon

The JON Agent script rhq-agent-wrapper.sh located in the /bin directory can be used to run the Agent as a daemon. There are two distinct scenarios in which you can run the agent as a daemon:
  1. If you previously run the agent in a console: Assuming you run rhq-agent-wrapper.sh as the same user you initially ran the agent as, then all you should have to do is to execute rhq-agent-wrapper.sh start and the agent will start up in daemon mode.
  2. If you have never previously run the agent: In this case you need the tweak rhq-agent-wrapper.sh file and also ensure you use a fully configured agent configuration file. This is necessary because you will not be able to answer the questions the agent asks when it first starts up, so these settings need to be specified in the configuration file
    • In the agent-configuration.xml make sure the agent has all the correct settings it needs to connect to the agent e.g.
      <entry key="rhq.agent.name" value="my-agent-name"/>
      <entry key="rhq.agent.server.bind-address" value="jon-server.mycompany.com" />
      
      With these files setup correctly you should be able to start the agent in daemon mode with rhq-agent-wrapper.sh start

Note

You can set environment variables to control the behavior of the agent - see the rhq-agent-env.sh script for the different variables you can set.

Important

Unlike the wrapper script on Windows, the rhq-agent-wrapper.sh script does not utilize the Java Service Wrapper utility.

Important

Solaris Admins: Symbolically linking the rhq agent binaries requires invocation of readlink in rhq-agent-wrapper.sh. However, readlink is not supplied by default in some Solaris installations. Solaris users must either download readlink from a third party provider, such as Sunfreeware, or refrain from symbolically linking the agent binaries when using the wrapper script.

4.5.3. Running with init.d

To run the JON Agent at boot time, you will need to complete some additional steps. You will need either root or sudo root access to perform parts of this installation.

Important

Solaris Admins: Symbolically linking the rhq agent binaries requires invocation of readlink in rhq-agent-wrapper.sh. However, readlink is not supplied by default in some Solaris installations. Solaris users must either download readlink from a third party provider, such as Sunfreeware, or refrain from symbolically linking the agent binaries when using the wrapper script.

4.5.3.1. Configuration

Configuration Parameters
Below are the configuration parameters that appear at the top of the JON Agent script rhq-agent-wrapper.sh located in the /bin directory
# RHQ_AGENT_HOME=/path/to/agent/installation
# export RHQ_AGENT_DEBUG=true
# export RHQ_AGENT_JAVA_HOME=/path/to/JDK/
# export RHQ_AGENT_JAVA_EXE_FILE_PATH=/path/directly/to/java/executable 
# export RHQ_AGENT_JAVA_OPTS=VM options
# export RHQ_AGENT_ADDITIONAL_JAVA_OPTS=additional VM options 
# PIDFILEDIR=/path/to/writable/directory
Information preceded by the # symbol is commented out and not enabled. To run the JON Agent at boot time you will need to enable some of these parameters by removing the # symbol that appears at the start of each line. The following three parameters are mandatory and must be uncommented:
  1. RHQ_AGENT_HOME=/path/to/agent/installation - This is the directory above your Agent installation's bin directory.
  2. export RHQ_AGENT_JAVA_HOME=/path/to/JDK/ - This is the directory above the JDK's bin folder.
  3. PIDFILEDIR=/path/to/writable/directory - A directory writable by the user you run the Agent as. It defaults to /var/run. If /var/run is not writable, use $RHQ_AGENT_HOME/bin. Please note that this is only applicable for versions 2.1.2SP1. and earlier of the JON Agent. Changes have been made in subsequent versions of the agent that will fall back to a writable directory.

Important

If you change # PIDFILEDIR=/path/to/writable/directory, and you are using RHEL, you will need to make a parallel change to the chkconfig "pidfile" location at the very top of the Agent wrapper script.
The following are optional parameters:
  1. export RHQ_AGENT_DEBUG=true - This will turn Agent debug on. Turn this off when finished debugging.
  2. export RHQ_AGENT_JAVA_EXE_FILE_PATH=/path/directly/to/java/executable - You can enable this if you need to specify a java executable. This is an optional configuration item.
  3. export RHQ_AGENT_JAVA_OPTS=VM options - Pass additional VM options. This is an optional configuration item.
  4. export RHQ_AGENT_ADDITIONAL_JAVA_OPTS=additional VM options - Pass additional java options. This is an optional configuration item.

4.5.3.2. Installation

Red Hat Enterprise Linux (RHEL) using chkconfig
The rhq-agent-wrapper script contains standard chkconfig options that can be used by the chkconfig init script management system. You will need to be root or have sudo root access to perform these steps.
  1. Symlink your edited rhq-agent-wrapper.sh file to /etc/init.d/. Example command:
    • ln -s /path/to/agent/installation/bin/rhq-agent-wrapper.sh /etc/init.d/rhq-agent-wrapper.sh
  2. Register rhq-agent-wrapper.sh with the chkconfig system by entering the following command:
    • /sbin/chkconfig --add rhq-agent-wrapper.sh
  3. Enable the Agent service at boot time and have it stop gracefully at shutdown/reboot by entering the following command:
    • /sbin/chkconfig rhq-agent-wrapper.sh on
  4. If you need to disable the Agent boot-time service enter the following command:
    • /sbin/chkconfig rhq-agent-wrapper.sh off
Other UNIX-like operating systems
Please consult your system administrator for instructions on how to install and configure the Agent init script with your init system.

4.6. Command line options

The rhq-agent.bat and rhq-agent.sh scripts can both take the following command line options.
Option Description
-a, --advanced
If setup is needed at startup, the advanced setup is run, rather than the basic
-c, --config=<filename>
explicitly specifies the configuration file the agent is to use for its configuration; if the preferences node in the file is different than "default", you must specify that preference node name via --pref
-d, --daemon
if specified, keyboard input will not be read by the agent. If the --input switch is used to specify a file, it will be processed
-D<name>[=<value>]
overrides a configuration preference with the given name with the given value. This also sets the JVM's system property with the same name/value pair (which does not necessarily have to map to a valid agent configuration preference)
-h, --help
displays the help text for the command line arguments of the agent
-i, --input=<filename>
specifies an input script containing agent prompt commands that the agent should execute upon startup; if not specified, keyboard input will be read
-l, --cleanconfig
Clears out any existing configuration and purges the agent's persisted data so the agent starts with a clean slate. The default configuration file will be loaded if --config is not specified. If you only wish to purge the agent's persisted data, without cleaning its configuration settings, use --purgedata.
-n, --nostart
If specified, the agent will not be automatically started
-o, --output=<filename>
specifies an output file that all non-log output will be written to. This does not affect the log messages - those go to the file as specified in the log4j.xml configuration
-p, --pref=<preferences name>
defines the preferences node name that the agent's configuration is known as. This allows the agent to reuse persisted preferences under this preferences name (and is how you can have multiple configuration sets defined and start the agent with one of them)
-s, --setup
Forces the agent to ask basic setup questions, even if the agent has already been fully configured. If --advanced was also specified, the advanced setup questions will be asked.
-t, --nonative
Forces the agent to disable the native system, even if the agent was configured for it.
-u, --purgedata
Purges the agent's persistent inventory and other data files. This does not erase the agent's configuration settings, use --cleanconfig if you wish to clean the agent's configuration along with purging its persisted data.

4.7. Running embedded in a JON Server

Warning

Running an embedded Agent in production is not recommended and, therefore, it is not currently supported. There are some known issues with managing certain resources with the embedded agent.
There is actually a third way you can run the JON Agent, and that is embedded in a JON Server. For those platforms that are running your JON Server, you have the option to either run a standalone JON Agent normally (as described in the sections above) or you can run the JON Agent embedded in the JON Server itself. This allows you to manage the JON Server platform and all the products running on that platform (including the JON Server itself) by simply starting the JON Server and having it start a JON Agent for you. This feature is to enable testing and demo'ing JON without needing to install and run a separate, standalone agent. It is not recommended to deploy in this way in a production JON environment.
The JON Server disables the Embedded JON Agent by default - you have to explicitly enable the Embedded JON Agent in order to run it. Refer to the section on Running the Embedded JON Agent in the JON Server Guide for information on how you can enable and configure the Embedded JON Agent.
The Embedded JON Agent implicitly runs in daemon mode, which means it has no command line interface. Its log file is located in $RHQ_SERVER_HOME/logs/embedded-agent.log.

4.8. Upgrading JON Agents

Important

Upgrading from JON 1.x or the JON 2.0 Beta or CR releases is not supported.

Important

To ensure compatibility with the JON Server, each Agent must be upgraded to the same version of JON as the Server.
Follow the steps below to upgrade your JON Agents to a new version of JON:

4.8.1. Upgrade the Server

The JON Server must be upgraded before any Agents are upgraded. Please shut down all agents and wait until all agents show red availability in the GUI before shutting down the server. On completing this procedure, please follow the JON Serverupgrade instructions to upgrade the JON server.

4.8.2. Install the new Agents

Once the JON Server has been upgraded, install the new version of JON Agent to each machine where an existing JON Agent is installed. Please upgrade each JON Agent as follows:
  1. Make sure the old Agent is not running. Do not delete the old Agent's directory yet.
  2. If you are running the Agent on Windows and installed the original Agent as a Windows service, uninstall the Windows service:
    cd <old-agent-install-dir>/bin
    ./rhq-agent-wrapper.bat remove
    
  3. Follow the usual Chapter 4, JON Agent Installation to install the new Agent. Note, you should not be prompted by the Agent with setup questions at the initial startup, as the setup preferences from the original Agent's installation will be found, and upgraded as needed.
  4. Verify the new Agent install. Start the Agent, open the JON GUI and make sure the Platform corresponding to the Agent and all its descendant Resources are still in inventory and have the expected Availability.
  5. Once you've verified the new Agent is operational, you may delete the old Agent's installation directory.

Chapter 5. Initial auto-discovery and import

Important

Please see Chapter 4, JON Agent Installation for instructions on how to install the JON Agent.
After installing the JON Server, you will be directed to the JON GUI Console after you click the Done! Click here to get started! message on the installer page (alternatively, you can point your browser to http://localhost:7080.

5.1. Login

The default username/password is rhqadmin/rhqadmin. Once you log in and install the license you can change the default password in the Administration section of the application.

5.2. Installing a license

Before you can access the JON Dashboard, you must first install the JON license you downloaded earlier.
Simply browse to the location of the saved license file and click OK to install the license. If you do not have a JON license, see the License documentation. If at a later time you need to update the license, you can do so in the Administration section of the application.

5.3. Initial auto-discovery and import

Once the agent has been started it will run discovery scans for resources on the machine and report them back to the JON Server. Before resources can be managed from the JON Server, they must be imported into its inventory. Importing is done through the Auto-Discovery portlet on the dashboard page. Simply select the newly discovered platform and its first level child servers (they will be automatically selected by default) and click the Import button.
Once the platform has been imported, the JON Agent will run a more detailed discovery scan. This discovery will check for child servers and services of the imported resources. Once complete, the Browse Resources link at the top of the page will display a summary of the JON Server inventory.
The JON Agent will continue to report back to the JON Server with data about the resources in inventory. This includes, their availability and metric data. At this point, the installation and initial setup are complete. You may begin by either exploring the JON Server user interface (UI) or continue to the Features section for more information on what JBoss ON has to offer.

Chapter 6. High Availability configurations

JON 2.1.0 introduced JON High Availability (HA) support. The goal of HA is to support multiple JON servers configured against a single database repository. JON Agent load can then be partitioned amongst the available Servers. Failover will occur for Agents whose Server becomes unreachable. A multi-server HA configuration provides fault tolerance and improved scalability.

Note

You can watch a demo that illustrates how you can install a new Server into an HA Server cloud.
This demo also shows you agent failover in action. You can watch this Affinity Groups demo to see how Affinity Groups is used to group your Servers and Agents together.

6.1. When should I define an HA configuration?

In many circumstances it may be satisfactory to run a single-server configuration. But if your environment satisfies one or more of the following criteria you may want to consider a multi-server approach:
  • Agent report processing is not meeting requirements:
    • Metrics
    • Alert generation
    • Event generation
    • Resource availability
  • Geographically distributed environment
    • Multiple Data Centers
    • Logical grouping of agents to servers
  • High Agent Load
    • 100+ Agents (this number can vary widely depending on Server strength)
    • JON server is having trouble processing the agent load (this is a better indicator)

6.2. HA infrastructure impact

In reality every JON 2.2.0 configuration is an HA configuration. Even a single-server configuration can be considered a 1-Server HA Cloud in that it can be managed via the HA Administration Console. For example, List Servers, List Agents, Setting Maintenance Mode, etc are all applicable to a single-server and accessible from the Administration page of the JON GUI. Since a single-server is a 1-Server cloud, it easily adapts to an increase in cloud size.
In general, JON Servers can be added or removed from the HA Cloud at any time. So, a single-server environment can be turned into a multi-server environment by running the JON Server installer on a second machine, configured for the same database, and defining a new Server (unique Server Name and public Endpoint).

6.2.1. Database impact

Although JON Servers can be added to the HA Server Cloud with relative ease, it should be done cautiously due to potential impact on the back-end database. Each JON Server limits its concurrent Database connections but there is no restriction on the Cloud itself. Meaning, adding a second server effectively doubles the potential database connections even if the number of Agents remains the same. The increase is linear as servers are added.
Each JON server instance has built-in mechanisms for limiting the load it will put on the database. In JON 2.2.0 that number out-of-the-box is 55 simultaneous connections. Each JON server may use less connections (that number based largely on how many agents are connected to it and how much data it needs to process concurrently), but the limits guarantee that they will each never use more than 55 connections to the database at any given point in time. So, for example, a 2-Server configuration would require that the database be able to handle 110 connections.
The JON Administrator should work closely with the Database Administrator to ensure an adequate configuration. In general, a large scale JON configuration requires DBA planning to handle not only connections, but to provide a database with reasonable data distribution and space allocation. HA impact is just another aspect to take into consideration.
Note that an HA configuration does not necessarily imply a large number of JON Agents. It may be the case that a relatively small JON implementation may be in place, with only a few JON Agents. But, those Agents may need high availability and therefore failover servers are required. In that case the backing database will still have a high number of potential connections, but in reality will not reach that limit.

6.2.2. Server and Agent endpoints

In a multi-server HA configuration it is important to realize that any agent could potentially try to connect to any server. Thus, it is critical that every JON Agent be able to resolve the Endpoint Address set for every Server in the HA Server cloud. So, when defining the server in the installer it is important that the Endpoint Address be public to the degree that the Agent population can reach the server via the defined address and port, or secure port if configured in that fashion.
Note that the Server endpoint information can be updated via the HA Administration pages in the JON GUI.
Conversely, an Agent connecting to a Server must provide an endpoint reachable by the Server in order to allow for the necessary two-way communication.

6.3. When should I use Affinity?

By default agent load is distributed evenly amongst the servers in the cloud. Balance can change in failover situations but in general, by default, agent load will be evenly distributed when all agents and all servers are running.
This is fine when it is unimportant which Agents connect to which Servers. But there are use cases where it may be desirable to create stronger bonds between specific Agents and Servers. This is accomplished by defining JON HA Affinity Groups. Agents will prefer connecting to Servers in the same Affinity Group. Affinity group assignment is optional and any given Agent or Server can participate in at most one Affinity Group.
Following are scenarios that may benefit from Affinity Group assignment.

6.3.1. Physical efficiency

In general if it is clear that certain agent-server connections will run more efficiently that others then defining affinity to prefer those connections makes sense. This could include Servers and Agents co-located in the same data center, or other geographic grouping, or various network topology scenarios.

6.3.2. Logical efficiency

It may not be the case that certain agents and servers will run more efficiently by talking to one another, but that there are other, organizational reasons to group agents and servers together. For example, Administration responsibilities, business units, etc.

6.3.3. Warm backup

It may be the case that certain machines should not be assigned agent load unless specifically needed for fail over purposes. In this case you would have all agents assigned affinity to a subset of the available servers, leaving some servers without any associated agents in normal operation.

6.3.4. Affinity behavior

Affinity is described in more detail in the HA Design Document but in short the following should be understood about Affinity Group behavior.
  1. Affinity is strong.
    1. JON will satisfy Affinity Group preference and then apply load balancing.
  2. An Agent will fail over to an available Server in its affinity group before it fails over to a non-affinity Server.
  3. Affinity is not guaranteed.
    1. Although strong, affinity can be broken if no affinity server is available.
    2. All Servers will be present in an Agent's failover list.
  4. JON attempts to distribute load evenly within the Affinity Group.

6.4. How do I move to an HA installation?

After deciding that a JON High Availability strategy is appropriate for your needs you should do two things to prepare for you installation or upgrade:
  1. Ensure your database is ready to support the load and connections. See Section 6.2.1, “Database impact”.
  2. Determine your affinity strategy. See Section 6.3.4, “Affinity behavior”
    Note that affinity assignments can be added or removed at any time but it is useful to consider your initial approach, even if it confirms that affinity assignments are unnecessary.
From an installation and upgrade perspective an HA environment does not require different steps, and actually can be moved to incrementally.

6.4.1. Moving to HA from JON 2.0.0/2.0.1

The recommended approach to move from a JON 2.0.0 or 2.0.1 environment to a JON HA environment is as follows:

6.4.2. Server requirements

  • All HA Servers must be running compatible versions of JON.
    Unless specifically noted, this means the exact same version of JON.
  • All HA Servers must be uniquely named.
    This string is defined during Server installation.
  • Each HA Server must define a unique endpoint that is resolvable by all JON Agents running against the HA Server Cloud.
    This address/port or address/secure port combination is defined during installation. It can be an alias as long as that alias is resolvable by all JON Agents. This requirement exists because any given JON Agent may be running against any JON Server at a given time. It is not the case that the JON Server defined in the JON Agent's initial configuration (from the Setup Questions, for example) will be the JON Server that the Agent is told to connect to. It is the JON Server that will initially be contacted by the JON Agent for registration purposes.
Note that the first JON Server installed will become the initial member in the HA Server Cloud. This means that a single-server installation can also be thought of as a 1-Server HA Cloud and therefore has the same Server requirements. The JON GUI HA Administration Console pages are still usable to inspect or manage your environment.
Perhaps more importantly this allows the 2nd, 3rd...Nth servers to be added at any time, even while other Servers are running. Conversely, HA Servers can be removed from the Cloud at any time.
HA Servers communicate solely via the database and therefore it is not required that their endpoints be visible to each other. No direct server to server communication is ever made.
To install or upgrade a JON Server, please follow the Section 6.4.2, “Server requirements”.

6.4.3. Agent requirements

  • All Agents must be running versions compatible with the JON Servers.
    Unless specifically noted, this means the exact same version of JON.
  • All Agents must be configured initially to contact a JON Server.
    This can be any JON Server in the JON HA Server Cloud.
  • All Agents must define an endpoint that is resolvable by any JON Server in the JON HA Server Cloud.
    This is because any given JON Agent may be running against any JON Server at a given time. It can be an alias as long as that alias is resolvable by all JON Servers. This requirement exists because any given JON Agent may be running against any JON Server at a given time. It is not the case that the JON Server defined in the JON Agent's initial configuration (from the Setup Questions, for example) will be the JON Server that the Agent will be served by. It is only the JON Server that will initially be contacted by the JON Agent for registration purposes.
To install or upgrade a JON Agent, please follow the Chapter 4, JON Agent Installation.
Since HA environments typically involve many agents it may be useful to perform pre-configured Agent installations to avoid having to answer initial Setup Questions interactively.

6.5. How do I manage my HA installation?

Even a 1-Server installation can take advantage of certain HA management capabilities. But after adding a second server, or more, it will be useful to become comfortable with the HA management features available in JON. In general, the steps to take when building up an HA Server Cloud are:
  1. Familiarize yourself with the HA Administration Console (HAAC)
    You will use these administration pages in the JON GUI to manage and monitor your HA environment. These pages are available even when running a single server so it should be easy to get comfortable with their use.
  2. Add your desired JON Server(s)
    Increasing the size of of your HA Server Cloud is done by running the installer on the desired Server node(s). To do this follow the JON Server Installation Guide. Use the List Servers page to examine your installed Servers.
  3. Add your desired JON Agents
    To do this follow the Chapter 4, JON Agent Installation. Use the List Agents page to examine your registered Agents.
  4. Update your Server Affinity Group membership
    If you have decided to use Affinity Groups to enable Agent-Server connection preferences then you can use the List Affinity Groups page to create your desired Affinity Groups and associate your Servers as desired. Note, you can also associate a Server with an Affinity Group via the Installer, using the Advanced Settings option.
  5. Update your Agent Affinity Group membership
    If you have decided to use Affinity Groups to enable Agent-Server connection preferences then you can use the List Affinity Groups page to associate your Agents as desired.
  6. Inspect your topology
    It may take some time, typically less than an hour, after making these changes before your Agent population establishes a steady state, connected to the expected Primary servers. You can use the HAAC pages to inspect the topology and should see Agents incrementally migrating.
  7. Optionally, test failover
    When you are satisfied that your HA Server Cloud is servicing Agents as expected you may want to test Agent Failover. To do this you can set Servers to Maintenance Mode via the List Servers page. To learn more about Maintenance Mode see High Availability-Agent Failover

Index

F

feedback
contact information for this manual, We need feedback