JBoss Operations Network 2.3 Installation Guide - Red Hat ...

pridefulauburnData Management

Dec 16, 2012 (4 years and 8 months ago)

2,106 views

JBoss Operations Network

2.3
Installation Guide
Installation and Initial Setup of the JBoss Operations Network
Edition 1
JBoss Documentation
JBoss ON

Team
Red Hat

JBoss
Copyright © 2009 Red Hat, Inc.
JBoss Operations Network 2.3 Installation Guide

1
Legal Notice
Copyright
© 2009 Red Hat, Inc..
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons
Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at
http://creativecommons.org/licenses/by-sa/3.0/
. In accordance with CC-BY-SA, if you distribute this
document or an adaptation of it, you must provide the URL for the original version.
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.
All other trademarks are the property of their respective owners.
2

Legal Notice
Abstract
A guide to download, install, and set up JBoss Operations Network 2.x servers and agents.
JBoss Operations Network 2.3 Installation Guide

3
Table of Contents
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. PostgreSQL preparation
2.3.2. PostgreSQL quick start installation
2.3.3. Oracle
3. JON Server Installation
3.1. Overview
3.2. Upgrading the JON Server
3.2.1. Remove obsolete alert definitions
3.2.2. Remove unwanted platforms from inventory
3.2.3. Stop the Server and all Agents
3.2.4. Unzip the new version of the JON Server
3.2.5. Install the new versions of JON Agent Plugin Packs
3.2.6. Setup the JON Server
3.2.7. Install the new version of the JON Agent to each Agent machine
3.2.8. Start the new Server and Agents
3.2.9. JON Server resource in inventory
3.3. JON High Availability
3.4. Installation preparation
3.5. Running the installer
3.5.1. Advanced settings
3.5.2. Database settings
3.5.3. Installation settings
3.5.4. Server settings
3.5.5. Complete the JON Server Installation
3.5.6. Installing as a boot-time service
3.6. Startup properties
3.6.1. Database
3.6.2. Server bindings
3.6.3. High Availability bindings
3.6.4. Cluster bindings
3.6.5. JON Console transport security
3.6.6. Incoming Agent communication bindings
3.6.7. Incoming Agent communications transport security
3.6.8. Outgoing Agent communications transport security
3.6.9. Outgoing email
3.6.10. Operation invocation default timeout
3.6.11. Concurrency limits
3.7. Adding and updating Agent plugins
4. JON Agent Installation
4.1. Overview
4.2. Obtaining the Agent
4.3. Installation preparation
4.4. Preparing the Agent for auto-update
4.4.1. Starting the Agent using the wrapper service
4.4.2. Do not alter the launcher scripts
4.4.3. Configuring the Agent using support scripts
4.4.4. Installing Keystores and Truststores
4.4.5. Installing the Agent in a writable directory
4.5. Agent auto-update
4.6. Manually Upgrading the JON Agent
5. Running the JON Agent
5.1. Running on Windows
5.1.1. Running in a Windows console
5.1.2. Installing and running as a Windows service
5.2. Running on
UNIX
®
5.2.1. Running in a console
5.2.2. Running as a daemon
4

