5.6. Upgrading the Agent RPM

The RPM with the agent packages installs an agent on a managed platform. That agent can then be upgraded using the latest agent RPM.
If an agent was installed on the same system as a JBoss ON server, that agent cannot be upgraded or managed through the agent RPM or the configured system tools. That agent must be converted to work with the JBoss ON server and its rhqctl tool.

5.6.1. Upgrading the Agent RPM on a Managed System

Important

This section is for upgrading an agent on a platform which will be managed by JBoss ON.
If this system hosts a JBoss ON server, then migrate the agent as part of the server installation process, as described in Section 5.6.2, “Migrating an Agent on a JBoss ON Server Machine”. 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.
  1. Configure the yum repos to include the JBoss ON channel (as listed in Table 5.3, “Available Channels for the Agent RPM”). For example:
    [root@server ~]# yum-config-manager --enable jbappplatform-6-x86_64-server-6-rpm
  2. Use yum to upgrade the package.
    [root@server ~]# yum upgrade jboss-on-agent
It is also possible to download the packages from the Customer Portal and then upgrade them using the rpm -U command:
[root@server ~]# rpm -Uvh jboss-on-agent-3.2.0.GA.el6.noarch.rpm

5.6.2. Migrating an Agent on a JBoss ON Server Machine

In JBoss ON 3.1.x versions, an agent was installed and managed independently of any installed JBoss ON server, even if they were on the same system. This meant that an agent could be installed from an RPM on a system which hosted a JBoss ON server, as well as a managed platform.
However, starting in JBoss ON 3.2, any agent installed on the same system as a JBoss ON server is installed and managed in tandem with the server, using the same installation packages and management script (rhqctl). This means that agents on a JBoss ON server machine cannot be installed from an RPM.
For existing agent installations, the agent must be migrated to the new management scripts and configuration.

Note

This migration script is provided as a convenience for skilled administrators. For assistance, contact Red Hat support services.
  1. Install a new JBoss ON 3.2 server or upgrade a server to JBoss ON 3.2.
  2. Get the agent name, token, bind address, and server bind address for the agent.
    1. Log into the JBoss ON server UI.
    2. Click the Administration tab in the top menu.
    3. In the Topology box on the left, click the Agents link.
    4. Click the name of the agent to be migrated in the list.
    5. The Agent Details area lists all of the required information. This agent information must be coped into the agent-configuration.xml file to migrate the agent instance.
  3. Copy the existing agent-configuration.xml file to the new agent location, agentRoot/rhq-agent/conf/agent-configuration.xml.
  4. Update the agent-configuration.xml properties for the agent identity information. For example:
    <entry key="rhq.agent.name" value="agent-01" />
    <entry key="rhq.agent.security-token" value="abcd1234" />
    <entry key="rhq.agent.server.bind-address" value="server.example.com" />
    <entry key="rhq.communications.connector.bind-address" value="1.1.1.1" />
    UI Field Name Configuration File Property
    Agent Name rhq.agent.name
    Token rhq.agent.security-token
    Address rhq.agent.server.bind-address
    Current Server rhq.communications.connector.bind-address
  5. Stop the old agent process.
    [jsmith@server ~]$ sudo service jon-agent stop
  6. Copy this example script, and fill in the location for the old agent installation, the updated configuration file, and the new server in the agent-configuration-migrate.sh script.
    ###### agent-configuration-migrate.sh #########
    #!/bin/sh
    #	
    #
    # Note: Assumes and installs agent into default location. Modify steps as
    necessary
    #       if this is not true.
    ######################################################################
    
    #Ex. OLDER_RPM_AGENT_INSTALL=/usr/share/jboss-on-3.1.2.GA/agent
    OLDER_RPM_AGENT_INSTALL=
    
    #Ex. AGENT_MIGRATION_CONFIG_LOCATION=/tmp/agent-migration.xml  For security
    consider using $(mktemp) if you automate this further.
    AGENT_MIGRATION_CONFIG_LOCATION=
    
    #Ex. NEWEST_SERVER_LOCATION=/opt/jon/jboss-on-3.2.0.GA . Note bin, etc,
    modules are immediate sub directories.
    NEWEST_SERVER_LOCATION=
    
    #Install newer native agent including older agent configuration details.
    #NOTE: new agent will be installed to default location. Modify the following
    line accordingly
    $NEWEST_SERVER_LOCATION/bin/rhqctl install --agent --agent-config
    $AGENT_MIGRATION_CONFIG_LOCATION
    
     # Echo next steps to complete migration.
     echo -e "\n If no errors, then migration of older agent configuration was
     successful."
     echo Ex. Additional environment variables added to old agent.
     echo -e "\t i) (if necessary) Merge $OLDER_RPM_AGENT_INSTALL/bin/*.sh with
     $NEWEST_SERVER_LOCATION/../rhq-agent/bin/*.sh."
     echo -e "\t ii)(if necessary) Manually and carefully merge old and new agent
     log settings."
     echo -e "\t iii)Continue JON server upgrade. Ex. \n '
     $NEWEST_SERVER_LOCATION/bin/rhqctl upgrade --from-server-dir (insert older
     jon server directory) --run-data-migrator do-it '"
     echo    "iv)Start all desired components. Ex.'
     $NEWEST_SERVER_LOCATION/bin/rhqctl start'"
     echo    "v)Verify migration and remove intermediate migration
     scripts/files.'"
     echo "Done."
  7. Run the migration script.