Search
SupportConsoleDevelopersStart a trialContact

2. General Management

download PDF
This section covers the configuration, files, and options for the JBoss Operations Network server and agents.

2.1. JBoss ON File Locations

This section covers the common files and directories by JBoss ON servers and agents. A basic reference for these files can make managing and troubleshooting JBoss ON easier.

2.1.1. JBoss ON Server File Locations

All JBoss Operations Network servers are installed in a single, user-defined server root directory. In the documentation and examples, this is called serverRoot. The directory layout within that server root directory are the same for every server. 
                           serverRoot
                               |
                              jon
                               |
      ----------------------------------------------------------
      |          |     |      |       |        |       |       |
alert-scripts/  bin/  etc/  EULA  jbossas/  LICENSE  logs/  plugins/
The directories and files that are most commonly used to managed JBoss ON servers are listed in Table 1, “JBoss ON Server Directories and Files”. The server root varies for each installation and each platform, but the layout of the JBoss ON subdirectories is the same for every platform.
Table 1. JBoss ON Server Directories and Files
Configuration Area Directory or File Location Description
Configuration directory serverRoot/bin/ Contains the server start scripts, PID files, and configuration file.
Start scripts serverRoot/bin/rhq-server{.sh|.bat} The script to start, stop, and check the status of the server.
Configuration file serverRoot/bin/rhq-server.properties The configuration file for all server settings that are not stored in the JBoss ON database.
Password hash script serverRoot/bin/generate-db-password{.sh|.bat} For a migrated server, it generates an encoded form of the database password to use in the rhq-server.properties file.
SNMP files serverRoot/etc/RHQ-mib.txt The JBoss ON MIB file to use for setting SNMP traps.
Log files serverRoot/logs/ The JBoss ON server log files are automatically created in this directory. The current log is named rhq-server-log4j.log. Older log files are named rhq-server-log4j.log.#, and the higher the number, the older the log file.
Custom plug-in deployment directory serverRoot/plugins/ The directory where custom plug-in files can be dropped for them to be automatically detected and polled by the JBoss ON server.
JBoss AS directory serverRoot/jbossas/ Contains all of the required JBoss AS client and server libraries.[a]
Server JAR files serverRoot/jbossas/default/deploy/rhq.ear/ Contains all of the JAR files used by JBoss ON servers, web interface, and clients.
Server-side plug-ins directory serverRoot/jbossas/default/deploy/rhq.ear/rhq-serverplugins/ Contains all of the JAR files for the default JBoss ON server-side plug-ins.
Agent plug-ins directory serverRoot/jbossas/default/deploy/rhq.ear/rhq-downloads/rhq-plugins/ Contains all of the JAR files for the default JBoss ON agent plug-ins.
Server-side plug-ins directory serverRoot/jbossas/default/deploy/rhq.ear/rhq-serverplugins/ Contains all of the JAR files for the default JBoss ON server-side plug-ins.
Agent package directory serverRoot/jbossas/default/deploy/rhq.ear/rhq-downloads/rhq-agent/ Contains the snapshot packages for the JBoss ON agent.
Web interface directory serverRoot/jbossas/default/work/jboss.web/localhost/ Contains the directories that hold the files for rendering the web interface.
[a] Most of the libraries and files in this directory don't relate directly to JBoss ON.

2.1.2. JBoss ON Agent File Locations

Like the server, the JBoss ON agent is installed in a single, user-defined root directory. All of the agent files and directories are under the rhq-agent/ directory in that root directory. 
                   serverRoot
                       |
                  rhq-agent/
                       |
      ------------------------------------
      |      |     |      |      |       |       
     bin/  conf/  data/  lib/  logs/  plugins/
Table 2. JBoss ON Agent Directories and Files
Configuration Area Directory or File Location Description
Start scripts serverRoot/rhq-agent/bin/ Contains the agent start scripts.
Configuration file serverRoot/rhq-agent/conf/agent-configuration.xml The configuration file for basic agent settings.
Library files serverRoot/rhq-agent/lib/ Contains the libraries used by the agent to monitor resources.
Start scripts serverRoot/rhq-agent/logs/ The JBoss ON agent log files are automatically created in this directory. The current log is named agent.log. Older log files are named agent.log.#, and the higher the number, the older the log file.
Plug-ins directory serverRoot/rhq-agent/plugins/ Contains the plug-ins used by the agent for managing resources (like editing resource configuration).

2.2. Default Server and Agent Ports