Table of Contents
5.2.3. Running with init.d
5.3. Command line options
5.4. Running embedded in a JON Server
5.5. Using the Agent plugin
5.5.1. Inventorying the Agent Server and its services
5.5.2. Top-level resource
5.5.3. Common services
5.5.4. Java service wrapper launcher (Windows-only)
5.5.5. Agent launcher script (UNIX-only)
5.5.6. Rebooting the Agent and its Java VM
6. Initial auto-discovery and import
6.1. Login
6.2. Installing a license
6.3. Initial auto-discovery and import
7. High Availability configurations
7.1. When should I define an HA configuration?
7.2. HA infrastructure impact
7.2.1. Database impact
7.2.2. Server and Agent endpoints
7.3. When should I use Affinity?
7.3.1. Physical efficiency
7.3.2. Logical efficiency
7.3.3. Warm backup
7.3.4. Affinity behavior
7.4. How do I move to an HA installation?
7.4.1. Moving to HA from JON 2.0.0/2.0.1
7.4.2. Server requirements
7.4.3. Agent requirements
7.5. How do I manage my HA installation?
8. Command Line Interface (CLI) installation
8.1. Remote Client and CLI installation
8.2. Download the Remote Client binary
8.3. Unzip the binary
8.4. Running the JON CLI
8.4.1. Introduction
8.4.2. Running the JON CLI
8.4.3. JON Command line options
8.4.4. Built-in commands
8.4.5. Working with the CLI
8.4.6. Proxy
8.5. References
9. JON Best Practices
9.1. Best practices for managing JBoss Application Servers
9.1.1. DynaGroups
9.1.2. Useful alerts
9.1.3. JBoss Application Server setup
9.1.4. Common issues
9.1.5. Debugging issues
9.1.6. Log tracking
9.2. Best Practices for managing JBoss Tomcat Servers
9.2.1. Enabling JBoss ON monitoring of your Tomcat Server
9.2.2. Enabling response time metrics for your Tomcat Server
9.3. Best practices for remote clients
9.3.1. Deciding on a Remote Client Approach
Index
JBoss Operations Network 2.3 Installation Guide

5
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 includes 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
keycaps 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 keycap, all presented in mono-spaced bold and
all distinguishable thanks to context.
Key combinations can be distinguished from keycaps 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 paragraph highlights the particular keycap to press. The second highlights two key
combinations (each a set of three keycaps with each set 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
System

Preferences

Mouse
from the main menu bar to launch
Mouse
Preferences
. In the
Buttons
tab, click 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
Applications

Accessories

Character Map
from the main menu bar. Next, choose
Search

Find…
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
Edit

Paste
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
.
6

Preface
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.
JBoss Operations Network 2.3 Installation Guide

7
Chapter 1. Download JBoss ON
1.1. Red Hat customers
JBoss Operations Network 2.3 is available for download from the
Customer Support Portal
.
Procedure 1.1. Download JBoss Operations Network 2.3 and the License
1
.
Log into the
Customer Support Portal
, click on
Software
and then click on the
Product
drop-
down box arrow. Navigate to the
JBoss Operations Network
software download. If you do not
have access to the
JBoss ON
downloads section please contact your sales representative.
2
.
Download the following files to run JBoss ON:
Download the
JBoss Operations Network 2.3 Base Distribution
by clicking on the
Download
icon.
You will also need to download the required
plugin pack
for JBoss ON 2.3 by navigating to
the required
JBoss Operations Network
software download. For example, to download
the plugin pack for JBoss ON for EAP navigate to the
JBoss ON for EAP
software download
in the
Product
drop-down box. Then click on the
Download
icon next to the
EAP Plugin
Pack for JBoss ON 2.3
link.
Unlike previous releases of JBoss ON, there are no operating system specific versions of the
distribution.
3
.
Next you will need to download the JBoss ON license. 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.
To download the license right click on the license and save the file to your desktop. After the
JBoss ON installation is complete, you will be prompted to upload the license.
If you do not have access to the correct license, please 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
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.3
1
.
Navigate to the
Jopr homepage
. Click on the
Downloads
tab. Under
Jopr - Releases
>
Jopr
2.3.0
click on the
Download
link located in the
Download
table under
Link
.
2
.
Download the Jopr Server.
8

Chapter 1. Download JBoss ON
Chapter 2. JON 2.x prerequisites
2.1. Operating system
JBoss ON 2.x Server and Agent are supported on Linux and Windows with the amd64, i686 and ia64
architectures. Other platforms that support Java 5 are supported, but you must disable native support as
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
operating system 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.3 requires Java 5 or Java 6
Important
GNU libgcj is
not
supported.
After downloading and installing the latest JRE or JDK you will need to configure your system. This
consists of two tasks:
1
.
Setting the
JAVA_HOME
environment variable to the installation directory; and
2
.
Ensuring the system is using the correct JDK (or JRE) using the
alternatives
command.
The
JAVA_HOME
environment variable tells the JON Server and the JON Agent where to locate the JVM.
Setting
JAVA_HOME
generally overrides the values for
java
,
javac
and
java_sdk_1.5.0
in
alternatives
, however it is recommended that you specify the value for consistency.
Setting the
JAVA_HOME
Environment Variable on Linux
After installing the JDK, ensure the
JAVA_HOME
environment variable exists and points to the location of
the JDK installation.
Determine whether
JAVA_HOME
is set by executing the following command:
~]$ echo $JAVA_HOME
If
JAVA_HOME
is not set, the value must be set to the location of the JDK or JRE installation on your
system. This can be achieved by adding two lines to the
.bashrc
configuration file. Open
.bashrc
and
add a line similar to the following one anywhere inside the file:
export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<
version
>"
Selecting the Correct System JVM on Linux using
alternatives
Next you will need to set
java
,
javac
and
java_sdk_1.5.0
using the
alternatives
command.
On systems with the
alternatives
command, including Red Hat Enterprise Linux and Fedora, it is
possible to choose which JDK (or JRE) installation to use, as well as which
java
and
javac
executables should be run when called.
As the root user
, call
/usr/sbin/alternatives
with the
--config java
option to select between
the JDKs and JREs installed on your system. For example:
JBoss Operations Network 2.3 Installation Guide

