JBoss Operations Network 2.

1 JON Server Guide

The JON Server that ships with JBoss Operations Network 2.0

JBoss ON Team

JON Server Guide

JBoss Operations Network 2.1 JON Server Guide The JON Server that ships with JBoss Operations Network 2.0 Edition 1
Author Copyright 2009 Red Hat, Inc. JBoss ON Team

Copyright 2009 Red Hat, Inc.. This material may only be distributed subject to the terms and conditions set forth in the Open Publication License, V1.0 or later (the latest version of the OPL is presently available at http://www.opencontent.org/openpub/). Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries. All other trademarks referenced herein are the property of their respective owners. 1801 Varsity Drive Raleigh, NC 27606-2072 USA Phone: +1 919 754 3700 Phone: 888 733 4281 Fax: +1 919 754 3701 PO Box 13588 Research Triangle Park, NC 27709 USA

The JON Server that ships with JBoss Operations Network 2.0

Preface v 1. Document Conventions ................................................................................................... v 1.1. Typographic Conventions ...................................................................................... v 1.2. Pull-quote Conventions ........................................................................................ vi 1.3. Notes and Warnings ........................................................................................... vii 2. We need feedback ........................................................................................................ viii 1. JON Server 1.1. Configuring the JON Server .......................................................................................... 1.2. Running the JON Server .............................................................................................. 1.2.1. Running on Windows ......................................................................................... 1.2.2. Running on Unix ............................................................................................... 1.3. Running the Embedded JON Agent .............................................................................. 2. Communications Subsystem A. Revision History Index 1 1 1 1 3 5 7 9 11

iii

iv

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

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows. Mono-spaced Bold Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example: To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command. The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context. Key-combinations can be distinguished from key caps by the hyphen connecting each part of a keycombination. For example: Press Enter to execute the command. Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session. The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously. If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example: File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions. Proportional Bold This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
1

https://fedorahosted.org/liberation-fonts/

Preface

Choose System > Preferences > Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). To insert a special character into a gedit file, choose Applications > Accessories > Character Map from the main menu bar. Next, choose Search > Find from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit > Paste from the gedit menu bar. The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context. Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach. Mono-spaced Bold Italic or Proportional Bold Italic Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com. The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home. To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release. Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example: When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.

1.2. Pull-quote Conventions

Two, commonly multi-line, data types are set off visually from the surrounding text.

vi

Notes and Warnings

Output sent to a terminal is set in Mono-spaced Roman 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 Mono-spaced Roman but are presented and highlighted as follows:

package org.jboss.book.jca.ex1; import javax.naming.InitialContext; public class ExClient { public static void main(String args[]) throws Exception { InitialContext iniCtx = new InitialContext(); Object ref = iniCtx.lookup("EchoBean"); EchoHome home = (EchoHome) ref; Echo echo = home.create(); System.out.println("Created Echo"); System.out.println("Echo.echo('Hello') = " + echo.echo("Hello")); } }

1.3. Notes and Warnings

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

Note
A note is a tip or shortcut or alternative approach 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 Important boxes won't cause data loss but may cause irritation and frustration.

vii

Preface

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

2. We need feedback
To see all outstanding issues regarding this guide, please visit: https://jira.jboss.org/jira/browse/JOPR If you find a typographical error in the 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.

viii

Chapter 1.

JON Server
This chapter describes the JON Server that ships with JBoss Operations Network 2.0.

1.1. Configuring the JON Server

The startup configuration settings read by the JON Server are stored in the rhqserver.properties file located in the /bin directory of the distribution. This file includes settings not persistent in the database such as those set via the GUI's Administration page. If you modify any setting in this file, you must restart the JON Server in order for the changes to take effect. Refer to the Startup Properties chapter in the Installation Guide for further information. The rhq-server.properties file defines typical server settings such as the TCP ports JON Server components listen to and the security settings for the server-agent communications subsystem. The installer sets the initial values of these variables during installation. The values are customized by you during the installation process as per your requirements. Refer to the Installation Guide for information on these properties and on running the installer.

Warning
The rhq-server.properties file also contains the database username and password. This password is not encrypted. Ensure this file is protected from unwanted access.

1.2. Running the JON Server

The JON Server is actually a customized JBossAS server located in the jbossas directory where the JON Server distribution is installed. When you start the JON Server, you are actually starting that JBossAS server instance. To run the JON Server in debug mode, modify the standard jbosslog4j.xml file appropriately (located in the jbossas/server/default/conf directory). We do not recommend modifying anything else under the jbossas directory; this could adversely affect the performance of the JON Server. Debug mode logs debug messages caused by the launcher scripts. To run the scripts in debug mode, define the environment variable RHQ_SERVER_DEBUG to any value. To disable debug mode, unset the environment variable.

1.2.1. Running on Windows

The JON Server can be run from within a console window or it can be installed as a Windows Service and run as a service.

1.2.1.1. Running in a Windows Console

