Red Hat Training

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

Chapter 6. Installing and Upgrading an Agent on a Managed Platform from the JAR File

JAR files to install the Red Hat JBoss Operations Network agent on Red Hat Enterprise Linux, Windows, Solaris, AIX, and other *nix distributions are available as a download from the JBoss ON server.
Important
This is for installing an agent on a platform which will be managed by JBoss ON. If this system will host a JBoss ON server, then install the agent as part of the server installation process, as described in Chapter 3, Installing the JBoss ON Server.
Report a bug

6.1. Before Installing the Agent

6.1.1. Verify the Parent Directory Permissions

During the update process, files are written to the directory where the agent is currently installed. This means the parent directory of the agent's install directory must be writable by the user that is running the agent.
For example, if the agent's rhq-agent-env.sh file specifies $RHQ_AGENT_HOME as /opt/rhq-agent-parent/rhq-agent, the agent must have write permissions on the /opt/rhq-agent-parent directory.
Report a bug

6.1.2. (Optional) Setting up the JRE for the JBoss ON Agent

This procedure is only required if:
  • Your default Java JRE is not compatible with the JBoss ON Agent,
  • You are required to override the JAVA_HOME environmental parameter using RHQ_JAVA_HOME,
  • The JAVA_HOME environmental parameter is incorrect or not set.
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 RHQ_JAVA_HOME environment variable to the installation directory.
    1. Open the rhq-agent-env.sh|.bat of your JBoss ON Agent install. For example: 
      vim JBossON-Agent-install-location/bin/rhq-agent-env.sh
    2. Uncomment RHQ_JAVA_HOME and edit if required.
Report a bug

6.1.3. Configuring the Java Path

The agent requires that the path to the Java home directory is explicitly set as an environment variable.
Report a bug

6.1.4. 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 5 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 6.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 it can not 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
Report a bug