9

home]$ sudo /usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

Selection Command
-----------------------------------------------
1 /usr/lib/jvm/jre-1.5.0-gcj/bin/java
2 /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3 /usr/lib/jvm/jre-1.5.0-sun/bin/java

Enter to keep the current selection[+], or type selection number:
The Sun JDK, version 5, is required to run the
java
executable. In the
alternatives
listing above, a
plus (
+
) symbol next to a number indicates the option currently being used. Press
Enter
to keep the
current JVM, or enter the number corresponding to the JVM to select that option.
As the root user, repeat the procedure above for the
javac
command and the
java_sdk_1.5.0
environment variable:
home]$ sudo /usr/sbin/alternatives --config javac
home]$ sudo /usr/sbin/alternatives --config java_sdk_1.5.0
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.
Unsupported databases
Please note that although the installer offers a choice of other databases (for example,
embedded H2 and MS SQL server), these are for
demonstration
purposes only and are
not
supported.
2.3.1. PostgreSQL preparation
PostgreSQL version
JBoss ON currently supports versions 8.2.4-8.4.x 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
10

Chapter 2. JON 2.x prerequisites
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
max_prepared_transactions = 60 # default is 5 (in v8.3) or 0 (in v8.4)
max_prepared_transactions
Note that
max_prepared_transactions
is set to the same value as
max_connections
as
explained in the
PostgreSQL documentation
. See specifically the
max_prepared_transactions
(integer)
section.
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 operating system you are using, you may need to adjust some kernel parameters.
Refer to the
Managing Kernel Resources
documentation 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 please see
Client
Authentication
.
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
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:
To build and install PostgreSQL please refer to the
Installation Instructions
For Windows:
Follow the installations instructions described at:
PostgreSQL Installer
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:
JBoss Operations Network 2.3 Installation Guide

11
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, “PostgreSQL preparation”
to configure your machine for production use with
JBoss ON.
2.3.3. Oracle
Oracle version
JBoss ON currently supports version 10g of Oracle. Earlier versions are not supported.
To install Oracle, please consult the
Oracle documentation
.
When you have an Oracle server installed, continue to
Section 2.3.3.1, “Oracle preparation”
to prepare
your database.
2.3.3.1. 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.6, “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.2. JON user requirements for XA
12

