Preconfiguring the Agent

When the agent starts up, it will prompt you for some initial configuration preference values. If you want to prepackage your own agent distribution with a custom set of preset configuration preferences, you can edit agent-configuration.xml (located in any agent's /conf directory) and set all the preferences to your own values. Doing this will allow a new agent to start up without asking the setup questions on the console. This allows you to deploy agents without requiring administrators to manually answer the setup questions, providing the ability for more automated agent installs.

Preparing the Agent Configuration

To make sure an agent knows it is already preconfigured and does not have to prompt the user the first time it starts up, edit a agent-configuration.xml and be sure to set the configuration preference rhq.agent.configuration-setup-flag to "true". When this is true, the agent will assume it is fully configured and will not ask setup questions when it starts up. (note that you may wish to distribute agent configuration files with only a subset of configuration preferences set and rely on each agent's startup setup mechanism to finish its configuration - in this case, you'll want to leave this as false and let the user fill in the remaining configuration preference values then; of course, this still requires an administrator to answer the setup questions at the console)

You can not set rhq.agent.configuration-setup-flag to true if the agent's fully qualified domain name can not be determined. This is typically not an issue but it should be noted that the FQDN will be used as the agent name in this type of preconfigured installation.

You can not set rhq.agent.configuration-setup-flag to true if the agent's default IP address is not reachable by the RHQ Server (or all of the servers in a RHQ High Availability cloud). The agent's default IP address will be the default value used for the agent public endpoint that all RHQ Servers will use to communicate with the agent.

Note that the following properties found in agent-configuration.xml define the RHQ Server to be contacted by the RHQ Agent when it needs to perform its initial registration. These must be preconfigured appropriately in agent-configuration.xml:

• rhq.agent.server.transport
• rhq.agent.server.bind-address
• rhq.agent.server.bind-port

This address points to the "Registration Server" - in other words, the RHQ Server that the Agent will talk to when it needs to initially register. If this bind address is not specified, the default will be defined by looking up the name "rhqserver" in DNS. If a host is found with that alias, it will be used (RHQ 2.3 and below did not have this feature) . localhost will be used as the fallback default. Also note that this Registration Server is not necessarily the same server the agent will continue to use as its primary server - for more details on why this is, please read about failover lists.

The following property defines the agent endpoint port and must be set appropriately in agent-configuration.xml if the default of port 16163 is not to be used:

• rhq.communications.connector.bind-port

The agent-configuration.xml is fully commented and can be inspected for a variety of other configuration options (e.g. secure SSL communications among other things).

Building Your Own Preconfigured Agent Bundle

After you have preconfigured a agent-configuration.xml for all of your agents to use, you need to bundle it into what is known as a "agent update binary". Out-of-box, the RHQ Server already comes with the standard agent update binary (one that is not preconfigured). You have the option of preconfiguring the agent update binary. Once the RHQ Server has your preconfigured agent update binary, everyone who gets the agent from your RHQ Servers will get your preconfigured agents.

To preconfigure the agent update binary is conceptually very simple. You simply overwrite the default agent-configuration.xml file that comes with the agent update binary with your own. But because this .xml file is buried inside the agent update binary jar, it takes a few steps to do this:

1. Find the existing agent update binary jar that already exists in the RHQ Server. The agent update binary is the only .jar file found here: <server-install-dir>/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-agent (note that if you have not run the RHQ Server installer yet, the .ear directory will be named "rhq.ear.rej"). The agent update binary filename is usually something like "rhq-enterprise-agent-#.#.#.jar". These instructions will refer to this jar file as <agent-update-binary.jar>.
2. Use "jar tf <agent-update-binary.jar>" to find the name of the agent distribution .zip found at the top root directory inside of the .jar. The name of this agent distribution .zip is typically the same name as the .jar itself, except it will have a .zip extension instead of .jar. (e.g. "rhq-enterprise-agent-#.#.#.zip"). These instructions will refer to this agent distribution .zip file as <agent-distro.zip>.
3. Extract the <agent-distro.zip> by unjar'ing it from the <agent-update-binary.jar>

   jar xvf <agent-update-binary.jar> <agent-distro.zip>

4. If you have a preconfigured agent-configuration.xml, place a copy of it under the directory "rhq-agent/conf" next to your <agent-distro.zip> that you just extracted. If you do not yet have your own preconfigured agent-configuration.xml, you can extract the default configuration file from the <agent-distro.zip>:

   jar xvf <agent-distro.zip> rhq-agent/conf/agent-configuration.xml

   Once you get the rhq-agent/conf/agent-configuration.xml, you can edit it appropriately with all of your desired preconfigured settings (see the previous section for more information on this).

5. Update the agent distribution .zip with your custom, preconfigured rhq-agent/conf/agent-configuration.xml file:

   jar uvf <agent-distro.zip> rhq-agent/conf/agent-configuration.xml

6. Update the agent update binary .jar with your new, preconfigured agent distribution .zip:

   jar uvf <agent-update-binary.jar> <agent-distro.zip>

7. Make sure your new, preconfigured <agent-update-binary.jar> is copied into <server-install-dir>/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-agent (overwriting the old agent update binary that used to be there) and make sure it is the only .jar file found in that directory.
8. If one exists, delete any existing *.properties file you find in the RHQ Server at <server-install-dir>/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-agent
9. If you have more than one RHQ Server in your RHQ Server cloud, make sure you distribute your <agent-update-binary.jar> to all of your RHQ Servers - placing it in the same rhq-downloads/rhq-agent subdirectory as mentioned above.

At this point, your new preconfigured agent update binary is ready for download from the RHQ Server. When you install your RHQ Agent, it will have your preconfigured settings.

Preconfiguring your agents like this is not limited to customizing the agent-configuration.xml. You can customize your agents anyway you like - just make sure you bundle up the agent distribution .zip file as you want it and put that .zip in the agent update binary .jar. For example, if you want all of your agents to use secure bi-directional communications, you could place SSL keystore and truststore files in the agent distribution .zip file's "data/" directory.