As with other servers and services, JBoss ON servers and agents communicate with each other by connecting over system ports. JBoss ON uses ports for three types of connections:
  • Server to database communication
    The server has to be able to connect to its database. The database port number depends on both the type of database and the specific configuration for the database.
  • Server to agent communication
    The server connects to an agent over a single port configured for the agent. This port is used for both standard and SSL communications between the server and agent.
  • Agent to server communication
    An agent can talk to multiple JBoss ON servers, even if they use the same port (since each server is on a different host.) The agent will use either a standard port or an SSL port to connect to the JBoss ON server, depending on the connection (transport) method that is configured. The agent will only attempt to use a single port.

Note

Servers do not talk to one another directly, so there are no ports for server-to-server links.
The default port numbers for JBoss ON connections are listed in Table 3, “Default JBoss ON Ports”. The port numbers can be changed for any of the JBoss ON services or different values can be used at installation.
Table 3. Default JBoss ON Ports
Connection Type Port Number
Server to agent 16163
Agent to server (standard) 7080
Agent to server (secure) 7443
Server to database 5432 (default PostgreSQL port)

2.3. Starting the JBoss ON Server

The JBoss ON server is actually a customized JBoss AS server, included in the JBoss ON installation, so starting the JBoss ON server means starting that JBoss instance.
The JBoss ON server can be started manually or can be configured to start and run as a system service.

2.3.1. Starting the JBoss ON Server (Basic)

The JBoss ON server process is started by running a scripting in the serverRoot/bin/ directory. There is an .sh script for Linux and Unix systems and a .bat script for Windows systems.
The simplest way to start the server is simply to run the script with the start command. This starts the server process and then exits from the script. 
serverRoot/bin/rhq-server.{sh|bat} start
Trying to start the RHQ Server...
RHQ Server (pid 27547) is starting
The rhq-server.{sh|bat} script looks for specific environment variables during its execution, especially related to the JVM to use with the JBoss AS server instance. A complete list of environment variables is given in the script itself; defaults based on the installation information are used, so most environment variables don't need to be reset.

Note

The RHQ_SERVER_JAVA_HOME environment variable must be set on Red Hat Enterprise Linux systems for the server to start. This can be set to a general value like /usr/.
The server can also be started in console mode, which prints detailed information about the server process to the terminal and leaves the script open as long as the server is running. 
serverRoot/bin/rhq-server.{sh|bat} console

Starting RHQ Server in console...
=========================================================================

  JBoss Bootstrap Environment

  JBOSS_HOME: serverRoot/jon-server-3.0.0.GA1/jbossas

  JAVA: /usr/bin/java

  JAVA_OPTS: -Dprogram.name=run.sh -Dapp.name=rhq-server -Xms1024M -Xmx1024M -XX:PermSize=256M -XX:MaxPermSize=256M -Djava.net.preferIPv4Stack=true -Djboss.server.log.dir=serverRoot/jon-server-3.0.0.GA1/logs -Djava.awt.headless=true -Djboss.platform.mbeanserver -Dsun.lang.ClassLoader.allowArraySyntax=true -Djava.util.logging.config.file=serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/conf/logging.properties  -Djava.net.preferIPv4Stack=true

  CLASSPATH: serverRoot/jon-server-3.0.0.GA1/jbossas/bin/run.jar

=========================================================================

15:51:45,955 INFO  [Server] Starting JBoss (MX MicroKernel)...
15:51:45,956 INFO  [Server] Release ID: JBoss [Trinity] 4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200807181417)
15:51:45,957 INFO  [Server] Home Dir: serverRoot/jon-server-3.0.0.GA1/jbossas
15:51:45,957 INFO  [Server] Home URL: file:serverRoot/jon-server-3.0.0.GA1/jbossas/
15:51:45,957 INFO  [Server] Patch URL: null
15:51:45,958 INFO  [Server] Server Name: default
15:51:45,958 INFO  [Server] Server Home Dir: serverRoot/jon-server-3.0.0.GA1/jbossas/server/default
15:51:45,958 INFO  [Server] Server Home URL: file:serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/
15:51:45,958 INFO  [Server] Server Log Dir: serverRoot/jon-server-3.0.0.GA1/logs
15:51:45,958 INFO  [Server] Server Temp Dir: serverRoot/jon-server-3.0.0.GA1/jbossas/server/default/tmp
15:51:45,958 INFO  [Server] Root Deployment Filename: jboss-service.xml
15:51:46,183 INFO  [ServerInfo] Java version: 1.6.0_15,Sun Microsystems Inc.
15:51:46,183 INFO  [ServerInfo] Java VM: Java HotSpot(TM) Server VM 14.1-b02,Sun Microsystems Inc.
15:51:46,184 INFO  [ServerInfo] OS-System: Linux 2.6.18-164.15.1.el5,i386
15:51:46,377 INFO  [Server] Core system initialized
....