Chapter 2. JON 2.x prerequisites
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
login
In order to execute the above
GRANT
statements, you will need to be logged in as
SYS
. To login
as
SYS
, use the following:
CONNECT sys/your_sys_password AS sysdba;
2.3.3.3. Sessions and processes
Currently the recommended algorithm for determining the maximum number of Oracle processes (as
kept in
v$resource_limit
) which JBoss ON should use is the following:
Take the maximum of:
1
.
1.5 * total number of JBoss ON Agents in the environment, and;
2
.
60 * total number of JBoss ON Servers in the environment
then add 40 if you are also using Oracle Enterprise Manager (EM).
For example if you had 100 JBoss ON Agents and 2 JBoss ON Servers, and you were using Oracle EM,
you would have:
1
.
1.5 * 100 = 150
2
.
60 * 2 = 120
So the maximum of the two is 150. Then add 40 to support Oracle EM and that gives 190 processes.
The number of sessions (as kept in
v$resource_limit
) should be:
1.1 * number of processes
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.4. SGA and PGA sizes
Oracle settings for SGA and PGA sizes are very important in the performance of JBoss ON. If they are
too small, your database will perform very slow, affecting JBoss ON in a very negative way. Talk to your
DBA for proper sizing of your Oracle's SGA and PGA requirements. The settings you need to tune are
sga_target
and
pga_aggregate_target
.
2.3.3.5. Tuning open cursors
If the following sql:
select max(a.value) as highest_open_cur, p.value as max_open_cur
from v$sesstat a, v$statname b, v$parameter p
where a.statistic# = b.statistic#
and b.name = 'opened cursors current'
and p.name= 'open_cursors'
group by p.value;
returns a max_open_cur value of less than 300 then execute the following:
ALTER SESSION SET OPEN_CURSORS = 300 SCOPE=BOTH;
2.3.3.6. 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
JBoss ON 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.
JBoss Operations Network 2.3 Installation Guide

13
Warning
Locally manage all tablespaces.
3
.
Create the JBoss ON user.
CREATE USER jon IDENTIFIED BY jon;
4
.
Grant permissions to the new user.
GRANT CONNECT, RESOURCE TO jon;
14

Chapter 2. JON 2.x prerequisites
Chapter 3. JON Server Installation
This chapter describes the JBoss Operations Network 2.3 Server installation process. We
recommended that you also read the
JON Server Guide
for more information about the JON Server.
3.1. Overview
The JBoss ON Server can run on either a Windows or UNIX platform. The following provides a summary
of the installation steps you need to perform:
1
.
If you already have a JBoss ON Server installed and you need to upgrade it, go to
Section 3.2,
“Upgrading the JON Server”
.
2
.
It is recommended you read through
Chapter 7,
High Availability configurations
. This section will
help you decide if you need high availability features and if so, how many servers you should
install and how they should be configured.
3
.
Before you install your Server, read
Section 3.4, “Installation preparation”
to prepare your
environment.
4
.
After you are familiar with the high availability features and you have prepared your environment
for the JBoss ON Server, read
Section 3.5, “Running the installer”
to install your server.
5
.
After the server has been installed and 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. Go to Running the JBoss ON
Server for more information.
3.2. 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.x GA.
You will need to perform a new JON installation if moving from a pre-JON 2.x 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.2.1. Remove obsolete alert definitions
Important
This 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.2.2. Remove unwanted platforms from inventory
Remove "out of service" platform resources prior to the upgrade.
3.2.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.
Stop all the JON Agents
JBoss Operations Network 2.3 Installation Guide

15
Auto-upgrade
In JBoss ON 2.2 agents hve the ability to upgrade automatically. So once you install JBoss ON
2.2, you will find that upgrading the agents thereafter will be simpler, because the agent will be
able to detect when a server has been upgraded and the agent will upgrade itself accordingly.
Therefore, if you have prepared your agents for auto-update, you will not want to shut them down.
Let them detect when the new JBoss ON Server comes online and upgrade themselves.
Stop the JON Server after all agents are down
Do not stop the JON Database.
3.2.4. Unzip the new version of the JON Server
Unzip the server distribution to the directory where it will be executed from.
cd /opt
unzip jon-server-2.3.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.3.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 by executing the following command:
cd <
old-server-install-dir
>/bin
./rhq-server.bat remove
Install a Windows service for the new Server by executing the following command:
cd <
new-server-install-dir
>/bin
./rhq-server.bat install
3.2.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
execute the following command:
cd
[install-dir]
unzip jon-plugin-pack-
<name>
-2.3.0.GA.zip
Then 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.2.6. Setup the JON Server
Backup Your Database
We recommend that you back 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.
16

