JBoss Operations Network 2.1
JON Agent Guide
The JON Agent that ships with JBoss Operations Network 2.0
Edition 1
JBoss Documentation JBoss ON Team
JBoss Operations Network 2.1 JON Agent Guide
The JON Agent that ships with JBoss Operations Network 2.0
Edition 1
JBo ss ON Team
Red Hat JBo ss
JBo ss Do cumentatio n
Legal Notice
Copyright © 2009 Red Hat, Inc..
T his 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 T orvalds 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.
T he 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
T his page describes the JON Agent that ships with JBoss Operations Network 2.0. It is incompatible
with the old agents that shipped with 1.x. T he new agent is more configurable, performs better and has
more features than the old agent. See Agent Features for more information.
Table of Contents
Table of Contents
.Preface
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . .
1. Document Conventions
4
1.1. T ypographic Conventions
4
1.2. Pull-quote Conventions
5
1.3. Notes and Warnings
6
2. We need feedback
6
.Chapter
. . . . . . . . 1.
. . .JON
. . . . .Agent
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8. . . . . . . . . .
1.1. Communications Security
8
1.1.1. Setting up Secure Communications
8
1.2. New Agent Features
8
1.2.1. Preferences
8
1.2.2. Prompt Commands
9
1.2.3. JON Server Auto-Detection and Polling
10
1.2.4. T hrottling
11
1.2.5. Guaranteed Delivery
12
1.2.6. T ransports
13
1.2.7. Secure Communications - Encryption and Authentication
13
1.2.8. Native Code with Java Fallback
14
1.2.9. Embedded JON Agent
15
1.2.10. Internalization
15
1.2.11. Log Message Customization
15
.Chapter
. . . . . . . . 2.
. . .Communications
. . . . . . . . . . . . . . . . . Configuration
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
............
2.1. JON Agent Communications Services
16
2.2. JON Server Communications Services
17
2.3. T ransport Parameters
18
2.4. Agent Communications Services Configuration
20
2.4.1. Agent Communications Services Configuration
20
2.4.2. Connector
21
2.5. Securing Server-Agent Communications
21
2.5.1. JBoss ON and SSL
22
2.5.1.1. Encryption
22
2.5.1.2. Authentication
22
2.5.2. Setting Up Secure JBoss ON Communications
22
2.5.2.1. Step 1 - Use SSL T ransport to Enable Encryption
23
2.5.2.1.1. JON Server Instructions
23
2.5.2.1.2. JON Agent Instructions
24
2.5.2.2. Step 2 - Prepare your SSL Certificates
25
2.5.2.3. Step 3 - Distribute your Keystores and T ruststores
27
2.5.2.3.1. JON Server Instructions
27
2.5.2.3.2. JON Agent Instructions
27
2.5.2.4. Step 4 - T ell the JON Servers and Agents about their Keystores/T ruststores
28
2.5.2.4.1. JON Server Instructions
28
2.5.2.4.2. JON Agent Instructions
29
2.5.2.5. Step 5 - T est Your Setup
30
.Chapter
. . . . . . . . 3.
. . .JON
. . . . .Agent
. . . . . . Advanced
. . . . . . . . . . .Setup
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
...........
3.1. JON Agent Advanced Setup
31
. . . . . . . . . .History
Revision
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. .2. . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. .2. . . . . . . . . .
Index
1
JBoss Operations Network 2.1 JON Agent Guide
F
2
42
Table of Contents
3
JBoss Operations Network 2.1 JON Agent Guide
Preface
1. Document Conventions
T his 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. T he
Liberation Fonts set is also used in HT ML 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. T hese
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:
T o see the contents of the file m y_next_bestselling_novel in your current working
directory, enter the cat m y_next_bestselling_novel command at the shell prompt
and press Enter to execute the command.
T he 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.
T he first example highlights a particular key to press. T he 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 m ono-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
T his 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, select the Left-handed m ouse 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).
T o insert a special character into a gedit file, choose Applications → Accessories →
4
Preface
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. T he character you sought will be highlighted in the Character T able. Double-click
this highlighted character to place it in the T ext to copy field and then click the Copy
button. Now switch back to your document and choose Edit → Paste from the gedit menu
bar.
T he 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:
T o connect to a remote machine using ssh, type ssh username@ domain.name at a shell
prompt. If the remote machine is exam ple.com and your username on that machine is
john, type ssh john@ exam ple.com .
T he m ount -o rem ount file-system command remounts the named file system. For
example, to remount the /hom e file system, the command is m ount -o rem ount /hom e.
T o 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
T erminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in m ono-spaced rom an and presented thus:
books
books_tests
Desktop
Desktop1
documentation
downloads
drafts
images
mss
notes
photos
scripts
stuff
svgs
svn
Source-code listings are also set in m ono-spaced rom an but add syntax highlighting as follows:
5
JBoss Operations Network 2.1 JON Agent Guide
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
T o see all outstanding issues regarding this guide, please visit: https://jira.jboss.org/jira/browse/JOPR
If you find a typographical error in the Features 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.
6
Preface
7
JBoss Operations Network 2.1 JON Agent Guide
Chapter 1. JON Agent
1.1. Communications Security
JBoss ON does not secure the communications between the JON Server and JON Agent by default (outof-box). Some issues that are of concern when running JBoss ON without secure communications are
outlined below. You need to be aware of these issues before deciding to run JBoss ON with an
unsecured communications channel between server and agent:
It is possible for an unauthorized person to install a rogue JON Agent and have that agent register
with the JON Server. A rogue agent is one in which the JBoss ON administrator did not install or give
permission to register into the JBoss ON system.
It is possible for an intruder to silently sniff the communications between the JON Agent and JON
Server, possibly obtaining very sensitive data about the machines they are running on.
It is possible for an intruder to capture and manipulate the communications traffic between the JON
Agent and JON Server as part of a man-in-the-middle attack, possibly being able to do very
damaging things to the machines they are running on.
Running JBoss ON without securing the communications should only be done under the following
circumstances, and only when you understand the full implications of doing so (as explained above):
If you are installing the JON Server and all JON Agents on a fully secured network, with firewalls
and/or a VPN limiting access to your entire network to only authorized and trusted personnel.
If you are running a demo of JBoss ON. When running JBoss ON as a demo, you may typically want
to get the system installed and running as quickly and easily as possible. You normally would not
want to concern yourself with securing the communications which involves manual, time-consuming
steps.
1.1.1. Setting up Secure Communications
If you do not wish to be vulnerable to the issues described above, you must secure the server-agent
communications. T o learn the details on how to secure the communications channel between your JON
Servers and JON Agents, please refer to Section 2.5, “Securing Server-Agent Communications”.
1.2. New Agent Features
1.2.1. Preferences
T he new configuration file is now in XML format and the properties (now called preferences) are
persisted on a per-user basis in an OS-specific way (i.e. on Windows, they are stored in the registry; on
UNIX in a directory located under the user's home directory). T he configuration preferences will,
therefore, survive agent upgrades or re-installs.
You can define different configuration preferences by specifying the -p command line argument of the
agent to the name of the preferences node as specified in the node element in the configuration XML file
under the parent "jboss-on-agent" node.
T he XML file's schema is that which is required of the Java Preferences API. T he agent configuration
schema version (not to be confused with the XML Schema) defines the version level that the
configuration is at. T his allows future versions of the agent to be able to change the configuration
preference definitions while providing a means to allow auto-migration of the old configuration data (at
8
Chapter 1. JON Agent
the old version level) to the new configuration version level. When the agent starts, its preferences are
checked to see if they can be upgraded, and if so, upgrades the configuration to the latest schema. T his
is helpful when you upgrade the agent. When the new agent starts up, it makes sure any previous
configuration is carried over with the old and new preferences added while obsolete preferences are
deleted.
A default configuration file ships in the agent's jar and it is documented inline.
When a new agent that has yet to be setup starts up, it automatically begins asking configuration setup
questions (just as if the setup prompt command was invoked). T his happens once - thereafter, the agent
will use its configuration preferences as setup by the user. You can clear this configuration via the
"config" prompt command. You can also re-setup the agent by simply executing the "setup" prompt
command. T he setup command allows you to perform the basic setup (which is the same as when
starting a newly installed agent) or, alternatively, it allows you to perform a more advanced setup that
let's you fine tune the agent's settings. Go to the page JON Agent Advanced Setup to see what the
advanced setup allows you to set.
1.2.2. Prompt Commands
T he agent can process simple prompt commands entered as either input from a file (see command line
option --input) or as input from the keyboard (assuming --daemon is not specified as a command line
argument). You can see the list of prompt commands that are accepted by the agent by entering "help"
at the prompt. T o get detailed help on a particular prompt command, enter "help" followed by the name of
the prompt command you are interested in. T he following are the current set of prompt commands that
the agent understands:
avail
Get availability of inventoried resources
config
Manages the agent configuration
download
Downloads a file from the JON Server
discovery
Asks a plugin to run a server scan discovery
dumpspool
Shows the entries found in the command spool
file
execute
Executes an external program
exit
Shuts down the agent's communications services
and kills the agent
failover
Shows/updates the HA failover list
getconfig
Displays one, several or all agent configuration
preferences
help
Shows help for a given command
identify
Asks to identify a remote server
inventory
Provides information about the current inventory
of resources
log
Configures some settings for the log messages
metrics
Shows the agent metrics
native
Accesses native system information
pc
Starts and stops the plugin container and all
deployed plugins
ping
Pings the JON Server
piql
Executes a PIQL query to search for running
processes
9
JBoss Operations Network 2.1 JON Agent Guide
plugins
Updates the agent plugins with the latest
versions from the server
register
Registers this agent with the JON Server
sender
Controls the command sender to start or stop
sending commands
setconfig
Sets an agent configuration preference
setup
Sets up the agent configuration by asking a
series of questions
shutdown
Shuts down all communications services without
killing the agent
start
Starts the agent comm services so it can accept
remote requests
timer
T imes how long it takes to execute another
prompt command
version
Shows the agent version information
quit
An alias for 'exit'
1.2.3. JON Server Auto-Detection and Polling
T he agent can be configured to auto-detect its JON Server. It can do this in two different ways:
1. Multicast detection : using JBoss/Remoting's multicast detection technology, the agent can usually
detect the JON Server coming online or going offline within a matter of seconds (a time which is
configurable). T his requires your network to support multicast traffic; if it does not, then you cannot
use this method of server auto-detection. T he following configuration preferences affect autodetection using the multicast detector:
rhq.agent.server-auto-detection must be set to true in order to enable this feature
rhq.communications.multicast-detector.enabled must be set to true in order to enable
this feature
rhq.communications.multicast-detector.default-time-delay is the number of
milliseconds that must pass without hearing from the JON Server before the JON Server is to
be considered "offline". T o quickly detect a JON Server shutting down or starting up, please
set this to a short time. T o reduce the amount of network traffic, please set this value to a
longer time. However, ensure that this value is longer than the server's heartbeat-time-delay,
otherwise, unnecessary network traffic will result.
rhq.communications.multicast-detector.heartbeat-time-delay is the number of
milliseconds that must pass between the agent's own heartbeat messages. T his value must
be shorter than the JON Server's default-time-delay otherwise, unnecessary network traffic will
result.
2. Server polling : this mechanism polls the JON Server periodically to determine if it is online or
offline. T his method of auto-detection does not require multicast traffic but does require the agent
to periodically connect to the JON Server and send it a ping command. T he following configuration
preference affects this "manual" server detection via polling:
rhq.agent.client.server-polling-interval-msecs is set to the number of milliseconds that
must pass before polling the server. T o quickly detect the JON Server going down or coming
up, set this to a short time; to reduce the amount of network traffic, set this to a longer time. If
this value is 0 or less, server polling is disabled.
T ypically one or both of these mechanisms are enabled. With the ability to auto-detect the JON Server
going offline, the agent will be given the opportunity to persist commands that are waiting to be sent and
allows the agent to shutdown its attempts to send commands. When the JON Server comes back online
10
Chapter 1. JON Agent
(and is auto-detected), the agent can resume. If, however, both auto-detection features are disabled,
then the agent, upon startup, will immediately assume the JON Server is online and will allow commands
to be sent. If, at some point, the JON Server is down, the agent will continually attempt to send it
commands - and receive "connection refused" errors. If the JON Server is down for a long period of time,
this will cause the agent log file to grow very large. T his is one reason why it is best to have at least one
auto-detection mechanism enabled.
1.2.4. Throttling
T he agent has several configuration preferences that define its client-side commands sender - they limit
how many resources it can use and how "fast" it can perform some functions (called throttling). T hese
configuration preferences have two main purposes: 1) to help limit the amount of resources the agent is
able to claim for itself and 2) to help avoid flooding the server with large amount of commands which
could put too-heavy a load on the JON server and/or starve other agents from being able to
communicate with the JON Server. T he following configuration preferences define the settings that
enable the agent to throttle its outbound messages. Most of these settings should be configured with
the other settings in mind. While these do work independently, their effects are usually determined not by
their own value but by related values. For example, a queue-size should be set to a larger number if the
command timeout is lengthened. T his is because if commands are given more time to complete, then
more commands will be in the queue waiting to be sent. But, if max-concurrent is raised, this would allow
more commands to be dequeued at any one time, so an increase in the queue-size may not be needed.
As you can see, all of those preferences set an independent parameter within the agent, but their effects
on the agent's behavior as a whole is dependent on the other agent's preferences.
rhq.agent.client.queue-size defines the maximum number of commands the agent can queue up
for sending to the JON Server. T he larger the number, the more memory the agent will be able to use
up. Setting this to 0 effectively sets the queue to be unbounded. Please take caution when setting
this to 0; if the JON Server is down for a long period of time, the agent may run out of memory if it
attempts to queue up more commands than it has memory for.
rhq.agent.client.max-concurrent is the number of messages the agent can send at any one time.
T he larger the number, to more messages the agent can dequeue (thus freeing up space in the
queue for more messages to come in). However, the higher this number is, the more messages will
get sent to the server at the same time and may require the agent to use more CPU cycles.
rhq.agent.client.command-timeout-msecs defines the amount of time the agent will wait for the
JON Server to reply with a response from a command before that command will be aborted. T he
longer this time is, the less of a chance the agent will abort a command that otherwise would have
succeeded (e.g. if the server just needs alot of time to process the particular command). However,
the longer this time is, the more messages have to be queued up and wait before being sent to the
server.
rhq.agent.client.retry-interval-msecs is the amount of time the agent will wait before attempting
to retry a command. Only those commands that are flagged for guaranteed delivery will be retried.
Non-guaranteed commands (aka volatile commands) will not be retried and thus this setting will have
no effect.
rhq.agent.client.send-throttling , if defined, enables send-throttling. When this is enabled, only a
certain number of commands can be sent before the agent enters a quiet period. During the quiet
period, no throttle-able commands are allowed to be sent to the server. T he commands can resume
after the quiet period ends. Send throttling only affects those commands configured as "throttle-able"
- these are typically commands containing metric collection data (i.e. those commands that tend to be
sent to the JON Server very frequently and in large numbers). Any other commands are not affected
by the send-throttle. Send throttling helps in preventing message storms on the JON Server, thus
helping to avoid the server from getting flooding with incoming messages and preventing agent
11
JBoss Operations Network 2.1 JON Agent Guide
starvation (that is, not locking out other agents from being able to talk to the JON Server). T he sendthrottling preference defines both the maximum number of commands that can be sent and the length
of the quiet period. For example, a preference value of "50:10000" means that after 50 'throttleable'
commands are sent, a quiet period will commence and last for 10000 milliseconds. After that time
expires, 50 more commands can be sent before the next quiet period begins.
rhq.agent.client.queue-throttling , if defined, enables queue throttling. T his limits the amount of
commands that can be dequeued in a given amount of time, called the burst period. If more
commands are attempted to be dequeued during the burst period than allowed, those dequeue
requests will be blocked until the next burst period begins. For example, if this is set to "50:10000", it
means that at most 50 commands can be dequeued in any 10000 millisecond interval. If, during a
burst period, a 51st command attempts to be dequeued, that dequeue request will block until the
burst period finishes (at which time a new burst period begins and the dequeue request becomes
the first of the next 50 allowed dequeue requests). T he purpose of queue throttling is not so much to
limit the amount of requests being sent to the server (although this does have that side-effect), it
really is to prohibit the agent from spinning the CPU too much as it attempts to dequeue and send
commands as fast as it can. If an agent is using too much CPU cycles, you can throttle the queue
thus (hopefully) reducing the amount of CPU required for the agent to send its commands. Note that
if you enable queue-throttling, you must take care in ensuring your queue-size is large enough (since
you are limiting the amount of commands that can be dequeued in a specific amount of time, you
need to make sure you have enough space in the queue to support the extra amount of commands
that get queue up).
1.2.5. Guaranteed Delivery
Some commands that the agent sends to the JON Server are not critical in the grand scheme of things.
For example, if a ping request fails to make it to the JON Server, we do not want to retry it nor do we
want to persist the command to ensure it survives an agent shutdown. T hese commands are called
volatile commands. Volatile commands are sent once - if they fail for whatever reason to be successfully
processed by the JON Server, the failure is logged and the agent drops the command and moves on to
the next that it needs to send.
However, there are some commands that must make their way to the JON Server and the agent must
ensure the JON Server processes them. T he agent must guarantee that these commands are delivered
- these are called guaranteed commands.
Important
While the agent will do its best to guarantee the delivery of guaranteed commands; this guarantee
is not 100%. T hat is to say, there may be rare circumstances that arise that cause a guaranteed
command to fail to get delivered (e.g. if the JVM crashes suddenly in the middle of an attempt to
send a guaranteed command).
Guaranteed commands are retried every X milliseconds while the agent is alive and actively sending
commands to the server (where X is the rhq.agent.client.retry-interval-msecs preference setting).
Guaranteed commands also survive agent shutdowns. If an agent shuts down prior to being able to
deliver a guaranteed command, that command is persisted to disk in what is called the command spool
file. T he next time the agent starts up, it will load up commands it has spooled to disk and immediately
queue them for sending to the JON Server.
T here are a couple preferences that define the behavior of this command spool file:
rhq.agent.client.command-spool-file.params defines the parameters for the spool file. T he
12
Chapter 1. JON Agent
value's format is defined as "max-file-size:purge-percentage". T he first number is the size, in bytes,
of the maximum file size threshold. If the spool file grows larger than this, a "purge" will be triggered
in order to shrink the file. T he second number is the purge percentage which indicates how large the
file is allowed to be after a purge. T his is specified as a percentage of the first parameter - the max
file size threshold. For example, if the max file size is 100000 (i.e. 100KB) and the purge percentage
is 90, then when the spool file grows larger than 100KB, a purge will be triggered and the file will be
compressed to no more than 90% of 100KB - which is 90KB. In effect, 10KB will be freed to allow
room for new commands to be spooled. When this occurs, unused space is compressed first and if
that does not free up enough space, the oldest commands in the spool file will be erased in order to
make room for the newer commands.
rhq.agent.client.command-spool-file.compressed is a true or false flag. If this flag is true, the
commands stored in the spool file will be compressed. T his can potentially save about 30%-40% in
disk space (give or take), however, it slows down the persistence mechanism considerably. T he
performance hit will only appear when unusual conditions occur, such as shutting down while some
guaranteed commands have not been sent yet or if the JON Server is down. It will not affect the
agent under normal conditions (while running with the JON Server up and successfully
communicating with the agent).
1.2.6. Transports
Both the JON Agent and JON Server use the same underlying communications services (based on
JBoss/Remoting technology). One feature this enables is the ability for the communications layer to use
different transports simply by changing configuration preferences. T he following configuration
preferences define the transports used by the agent:
rhq.agent.server.transport defines the transport protocol that the agent will use to talk to the JON
Server
rhq.communications.connector.transport defines the transport that the agent, itself, expects the
JON Server to use when the server wants to send messages to the agent.
T he transports that are supported are those supported by JBoss/Remoting - which today includes:
socket (raw and unencrypted socket based transport), sslsocket (encrypted and optionally authenticated
SSL transport), servlet, sslservlet, http, and https.
In additional to customizing the transport, you can also provide transport parameters that help define the
behavior of the connection using the configured transport.
rhq.agent.server.transport-params defines the transport parameters used when connecting to
the JON Server
rhq.communications.connector.transport-params defines what transport parameters the JON
Server should use when sending messages to the agent
See Chapter 2, Communications Configuration for more information on configuring these transport
parameters.
1.2.7. Secure Communications - Encryption and Authentication
T he communications services used by the JON Server and JON Agent can secure the network traffic
between the two by using SSL in order to encrypt and optionally authenticate the traffic. By simply using
a transport that uses SSL, you automatically get encryption. Each JON Server and JON Agent can be
optionally configured with a keystore and/or a truststore. You can configure the JON Server to
authenticate JON Agents, JON Agents to authenticate the JON Server or both. By setting up the proper
certificates in the proper keystores/truststores, you can set up a fully secured network of JON Servers
and JON Agents. You can even define what encryption protocols you want to use to encrypt the network
13
JBoss Operations Network 2.1 JON Agent Guide
traffic and what algorithms you want to use within your keystores/truststores.
T here are two configuration preferences that are important to consider:
rhq.communications.connector.security.client-auth-mode defines whether or not the agent's
server-side components must authenticate incoming requests (that is, authenticate the JON Server's
certificate). T he client-auth-mode can be set to one of three values:
1. none means the agent will not attempt to authenticate the JON Server's certificate during the
SSL handshake. In this case, the agent will not need a truststore file defined.
2. want means that only if the JON Server sends a certificate will it be authenticated. If the JON
Server does not have a certificate (thus doesn't provide one during the SSL handshake), this
anonymous connection will be accepted by the agent. T he agent must have a truststore file
containing all its trusted certificates (which must include the JON Server's public certificate).
3. need means that the agent must authenticate the JON Server's certificate in order for the
incoming requests to be accepted. If the JON Server provides an untrusted certificate or if it
provides no certificate at all during the SSL handshake, the agent will deny the connection
request and not accept any data from that connection. T he agent must have a truststore file
containing all its trusted certificates (which must include the JON Server's public certificate).
rhq.agent.client.security.server-auth-mode-enabled defines whether or not the agent's clientside sender components must authenticate the JON Server's certificate when it sends outbound
requests to the JON Server. When the agent initiates communicates with the JON Server (i.e. when
the agent wants to send a command to the server), it must first engage in the SSL handshake, at
which time both the agent and server swap certificates. If server-auth-mode-enabled is true, the
agent must authenticate/trust the JON Server's certificate, otherwise, the agent will refuse to send its
command to the server. If this mode is false, the server's certificate is ignored and the agent sends
its command regardless of the server's trustworthiness. When this mode is enabled, the agent must
have a truststore file containing all its trusted certificates (which must include the JON Server's public
certificate).
If the agent does not yet have a keystore containing its certificate, it will create and self-sign its own. T he
self-generated keystore file will, by default, be stored in the agent's data directory under the filename
"keystore.dat". A keystore file is required if the agent is to engage in any SSL-based transport. If you
wish, you can create and assign the agent your own custom certificate stored in your own keystore file.
Simply create the keystore file, put it somewhere on the local file system where the agent has access to
and define your keystore configuration preferences accordingly. T he same holds true for the truststore
files. T he agent will not create any truststore files. If you wish to enable either client-auth or server-auth,
you must provide the trusted certificates to the agent by putting the truststore files somewhere where
the agent can get to them and defining the appropriate truststore configuration preferences.
See the Section 2.5, “Securing Server-Agent Communications” page for more information on how to
secure the Agent-Server communications channel.
1.2.8. Native Code with Java Fallback
T he JON Agent still loads in native code to help it with things that only a low-level native layer can
perform (such as examining the operating system's process table). However, unlike previous versions, if
the native libraries are not available for your hardware/operating system, the agent will still run and be
supported. Your agent will lose some capabilities (such as being able to auto-discover resources via
process table scanning), however, your agent will still run and function. In addition, you can manually
disable the native layer, in the case where the native libraries do exist but for some reason are not
working properly - you can disable it to get the agent working again (albeit with the reduced set of
capabilities).
14
Chapter 1. JON Agent
1.2.9. Embedded JON Agent
T he JON Agent now has the ability to run embedded inside the JON Server. You are no longer required
to run a separate, standalone JON Agent on the JON Server machine if you wish to manage that JON
Server box. It is still recommended that you run a standalone JON Agent in production, but you now also
have the option to embed it for testing/demo purposes.
Note
T here are a few known bugs using the embedded agent with certain resources (notably JMXbased ones) and therefore you should only be using the external agent in production
environments.
1.2.10. Internalization
T he agent and the underlying communications services are all internationalized (I18N). T he agent user
interface (prompt commands, help messages, etc) is I18N compliant as well as all log messages in the
log files. T he locale in which the log messages are emitted can be the same or different than the locale
of the agent user interface messages. T his allows the end-user to see the user interface in his home
language with the log files containing messages in the locale of the support organization that is
supporting the end-user. If the end-user wants to perform his own log file analysis (to debug a problem
on his own), the log file messages can be switched to the same locale that the end-user wants to see.
1.2.11. Log Message Customization
In addition to supporting the "normal" Log4J customizations, the agent provides a few additional
features that further customize the log files and their messages. You can define what locale you want
your log messages to be emitted in (this is explained in the previous section). Also, you can configure
the log file to not include any exception stack traces, except for those messages at the FAT AL log level.
T his helps quiet down the log file and shrinks its size, especially during times when debugging a
problem results in large amounts of exceptions getting logged. Another feature allows you to dump the
message key codes in addition to the actual message string itself. T his is helpful if the log file is in a
different locale and you can't read the language of the messages or if you simply want to see the
message key codes for easier correlation to the source code or documentation. See the log prompt
command for enabling or disabling these features.
15
JBoss Operations Network 2.1 JON Agent Guide
Chapter 2. Communications Configuration
Both the JON Server and JON Agent use the same underlying communications layer for their incoming
and outgoing messages (which is based on JBoss/Remoting). T heir configuration files look similar
because many of their preference settings configure this communications layer. T his section describes
these settings for you to configure your JON Servers and JON Agents appropriately.
2.1. JON Agent Communications Services
When T he JON Agent starts for the first time, it enters setup mode. You can also manually enter this
setup mode by using the --setup command line option or use the setup agent prompt command. Once
in setup mode, you will be prompted to provide values for a series of preference settings. Some of these
settings involve setting up the communications services of the agent. Other settings are only prompted if
you enter "advanced" setup mode or "all" setup mode (these "advanced" and "all" settings are marked
with a (a) below). T o enter advanced setup mode and thus be able to set advanced settings, use the -advanced command line option with --setup or use the prompt command setup advanced. T o
enter the "all" setup mode (which allows you to set every preference available), you must use the prompt
command setup all. Please refer to Chapter 3, JON Agent Advanced Setup for more information on all
the prompts in "advanced" or "all" setup mode.
Agent IP Address - this is the address that the agent will bind to when listening for incoming
messages. T his usually is the same address that the agent's remote clients (aka JON Servers) will
use when trying to connect to the agent. However, in some network setups, this may not always be
the case (e.g. a remote client going through a router that forwards requests to a different host). If you
want the JON Server to connect to this JON Agent via a different address, you need to set up some
special Section 2.3, “Transport Parameters” to indicate this, as described below.
Agent Port - this is the port that the agent will actually be listening to. T his usually is the same port
that the agent's remote clients (JON Servers) will use when trying to send messages to the agent.
However, in some network setups, this may not always be the case (e.g. a remote client going
through a router that forwards requests to a different port). If you want the JON Server to connect to
this JON Agent via a different port, you need to set up some special Section 2.3, “Transport
Parameters” to indicate this, as described below.
Agent T ransport Protocol(a) - this is the transport the agent expects incoming messages to
adhere to. T his is usually "socket" or "sslsocket" (for raw binary socket messages, either unsecured
or secured). JBoss/Remoting has several different types of transports available. Please refer to the
JBoss Remoting documentation if you wish to experiment with other types of transports.
Agent T ransport Parameters(a) - these are additional parameters to be used when the agent
creates its communications services and when its remote clients (JON Servers) needs to talk to the
agent. See the section below, Section 2.3, “T ransport Parameters”, for the different types of transport
parameters you can set.
RHQ Server IP Address - this is the IP address for the endpoint of the primary JON Server this
agent will talk to. T his JON Server IP Address value is dictated by the way the JON Server has
configured its communications services (using similar settings as the ones being described for the
agent). Please refer to your JON Server's communications configuration to see what exact value this
should be.
RHQ Server Port - this is the port that the primary JON Server is listening to. T his JON Server Port
value is dictated by the way the JON Server has configured its communications services (using
similar settings such as these being described for the agent). Please refer to your JON Server's
communications configuration for what exact value this should be.
RHQ Server T ransport Protocol(a) - this is the transport the primary JON Server will expect its
incoming messages to flow over. T his JON Server T ransport value is dictated by the way the JON
Server has configured its communications services (using similar settings such as these being
16
Chapter 2. Communications Configuration
described for the agent). Please refer to your JON Server's communications configuration for what
exact value this should be.
RHQ Server T ransport Parameters(a) - this are additional Section 2.3, “T ransport Parameters”
that are to be used when the agent connects to the primary JON Server. T his JON Server T ransport
Parameters value is dictated by the way the JON Server has configured its communications services
(using similar settings such as these being described for the agent). Please refer to your JON
Server's communications configuration for what exact value this should be. In particular, you need to
know what additional transport parameters the JON Server wants its clients to define. T his is
especially important if the JON Agent needs to connect to a different host and/or port than what the
JON Server actually binds to.
Command Send T imeout(a) - this is the amount of milliseconds the agent will wait before aborting
a command (i.e. the amount of time in milliseconds that the JON Server has in order to process
commands and return its results). Please ensure that this value is the same as the timeout specified
in the transport parameters of your JON Server URI (if specified), since both timeouts will be
enforced. If this Command Send T imeout value is less than or equal to 0, the agent will not timeout its
messages (note that if a timeout is specified in the JON Server URI transport parameters, that
timeout will be enforced).
Command Send Retry Interval(a) - T his is the minimum amount of time, in milliseconds, the agent
will wait before trying to resend a guaranteed command that previously failed.
Command Send Max Retries(a) - If a guaranteed delivery message is sent, but the agent fails to
connect to the server and deliver the message, it will
always be retried. However, if the error was something other than a 'cannot connect' error, the
command will only be retried this amount of times before the command is dropped (at which time it will
be considered lost forever).
Maximum Commands T o Concurrently Send(a) - T his is the maximum number of commands the
agent can send to the server at any one time. If you defined clientMaxPoolSize in your JON Server
URI transport parameters, make sure its value is the same as this "Maximum Commands T o
Concurrently Send" value since you effectively cannot have one higher than the other.
2.2. JON Server Communications Services
Settings analogous to those described above exist on the JON Server side as well. In order to set these
communications configuration preferences on the JON Server, please edit their values in the
/bin/rhq-server.properties file. T he JON Server must be restarted for any new values in the
properties file to be implemented.
Note
Many of these properties found in rhq-server.properties define system properties that are
substituted in the comm overrides file found in
jbossas/server/default/deploy/on.ear/server-com m -service.xm l which override
the defaults defined in server-com m -configuration.xm l (found within the same directory).
If you are unsure what a particular setting is for in the rhq-server.properties file, Please
refer to the Startup Properties chapter in the Installation Guide or the server-com m configuration.xm l file which contains detailed comments for each of these settings.
17
JBoss Operations Network 2.1 JON Agent Guide
Important
Currently, the JON Server only officially supports the "servlet" and "sslservlet" transports for
incoming messages. T hat is to say, when you configure your agents to talk to the JON Server,
they should use either "servlet" or "sslservlet". T he following example shows the experimental
usage of the "socket" transport just as an illustration of configuring the JON Server's
communications, but this should not be used in production.
Note that the rhq.com m unications.connector.transport-param s setting allows you to set
custom Section 2.3, “T ransport Parameters” just like you could do for the agent. Also note that the
agent's JON Server URI preference value is a combination of the following JON Server settings:
rhq.communications.connector.transport
rhq.communications.connector.bind-address
rhq.communications.connector.bind-port
rhq.communications.connector.transport-params
For example, if the following settings are used to configure your JON Server:
rhq.communications.connector.transport=socket
rhq.communications.connector.bind-address=192.168.0.10
rhq.communications.connector.bind-port=16163
rhq.communications.connector.transport-params=enableTcpNoDelay=true&backlog=200
then when you setup your JON Agent, its configuration values would be:
RHQ
RHQ
RHQ
RHQ
Server
Server
Server
Server
IP Address=192.168.0.10
Port=16163
Transport Protocol=socket
Transport Parameters=enableTcpNoDelay=true&backlog=200
2.3. Transport Parameters
Both the JON Server and JON Agent use JBoss/Remoting as its underlying remoting framework.
JBoss/Remoting defines remote endpoints (which identify how to connect to a JON Server or JON
Agent) via InvokerLocator strings, which look like simple URLs. An example is
socket://m yhost.corp.com :16163/?transportParam 1=value1& param 2=value2.
InvokerLocators consist of a transport protocol (socket:) as well as the host and port of the remote
endpoint. Also as part of an InvokerLocator, are transport parameters which further customize the
endpoint. T hey help define the behavior of the underlying communications connector (which is the thing
that accepts incoming messages from remote clients). T he JON Server and JON Agent can each define
their own transport parameters via their rhq.communications.connector.transport-params preference
setting (the agent's advanced setup mode will prompt you with Agent T ransport Parameters when
asking for this value).
T ransport parameters are appended to the end of the InvokerLocator - in the same way a query string is
appended to a URL. When you define your transport parameters, you must set them using the same
syntax, specifically, multiple transport parameters are separated by ampersand characters. If you set
transport parameters inside your XML config file, be sure you use the proper & string to represent the
ampersand.
18
Chapter 2. Communications Configuration
Below you will find listed all the possible transport parameters that can be defined in your JON Server or
JON Agent rhq.communications.connector.transport-params setting. T hey are split into two groups: the
first group are settings that affect the server-side socket behavior and the second group are settings
that affect the client-side behavior. In this context, "server-side" refers to the connector that accepts
incoming messages and "client-side" refers to the remote clients that send outgoing messages. JON
Servers and JON Agents have both a server-side and client-side since they both send and receive
messages from each other.
Note
Please refer to the JBoss/Remoting documentation for additional information on these settings
and their low-level implementation details.
Settings that affect the server-side
serverBindAddress - T he address on which the server socket binds to listen for requests. T he
default is an empty value which indicates the server socket should be bound to the host provided
by the InvokerLocator URL (the host).
serverBindPort - T he port to listen for requests on.
timeout - T he socket timeout value. T he default on the server side is 60000 (one minute). If the
timeout parameter is set, its value will also be passed to the client-side (see below).
backlog - T he preferred number of unaccepted incoming connections allowed at a given time.
T he actual number may be greater than the specified backlog. When the queue is full, further
connection requests are rejected. Must be a positive value greater than 0. If the value passed if
equal or less than 0, then the default value will be assumed. T he default value is 200.
numAcceptT hreads - T he number of threads that exist for accepting client connections. T he
default is 1.
maxPoolSize - T he number of server threads for processing client requests. T he default is 300.
socket.check_connection - indicates if the invoker should try to check the connection before
re-using it by sending a single byte ping from the client to the server and then back from the
server. T his configuration needs to be set on both the client and server to work. T he default
value is false.
Settings that affect the client-side
clientConnectAddress - the IP address or hostname the client will use to connect to the
server-side socket. T his would be needed in the case that the client will be going through a router
that forwards requests made externally to a different IP address or hostname internally. If no
clientConnectAddress or serverBindAddress is specified, the local host's address is used.
clientConnectPort - the port the client will use to connect to the server-side socket. T his would
be needed in the case that the client will be going through a router that forwards requests made
externally to a different port internally.
timeout - T he socket timeout value. T he default on the client side is 1800000 (or 30 minutes).
enableT cpNoDelay - can be either true or false and will indicate if the client socket should have
T CP_NODELAY turned on or off. T CP_NODELAY is for a specific purpose; to disable the Nagle
buffering algorithm. It should only be set for applications that send frequent small bursts of
information without getting an immediate response. T he default is false.
clientMaxPoolSize - the client-side maximum number of active socket connections. T his
basically equates to the maximum number of concurrent client calls that can be made from the
socket client invoker. T he default is 50.
numberOfRetries - number of retries to get a socket from the pool. T his basically equates to
19
JBoss Operations Network 2.1 JON Agent Guide
the number of seconds the client will wait to get a client socket connection from the pool before
timing out. If the max retries is reached, a CannotConnectException will be thrown. T he default is
30.
numberOfCallRetries - number of retries for making the invocation. T his is unrelated to
numberOfRetries in that when this comes into play is after it has already received a client socket
connection from the pool. However, it is possible that the socket connection timed out while
waiting within the pool. Since a connection check is not done by default, the connection is thrown
away and an attempt to get a new one will be made. T his will happen for however many
numberOfCallRetries is (which defaults to 3). However, when (numberOfCallsRetries - 2) is
reached, the entire connection pool is flushed under the assumption that all connections in the
pool have timed out and are invalid and will start over by creating a new connection. If this still
fails, a MarshalException is thrown.
socket.check_connection - Indicates if the invoker should try to check the connection before
re-using it by sending a single byte ping from the client to the server and then back from the
server. T his configuration needs to be set on both client and server to work. T his if false by
default.
T he example below illustrates how a single InvokerLocator URL with transport parameters can configure
both server-side and client-side behavior. Let's assume we are configuring a JON Server with the
following settings:
transport: socket
bind-address: 192.168.0.5
bind-port: 56565
transport-params: backlog=300&enableT cpNoDelay=false
T he full JON Server URI would then look like:
socket://192.168.0.5:56565/?backlog=300& enableT cpNoDelay=false
T he backlog transport parameter is a server-side configuration and the enableT cpNoDelay
transport parameter is a client-side configuration. When the JON Server creates its server socket and
begins listening for incoming messages from JON Agents, it sets its backlog to 300. T he JON Server
ignores the enableT cpNoDelay parameter because it is only useful for clients that want to talk to its
server socket. When a JON Agent sends a message to this JON Server, the JON Agent will ignore the
backlog parameter because it is strictly a server-side setting but it will disable its T CP_NODELAY
setting. As you can see, a single InvokerLocator can provide useful information for both ends of the
communications channel (client and server).
2.4. Agent Communications Services Configuration
T he previous sections described the configuration preferences for most of the features available in the
agent. T he main set of preferences not yet discussed are those configuration settings that define the
communications services the agent will create in order to be able to receive commands from the JON
Server.
T here are two main components that are configurable:
1. Multicast Detector
2. Connector
2.4.1. Agent Communications Services Configuration
T he Multicast Detector is an optional service and is only needed if server auto-detection is enabled
20
Chapter 2. Communications Configuration
(rhq.agent.server-auto-detection=true). T his service is responsible for listening for multicast heartbeat
messages from remote JON Servers running on the network. T he Multicast Detector role is to detect if
the JON Server starting up or shutting down and notify the agent. T he agent will immediately stop
sending messages when notified that its JON Server has shut down. It will begin spooling guaranteed
commands to disk and continue queuing volatile commands in case the JON Server starts. When the
Multicast Detector sees the JON Server is online, it will notify the agent which will then begin to start
sending messages again.
You can configure the multicast address and port the detector will use. You can also configure the
amount of time must pass without hearing from the JON Server before that server is considered dead.
2.4.2. Connector
T he Connector is the server-side component responsible for opening up the agent's socket that will
accept incoming commands from the JON Server. You can configure what transport the connector will
use, what address the socket will bind to and what port it listens to. T here are additional transport
parameters you can define; such as what address the agent's client (JON Server) should use to connect
to the agent, what the socket timeout should be, etc. T hese transport params are specific to the type of
transport is being used. See Chapter 2, Communications Configuration for more detailed information on
how to configure your connector via its transport params.
Note
T hese parameters are actually features supplied by the underlying JBoss/Remoting
infrastructure used by the JON communications layer. For more information on all available
transport params, please refer to the JBoss/Remoting configuration documentation.
2.5. Securing Server-Agent Communications
T ypically, the JON Server and JON Agents talk to each other in the clear, meaning all communications
traffic is unencrypted and no authentication is performed on either end. Many times, the environment in
which you install your JON Servers and JON Agents does not warrant the extra setup time and runtime
performance degradation you incur when enabling security on JBoss ON communications traffic (for
example, if you already have a VPN and/or firewall protections in place that guard your JON Servers and
JON Agents against intrusion). However, there are those that need or simply want the peace of mind of
knowing their JBoss ON traffic is fully encrypted and authenticated. T his section will describe the steps
that you need to perform in order to fully secure the communications traffic between JON Servers and
JON Agents. Please refer to Section 1.1, “Communications Security” which discusses the implications of
running JBoss ON without securing the communications channel.
Important
T here is a basic authentication mechanism employed by the server in which it assigns security
tokens to its agents which are used to identify and "authenticate" registered agents. T his token
mechanism should not, however, be considered a strong authentication scheme for the purposes
of protecting your JBoss ON network from infiltration.
21
JBoss Operations Network 2.1 JON Agent Guide
Note
If you need information on configuring the non-security related communications settings, please
refer to Chapter 2, Communications Configuration.
2.5.1. JBoss ON and SSL
JBoss ON utilizes SSL technology to perform both encryption and authentication. You can enable
encryption (scrambling the data between server and agent to avoid someone eavesdropping on the
traffic) and optionally enable authentication (which prohibits an intruder from attempting to spoof either a
JON Server or JON Agent). It is recommended that you understand the basics of SSL and certificatebased security before attempting to secure your JBoss ON communications.
2.5.1.1. Encryption
By simply using a transport that uses SSL, you automatically get encryption. T his means that when you
configure your JON Server and JON Agent's communications layer, use an SSL-enabled transport to
encrypt the traffic. An SSL-enabled transport includes https and sslsocket. You do not have to worry
about setting up certificates if you want to use SSL-enabled transports just for encryption. T he JON
Server ships with a certificate and the JON Agent will create a self-signed certificate if it needs one.
Note that it is possible to just use SSL encryption without authentication. Some people may just wish to
encrypt their JBoss ON traffic, without requiring the JON Servers and JON Agents authenticating each
other. T his setup, while less secure, is much easier to setup because it does not require creating and
distributing trusted certificates.
2.5.1.2. Authentication
Authentication via SSL requires that you distribute trusted certificates to your JON Servers and JON
Agents. You must also configure those JON Servers and JON Agents to reject any messages coming
from remote clients that do not match any of those trusted certificates. In order to support authentication,
you must use SSL-enabled transports (which include https and sslsocket). You must also obtain trusted
certificates for all your servers and agents and package those certificates in a set of keystore and
truststore files. You can configure the JON Server to authenticate JON Agents, JON Agents to
authenticate the JON Server or both. JBoss ON provides this flexibility in case you only want to
authenticate in one direction but not another. However, when people feel the need for authentication,
they will usually enable it in both directions.
Authentication requires a bit more work to setup. Because true authentication requires a high degree of
trust, you have to manually create and sign your certificates, create keystores and truststores that
contain those certificates, then distribute your keystores and truststores in a highly secure manner to all
your JON Servers and JON Agents. T his may mean going as far as physically hand-delivering your
trusted certificates via CD and copying the certificates from the CD to all the computers hosting the JON
Servers and JON Agents. Many times it is not as highly paranoid as that - however, at some point along
the way, you have to place trust in whatever certificates you are using and distributing.
2.5.2. Setting Up Secure JBoss ON Communications
T he following are the steps necessary to set up secure communications in JBoss ON. Remember that
you have the option for encryption-only or encryption-with-authentication. If you choose the former, you
do not need to perform any of the steps dealing with the creation, packaging and distribution of
certificates and keystores/truststores. If you wish to have full security with encryption-withauthentication, follow all the steps listed below. If you are setting up with encryption-with-authentication,
these steps assume you want authentication in both directions (that is, the agents will need to
22
Chapter 2. Communications Configuration
authenticate with the server and the server will need to authenticate with the agents).
2.5.2.1. Step 1 - Use SSL T ransport to Enable Encryption
T he first thing you need to do is tell the JON Servers and JON Agents to use SSL when talking to each
other. T he JBoss ON low-level communications layer is based on JBoss/Remoting and uses what is
known as a transport to ship messages back and forth between agents and servers. A transport can be
either unencrypted (like the raw socket transport or http) or it can be encrypted (like sslsocket or https).
We are going to use a raw socket transport since it is faster (HT T P is a text-based protocol and
requires binary messages to be encoded and decoded into HT T P messages - JBoss ON can use raw
sockets to send the binary messages without requiring it to build and parse HT T P headers). But, that
said, you can easily replace https in place of sslsocket in these instructions if you wish to use HT T PS
(you might wish to do this, for example, if you have a firewall that allows only HT T PS traffic to flow).
2.5.2.1.1. JON Server Instructions
Shutdown the JON Server
Go to the /bin directory under the location where your JON Server is installed
In that directory, find the file rhq-server.properties and load it into your favorite text editor
Find the following configuration preferences used to set the server's communications connector and
set them appropriately:
rhq.communications.connector.transport=sslsocket
rhq.communications.connector.bind-address=${jboss.bind.address}
rhq.communications.connector.bind-port=56565
rhq.communications.connector.transport-params=
where transport is the SSL transport you wish to use, bind-address is the IP address/hostname that
the server will bind its listening connector to, bind-port is any free server socket port the server will
listen to for incoming agent requests and Section 2.3, “T ransport Parameters” are JBoss/Remotingspecific configuration parameters used to configure how the server and agent interact with this
connector. You may notice that the bind-address uses "${jboss.bind.address}" - this is the value as
defined by the JON Server's JBossAS bind address. If you wish to change the bind address the JON
Server uses (and thus the address used by the connector to bind to), you can modify the
jboss.bind.address setting in rhq-server.properties.
Important
If you are a using a protocol such as sslsocket which does not use T omcat for socket
management and jboss.bind.address maps to more than one network interface, then the
connector will bind to only one of the available interfaces not all of them. For example, this
could occur if the JON server has multiple network interfaces and jboss.bind.address is set to
0.0.0.0. Without turning on debug logging it is hard to to tell which of the available interfaces
the sslsocket is using. T o avoid this ambiguity update rhq-server.properties to have the JON
Server bind to a single interface.
Ensure that the following properties have valid values, e.g. longer than 6 characters, otherwise errors
will occur when restarting the JON server.
rhq.communications.connector.security.keystore.password=rhqpwd
rhq.communications.connector.security.keystore.key-password=rhqpwd
If you are only wanting SSL encryption, ensure that certificate based authentication is disabled by
23
JBoss Operations Network 2.1 JON Agent Guide
having the following properties set as below:
rhq.communications.connector.security.client-auth-mode=none
rhq.server.client.security.server-auth-mode-enabled=false
(Optional) You may wish to explicitly define the secure socket protocol used by this connector,
although the default (T LS) is usually good enough. If the default protocol of T LS is not what you want,
find the following configuration preferences and set them appropriately:
rhq.communications.connector.security.secure-socket-protocol=TLS
rhq.server.client.security.secure-socket-protocol=TLS
Note that you can define one protocol when sending to the agent (rhq.server.client.security.*) and a
different protocol when receiving messages from the agent
(rhq.communications.connector.security.*). Of course, you must make sure your agents' protocols
are configured in reverse (i.e. the agent must know what protocol the server expects when receiving
and what protocol the server uses when sending). You usually do not need to change the secure
socket protocols, as the defaults are normally suitable. T he important thing to understand is that the
transport must be an SSL-enabled transport, and the bind-port must be set to any port as long as it
is unused on your server host.
Save the configuration file
If you do not plan on proceeding to setup SSL authentication at this stage, you can restart the JON
Server.
Important
If the rhq.communications.connector.transport setting is changed to sslservlet, it tells the JON
Server to piggyback on the secured embedded T omcat connector to accept agent messages via
HT T PS on the default port (which is 7443). On the agent, you don't have to change anything
other than changing "RHQ Server T ransport Protocol" to use sslservlet and "RHQ Server Port"
to 7443. Most importantly do not change "Agent T ransport Protocol" to sslservlet. T his will not
work because there is no servlet container on the agent side to handle this transport. Using the
sslservlet transport, you use the JON Server's T omcat certificate and the agent's auto-generated
self-signed certificate for encryption. However, if you want to enable certificate-based
authentication, then you must follow the steps outlined in this section; otherwise, you would need
to configure T omcat's keystore and truststores appropriately. We will not discuss this option
here. Please refer to the T omcat documentation for more information.
2.5.2.1.2. JON Agent Instructions
Important
While in setup mode, enter !? at any prompt to get help
You must enter the JON Agent's advanced setup mode. You can do this in one of the following ways:
Start the agent with the the command line option --clean --setup --advanced
Answer all prompts until you get to the prompt asking for the Agent T ransport Protocol and enter
sslsocket
At the prompt asking for the RHQ Server IP Address, enter the bind address of the JON Server
from the configuration settings from the previous section. T hat is, you must use the JON Server's
24
Chapter 2. Communications Configuration
bind address as defined by its rhq.communications.connector.bind-address setting.
At the prompt asking for the RHQ Server Port, enter a bind port of the JON Server from the
configuration settings described in the previous section. T hat is, you must use the JON Server's new
bind port as defined by its rhq.communications.connector.bind-port setting.
At the prompt asking for the RHQ Server T ransport Protocol, enter sslsocket (which is the JON
Server's new transport as defined by its rhq.communications.connector.transport setting.
At the prompt asking for the RHQ Server T ransport Parameters, enter the parameters of the JON
Server configuration settings from the previous section. T hat is, you must use the JON Server's new
transport parameters as defined by its rhq.communications.connector.transport-params setting. T o
specify no parameters, i.e. clear the default, just enter a space and hit return.
If you only want SSL encryption, ensure that certificate based authentication is disabled by having the
following properties set:
Client Authentication Mode : none
Server Authentication Mode Enabled? : false
Make sure the following password settings at least 6characters long (this is the default after JON
2.0.1):
Server-side Keystore Password
Server-side Keystore Key Password
Client-side Keystore Password
Client-side Keystore Key Password
(Optional) You may wish to explicitly define the agent connector's transport parameters. You may
also wish to explicitly set the secure socket protocols used by the agent (however, the default
protocol of T LS is usually sufficient). T hese settings can also be set when in advanced setup mode.
Agent T ransport Parameters are the optional JBoss/Remoting transport parameters that are
used by the agent and server to interact with the agent's connector
Incoming Secure Socket Protocol is the protocol used when accepting incoming messages
from the JON Server (make sure this matches the JON Server's protocol setting
rhq.server.client.security.secure-socket-protocol)
Outgoing Secure Socket Protocol is the protocol used when sending outgoing messages to
the JON Server (make sure this matches the JON Server's protocol setting
rhq.communications.connector.security.secure-socket-protocol)
Exit the agent (effectively shutting it down) and then restart it.
At this point, you have now configured your JON Servers and JON Agents to encrypt their messages to
each other via SSL. You can be assured that no one can effectively eavesdrop on the communications
between them. However, if you wish to strengthen the security of the network traffic even further,
continue on to the next series of steps which will enable certificate-based authentication between your
JON Servers and JON Agents.
2.5.2.2. Step 2 - Prepare your SSL Certificates
If you wish to have your JON Servers and JON Agents authenticate one another, you need something
that "identifies" each one of them. SSL requires digital certificates for this purpose. If your company or
organization can request and receive officially signed certificates from a trusted CA, you will need to
obtain one certificate for each of your JON Servers and JON Agents that you plan on deploying in your
JBoss ON environment. If you already have the certificates given to you from your CA, you must place
each of them in their own keystore file and combine all of them into a single truststore file. Otherwise,
please follow the instructions to create your own certificates.
T he purpose of these instructions is to generate a keystore file and a truststore file for each JON Server
and JON Agent. Each keystore file will contain a single self-signed certificate that belongs to one of the
25
JBoss Operations Network 2.1 JON Agent Guide
JON Server or JON Agent entities. Each truststore file contains all the certificates belonging to every
JON Server and JON Agent.
Important
T hese instructions assume you have access to the keytool utility that comes with Sun
Microsystem's Java distribution. If you are using another vendor's Java implementation, these
instructions may or may not be exactly what you need. Please consult your vendor's
documentation on how to use their key generation tools.
For each JON Server or JON Agent, execute this command to generate its keystore file:
keytool -genkey -dname "CN=myhost.mycorp.com" -keystore myhost-keystore.dat validity 3650 -alias myhost \
-keyalg DSA -storetype JKS -keypass jonpassword -storepass jonpassword
In this example, assume one of my JON Agents will be installed on a machine whose hostname is
"myhost.mycorp.com". T his command creates and self-signs a certificate and stores it under the
alias "myhost" in the file "myhost-keystore.dat". T he certificate is good for 10 years (3650 days).
T he certificate keys were generated using the DSA algorithm and were stored in the keystore using
the JKS format. T he key itself and the keystore file have been password protected with the password
"jonpassword". It is recommended that you at least choose your own passwords when generating
your keystores.
T he important part is to make sure you set the Common Name (CN) of the Distinguished Name (the dname option) to the correct address where this keystore is to be installed. T hat is because as part
of the SSL handshake, a remote client will attempt to verify that the issuer of the certificate (as listed
in the CN) is the same name as where the certificate actually came from. Now that we have
generated a self-signed certificate for this JON Agent and stored it in a file named "myhostkeystore.dat", we can store that away for now and continue generating certificates/keystores for the
rest of the machines until we have one keystore file for each and every machine that will host a JON
Server or JON Agent. It is best to name the keystores so you remember which keystore file belongs
to which machine (hence why, in the example above, the hostname was part of the filename). Same
holds true with the alias names.
Put each self-signed certificate you generated in the previous step in a single truststore file. You do
this by exporting each certificate from each keystore and importing them all into a single truststore
file.
For each keystore file, export the self-signed certificate:
keytool -export -keystore myhost-keystore.dat -alias myhost -storetype JKS storepass jonpassword \
-file myhost-cert
T his extracts the self-signed certificate from the previously created myhost-keystore.dat file and
stores the certificate in the file "myhost-cert".
For each exported self-signed certificate, import them into a single truststore file:
keytool -import -keystore truststore.dat -alias myhost -storetype JKS -file
myhost-cert
-noprompt -keypass jonpassword -storepass jonpassword
T his command is similar to the -genkey command used to create the original keystore certificate.
However, rather than asking the keytool to generate a new certificate, we are giving it an existing
26
Chapter 2. Communications Configuration
certificate and asking keytool to place it in the truststore file. T he -keystore option defines the
name of our truststore file. -alias is the name that we assign this certificate within the truststore
file (note that for convenience, we give it the same alias under which it was found in its keystore
file).
Repeat these steps for each keystore file you created. You want to import every certificate into
the same truststore - eventually having a single truststore file that contains all of your certificates.
For example, if I had a total of 5 JON Servers and JON Agents in my JBoss ON environment, I
would have 5 separate keystore files but a single truststore.dat file that contains all 5 certificates.
When you are all done, you can use keytool to list the certificates in your truststore file, to make
sure you did them all:
> keytool -list -keystore truststore.dat -storepass jonpassword -storetype
JKS
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 2 entries
anotherhost, Feb 25, 2007, trustedCertEntry,
Certificate fingerprint (MD5):
24:D9:8A:50:BA:1B:26:08:DC:44:A8:2A:9E:8A:43:D9
myhost, Feb 25, 2007, trustedCertEntry,
Certificate fingerprint (MD5):
91:F8:78:15:21:E8:0C:73:EC:B6:3B:1D:5A:EC:2B:01
2.5.2.3. Step 3 - Distribute your Keystores and T ruststores
At this point, you have created a set of keystore files (one for each JON Server and JON Agent in your
JBoss ON environment) and a single truststore file (a duplicate copy is to be given to each JON Server
and JON Agent). You must now distribute those files to all the machines where your JON Servers and
JON Agents live. You must do so in a secure fashion and ensure that no one can steal, intercept or
otherwise manipulate your keystore/truststore files. You must also make sure that you distribute the
keystore files to the host machines that match the certificates' CN host addresses. If you mix them up
and, for example, put the "myhost" keystore file on the "anotherhost.mycorp.com" machine, the SSL
communications will fail for the JON Server or JON Agent running on "anotherhost".
2.5.2.3.1. JON Server Instructions
Each JON Server distribution has a JBossAS within it. T hat JBossAS's /data directory is the location to
store the server's keystore/truststore files (but technically, you can put them anywhere that the server
can access them. Please ensure you remember the location because you will need it for the next step).
For each JON Server, take its keystore file (make sure the keystore file has the appropriate CN value
that matches the JON Server's hostname) and store it in
$RHQ_SERVER_YOME\jbossas\server\default\data under the name keystore.dat. Make a
copy of your truststore file and place it in that same data directory as well, under the name
truststore.dat.
2.5.2.3.2. JON Agent Instructions
Each JON Agent distribution has a /data directory (the agent will create one if it doesn't yet exist). It is
the logical choice to store the agent's keystore/truststore files (but technically, you can put them
anywhere that the agent can access them. Please ensure you remember the location because you will
need it for the next step). For each JON Agent, take its keystore file (make sure the keystore file has the
appropriate CN value that matches the JON Agent's hostname) and store it in the agent's /data
directory. Make a copy of your truststore file and place it in the agent's /data directory as well.
27
JBoss Operations Network 2.1 JON Agent Guide
2.5.2.4 . Step 4 - T ell the JON Servers and Agents about their Keystores/T ruststores
Now you have to tell your JON Servers and JON Agents where your keystore and truststore files are in
addition to providing other information about those files so they can be read properly. After completing
this step, your JON Servers and JON Agents will be able to successfully authenticate themselves to
each other.
2.5.2.4 .1. JON Server Instructions
Shutdown the JON Server.
Open the /bin directory in the JON Server installation directory.
In that directory, find the file rhq-server.properties and load it into your favorite text editor.
Find the following configuration preferences used to set the server's security:
# Server-side SSL Security Configuration (for incoming messages from agents)
rhq.communications.connector.security.keystore.file=${jboss.server.data.dir}/key
store.dat
rhq.communications.connector.security.keystore.algorithm=SunX509
rhq.communications.connector.security.keystore.type=JKS
rhq.communications.connector.security.keystore.password=jonpassword
rhq.communications.connector.security.keystore.key-password=jonpassword
rhq.communications.connector.security.keystore.alias=myhost
rhq.communications.connector.security.truststore.file=${jboss.server.data.dir}/tr
uststore.dat
rhq.communications.connector.security.truststore.algorithm=SunX509
rhq.communications.connector.security.truststore.type=JKS
rhq.communications.connector.security.truststore.password=jonpassword
rhq.communications.connector.security.client-auth-mode=need
# Client-side SSL Security Configuration (for outgoing messages to agents)
rhq.server.client.security.keystore.file=${jboss.server.data.dir}/keystore.dat
rhq.server.client.security.keystore.algorithm=SunX509
rhq.server.client.security.keystore.type=JKS
rhq.server.client.security.keystore.password=jonpassword
rhq.server.client.security.keystore.key-password=jonpassword
rhq.server.client.security.keystore.alias=myhost
rhq.server.client.security.truststore.file=${jboss.server.data.dir}/truststore.da
t
rhq.server.client.security.truststore.algorithm=SunX509
rhq.server.client.security.truststore.type=JKS
rhq.server.client.security.truststore.password=jonpassword
rhq.server.client.security.server-auth-mode-enabled=true
What is being configured here is the server-side SSL security settings
(rhq.communications.connector.security...) to handle incoming messages from JON Agents and the
client-side SSL security settings (rhq.server.client.security...) to handle outgoing messages to JON
Agents. Because we are sharing the keystore and truststore for both directions, a lot of these values are
the same.
Note that the locations of the keystore and truststore files are configured by default to be in the
jbossas/server/default/data location (which is what "${jboss.server.data.dir}" resolves to) under
the names keystore.dat and truststore.dat. If, for whatever reason, you do not want to put your
keystore/truststore files in that location, you must change those values to the location of those files
making sure that the JBossAS process has read permissions to those locations.
28
Chapter 2. Communications Configuration
Important
As mentioned earlier, we will be setting up SSL authentication for both sides of the
communications channel - if you do not want this, it is in the rhq-server.properties file that
you would define which side you want to configure your SSL authentication and which side you do
not (specifically you would enable/disable the server-auth-mode-enabled and client-auth-mode
appropriately). Because it is rare that you would want to do this, we will not examine this optional
configuration.
Since we want to enable both server-side and client-side with SSL authentication, we set client-authmode to "need" (meaning, in order to process an incoming request, that request must have a valid SSL
certificate) and we set server-auth-mode-enabled to "true" (meaning any outgoing messages sent to a
JON Agent will only be sent if that JON Agent has a valid SSL certificate).
T he rest of the settings and their values should be fairly self-evident. You are simply telling the JON
Server where it can find its keystore and truststore files, the passwords to access data in those files, the
alias of the JON Server's own certificate as found in the keystore, etc.
Save the configuration file
Restart the JON Server
2.5.2.4 .2. JON Agent Instructions
You must enter the JON Agent's advanced setup mode. You can do this in one of the following ways:
Start the agent with the the command line options --setup --advanced
If the agent is already running in non-daemon mode, go to the console, enter shutdown to make
sure its down and then enter setup advanced
Answer all prompts until you get to the prompts asking about security. Because we are sharing the
keystore and truststore for both directions, a lot of these values are the same. T he prompts to look
for and their new values are:
Client Authentication Mode : need
Server Authentication Mode Enabled? : true
Incoming Secure Socket Protocol : T LS
Server-side Keystore File : data\myhost-keystore.dat
Server-side Keystore Algorithm : SunX509
Server-side Keystore T ype : JKS
Server-side Keystore Password : jonpassword
Server-side Keystore Key Password : jonpassword
Server-side Keystore Key Alias : myhost
Server-side T ruststore File : data\truststore.dat
Server-side T ruststore Algorithm : SunX509
Server-side T ruststore T ype : JKS
Server-side T ruststore Password : jonpassword
Outgoing Secure Socket Protocol : T LS
Client-side Keystore File : data\myhost-keystore.dat
Client-side Keystore Algorithm : SunX509
Client-side Keystore T ype : JKS
29
JBoss Operations Network 2.1 JON Agent Guide
Client-side Keystore Password : jonpassword
Client-side Keystore Key Password : jonpassword
Client-side Keystore Key Alias : myhost
Client-side T ruststore File : data\truststore.dat
Client-side T ruststore Algorithm : SunX509
Client-side T ruststore T ype : JKS
Client-side T ruststore Password : jonpassword
Exit the agent (effectively shutting it down) and then restart it
At this point, you have now configured your JON Servers and JON Agents to both encrypt their
messages to each other and to authenticate each other via SSL. You now be assured that no one can
neither effectively eavesdrop on your JBoss ON communications nor an infiltrator attempt to spoof itself
as a bogus JON Server or JON Agent.
2.5.2.5. Step 5 - T est Your Setup
Once you are done with the preceding steps, you can finally restart your JON Servers and JON Agents.
T hey should begin to talk to each other normally - if you have done everything correctly, you will not
notice anything different! If you want to confirm that they really are using SSL authentication, simply
remove a keystore or truststore file from either a JON Server or JON Agent and you should begin to
notice errors appear in their log files. Removing a keystore file or truststore file from a JON Agent will
prohibit that agent from being able to send and receive messages to/from the JON Server - which you
can confirm by looking at the agent log file and looking for error messages. After you have finished
testing, make sure you remember to restore the keystore/truststore files. You can test the SSL
authentication by creating another keystore for one of your JON Agents, replace that keystore with the
original keystore and try to see if that JON Agent can talk to the JON Server. Because this new keystore
has a certificate that does not exist in the JON Server's truststore, the JON Server will no longer trust
that agent and will reject its messages. In effect, you simulated an infiltrator trying to spoof a JON Agent
and the JON Server detected this security breach.
30
Chapter 3. JON Agent Advanced Setup
Chapter 3. JON Agent Advanced Setup
3.1. JON Agent Advanced Setup
T he following is a capture of the output of the full JON Agent Advanced setup (setup all). T his shows
all the preferences the advanced setup allows you to customize, with the help text of each. T his actual
run of the setup command accepted the default values of all the preferences after the help text was
requested (using !? command).
31
JBoss Operations Network 2.1 JON Agent Guide
shutdown> setup advanced
!! Full Advanced Setup !!
Answer the following questions to setup this RHQ Agent instance.
This will ask for practically all possible configuration preferences
thus allowing you to fine tune the agent via every available setting.
Please refer to the help text and documentation if you are not sure
what a setting does or what are its appropriate values.
- After each prompt, a default value will appear in square brackets.
If you press the ENTER key without providing any value, the new preference value
will be set to that default value.
- If you wish to rely on the system internal default value and not define any
preference value, enter '!*'.
- If you wish to stop before finishing all the questions but still retain those
preferences you already set, enter '!+'.
- If you wish to cancel before finishing all the questions and revert all
preferences back to their original values, enter '!-'.
- If you need help for a particular preference, enter '!?'.
Agent Name [host.mycorp.com] : !?
The name that this agent is to be known as. This must be unique across
all agents. The default is the fully qualified domain name of the host
that this agent is running on. However, you can name it anything you
want, as long as it is unique among all other agents in the system.
(rhq.agent.name)
Agent Name [host.mycorp.com] :
Agent IP Address [10.1.20.22] : !?
The IP address the agent will bind to in order to
listen for incoming messages.
(rhq.communications.connector.bind-address)
Agent IP Address [10.1.20.22] :
Agent Port [16163] : !?
The port that the agent listens to for incoming messages.
(rhq.communications.connector.bind-port)
Agent Port [16163] :
Agent Transport Protocol [socket] : !?
The transport that the agent expects incoming messages to flow over.
Typical values are socket and sslsocket.
(rhq.communications.connector.transport)
Agent Transport Protocol [socket] :
Agent Transport Parameters
[numAcceptThreads=1&maxPoolSize=303&clientMaxPoolSize=304&socketTimeout=60000&ena
bleTcpNoDelay=true&backlog=200] : !?
A set of transport parameters that is used to further configure
the agent listener. See the documentation for information on
the format of this setting and all the different values allowed
for the specific transport being used.
(rhq.communications.connector.transport-params)
Agent Transport Parameters
[numAcceptThreads=1&maxPoolSize=303&clientMaxPoolSize=304&socketTimeout=60000&ena
bleTcpNoDelay=true&backlog=200] :
RHQ Server IP Address [127.0.0.1] : !?
The IP address the RHQ Server will bind to in order to
listen for incoming messages from agents.
(rhq.agent.server.bind-address)
RHQ Server IP Address [127.0.0.1] :
32
Chapter 3. JON Agent Advanced Setup
RHQ Server Port [7080] : !?
The port that the RHQ Server listens to for incoming messages from agents.
(rhq.agent.server.bind-port)
RHQ Server Port [7080] :
RHQ Server Transport Protocol [servlet] : !?
The transport that the RHQ Server expects its messages to flow over.
Typical values are servlet, sslsocket
(rhq.agent.server.transport)
RHQ Server Transport Protocol [servlet] :
RHQ Server Transport Parameters [/jboss-remoting-servletinvoker/ServerInvokerServlet] : !?
A set of transport parameters that is used to further configure
how the agent connects to the server. Any value you provide here
will overwrite (not augment) the current value.
See the documentation for information on the format of this setting
and all the different values allowed for the specific transport being used.
(rhq.agent.server.transport-params)
RHQ Server Transport Parameters [/jboss-remoting-servletinvoker/ServerInvokerServlet] :
Client Authentication Mode [none] : !?
Client-auth mode determines if the agent should authenticate some or all
senders of incoming messages sent to the agent. If authentication is to be
performed, the agent must have a server-side truststore.
This preference value must be one of the following: none, want, need
Client Authentication Mode [none] :
Server Authentication Mode Enabled? [false] : !?
When server authentication mode is true, the agent will attempt to
authenticate the RHQ Server every time it sends a message to it. If
this is true, the agent must have a client-side truststore.
Server Authentication Mode Enabled? [false] :
Incoming Secure Socket Protocol [TLS] : !?
The secure protocol required when receiving messages from the RHQ Server.
Incoming Secure Socket Protocol [TLS] :
Server-side Keystore File [data/keystore.dat] : !?
The agent server-side keystore file that contains a key that is sent to
the RHQ Server when the server is sending a message to the agent.
This keystore contains the key that identifies the agent and is
used if the RHQ Server has its "server authentication mode" enabled.
This can be the same as the agent client-side keystore file.
Server-side Keystore File [data/keystore.dat] :
Server-side Keystore Algorithm [SunX509] : !?
The algorithm used to generate the server-side keystore key.
Server-side Keystore Algorithm [SunX509] :
Server-side Keystore Type [JKS] : !?
Identifies the server-side keystore file format implementation.
Server-side Keystore Type [JKS] :
Server-side Keystore Password [jbosson] : !?
The password to access the server-side keystore.
Server-side Keystore Password [jbosson] :
33
JBoss Operations Network 2.1 JON Agent Guide
Server-side Keystore Key Password [jbosson] : !?
The password to access the key in the server-side keystore.
Server-side Keystore Key Password [jbosson] :
Server-side Keystore Key Alias [jbosson] : !?
The alias of the key in the server-side keystore used to identify the agent.
Server-side Keystore Key Alias [jbosson] :
Server-side Truststore File [data/truststore.dat] : !?
The agent server-side truststore file contains keys of trusted
RHQ Servers that are allowed to send the agent incoming messages. This is
used if the agent's client-auth mode is set to something other than none.
This can be the same as the agent client-side truststore file.
Server-side Truststore File [data/truststore.dat] :
Server-side Truststore Algorithm [SunX509] : !?
The algorithm used to generate the server-side truststore keys.
Server-side Truststore Algorithm [SunX509] :
Server-side Truststore Type [JKS] : !?
Identifies the server-side truststore file format implementation.
Server-side Truststore Type [JKS] :
Server-side Truststore Password [jbosson] : !?
The password used to access the server-side truststore.
Server-side Truststore Password [jbosson] :
Outgoing Secure Socket Protocol [TLS] : !?
The secure protocol required when sending messages to the RHQ Server.
Outgoing Secure Socket Protocol [TLS] :
Client-side Keystore File [data/keystore.dat] : !?
The agent client-side keystore file that contains a key that is sent to
the RHQ Server when the agent sends a message to the server.
This keystore contains the key that identifies the agent and is
used if the RHQ Server has its "client authentication mode" set.
This can be the same as the agent server-side keystore file.
Client-side Keystore File [data/keystore.dat] :
Client-side Keystore Algorithm [SunX509] : !?
The algorithm used to generate the client-side keystore key.
Client-side Keystore Algorithm [SunX509] :
Client-side Keystore Type [JKS] : !?
Identifies the client-side keystore file format implementation.
Client-side Keystore Type [JKS] :
Client-side Keystore Password [jbosson] : !?
The password to access the client-side keystore.
Client-side Keystore Password [jbosson] :
Client-side Keystore Key Password [jbosson] : !?
The password to access the key in the client-side keystore.
Client-side Keystore Key Password [jbosson] :
Client-side Keystore Key Alias [jbosson] : !?
The alias of the key in the client-side keystore used to identify the agent.
Client-side Keystore Key Alias [jbosson] :
Client-side Truststore File [data/truststore.dat] : !?
34
Chapter 3. JON Agent Advanced Setup
The agent client-side truststore file contains keys of trusted
RHQ Servers to which the agent is allowed to send outgoing messages. This is
used if the agent's server authentication mode is enabled.
This can be the same as the agent server-side truststore file.
Client-side Truststore File [data/truststore.dat] :
Client-side Truststore Algorithm [SunX509] : !?
The algorithm used to generate the client-side truststore keys.
Client-side Truststore Algorithm [SunX509] :
Client-side Truststore Type [JKS] : !?
Identifies the client-side truststore file format implementation.
Client-side Truststore Type [JKS] :
Client-side Truststore Password [jbosson] : !?
The password used to access the client-side truststore.
Client-side Truststore Password [jbosson] :
The setup has been completed for the preferences at node [/jboss-on-agent/default].
RHQ Server Polling Interval [2000] : !?
If this value is larger than 0, it indicates the agent
should periodically poll the RHQ Server to make sure it is still
up or (if it was down) see when it comes back up. The value is
the number of milliseconds to wait in between polls. If the
value is 0, server polling is disabled. Server polling
is less efficient that the auto-detection mechanism,
but server polling does not use multicasting, and thus might
be the only way for the agent to detect the server.
(rhq.agent.client.server-polling-interval-msecs)
RHQ Server Polling Interval [2000] :
Enable RHQ Server Auto-Detection? [true] : !?
If true, the agent will attempt to auto-detect the RHQ Server
coming online and going offline. This is more efficient than
server polling but it requires multicast traffic to be enabled on
your network and also requires the multicast detector be enabled.
(rhq.agent.server-auto-detection)
Enable RHQ Server Auto-Detection? [true] :
Multicast Detector Multicast Address [224.16.16.16] : !?
The multicast address used to broadcast detection messages.
To be more specific, it is the IP address of the multicast group
the detector will join.
(rhq.communications.multicast-detector.multicast-address)
Multicast Detector Multicast Address [224.16.16.16] :
Multicast Detector Bind Address [127.0.0.1] : !?
The IP address that is bound by the network interface
(rhq.communications.multicast-detector.bind-address)
Multicast Detector Bind Address [127.0.0.1] :
Multicast Detector Port [16162] : !?
The port that is used to broadcast detection messages on via multicast.
(rhq.communications.multicast-detector.port)
Multicast Detector Port [16162] :
Multicast Detector Server-Down Detection Default Time Delay [5000] : !?
If no RHQ Server heartbeat message is received within this amount
of milliseconds, it will be assumed the RHQ Server has gone down.
This setting affects the timeliness of the auto-detection mechanism.
35
JBoss Operations Network 2.1 JON Agent Guide
(rhq.communications.multicast-detector.default-time-delay)
Multicast Detector Server-Down Detection Default Time Delay [5000] :
Multicast Detector Heartbeat Time Delay [1000] : !?
This is the time delay that the agent will wait before it
emits its own heartbeat message.
(rhq.communications.multicast-detector.heartbeat-time-delay)
Multicast Detector Heartbeat Time Delay [1000] :
Update Plugins at Startup [true] : !?
If true, the agent will attempt to update its current set of plugins to their
latest versions at startup. If false, the agent will not automatically update
the plugins; the agent will use its current plugins.
(rhq.agent.update-plugins-at-startup)
Update Plugins at Startup [true] :
Register With RHQ Server at Startup [true] : !?
If true, the agent will automatically attempt to register
itself with the RHQ Server when the agent starts up.
If false, you must ensure the agent is either already registered
or will be manually registered (see the register prompt command).
(rhq.agent.register-with-server-at-startup)
Register With RHQ Server at Startup [true] :
Wait for RHQ Server at Startup [5000] : !?
This defines how many milliseconds the agent should wait at
startup for the RHQ Server to be detected. If the RHQ Server
has not started up in the given amount of time, the agent will
continue initializing and expect the server to come up later.
If this is 0, the agent will not wait at all.
(rhq.agent.wait-for-server-at-startup-msecs)
Wait for RHQ Server at Startup [5000] :
Disable Native System [false] : !?
This will allow you to tell the agent to disable the native system,
thus turning off the usage of the native libraries (if they are
available on the agent platform). In fact, disabling the native system
will ensure that the native JNI libraries are not even loaded into the
agent's Java VM. You normally do not want to disable the native system
unless you have a good reason to do so. Disabling the native system will
turn off the ability of the plugins to perform auto-discovery using
process table scans and will not allow the plugins to obtain
any information from the low-level operating system resources.
(rhq.agent.disable-native-system)
Disable Native System [false] :
Server Discovery Scan Period [900] : !? T
he time in seconds that defines how often a server discovery
scan is performed. A server discovery looks for new servers
that can be imported into inventory.
(rhq.agent.plugins.server-discovery.period-secs)
Server Discovery Scan Period [900] :
Server Discovery Scan Initial Delay [10] : !?
The time in seconds before the initial server discovery scan is performed.
(rhq.agent.plugins.server-discovery.initial-delay-secs)
Server Discovery Scan Initial Delay [10] :
Service Discovery Scan Period [86400] : !?
The time in seconds that defines how often a service discovery scan is
36
Chapter 3. JON Agent Advanced Setup
performed. A service discovery scan looks for resources that were
added or removed from existing platform and server resources.
(rhq.agent.plugins.service-discovery.period-secs)
Service Discovery Scan Period [86400] :
Service Discovery Scan Initial Delay [20] : !?
The time in seconds before the initial service discovery scan is performed.
(rhq.agent.plugins.service-discovery.initial-delay-secs)
Service Discovery Scan Initial Delay [20] :
Availability Scan Period [86400] : !?
The time in seconds that defines how often an availability scan is
performed. An availability scan looks to determine what resources
are up and running and what resources have gone down.
(rhq.agent.plugins.availability-scan.period-secs)
Availability Scan Period [86400] :
Availability Scan Initial Delay [20] : !?
The time in seconds before the initial availability scan is performed.
(rhq.agent.plugins.availability-scan.initial-delay-secs)
Availability Scan Initial Delay [20] :
Measurement Collection Initial Delay [30] : !?
The time in seconds before the initial measurement collection is performed.
(rhq.agent.plugins.measurement-collection.initial-delay-secs)
Measurement Collection Initial Delay [30] :
Measurement Collection Thread Pool Size [10] : !?
This defines the number of threads within the plugin container's measurement
collection thread pool. The higher the number, the more measurements that
can be collected concurrently.
(rhq.agent.plugins.measurement-collection.threadpool-size)
Measurement Collection Thread Pool Size [10] :
Operation Invoker Thread Pool Size [10] : !?
This defines the number of threads within the plugin container's operation
invoker thread pool. The higher the number, the more operations that
can be concurrently invoked.
(rhq.agent.plugins.operation-invoker.threadpool-size)
Operation Invoker Thread Pool Size [10] :
Operation Invocation Timeout [600] : !?
This is the default timeout used for operation invocations. When a plugin
invokes an operation on a managed resource, and that invocation does not
finish with this amount of seconds, the invocation will be aborted.
Note that this is only a default; a plugin may actually override this value
by defining its own timeouts within its plugin descriptor.
(rhq.agent.plugins.operation-invocation-timeout-secs)
Operation Invocation Timeout [600] :
Content Discovery Period [10] : !?
The time in seconds that defines how often content discoveries are run.
(rhq.agent.plugins.content-discovery.period-secs)
Content Discovery Period [10] :
Content Discovery Initial Delay [30] : !?
The time in seconds before the initial content discovery is performed.
(rhq.agent.plugins.content-discovery.initial-delay-secs)
Content Discovery Initial Delay [30] :
37
JBoss Operations Network 2.1 JON Agent Guide
Content Discovery Thread Pool Size [10] : !?
This defines the number of threads within the plugin container's content
discovery thread pool. The higher the number, the more content discoveries
that can be collected concurrently.
(rhq.agent.plugins.content-discovery.threadpool-size)
Content Discovery Thread Pool Size [10] :
Command Send Timeout [0] : !?
The time in milliseconds that the agent will wait
before aborting a command. This is the amount of time in
milliseconds that the RHQ Server has in order to process commands.
This value is only the default if a command has not specified
its own timeout. A command can override this by setting its
own timeout in its command configuration, so this value may
not be used for all commands that are sent. If this value is
less than or equal to 0, there will be no default timeout
and commands will therefore be allowed to take as long as they
need (again, this is the default, individual commands may
override this and set their own timeout). While this infinite
timeout default could conceivably cause a thread to hang
waiting for a rogue command that never finishes, it also reduces
the amount of short-lived threads created by the agent
and will increase throughput, dramatically in some cases.
(rhq.agent.client.command-timeout-msecs)
Command Send Timeout [0] :
Command Send Retry Interval [15000] : !?
This is the minimum amount of time, in milliseconds, the agent
will wait before trying to resend a guaranteed command
that previously failed. This is not a guarantee of when
a command is retried - all that can be inferred is that a
command that fails to be sent will not be retried until at
least this amount of time passes.
Note: if the agent is currently waiting in this retry pause
period, the agent will not be able to be shutdown until that
retry period is over. In other words, if the agent is asked
to shutdown, it will wait for those commands waiting in this
retry interval to wake up. This is to help ensure those
commands are not lost. Keep this time period short enough
to make agent shutdowns fairly responsive but long enough
to avoid spinning the agent with continuous resending of
commands during periods of RHQ Server downtime. It is
recommended to use auto-detection or server polling in order
to automatically stop the agent from continuously
trying to retry commands during long periods of RHQ
Server downtime.
(rhq.agent.client.retry-interval-msecs)
Command Send Retry Interval [15000] :
Command Send Max Retries [10] : !?
If a guaranteed delivery message is sent, but the agent fails
to connect to the server and deliver the message, it will
always be retried. However, if the error was something other
than a 'cannot connect' error, the command will only be retried
this amount of times before the command is dropped. When this
happens, the guaranteed command will never be delivered. This
will normally happen under very odd and rare circumstances.
Also, this setting only effects asynchronous messages that are
sent with guaranteed delivery.
This setting has no effect on other messages.
38
Chapter 3. JON Agent Advanced Setup
(rhq.agent.client.max-retries)
Command Send Max Retries [10] :
Maximum Commands To Concurrently Send [5] : !?
The maximum number of commands that can be in the process
of being sent to the RHQ Server at any one time.
(rhq.agent.client.max-concurrent)
Maximum Commands To Concurrently Send [5] :
Command Queue Size [50000] : !?
The maximum number of commands that can be queued for sending to the RHQ Server.
If this is 0, then the queue is unbounded (be careful - setting this to 0
could cause the agent to use up too much memory if, for some reason,
commands are getting queued but are unable to be sent
(rhq.agent.client.queue-size)
Command Queue Size [50000] :
Queue Throttling Parameters [50:3000] : !?
If this setting is defined, it will enable queue throttling to
occur while sending commands to the server. The format is
defined as 'max-commands-per-burst:burst-period-milliseconds'
where the maximum commands per burst defines the maximum number
of commands that can be dequeued within a burst period.
The burst period defines the number of milliseconds in which the
defined maximum number of commands can be dequeued. If more
than the maximum number of commands are queued within this
time period, they will wait until the next burst period starts
before being able to be dequeued.
The maximum commands per burst must be at least 1.
The burst period must be at least 100 milliseconds.
This does not affect sending commands synchronously.
It only effects commands queued to be sent asynchronously.
(rhq.agent.client.queue-throttling)
Queue Throttling Parameters [50:3000] :
Send Throttling Parameters [100:1000] : !?
If this setting is defined, it will enable send throttling to
occur while sending commands to the server. The format is
defined as 'max-commands:quiet-period-milliseconds'
where the maximum commands defines the maximum number
of commands that will be sent before the start of a quiet
period. The quiet period defines the number of milliseconds
in which no commands should be sent. After this duration
expires, commands can again be sent, up to the maximum defined.
Note that send throttling only affects those commands that
are throttle-able. Some commands are sent as soon as
possible, regardless of the throttling settings.
To disable send throttling, set this to its internal default.
The maximum commands must be at least 1.
The quiet period must be at least 100 milliseconds.
This affects sending commands synchronously and asynchronously.
(rhq.agent.client.send-throttling)
Send Throttling Parameters [100:1000] :
Remote Stream Max Idle Time [30000] : !?
The maximum amount of milliseconds a remoted stream
is allowed to be idle before it is automatically closed and
removed from the agent listener. This means that the
39
JBoss Operations Network 2.1 JON Agent Guide
RHQ Server must attempt to access the remoted stream
every X milliseconds (where X is the value of this setting)
or that input stream will no longer be available. Note that this
does not mean the RHQ Server must read or write the
entire stream in this amount of time, it only means
the RHQ Server must make a request on the stream every
X milliseconds (be it to read or write one byte, see how many
bytes are available to be read, etc).
(rhq.communications.remote-stream-max-idle-time-msecs)
Remote Stream Max Idle Time [30000] :
Data Directory [data] : !?
Directory location where the agent will persist its data.
(rhq.agent.data-directory)
Data Directory [data] :
Plugins Directory [plugins] : !?
The directory location where the plugins can be found.
(rhq.agent.plugins.directory)
Plugins Directory [plugins] :
Command Spool File Parameters [1000000:75] : !?
This defines the parameters for the command spool file.
The spool file is where the agent persists commands that
are flagged for guaranteed delivery and need to be sent.
The format is defined as 'max-file-size:purge-percentage'.
The first number is the size, in bytes, of the maximum file
size threshold. If the spool file grows larger than this, a
purge will be triggered in order to shrink the file.
The second number is the purge percentage which indicates how
large the file is allowed to be after a purge. This is
specified as a percentage of the first parameter - the max
file size threshold. For example, if the max file size is
100000 (i.e. 100KB) and the purge percentage is 90, then when
the spool file grows larger than 100KB, a purge will be
triggered and the file will be shrunk to no more than
90% of 100KB - which is 90KB. In effect, 10KB will be freed
to allow room for new commands to be spooled. When this
occurs, unused space is freed first and if that does not
free up enough space, the oldest commands in the spool file
will be sacrificed in order to make room for the newer
commands.
The maximum file size must be at least 10000 bytes.
The purge percentage must be between 0 and 99.
(rhq.agent.client.command-spool-file.params)
Command Spool File Parameters [1000000:75] :
Compress the Spool File? [false] : !?
If this flag is true, the commands stored in the spool file
will be compressed. This can potentially save about 30%-40% in
disk space (give or take), however, it slows down the
persistence mechanism considerably. Recommended setting for
this should be false unless something on the agent deployment
box warrants disk-saving over persistence performance. The
performance hit will only appear when unusual conditions occur,
such as shutting down while some guaranteed commands have not
been sent yet or if the RHQ Server is down. It will not affect
the agent under normal conditions (while running with the RHQ
Server up and successfully communicating with the agent).
40
Chapter 3. JON Agent Advanced Setup
In those unusual/rare conditions, having performance degradation
may not be as important.
(rhq.agent.client.command-spool-file.compressed)
Compress the Spool File? [false] :
41
JBoss Operations Network 2.1 JON Agent Guide
Revision History
Revision 1-10.4 00
Rebuild with publican 4.0.0
2013-10-31
Rüdiger Landmann
Revision 1-10
Rebuild for Publican 3.0
2012-07-18
Anthony T owns
Revision 1.0-0
Wed Jan 21 2009
First Conversion from wiki to docbook
Index
F
feedback
- contact information for this manual, We need feedback
42
Sarah Meehan