2.3.2. Running the JBoss ON Server as a Service

The JBoss ON server can be configured to run as a service, managed with systems tools, on both Red Hat Enterprise Linux and Windows.
2.3.2.1. Configuring the JBoss ON Server as a Service on Red Hat Enterprise Linux
The rhq-server.sh script can be managed by the init process so that the server starts automatically when the system boots. This also allows the server process to be managed by services like service and chkconfig.
  1. Copy the rhq-server.sh script into the /etc/init.d/ directory. 
    cp serverRoot/bin/rhq-server.sh /etc/init.d/
  2. Edit the /etc/init.d/rhq-server.sh script to set the RHQ_SERVER_HOME variable to the JBoss ON server install directory and the RHQ_SERVER_JAVA_HOME variable to the appropriate directory for the JVM. For example: 
    RHQ_SERVER_HOME=serverRoot/jon-server-3.0.0.GA1/
    RHQ_SERVER_JAVA_HOME=/usr/
  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. 
    #!/bin/sh
#chkconfig: 2345 95 20   
#description: JBoss Operations Network Server
#processname: run.sh
    The last two numbers in the #chkconfig: 2345 95 20 line specify the start and stop priority, respectively, for the JBoss ON server.
  4. Add the service to the chkconfig service management command, and verify that it was added properly. 
    chkconfig --add rhq-server.sh
chkconfig rhq-server.sh --list
  5. Set the rhq-server.sh service to run at run level 5. 
    chkconfig --level 5 rhq-server.sh on
Once the init scripts and chkconfig files are updated, then the JBoss ON server can be started and stopped using the servicecommand. The status of the process can also be checked. 
service rhq-server.sh {start|stop|status}
2.3.2.2. Configuring JBoss ON as a Windows Service
The rhq-server.bat script has an installation option that installs the script as a Windows service. Once installed, the JBoss ON server can be started, stopped, and managed through Windows tools (Add and Remove Programs and Services) or through the rhq-server.bat script.
  1. Set the environment variable to run the Windows service as.
    Every Windows service has to run as some system user. There are two environment variables in the rhq-server.bat script that set the user to use:
    • RHQ_SERVER_RUN_AS sets any Windows user to be the JBoss ON server user. The username given here must be in the standard Windows format, DOMAIN\user, such as EXAMPLEDOMAIN\jsmith.
    • RHQ_SERVER_RUN_AS_ME sets the server to run as whoever the current user is. This overrides the RHQ_SERVER_RUN_AS, if both as set.
    If neither environment variable is set, then the JBoss ON server runs as the system account.
  2. Run the rhq-server.bat script with the install option to set up the service. This prompts for the password of whatever user account is used for the JBoss ON service. 
    serverRoot\bin\rhq-server.bat install
After the service is set up, the JBoss ON server can be started or stopped using Windows administrative tools or by using any of the options in Table 4, “rhq-server.bat Options” with the script.
Table 4. rhq-server.bat Options
Option Description
start Starts the server service.
stop Stops the server service.
status Prints the current status (running or stopped) of the service.
remove Removes, or uninstalls, the JBoss ON server service.
The JBoss ON server Windows service can be modified by changing or adding parameters in the service wrapper configuration file, serverRoot\bin\wrapper\rhq-server-wrapper.conf. Table 5, “Common Wrapper Properties” lists some of the wrapper properties that are most commonly edited.

Note

Before editing the wrapper file, check out the list of properties in the Java Service Wrapper documentation at http://wrapper.tanukisoftware.org/doc/english/properties.html.
Table 5. Common Wrapper Properties
Parameter Description
wrapper.app.parameter.# Passes command-line options to the server (the JBoss AS container). Each individual option and its value must be given its own wrapper configuration property and must be placed in numerical order.

Important

Do not change any of the five default properties, wrapper.app.parameter.1. The number for new properties must begin at 5.
wrapper.java.additional.# Passes additional options to the virtual machine, such as -Xmx or -D. Increments the parameters upward numerically.

Important