Chapter 3. JON Server Installation
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 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:
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:[.....]
These can be safely ignored.
3.2.7. Install the new version of the JON Agent to each Agent machine
Follow the Agent upgrade instructions in
Section 4.6, “Manually Upgrading the JON Agent”
.
3.2.8. Start the new Server and Agents
Start the new Server and Agents
3.2.9. JON Server resource in inventory
1
.
If a JBoss ON Server Resource corresponding to your old JBoss ON Server installation is in the
inventory, remove it from the inventory.
2
.
(optional) If desired, import the new JBoss ON Server resource into the inventory.
3.3. 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 and there is no separate HA installer. It is
important to understand the following:
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 7,
High Availability configurations
.
3.4. Installation 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.
JBoss Operations Network 2.3 Installation Guide

17
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
Network Time Protocol (NTP)
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.
3.5. 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 where will be executed from. For example:
cd /opt
unzip jon-server-2.3.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.3.0.GA
. The
/opt/jon-server-2.3.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.3.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.5.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.
18

Chapter 3. JON Server Installation
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.5.2. Database settings
The main installer page will appear differently depending on the database settings. You must configure
the database for this server installation. The database settings area of the installer will look like this:
Procedure 3.2. Configure the database
1
.
Set your database connection properties by updating the default values as necessary.
Important
In 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:
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]
These messgaes can be safely ignored
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 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. Choose the default (
Keep (maintain existing
data)
) unless you are confident you do not need any previous JON data. If any errors occur
during the database schema installation, check the logs.
Important
The JBoss ON 1.x database schema is incompatible with the JBoss ON 2.0 schema; you cannot
upgrade a 1.x schema to a 2.0 schema.
3.5.3. Installation settings
The installation settings page will differ 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:
JBoss Operations Network 2.3 Installation Guide

19
If you are upgrading or reinstalling a 2.1.0 server, or installing a new server into a High Availability cloud,
the installer page will look identical with the exception of an additional drop-down list of existing
registered servers as follows:
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.5.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
20

Chapter 3. JON Server Installation
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 in
Section 3.6, “Startup properties”
.
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.5. Complete the JON Server Installation
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, “PostgreSQL preparation”
for a
workaround.
3.5.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.6. Startup properties
When the JON Server starts, it will load the properties defined in the
bin/rhq-server.properties
file. These startup properties provide settings that are necessary to bootstrap the JON Server (for
example, what host address to bind the web application to, or what ports the server will listen to for
incoming agent requests).
Note
These startup properties are different to the values stored in the database and can be modified
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.5, “Running the installer”
.
The startup parameters are documented below.
3.6.1. Database
These properties define the JON 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 JON's back end persistence store. The only
supported values are
PostgreSQL
or
Oracle
.
JBoss Operations Network 2.3 Installation Guide

21
Database connection URL
rhq.server.database.connection-url
The JDBC URL that the JON Server uses 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 JON Server uses to communicate with the
database. An example is
oracle.jdbc.driver.OracleDriver
.
Database XA DataSource class
rhq.server.database.xa-datasource-class
The fully qualified class name of the JDBC driver that the JON Server uses to communicate with the
database. Examples of this are
org.postgresql.xa.PGXADataSource
or
oracle.jdbc.xa.client.OracleXADatasource
.
Database user name
rhq.server.database.user-name
The name of the user that the JON Server uses when logging into the database.
Database password
rhq.server.database.password
The password of the database user that is used by the JON 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. This
is 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. This is
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. This is currently
only used when connecting to PostgreSQL.
3.6.2. Server bindings
These settings bind the JON 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 JON GUI Console, among other services, bind to this IP address. This is the host in the JON
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 JON Server in order for the change to take
effect.
HTTP the port
rhq.server.startup.web.http.port
22

