Chapter 7. 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 3, 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.
7.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.
7.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.
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 |
|
Home directory location | Wherever the JAR is installed | /usr/share/jboss-on-3.3.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.3.0.GA/agent/conf
[b]
symlinked to /usr/share/jboss-on-3.3.0.GA/agent/logs
|
7.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 6.1.4, “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 6.1.4, “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.
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.
|
7.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 6.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.
7.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.
7.1.5. Enabling a repository providing the JBoss ON Agent
The JBoss ON Agent (
jboss-on-agent-3.3
) is provided on various Red Hat JBoss Enterprise Application Platform repositories, beginning with Red Hat Enterprise Linux 6 and Red Hat JBoss Enterprise Application Platform 6.
The JBoss ON Agent is provided for both 32-bit and 64-bit architectures of Red Hat Enterprise Linux 6, however is only available for 64-bit architectures from Red Hat Enterprise Linux 7. The yum package manager on Red Hat Enterprise Linux detects your system architecture when you install jboss-on-agent-3.3.
Red Hat JBoss Enterprise Application Platform repositories are enabled using the Red Hat Subscription Manager (subscription-manager):
subscription-manager repos --enable=jb-eap-EAP_version-for-rhel-RHEL_VERSION-server-rpms
Where RHEL_VERSION refers to your version of Red Hat Enterprise Linux Server (such as Red Hat Enterprise Linux Server 7).
There are two types of Red Hat JBoss Enterprise Application Platform repository: Current and Minor.
If you require a current version of Red Hat JBoss Enterprise Application Platform (and the relevant JBoss ON Agent), then EAP_version refers to the major version (such as Red Hat JBoss Enterprise Application Platform 6 or 7).
For example, to use Red Hat JBoss Enterprise Application Platform 6 on Red Hat Enterprise Linux Server 7:
subscription-manager repos --enable=jb-eap-6-for-rhel-7-server-rpms
However, if a specific minor version of Red Hat JBoss Enterprise Application Platform is required, then EAP_version refers to the minor version (such as Red Hat JBoss Enterprise Application Platform 6.2, 6.3 or 7.0).
For example, to use Red Hat JBoss Enterprise Application Platform 6.4 on Red Hat Enterprise Linux Server 6:
subscription-manager repos --enable=jb-eap-6.4-for-rhel-6-server-rpms
For more information on the Red Hat JBoss Enterprise Application Platform repositories, see the Red Hat JBoss Enterprise Application Platform Installation Guide.