Do not edit the wrapper.java.additiona.1 property unless you want to point to your own log configuration file. Any other properties can be added, removed, or modified.
For example: 
wrapper.java.additional.5=-XX:+DisableExplicitGC
wrapper.ntservice.starttype Sets the start type, either automatically when the system boots (AUTO_START) or manually (DEMAND_START).
Alternatively, the wrapper service can be configured by creating a wrapper include file, in the serverRoot\bin\wrapper\rhq-server-wrapper.inc. An include file augments the service wrapper configuration file and is the recommended way to add more Java VM.

2.4. Starting the JBoss ON Agent

The JBoss ON agent can be started manually or can be configured to start and run as a system service.

Important

The agent's configuration is determined by what user is running the agent. If the agent is run as one user and then later run as another user, the agent will have a different configuration that second time because it will use a different backing store for its configuration settings.
This means that if one user is used to configure the agent when it is installed, that same user must be used to run the agent subsequently, or the agent will apparently lose its configuration and need to be reconfigured under the new user.
The agent configuration backing store is described in Section 6.8, “Managing the Agent's Persisted Configuration”.

2.4.1. Starting the JBoss ON Agent (Basic)

The agent is started and runs using a script in the agent's bin/ directory. Unlike the server start script, which starts the server process and then exits the script, the agent script remains open, with a prompt to accept further input if necessary. (Usually, the script can simply be started and left to run in the background.) 
/opt/rhq-agent/bin/rhq-agent.sh

RHQ 3.0.0-SNAPSHOT [cda7569] (Tue Apr 13 13:39:16 EDT 2011)
>
Most of the time, the JBoss ON agent can run without any additional options or settings. All of the available options for the rhq-agent.sh script are listed in Table 13, “Options for the rhq-agent.sh Script”. Additional configuration options can be set by editing the rhq-agent-env.sh script file.

Note

If there are any errors when starting the JBoss ON agent, run the agent start script with the --cleanconfig to wipe the previous agent configuration and start fresh.

2.4.2. Running the Agent as a Windows Service

Important

The agent does not prompt for the configuration when it is started as a service. The agent must either be pre-configured or have already been started once and the configuration entered. Both options are described in the Installation Guide.
  1. Edit the rhq-agent-wrapper.bat script and set the environment variable to define the system user as whom the init script will run. There are two options:
    • RHQ_AGENT_RUN_AS explicitly sets the user account name. This must match the format of a Windows user account name, DOMAIN\username.
    • RHQ_AGENT_RUN_AS_ME forces the agent to run as whoever the current user is; this uses the format . \ %USERNAME %. If both environment variables are defined, this variable overrides RHQ_AGENT_RUN_AS.

    Note

    Before setting RHQ_AGENT_RUN_AS_ME or RHQ_AGENT_RUN_AS, make sure that the given user actually has permission to start services. If necessary, assign the user the appropriate rights. Assigning rights is covered in the Windows documentation.
    If neither variable is set, the agent init script runs as the System user.
    Other available environment variables are listed and defined in the comments in the rhq-agent-wrapper.bat script.
  2. Run the rhq-agent-wrapper.bat script to install the init script as a service. Use the install command to install the init script.
  3. When prompted, fill in the password for the system user as whom the service will run.
The agent service starts automatically when the Windows system boots. The service can be started or stopped through the Windows Services Administrative Tools.
The agent service can also be started and stopped through the rhq-agent-wrapper.bat script using the start and stop commands. The status command shows whether the agent init script is installed as a service and whether it is running. The remove command removes the agent init script as a service.
The JBoss ON agent Windows scripts use the Java Wrapper Service to control the service. A configuration file, agentRoot\bin\wrapper\rhq-agent-wrapper.conf, contains the service configuration properties. These are standard wrapper service properties; more information is available at http://wrapper.tanukisoftware.org/doc/english/properties.html.
There are some common properties to edit to custom the service:
  • wrapper.app.parameter.# set command-line options to pass to the agent. These are the same options listed in Section 6.2, “Working with the Agent Command Prompt”. Each option requires its own configuration property. Properties must be placed in numeric order and the first two properties (wrapper.app.parameter.1 and wrapper.app.parameter.2) are reserved. Start with wrapper.app.parameter.3.
  • wrapper.java.additional.# set additional JVM options that are passed directly to the VM, corresponding to the -D and -X options. These also must be incremented numerically. wrapper.java.additional.1 always specifies the log configuration file.
  • wrapper.ntservice.starttype sets when to start the service. The default is AUTO_START, which starts the service when the system boots. To start the service manually, the value is DEMAND_START.