Chapter 3. JON Server Installation
The JON GUI Console listens to this port for unsecured HTTP requests coming in. This is the port
number in the JON 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 JON Server in order for the change to take
effect.
Secure HTTPS the port
rhq.server.startup.web.https.port
The JON GUI Console listens to this port for secured HTTPS requests coming in. This is the port
number in the JON 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 JON 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 JON 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 JON 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 JON 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 JON 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 JON Server in order for the change to take
effect.
AJP Port
rhq.server.startup.ajp.port
JBoss Operations Network 2.3 Installation Guide

23
The port used by an internal service.
If you change this value, you must shutdown and restart the JON 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 JON 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 JON Server in order for the change to take
effect.
3.6.3. High Availability bindings
Since 2.1, there are settings that configure the JON Server to identify itself to, and communicate with,
other JON Servers or server-side components. They are required for a single-server installation and
also facilitate membership in a multi-server, High Availability, JON Server Cloud.
Note
These settings cannot be changed in the
rhq-server.properties
files but are managed via
the JON GUI post-installation.
3.6.3.1. Server name
rhq.server.high-availability.name
Each JON 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 JON server cloud.
Although present in
rhq-server.properties
this setting is managed only via the JON HA
Administration Console.
3.6.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 JON 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.6.3.3. Server Affinity Group
JON performs load balancing and agent fail-over when operating with a multi-server configuration (JON
Server Cloud). In certain situations, regional datacenters for example, it may make sense for particular
JON Agents to prefer, or have affinity for, certain servers. JON Agents assigned to a particular Affinity
Group will prefer JON Servers assigned to the same Affinity Group. Note that the pairing is not strict and
JON 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 JON GUI.
3.6.3.4. Registered servers
When installing or upgrading the JON server against an existing database, the installer will present a list
of previously installed JON Server Names. These Server Names represent the servers in the current
JON Server Cloud. If you are performing an upgrade, or re-installing a JON 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.
24

Chapter 3. JON Server Installation
3.6.4. Cluster bindings
Prior to 2.1, these are settings that configure the JON Server to participate in a JON 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 more details about JBoss cluster settings see
http://www.jboss.org/community/docs/DOC-12460
.
If you change any cluster binding values, you must shutdown and restart the JON Server in order for the
changes to take effect.
Partition name
jboss.partition.name
The name of the JON Server cluster partition. All JON 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 JON Server as part
of a cluster of JON Servers, you may set this to
127.0.0.1
so it binds only to the local loopback
interface.
Partition UDP multicast group 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
JBoss Operations Network 2.3 Installation Guide

25
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.6.5. JON Console transport security
JON Console Keystore
rhq.server.startup.keystore.filename
The JON Console can accept browser requests over HTTPS. If you want to authenticate your JON
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 file name must be a relative file path relative to the
<JON

Server Install Dir>
/jbossas/server/default/conf
directory. The JON Server ships with a
self-signed certificate in a default keystore file.
If you change this value, you must shutdown and restart the JON Server in order for the change to take
effect.
JON Console keystore password
rhq.server.startup.keystore.password
The password of the keystore file. This is so the JON 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 JON Server in order for the change to take
effect.
JON Console SSL protocol
rhq.server.startup.keystore.sslprotocol
The protocol that browser clients should use to communicate with the JON Console.
If you change this value, you must shutdown and restart the JON Server in order for the change to take
effect.
3.6.6. Incoming Agent communication bindings
These settings define how the JON Server will accept incoming messages from the JON Agents. See
Communications Configuration
for more information on setting up the JON Server's agent
communications subsystem.
Incoming Agent communications transport
rhq.communications.connector.transport
Defines how the JON Agents need to transport messages to the JON 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 the only two currently supported transports,
servlet
or
sslservlet
, it means the
agent requests will go through the JON 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
they are also secured though the secure Tomcat Connector. 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.6.5, “JON Console transport security”
.
Note that this transport setting does
not
restrict agents from only going over that particular transport. By
default, the JON Server always deploys the comm connector that allows for both
servlet
and
sslservlet
traffic. What this means is that the agent decides what transport is 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 is placed in the server's JBoss/Remoting locator URL.
26

