Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

Chapter 8. Installing and Upgrading the Agent from the JAR File

JAR files to install the JBoss Operations Network agent on Red Hat Enterprise Linux, Windows, Solaris, AIX, and other *nix distributionsare available as a download from the JBoss ON server.

8.1. Before Installing the Agent

8.1.1. Setting up the JRE for the JBoss ON Agent

The JBoss ON agent requires either Java 6 or Java 7 JRE.
  1. Download and install the appropriate version of the JRE, if necessary.
  2. Set the JAVA_HOME environment variable to the installation directory.
    1. Open the .bashrc for the system user that will run JBoss ON. For example: 
      vim /home/jon/.bashrc
    2. Add a line to set the JAVA_HOME environment variable to the specific JRE directory. For example: 
      export JAVA_HOME=/usr/lib/jvm/jre-1.6.0-openjdk/bin/java/
  3. Set the system to use the correct version of the JRE using the system alternatives command. The selected version has the *+ symbols by it. 
    /usr/sbin/alternatives --config java 

There are 5 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-sun/bin/java
   2           /usr/lib/jvm/jre-1.4.2-gcj/bin/java
   3           /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 4           /usr/lib/jvm/jre-1.6.0-openjdk/bin/java
   5           /usr/lib/jvm/jre-1.6.0-bea/bin/java

Enter to keep the current selection[+], or type selection number:

8.1.2. Picking the Agent System User

Before installing the agent, plan what system user and group to use to run the agent. The given user can have an impact on how resources are discovered and how they should be configured for management.
The common types of servers which JBoss ON manages are:
  • JBoss EAP servers
  • PostgreSQL databases
  • Tomcat servers
  • Apache servers
  • Generic JVMs
For the agent to be able to discover a resource requires, at a minimum, that the agent have read access to that resource's configuration. Some resource types may require more than just read access. For JBoss EAP resources, for example, the agent must have read permissions to the run.jar file, plus execute and search permissions for every directory in the path to the run.jar file.
Read access or even root access may not be sufficient for some resource types. Tomcat servers can only be discovered if the JBoss ON agent and the Tomcat server are running as the same user. The same is true for JVMs and JMX servers with the attach API.
The system user which the agent runs as impacts several common agent tasks:
  • Discovery
  • Deploying applications
  • Executing scripts
  • Running start, stop, and restart operations
  • Creating child resources through the JBoss ON UI
  • Viewing and editing resource configuration
There is a general assumption that the agent runs as the same user as the managed resources, and this is the easiest option to manage resources effectively.

Important

While it is possible to run the JBoss ON agent as the root user, and in some limited contexts that may be the simple choice, consider the security implications of running a service as root before setting up the agent.
Generally, services should be run with the least amount of access required to perform their operations. This is because if a service is ever compromised, its access permissions can be exploited by an attacker.
The Red Hat Enterprise Linux Security Guide contains a section on security guidelines and links to security planning documents. There are similar recommendations in the Windows documentation.
When the JBoss ON agent is installed from the agent installer JAR file, the system user and group who own the agent installation files is the same user who installs the JAR. So, a special system user can be created or selected, and then the agent can be installed by that user.
If the agent and the resource are run as different users and the agent needs to perform some actions as the resource user, there are a few configuration options, depending on what needs to be done:
  • Configure scripts or operations to run using sudo. For long-running operations, such as starting a service or a process, the user which executes the script should be the same as the resource user because that user will have the proper authorization and permissions.
  • Set start script environment variables to use the resource's principal and credentials, if available.
  • For JVM or JMX servers. Select the connection configuration based on the user settings. For different users, use JMX remoting. For the same user, use either JMX remoting or the attach API.

Table 8.1. Cheat Sheet for Agent and Resource Users

Resource User Information
PostgreSQL No effect for monitoring and discovery.
The agent user must have read/write permissions to the PostgreSQL configuration file for configuration viewing and editing.
Apache No effect for monitoring and discovery.
The agent user must have read/write permissions to the Apache configuration file for configuration viewing and editing.
Tomcat Must use the same user or can't be discovered
JMX server or JVM Different users are fine when using JMX remoting; cannot be discovered with different users and the attach API
JBoss AS/EAP Different users are all right, but requires read permissions on run.jar and execute and search permission on all ancestor directories for run.jar