2.4.3. Running the Agent as a Daemon or init.d Service

Important

The agent does not prompt for the configuration when it is started as a service. The agent must either be pre-configured or have already been started once and the configuration entered. Both options are described in the Installation Guide.
The agent's configuration is determined by what user is running the agent. If the agent is run as one user and then later run as another user, the agent will have a different configuration that second time because it will use a different backing store for its configuration settings.
This means that if one user is used to configure the agent when it is installed, that same user must be used to run the agent subsequently, or the agent will apparently lose its configuration and need to be reconfigured under the new user.
The agent configuration backing store is described in Section 6.8, “Managing the Agent's Persisted Configuration”.
Once the agent is configured (or pre-configured), the agent can be started in two ways. The rhq-agent.sh script starts the agent and opens the command console. The rhq-agent-wrapper.sh script simply starts the agent daemon and exits. Both methods can have additional environment variables configured through the rhq-agent-env.sh script file.
The daemon can be started and run as a system service. On Red Hat Enterprise Linux, this is done by configuring /etc/init.d and then installing it using chkconfig. For Solaris and other Unix systems, this is done by configuring /etc/init.d and then using other system tools to set up the service.
  1. Make sure the agent is fully set up.
  2. Open the rhq-agent-env.sh file.
  3. Uncomment and configure the required environment variables for the agent's bin directory, the JDK directory, and the PID directory (which must be writable by the agent user). 
    RHQ_AGENT_HOME=agentRoot/rhq-agent/bin/
export RHQ_AGENT_JAVA_HOME=/usr
PIDFILEDIR=/var/run

    Note

    When setting the PIDFILEDIR on Red Hat Enterprise Linux, edit the pidfile setting in the rhq-agent-wrapper.sh script file. The wrapper script value is used by chkconfig.
  4. Set any of the optional environment variables.
    • RHQ_AGENT_DEBUG enables debug logging.
    • RHQ_AGENT_JAVA_EXE_FILE_PATH specifies a Java executable.
    • RHQ_AGENT_JAVA_OPTS passes settings to the agent JVM.
    • RHQ_AGENT_ADDITIONAL_JAVA_OPTS passes additional Java options to the JVM.
  5. Log into the system as root.

    Important

    The rest of this procedure describes how to configure the agent init script as a service on Red Hat Enterprise Linux. For other Unix systems, follow a similar procedure that corresponds to the specific platform.
  6. Make sure the wrapper script is executable. 
    [root@server rhq-agent]# chmod a+x agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh
  7. Symlink the rhq-agent-wrapper.sh file to /etc/init.d/. For example: 
    # ln -s agentRoot/rhq-agent/bin/rhq-agent-wrapper.sh /etc/init.d/rhq-agent-wrapper.sh

    Important

    On Solaris, symlinking the agent script file requires invoking readlink in rhq-agent-wrapper.sh. readlink is not supplied by default in some Solaris installations. Solaris users must download readlink from a source such as Sunfreeware.
  8. Register rhq-agent-wrapper.sh with chkconfig. 
    # /sbin/chkconfig --add rhq-agent-wrapper.sh
  9. Enable the agent service to run at boot time and have it stop gracefully at when the system shuts down. 
    # /sbin/chkconfig rhq-agent-wrapper.sh on
If the agent service should not be started when the system boots, turn the script off in chkconfig: 
# /sbin/chkconfig rhq-agent-wrapper.sh off

2.4.4. Restarting the Agent and the JVM

The agent can be restarted without taking down the agent JVM process. It is also possible to restart both the agent and its JVM.
The agent is managed through a plug-in container managed by the JBoss ON server. The container loads and manages the lifecycle of all agents. Restarting the plug-in container restarts the agent and all its components without destroying the JVM.
  1. Select the Resources menu in the top navigation bar, and select the Servers menu item.
  2. Click the agent resource in the list.
  3. Click the Operations tab.
  4. Select and launch the Restart task.
Alternatively, both the agent and its JVM can be restarted (this can be useful if, for instance, the launcher script or the JVM options have been edited).
  1. Select the Resources menu in the top navigation bar, and select the Servers menu item.
  2. Click the agent resource in the list.
  3. Navigate to the launcher script child resource beneath the agent.
  4. Click the Operations tab for the launcher script resource.
  5. Select and launch the Restart task.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.