The rhq-server.bat script is found in the <install-dir>/bin/ directory of the distribution. To run the JON Server in a console, execute the command rhq-server.bat console. Alternatively, open Windows Explorer and locate the <install-dir>/bin/rhq-server-console.bat file. Double click on the file to start the JON Server. This script executes the rhq-server.bat console command. The rhq-server.bat script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the JON

Chapter 1. JON Server

Server at a new JVM. The comments at the top of the rhq-server.bat file contain a detailed list of these environment variables. You do not have to set any specific variables to get the JON Server to run; sensible defaults are used.

1.2.1.2. Installing and Running as a Windows Service

When the JON Server runs as a Windows service, it runs as a particular user. This user is specified by the RHQ_SERVER_RUN_AS environment variable. The RHQ_SERVER_RUN_AS_ME variable overrides the RHQ_SERVER_RUN_AS variable and allows the JON Server to run as the current user. If neither of these two variables are set, the JON Server Windows Service runs as the System account. Both variables are explicitly mentioned here because of their security implications. All environment variables can be defined in the rhq-server.bat script. To run the JON Server Windows service as a specific user, define the RHQ_SERVER_RUN_AS variable with a value conforming to the strict Microsoft Windows format of: DOMAIN\username, for example, MYDOMAIN\john. Alternatively, define the RHQ_SERVER_RUN_AS_ME variable; no value is required. The JON Server runs as the username defined in the USERNAME environment variable. Execute the rhq-server.bat script with one of the following command line options: install - This installs the JON Server as a Windows service. At the prompt, enter the password of the user designated to run the server. The Windows service now starts the server during the system boot. You can change this behavior by modifying the wrapper configuration file described below. start - This starts the Windows service, effectively starting the JON Server. Ensure that you have run the rhq-install.bat install command first. Alternatively, start the JON Server by using the Windows Services Administrative Tool. stop - This stops the Windows Service, effectively stopping the JON Server. You must have installed and started the Windows Service first in order to stop it. Alternatively, stop the JON Server by using the Windows Services Administrative Tool instead. remove - This removes the Windows Service from your Windows operating system. If the service is running, it is first stopped. Once the service is removed, it is no longer started at boot time and you can no longer start it with the start option. status - If the service is installed, this option informs you if the server is currently running or not.

Optional Configuration Files

The JON Server Windows Service can also be modified by the service wrapper configuration file, located at <server-install-dir>\bin\wrapper\rhq-server-wrapper.conf. This file sets some of the Java Service Wrapper configuration settings. The rhq-server.bat script uses 1 the Java Service Wrapper utility to install and control the Windows Service. Before editing this file, refer to the Java Service Wrapper's property configuration documentation located at http:// wrapper.tanukisoftware.org/doc/english/properties.html. A few common settings you might be interested in modifying are: wrapper.app.parameter.# - these command line options are passed to the JON Server. Because the JON Server runs inside a JBossAS container, the options are passed on to this
1

http://wrapper.tanukisoftware.org/doc/english/download.jsp

Running on Unix

container. Each individual option and its value must be given its own wrapper configuration property, and must be placed in numerical order. Do not change any of the five default properties, wrapper.app.parameter.1; to add a new property, start with wrapper.app.parameter.6. You should not need to add or modify these properties for a standard configuration. wrapper.java.additional.# - these additional VM options are passed directly to the VM (such as -Xmx or -D). As with the wrapper.app.parameter.# properties, you must increment each option in numerical order. Do not edit the wrapper.java.additiona.1 property unless you want to point to your own log configuration file. You can add, remove, and modify other properties. For example: wrapper.java.additional.5=-XX:+DisableExplicitGC wrapper.ntservice.starttype - by default, this is set to AUTO_START. This starts the JON Server automatically at boot time. To manually start the service, change the value to DEMAND_START. There are many other Java Service Wrapper configuration properties you can set. If you are interested in learning more, refer to the Java Service Wrapper documentation at http:// wrapper.tanukisoftware.org/doc/english/properties.html. Also refer to the comments located in the rhq-server-wrapper.conf file. You can also configure the JON Server Windows Service by creating a bin\wrapper\rhq-serverwrapper.inc include file. This effectively augments the service wrapper configuration file, serverinstall-dir\bin\wrapper\rhq-server-wrapper.conf. If you want to add additional Java VM options, we recommend that you add your settings in here, as opposed to the rhq-serverwrapper.conf file. The rhq-server-wrapper.inc file augments the settings found in the rhq-serverwrapper.conf file.

1.2.2. Running on Unix

The JON Server can run from a console window or run as a service started by the init process.

Setting Environment Variables

The rhq-server.sh file, located in the <server-install-dir>/bin/ directory, contains a detailed list of the environment variables it requires to run. For most variables, sensible defaults are used and therefore do not need editing. It is important however, to set the correct path to your Java installation. Before starting the JON Server, edit the rhq-server.sh file and ensure that either the RHQ_SERVER_JAVA_HOME or the RHQ_SERVER_JAVA_EXE_FILE_PATH variable is set appropriately.

