8.2. Installing the Agent from JAR File

  1. Point your browser to the download URL on the server. For example:
    http://server.example.com:7080/agentupdate/download
    Save the agent binary update .jar in a directory where you want to install the agent. The file you save should have a .jar extension.
  2. Copy the agent update binary .jar you downloaded from the JBoss ON server to the directory.
  3. Install the JAR:
    java -jar downloaded_agent_jar_file.jar --install
    This will tell the agent update binary to extract the JBoss ON agent distribution and install a fresh copy of it in the rhq-agent subdirectory.

    IMPORTANT

    Do not install the agent in a directory with spaces in the name, such as C:\Program Files.
    Installing the agent in a directory with spaces in the pathname can cause problems for the agent establishing a connection with certain types of resources, including some JBoss services.
  4. Start the agent to launch the setup process.
    agentRoot/rhq-agent/bin/rhq-agent.sh

    TIP

    It is possible to skip the setup wizard by submitting the configuration all at once. Section 8.3, “Using an Answer File for the Agent Installation” has the details for setting up an file that can pass the configuration directly to the agent installer.
  5. As prompted, supply the information to configure the agent and the server connection.
    [Agent Name] agentdomain.example.com
    [Agent Hostname or IP Address] agentdomain.example.com
    [Agent Port] 16163
    [JON Server Hostname or IP Address] server.example.com
    [JON Server Port] 7080
    native enable
    • The agent name must be unique among all agents in the JBoss ON deployment. By default, the name is the fully-qualified domain name of the host machine.
    • The port is the one that the agent uses to listen for incoming messages from the server. This is rhq.agent.server.bind-port in the configuration file, if the default value isn't used.
    • The server hostname and port are used by the agent to connect to a server to register itself with the JBoss ON system. This is not necessarily the primary server that the agent will use after registration. In the configuration file, these are rhq.agent.server.bind-address and rhq.agent.server.bind-port
    The full list of parameters, including advanced setup options, are listed in Table 8.2, “All Options Available During Advanced Setup”.
  6. Configure the agent as a background service, as in Section 8.4, “Running the JBoss ON Agent as a Service”.
Once the agent is configured, it persists its configuration in the Java Preferences backing store. Once this happens, agent-configuration.xml is no longer needed or used. Editing agent-configuration.xml will no longer have any effect on the agent, even after restarting the agent. To pick up changes to the agent-configuration.xml file, the agent must be restarted with the --cleanconfig command line option or the configuration must be reloaded with the config --import agent prompt command.

IMPORTANT

If the agent fails to register with the server and seems to hang after outputting the message The agent does not have plugins - it will now wait for them to be downloaded... or otherwise does not work property after configuring it, please check the agent log file for error messages (agentInstallDir/logs/agent.log).
Typically, problems occur when the agent binds to an IP address or hostname that is not resolvable or accessible by the JBoss ON servers.
Similarly, make sure all of the JBoss ON servers' public endpoint addresses are resolvable by the JBoss ON agent. The JBoss ON server that is entered for an agent to register with may not be the same one that the agent uses as its primary server; it depends on the high availability configuration. If the agent cannot contact its server, then it fails to start properly.

Table 8.2. All Options Available During Advanced Setup

Setup Option Description Normal or Advanced Setup
Agent Hostname or IP Address The address that the binds to to listen for messages from the server. This is usually the same as the address that the JBoss ON server uses to connect to the agent; if the addresses are different because of the network environment, then transport parameters must be set to resolve the address. Normal
Agent Port The port number that the agent listens on. As with the IP address, this is usually the same as the port configured for the servers to use to connect to agents, but if these ports are different because of the network environment, then transport parameters must be set to resolve the port. Normal
Agent Transport Protocol Sets the protocol that the agent expects to use to receive incoming messages from the server. This is usually socket or sslsocket. Advanced
Agent Transport Parameters Sets transport parameters to append to the end of the locator (URL-style address) used by the remoting framework for agent-server connections. Advanced
RHQ Server Hostname or IP Address Gives the IP address or hostname of the primary server that the agent communicates with. This information must be the same as the hostname or IP address that is configured in the JBoss ON server configuration. Normal
RHQ Server Port Gives the port number of the primary server that the agent communicates with. This information must be the same as the port number that is configured in the JBoss ON server configuration. Normal
RHQ Server Transport Protocol Sets the transport protocol that the agent uses for outgoing messages to the JBoss ON server. This information must be the same as the transport method that the server is configured to expect in its configuration preferences. Advanced
RHQ Server Transport Parameters Gives additional transport parameters that are to be used when the agent connects to the primary JBoss ON server. Since this is used to connect to the server, these parameters must be the same as the transport parameters set in the JBoss ON server configuration. These settings are especially important if the JBoss ON agent needs to connect to a different host or port than what the JBoss ON server actually binds to. Advanced
Command Send Timeout Sets the timeout period, in milliseconds, that the agent waits before aborting an attempt to send a command. This is essentially the amount of time that the JBoss ON server has in order to process commands and return its results. Both this timeout and any timeout period set in the transport parameters are enforced, so these should be the same (if server transport parameters are given). A setting of zero (0) means that there is no timeout period. Advanced
Command Send Retry Interval Sets the minimum amount of time, in milliseconds, the agent waits before trying to resend a guaranteed command that previously failed. Advanced
Command Send Max Retries Sets the maximum number of times that an agent attempts to resend a guaranteed delivery command that failed. Any command that fails with the message cannot connect will be retried infinitely, until the send succeeds. For any other error, the agent retries the send until it hits this limit and drops the command. Advanced
Maximum Commands To Concurrently Send Sets the maximum number of commands the agent can send to the server at any one time. If the clientMaxPoolSize setting is passed in the JBoss ON server URI transport parameters, its value must be the same as this value. Advanced