Chapter 3. JON Server Installation
Prior to 2.1
: The address that the JON Server binds its connector to so it can receive JON Agent
messages.
Since 2.1
: This defines the endpoint that the JON Server will bind its connector to. 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 JON Server listens to in order to accept JON Agent messages.
Since 2.1
: This defines the endpoint that the JON Server will bind its connector to. 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, although it will still appear in the
rhq-
server.properties
file. It can be left blank; 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
This defines additional transport parameters the JON Server will set on its connector that will accept
incoming messages from the JON Agents. See
Communications Configuration - TransportParameters
for further information on transport parameters.
Agent multicast detector enabled
rhq.communications.multicast-detector.enabled
If true, the JON Server will attempt to auto-detect JON 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 directly binds to. This is not used, or needed, 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 used, or needed, 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 used, or needed, if you have
not enabled multicast detection.
3.6.7. Incoming Agent communications transport security
These settings define how the server secures its communication channel when
accepting incoming
messages
from the JON Agents. See
Securing Communications
for more detailed information on setting
up server-agent communication security.
Note
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, 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 JON Server.
Incoming keystore file
JBoss Operations Network 2.3 Installation Guide

27
rhq.communications.connector.security.keystore.file
The keystore file that contains a certificate that authenticates the JON 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 JON Server's key within its keystore.
Incoming truststore file
rhq.communications.connector.security.truststore.file
The truststore file that contains certificates that this JON Server trusts. If you need the JON Server to
authenticate JON Agents, you must set this; otherwise it is not needed. This truststore contains
certificates for all JON Agents that need to communicate with this JON 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 need the JON Server to authenticate the JON Agents that are sending it messages. If
you are using a secured transport but do not have trusted certificates for all of your JON Agents in a
truststore, you must set this to
none
.
Valid values are:
none
,
want
or
need
3.6.8. Outgoing Agent communications transport security
These settings define how the server will secure its communication channel when sending outgoing
messages to the JON Agents. Refer to
Securing Communications
in the
JON Agent Guide
for more
information on setting up the Server-Agent communications security.
The other half of the communications channel, 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
Note that if your JON Agents are not using a secure transport, these settings are not used.
Outgoing secure socket protocol
28

Chapter 3. JON Server Installation
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 the JON Server to authenticate the JON Agents that are sending it messages. If
you are using a secured transport but do not have trusted certificates for all of your JON Agents in a
truststore, you must set this to
none
.
3.6.9. Outgoing email
Email SMTP hostname
rhq.server.email.smtp-host
The hostname of the SMTP server that is used when the JON Server sends emails.
Email SMTP the port
rhq.server.email.smtp-port
The port that the JON Server sends 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 JON Server.
3.6.10. Operation invocation default timeout
rhq.server.operation-timeout
An important feature of JON is the ability to invoke operations, or control actions, on a resource. The
JON Server can ask an agent to invoke a particular operation on a particular resource managed by that
agent. The remote, asynchronous nature of operation invocations, however, can be problematic. For
example, the network could go down, the resource could crash, etc. Operation timeout is the default
number of
seconds
that the JON Server will wait for an operation to complete and an agent to provide the
JBoss Operations Network 2.3 Installation Guide