Running in a Console
To run the JON Server in a console, execute the following commands as the root user:

# cd <server-install-dir>/bin/ # ./rhq-server.sh console

Chapter 1. JON Server

Running with init.d

To ensure the JON Server is started at boot time, the rhq-server.sh script can be managed by the init process. The script must be copied to the appropriate location and the RHQ_SERVER_HOME variable must be set to the installation directory of the JON Server. The exact procedure on how to do this varies between different flavors of UNIX. The example procedure below describes this process on Red Hat Enterprise Linux 5.2.

Note
Unlike the Windows script, this UNIX script does not utilize the Java Service Wrapper utility.

Service Installation on Red Hat Enterprise Linux 5.2

The rhq-server.sh script can be placed under the /etc/init.d/ directory and managed by the service and chkconfig command. To run the JON Server as a service on Red Hat Enterprise Linux 5.2 and ensure that it starts in run level 5, follow the procedure below as the root user. Procedure 1.1. Service Installation on Red Hat Enterprise Linux 5.2 1. Copy the rhq-server.sh script into the /etc/init.d/ directory.

# cp <server-install-dir>/bin/rhq-server.sh /etc/init.d/ 2. Edit the /etc/init.d/rhq-server.sh script and set the RHQ_SERVER_HOME variable to the JON Server install directory. For example:

RHQ_SERVER_HOME=/opt/jon-server-2.1.0.GA/ 3. Edit the /etc/init.d/rhq-server.sh script and add the following lines to the top of the file, directly under #!/bin/sh. The last two parameters in the #chkconfig: 2345 95 20 line, specify the start and stop priority respectively; edit these accordingly.

#!/bin/sh #chkconfig: 2345 95 20 #description: JBoss Operations Network Server #processname: run.sh 4. Add the service to the chkconfig service management command.

# chkconfig --add rhq-server.sh # chkconfig rhq-server.sh --list 5. Ensure the service will start in run level 5.

Running the Embedded JON Agent

# chkconfig --level 5 rhq-server.sh on The JON Server service can now be managed by the service rhq-server.sh { start | stop | status } command. To start the service enter the following command:

# service rhq-server.sh start

1.3. Running the Embedded JON Agent

Warning
We do not recommend running an embedded agent in production. It is therefore not currently supported. There are some known issues with managing certain resources with the embedded agent. The JON Agent embedded within the JON Server allows you to manage the platform, other products and the JON Server itself, without having to run a separate JON Agent process on the same machine. This feature enables quick testing and demoing of JON without the need to install and run a standalone agent. To enable the embedded JON Agent, edit the bin/rhq-server.properties file and set the rhq.server.embedded-agent.enabled flag to true. We recommend defining the name of your embedded agent if there is more than one JON Server installation where at least two servers are running embedded agents. You can also enable or disable the native system for that agent. An example portion of the rhq-server.properties file is shown below.

# Embedded RHQ Agent rhq.server.embedded-agent.enabled=true rhq.server.embedded-agent.name=embedded-agent rhq.server.embedded-agent.disable-native-system=true

Chapter 2.

Communications Subsystem
JBoss ON has an internal communications subsystem that is built on top of JBoss Remoting 2 . The communications infrastructure is used by both JON Servers and JON Agents to send and receive messages. It is highly configurable, but for the most part the defaults are sensibly defined and therefore do not need any modification. Please refer to the Communications Configuration chapter in the JON Agent Guide for more information on some of the low level configuration settings applicable to both the JON Server and JON Agent. Additionally, you can set concurrency limits on the JON Server to help its communication subsystem avoid getting flooded with agent messages. These limits are described in the Concurrency Limits section in the Installation Guide. Note that in order to change these values, you must understand the relationship between the concurrency limits and the other communication settings. Important factors that you should be familiar with are listed below: If you use the default JON Server transport of servlet or sslservlet, the number of allowed incoming messages are capped at the maximum web connections allowed by the Tomcat connector (rhq.server.startup.web.max-connections). Therefore, this puts an upper limit on the global concurrency limit (rhq.communications.global-concurrency-limit). The global concurrency limit (rhq.communications.global-concurrency-limit) is the upper limit for all other concurrency limits. The global concurrency limit is the maximum number of messages that can be processed, regardless of the message type. If you switch the transport that agents use to send messages to the server from something other than servlet or sslservlet (that is, a transport other than those that send messages over the Tomcat connector) then the low-level transport parameter maxThreads caps the maximum number of messages that can be received. Refer to the Transport Parameters section in the JON Agent Guide.
1

http://labs.jboss.com/jbossremoting/

Appendix A. Revision History

Revision 1.0 Wed Jan 21 2009 Sarah Meehan smeehan@redhat.com First Conversion from wiki to docbook

10

Index
F
feedback contact information for this manual, viii

11

12