Chapter 5. Installing the Agent from RPM

An RPM package is available for Red Hat Enterprise Linux systems to install the agent and, optionally, the agent service.

Important

This chapter is for installing and managing an agent on a platform which will be managed by JBoss ON.
If this system hosts a JBoss ON server, then install the agent as part of the server installation process, as described in Chapter 2, Installing the JBoss ON Server. An agent on the same machine as a JBoss ON server cannot be installed or managed through the agent RPM. It must be installed and managed using the rhqctl script.

5.1. About Agent RPMs

Installing an agent through an RPM offers a simpler and standardized installation process, which makes it possible to install agents on resources in cloud and PaaS environments or when kickstarting machines in data centers.
The JBoss ON agent RPMs can also make it easier to manage the agent more like other Linux system applications because the agent is automatically configured to function as a system service:
  • System user and group settings with appropriate permissions already set
  • System services to start, stop, and restart the agent
  • System service to change the agent's configuration
  • Upgrades using system tools
When installing the agent from the JAR file, there are several factors in the install environment that define the agent configuration, such as the installation directory and the location of the Java preferences store. Meaning, the installation directory is determined by where the JAR is unpacked. The agent user and the Java preferences location are both defined by what system user performs the installation.
Many of these settings are defined as part of the RPM setup, so the environment has minimal impact on the resulting agent configuration. This section describes some of the differences between RPM and JAR installations and some of the default configuration set by the RPM process.

5.1.1. Differences Between JAR and RPM Installations

The most notable difference is that the RPM defines the home directory and locations of important files, regardless of the location where the rpm is run or the user account (root) who initiated it.

Table 5.1. Some Differences Between JAR and RPM Installations

Configuration Area JAR Value RPM Value
Agent user Set to the system user who installs it jbosson-agent user, jbosson group
Agent service Not set jon-agent
Environment variables installDir/bin/rhq-agent-env.sh
  • /etc/init.d/jon-agent (init script) for ADDITIONAL_JAVA_OPTS
  • /usr/share/jboss-on-3.2.0.GA/agent/bin/rhq-agent-env.sh for JAVA_OPTS
Home directory location Wherever the JAR is installed /usr/share/jboss-on-3.2.0.GA/agent/
agent-configuration.xml location In the conf/ directory where the JAR is installed /etc/jboss-on/agent/[a]
Java preferences location ~/.java/default (system user Java preferences) /var/lib/jboss-on/agent/prefs/.java/.userPrefs/rhq-agent/default/
Data directory location agentInstallDir/data /var/lib/jboss-on/agent/data/
Log directory location In the logs/ directory where the JAR is installed /var/log/jboss-on/agent/[b]
Autoupgrade Enabled Disabled
[a] symlinked to /usr/share/jboss-on-3.2.0.GA/agent/conf
[b] symlinked to /usr/share/jboss-on-3.2.0.GA/agent/logs

5.1.2. The JBoss ON User

Before installing an agent JAR, one of the most critical decisions is selecting the system user as which the JBoss ON agent will run (Section 4.1.3, “Picking the Agent System User”). This has security implications for the agent process on the system, and it also affects how the user interacts with local server and application resources — which each have their own system users and permissions.
The agent RPM automatically creates a new system user with the appropriate system configuration to address security issues like directory access.

Important

The agent user still has to interact with resources. The appropriate group permissions, SELinux contexts, and other resource configuration can still affect how the agent can discover and manage a resource. Section 4.1.3, “Picking the Agent System User” outlines these considerations; if necessary, alter the system configuration to allow the agent the appropriate level of access to the resource.

Note

The agent RPM creates the jon-agent user and the jbosson group when it is installed. The user and group are not removed if the RPM is uninstalled.

Table 5.2. Agent User Configuration

Property Value
Username jbosson-agent
Group name jbosson
User ID (UID) 400
Group ID (GID) 400
User properties NOSHELL
Init script owner root
Init script user jon-agent[a]
[a] This can be edited to be any system user.

5.1.3. Service Tools and Init Script

Part of the RPM setup includes configuring the JBoss ON agent as a system service. An init script is installed for the agent at /etc/init.d/jon-agent. chkconfig is configured so that the agent starts when the system starts and runs as a daemon.
The init script includes all of the normal service management commands, as well as specific commands to manage the agent itself:
  • start
  • stop
  • restart
  • status
  • kill, which forces the agent process to stop
  • config, which runs through the agent configuration wizard again and refreshes the agent configuration with new settings
The start, stop, restart, and status commands are available when the agent is manually configured to run as a service, as described in Section 4.4, “Running the JBoss ON Agent as a Service”. However, the kill and config commands are only available with the init script provided with the agent RPM.
The agent init script, /etc/init.d/jon-agent, sets the environment variables that are set in the rhq-agent-env.sh file with a JAR installation. This init script defines the agent system user and group, the log and data directory locations, and Java options. Editing the init script can, for example, allow the agent to run as a different user or to start with different JVM settings.

Important

When the agent is installed from the RPM, the only supported way to edit the agent configuration is by running the config command or by editing the init script. Editing the rhq-agent-env.sh file or other configuration files directly is not supported.

5.1.4. Update Differences

When an agent is installed through a JAR, there is a key set in the agent-configuration.xml file that tells the agent to check for upgrades. The agent then polls the server, and if the JBoss ON server version is newer than the agent version, the agent requests updated binaries from the server.
The agent RPMs use an entirely different installation path than the agent JAR files, and an agent installed as an RPM relies on the local system tools to manage its packages. The upgrade flag, then, in the agent-configuration.xml file is turned off, to disable attempts at an autoupgrade and to allow the local system to manage the agent packages.
<entry key="rhq.agent.agent-update.enabled" value="false" />
With autoupdates disabled, the agent must be upgraded manually whenever the JBoss ON server is upgraded, to ensure that its version remains in sync with the JBoss ON server version.

5.1.5. Available Channels

Table 5.3. Available Channels for the Agent RPM

Product Name Product Version Channel Name
JBoss Enterprise Application Server (EAP) 5, x86 jbappplatform-5-i386-server-6-rpm
JBoss Enterprise Application Server (EAP) 5, x86_64 jbappplatform-5-x86_64-server-6-rpm
JBoss Enterprise Application Server (EAP) 6, x86 jbappplatform-6-i386-server-6-rpm
JBoss Enterprise Application Server (EAP) 6, x86_64 jbappplatform-6-x86_64-server-6-rpm