29
results. If this timeout expires, the operation is considered to have failed.
Note
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.6.11. Concurrency limits
JON is designed to scale to large numbers of agents. The JON 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. For example, this could happen if the JON Server is restarted after being
down for a period of time. JON Agents will then detect that the JON Server has come back up and
attempt to immediately send it a backlog of messages.
To help alleviate problems that could occur during high load, the JON Server is configured to limit the
number of concurrent messages allowed to be processed by different subsystems within the JON
Server. If more messages arrive concurrently, and 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
JON limits the number of web connections that can be concurrently created. This includes GUI
connections made by browsers. It can 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 need to 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.
The 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 and not GUI/browser requests. The 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, regardless of 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 being processed concurrently.
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 regularly sent from the agent, 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.
30

Chapter 3. JON Server Installation
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 periodically sent to the server whenever the agent completes measurement
collections. The number and size of measurement reports can vary, depending on the number and
frequency of measurements 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 the reports will be.
Measurement schedule request
rhq.server.concurrency-limit.measurement-schedule-request
Similar to inventory synchronization, measurement schedule requests are sent to the agent asking the
server for an up-to-date set of measurement schedules that have to be collected.
3.7. Adding and updating Agent plugins
This section explains the steps needed to install a new agent plugin or update an existing agent plugin
to your JBoss ON environment.
1
.
Log in to the JBoss ON GUI as a user with permissions to edit the server settings.
2
.
Go to the
Administration
>
System Configuration
>
Plugins
page
3
.
Upload the new or updated plugin jar file:
If you do not want to use the GUI to upload the
jar
file, you can explicitly copy your plugin
.jar
file to <
server-install-
dir
>/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-plugins
.
If you have to copy more than one plugin, and those plugins have dependencies on each other,
you should either; upload the plugins one at a time, with the first ones being the ones that the
other plugins depend on, or; you should shut down the server and copy the plugin jars to the
rhq-plugins
directory and then restart the server.
If you have more than one JBoss ON Server in your JBoss ON Server Cloud, you only need to
deploy the plugins to one of the servers; the other servers will automatically detect and copy
the plugins.
4
.
At this point, you can wait for the server to auto-detect your new plugin
jar
file, or you can force it
to detect it immediately by pressing the
SCAN
button. The server will log messages in its log file
when the plugin has been detected and deployed properly.
5
.
Once the JBoss ON Server has detected and deployed the plugin jars, you can then push the
plugins out to the agents. You can do this in one of several ways:
a
.
If you have the agent prompt available you can execute at the agent prompt the command:

plugins update
b
.
If you have the agent imported into your JBoss ON inventory, you can execute the operation
"Update All Plugins" which tells the agent to pull down any new or updated plugins that the
agent does not yet have.
c
.
If you have multiple agents imported into inventory, you can execute a group operation of
"Update All Plugins" so all of your agents pull down the plugins.
JBoss Operations Network 2.3 Installation Guide

31
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.
1
.
First install one or more JBoss ON Servers.
2
.
If you already have agents installed and you need to upgrade them, see
Section 4.6, “Manually
Upgrading the JON Agent”
3
.
To install a new JBoss ON Agent, follow the steps in the next sections.
4
.
After the agent has been installed and 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. Go to
Chapter 5,
Running the
JON Agent
5
.
If you would like to be able to have your agent auto-updated in the future please see
Section 4.4,
“Preparing the Agent for auto-update”
4.2. Obtaining the Agent
In JON 2.3, the JON Agent is bundled with the JON Server and is not available as a separate download.
This agent bundle is called the
agent update binary
. It is called this because it is used to not only
install a new agent, but will also be used to upgrade the agent in the future. 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
.
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
.
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.
This will tell the agent update binary to extract the JON Agent distribution and install a fresh copy
of it in the
rhq-agent
subdirectory. At this point, you will have a fully installed JON Agent located
in a
rhq-agent
directory where your agent update binary is located.
From here on, the instructions will refer to this "rhq-agent" directory as <agent-install-dir>.
4.3. Installation preparation
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.
32

Chapter 4. JON Agent Installation
Table 4.1. The JON Agent setup mode parameters
Parameter
Description
Agent Name
This is 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