[jopr-commits] JOPR SVN: r1171 - docs/enterprise/JON/2.3/Installation_Guide/en-US.
jopr-commits at lists.jboss.org
jopr-commits at lists.jboss.org
Wed Sep 9 00:57:57 EDT 2009
Author: smeehan
Date: 2009-09-09 00:57:57 -0400 (Wed, 09 Sep 2009)
New Revision: 1171
Modified:
docs/enterprise/JON/2.3/Installation_Guide/en-US/Book_Info.xml
docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml
docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Agent_Installation.xml
Log:
Changes to Install Guide - jopr wiki
Modified: docs/enterprise/JON/2.3/Installation_Guide/en-US/Book_Info.xml
===================================================================
--- docs/enterprise/JON/2.3/Installation_Guide/en-US/Book_Info.xml 2009-09-07 06:02:56 UTC (rev 1170)
+++ docs/enterprise/JON/2.3/Installation_Guide/en-US/Book_Info.xml 2009-09-09 04:57:57 UTC (rev 1171)
@@ -8,7 +8,7 @@
<productname>JBoss Operations Network</productname>
<productnumber>2.3</productnumber>
<edition>1</edition>
- <pubsnumber>12</pubsnumber>
+ <pubsnumber>13</pubsnumber>
<abstract>
<para>A guide to the download, installation and initial setup of the JBoss Operations Network 2.x product and management agent.</para>
</abstract>
Modified: docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml
===================================================================
--- docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml 2009-09-07 06:02:56 UTC (rev 1170)
+++ docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml 2009-09-09 04:57:57 UTC (rev 1171)
@@ -10,6 +10,7 @@
<xi:include href="Prerequisites.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="JON_Server_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="JON_Agent_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Running_the_JON_Agent.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Command_Line_Interface_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Initial_Auto_discovery_and_Import.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="High_Availability_Configurations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Modified: docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Agent_Installation.xml
===================================================================
--- docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Agent_Installation.xml 2009-09-07 06:02:56 UTC (rev 1170)
+++ docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Agent_Installation.xml 2009-09-09 04:57:57 UTC (rev 1171)
@@ -1,11 +1,11 @@
<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
+ ]>
<chapter id="Installation_Guide-JON_Agent_Installation">
<title>JON Agent Installation</title>
-
+
<section id="Installation_Guide-JON_Agent_Installation_Guide-Overview">
<title>Overview</title>
<para>
@@ -21,12 +21,14 @@
</listitem>
<listitem>
<para>
- If you already have agents installed and you need to upgrade them, see Manually Upgrading the JBoss ON Agent.
+ If you already have agents installed and you need to upgrade them, see <xref linkend="Installation_Guide-JON_Agent_Installation_Guide-Upgrading_JON_Agents"/>
</para>
</listitem>
<listitem>
<para>
- If you plan to install multiple JBoss ON Agents and would like to preconfigure them for easily automated installs, please see Preconfiguring the JBoss ON Agent.
+ If you plan to install multiple JBoss ON Agents and would like to preconfigure them for easily automated installs, please see
+ <xref linkend="Installation_Guide-JON_Agent_Installation_Guide-Preconfiguring_the_JON_Agent"/>
+
</para>
</listitem>
<listitem>
@@ -36,21 +38,24 @@
</listitem>
<listitem>
<para>
- After the agent has been installed and configured, you can run it as a Windows service, from a console, or run it as a daemon or init.d script in a UNIX environment. Go to Running the JBoss ON Agent for more information.
+ After the agent has been installed and configured, you can run it as a Windows service, from a console, or run it as a daemon or init.d script in a UNIX environment. Go to
+ <xref linkend="Installation_Guide-Running_the_JON_Agent"/>
+
+
</para>
</listitem>
<listitem>
<para>
- If you would like to be able to have your agent auto-updated in the future, you must make sure you follow the guidelines specified below.
+ If you would like to be able to have your agent auto-updated in the future please see <xref linkend="Installation_Guide-JON_Agent_Installation-Preparing_the_Agent"/>
</para>
</listitem>
</orderedlist>
-
-
-
-
-
-
+
+
+
+
+
+
<!--><para>
The steps below outline the installation process for the JON Agent. Detailed platform specific instructions are located in <xref linkend="Installation_Guide-JON_Agent_Installation-Running_on_Windows"/> and <xref linkend="Installation_Guide-JON_Agent_Installation-Running_on_UNIX"/>.
</para>
@@ -75,112 +80,119 @@
</section>
<section id="Installation_Guide-JON_Agent_Installation_Guide-Obtaining_the_Agent">
- <title>Obtaining the Agent</title>
-
- <para>
- In JON 2.3, the JON Agent is bundled along with the JON Server and is not available as a separate download.
- This agent bundle is called the "agent update binary" (it is called this because it is used to not only install a new agent but will also be used to upgrade the agent in the future).
- If there is a JON Server currently running in your environment, you can pull down an agent update binary .jar directly from the server using the following instructions.
- </para>
+ <title>Obtaining the Agent</title>
+
+ <para>
+ In JON 2.3, the JON Agent is bundled along with the JON Server and is not available as a separate download.
+ This agent bundle is called the "agent update binary" (it is called this because it is used to not only install a new agent but will also be used to upgrade the agent in the future).
+ If there is a JON Server currently running in your environment, you can pull down an agent update binary .jar directly from the server using the following instructions.
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Simply point your browser to http://<<replaceable>your-server-hostname</replaceable>>:7080/agentupdate/download
+ and 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. <<replaceable>your-server-hostname</replaceable>> should be the hostname or IP address of the server that is running and <emphasis role="bold">7080</emphasis> is the port on which that the server is accepting HTTP requests.
+ </para>
+ </listitem>
- <orderedlist>
- <listitem>
- <para>
- Simply point your browser to http://<<replaceable>your-server-hostname</replaceable>>:7080/agentupdate/download
- and 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. <<replaceable>your-server-hostname</replaceable>> should be the hostname or IP address of the server that is running and <emphasis role="bold">7080</emphasis> is the port on which that the server is accepting HTTP requests.
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- Copy the agent update binary .jar you downloaded from the JON Server to your chosen directory and run
- <command>java -jar <<replaceable>agent-update-binary.jar</replaceable>> --install</command>
- where <<replaceable>agent-update-binary.jar</replaceable>> is the name of the file you downloaded from the server.
- </para>
-
- <para>
- This will tell the agent update binary to extract the JON Agent distribution and install a fresh copy of it in the "rhq-agent" subdirectory. At this point, you will have a fully installed JON Agent located in a "rhq-agent" directory where your agent update binary is located.
- </para>
-
- <para>
- From here on, the instructions will refer to this "rhq-agent" directory as <agent-install-dir>.
- </para>
-
- </listitem>
- </orderedlist>
-
+ <listitem>
+ <para>
+ Copy the agent update binary .jar you downloaded from the JON Server to your chosen directory and run
+ <command>java -jar <<replaceable>agent-update-binary.jar</replaceable>> --install</command>
+ where <<replaceable>agent-update-binary.jar</replaceable>> is the name of the file you downloaded from the server.
+ </para>
+
+ <para>
+ This will tell the agent update binary to extract the JON Agent distribution and install a fresh copy of it in the "rhq-agent" subdirectory. At this point, you will have a fully installed JON Agent located in a "rhq-agent" directory where your agent update binary is located.
+ </para>
+
+ <para>
+ From here on, the instructions will refer to this "rhq-agent" directory as <agent-install-dir>.
+ </para>
+
+ </listitem>
+ </orderedlist>
+
+
</section>
-
- <section id="Installation_Guide-Running_on_Windows-Configuring_the_Agent">
- <title>Installation Preparation</title>
- <para>
- When the JON Agent is first executed, it enters into setup mode. In order for the JON Agent to contact the JON Server, you must enter values for the following parameters.
- </para>
+ <section id="Installation_Guide-Running_on_Windows-Configuring_the_Agent">
+ <title>Installation Preparation</title>
-
-
- <table id="tabl-Installation_Guide-The_JON_Agent_Setup_Parameters">
- <title>The JON Agent setup mode parameters</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Parameter</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>Agent Name</para>
- </entry>
- <entry>
- <para>A unique name for the agent. The default is the fully qualified domain name (FQDN) of the host system. However, you can specify any name you want, as long as it is unique among all other agents in the system.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Agent Hostname or IP Address</para>
- </entry>
- <entry>
- <para>The IP address the agent will bind to in order to listen for incoming messages. Refer to the <citetitle>JON Agent Communcation Services</citetitle> section in the <citetitle>JON Agent Guide</citetitle> for more information.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>Agent Port</para>
- </entry>
- <entry>
- <para>The port that the agent listens to for incoming messages.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>RHQ Server Hostname or IP Address</para>
- </entry>
- <entry>
- <para>
- The hostname or IP address the Server is listening to for incoming messages from agents. This is the address that the agent connects to when sending its initial registration request. If you are running in a RHQ High Availability (HA) environment (that is, you have multiple RHQ Servers running), this will not necessarily be this agent's primary Server. If you only have a single RHQ Server running in your environment, this address is the one the agent will always use when it needs to send messages to the Server.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>RHQ Server Port</para>
- </entry>
- <entry>
- <para>
- The port that the Server listens to for the incoming message registration message from the agent. Again, if you are running in RHQ HA environment, this isn't necessarily the port that all of your RHQ Servers are listening to. However, it should be set to the port that your "registration" Server is listening to.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <para>
+ When the JON Agent is first executed, it enters into setup mode. In order for the JON Agent to contact the JON Server, you must enter values for the following parameters.
+ </para>
+
+
+ <table id="tabl-Installation_Guide-The_JON_Agent_Setup_Parameters">
+ <title>The JON Agent setup mode parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Parameter</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>Agent Name</para>
+ </entry>
+ <entry>
+ <para>A unique name for the agent. The default is the fully qualified domain name (FQDN) of the host system. However, you can specify any name you want, as long as it is unique among all other agents in the system.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Agent Hostname or IP Address</para>
+ </entry>
+ <entry>
+ <para>The IP address the agent will bind to in order to listen for incoming messages. Refer to the <citetitle>JON Agent Communcation Services</citetitle> section in the <citetitle>JON Agent Guide</citetitle> for more information.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Agent Port</para>
+ </entry>
+ <entry>
+ <para>The port that the agent listens to for incoming messages.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>RHQ Server Hostname or IP Address</para>
+ </entry>
+ <entry>
+ <para>
+ The hostname or IP address the Server is listening to for incoming messages from agents. This is the address that the agent connects to when sending its initial registration request. If you are running in a RHQ High Availability (HA) environment (that is, you have multiple RHQ Servers running), this will not necessarily be this agent's primary Server. If you only have a single RHQ Server running in your environment, this address is the one the agent will always use when it needs to send messages to the Server.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>RHQ Server Port</para>
+ </entry>
+ <entry>
+ <para>
+ The port that the Server listens to for the incoming message registration message from the agent. Again, if you are running in RHQ HA environment, this isn't necessarily the port that all of your RHQ Servers are listening to. However, it should be set to the port that your "registration" Server is listening to.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <important>
+ <para>
+ If the agent fails to register with the server and seems to hang after outputting the message <application>The agent does not have plugins - it will now wait for them to be downloaded...</application>, or otherwise does not work property after configuring it, please check the agent log file for error messages (<<replaceable>agent-install-dir</replaceable>>/logs/agent.log). The agent log will normally tell you what the problem is. Typically, problems occur when you bind your agent to an IP address or hostname that is not resolvable by the JBoss ON Servers or is otherwise not reachable by the JBoss ON Servers. Make sure your agents are bound to IP addresses or hostnames that are recognizable and reachable by all your JBoss ON Servers. Similarly, make sure all of your JBoss ON Servers' public endpoint addresses are resolvable by your JBoss ON Agent. Even if you entered a valid server endpoint in the agent setup question, the agent may attempt to switch to another JBo!
ss ON Server immediately after startup registration, and if one or more JBoss ON Servers are installed with unresolvable hostnames or IPs (as seen by this agent), the agent will fail to start properly
+ </para>
+ </important>
+
+
<procedure id="proc-Installation_Guide-JON_Agent_Installation-JON_Agent_Windows_Configuration">
<title>JON Agent Windows configuration</title>
@@ -192,889 +204,730 @@
<para>Run the <command>rhq-agent.bat</command> script in a console and follow the prompts, entering the appropriate values. If you need help on a particular preference setting, enter <literal>!?</literal> at the setup prompt for a description of that preference.
</para>
-<programlisting>
-C:\rhq-agent-2.3.0.GA\bin> rhq-agent.bat
-</programlisting>
-
+ <programlisting>
+ C:\rhq-agent-2.3.0.GA\bin> rhq-agent.bat
+ </programlisting>
+
<para>Option 2</para>
<para>
Edit the <filename>agent-configuration.xml</filename> and ensure to enter the correct settings. Run the <command>rhq-agent.bat</command> script and specifiy the <filename>agent-configuration.xml</filename>. For example:
</para>
-<programlisting>
-C:\rhq-agent-2.3.0.GA\bin> rhq-agent.bat --config ..\conf\agent-configuration.xml
-</programlisting>
-
+ <programlisting>
+ C:\rhq-agent-2.3.0.GA\bin> rhq-agent.bat --config ..\conf\agent-configuration.xml
+ </programlisting>
+
<para>Option 3</para>
<para>
Run the <filename>rhq-agent.bat</filename> script and specify a valid file containing the values of all the setup parameters. For example, the command below uses a file called <filename>myAnswers.txt</filename>.
</para>
-<programlisting>
-C:\rhq-agent-2.3.0.GA\bin> rhq-agent.bat --input myAnswers.txt --nonative
-</programlisting>
+ <programlisting>
+ C:\rhq-agent-2.3.0.GA\bin> rhq-agent.bat --input myAnswers.txt --nonative
+ </programlisting>
<para>
The <option>--nonative</option> temporarily disables the native system to allow reading input from a file. The contents of the <filename>myAnswers.txt</filename> file used in the example above is shown below. Each answer must be on its own line. To enable reading from standard input again, the last line must read <literal>native enable</literal>.
</para>
-<screen>
-[Agent Name] agentdomain.example.com
-[Agent Hostname or IP Address] agentdomain.example.com
-[Agent Port] 16163
-[RHQ Server Hostname or IP Address] serverdomain.example.com
-[RHQ Server Port] 7080
-native enable
-</screen>
+ <screen>
+ [Agent Name] agentdomain.example.com
+ [Agent Hostname or IP Address] agentdomain.example.com
+ [Agent Port] 16163
+ [RHQ Server Hostname or IP Address] serverdomain.example.com
+ [RHQ Server Port] 7080
+ native enable
+ </screen>
</step>
<step>
<para>After the agent has connected to the server, the agent command prompt appears. Enter the command <command>identify</command> to identify the RHQ Server.</para>
</step>
</procedure>
- <formalpara>
- <title>Reconfiguring the JON Agent</title>
+
+ <important>
<para>
- If you have previously installed a JON Agent on a machine and need to wipe all of its old persistent configuration data, start with a clean JON Agent by passing in the command line option <option>-l</option>, or <option>--cleanconfig</option>. This forces the agent to enter setup mode. If at any time, you need to start the JON Agent in setup mode, specify the <option>-s</option>, or <option>--setup</option>, command line option.
+ Once the agent is configured, it persists its configuration in the Java Preferences backing store. Once this happens, <filename>agent-configuration.xml</filename> is no longer needed or used. Editing <filename>agent-configuration.xml</filename> will no longer have any effect on the agent, even if you restart the agent. If you want the agent to pick up changes you make to <filename>agent-configuration.xml</filename>, you must either restart the agent with the <command>--cleanconfig</command> command line option or use the <command>config --import</command> agent prompt command.
</para>
- </formalpara>
+ </important>
<formalpara>
- <title>Debug mode</title>
-
-
+ <title>Reconfiguring the JON Agent</title>
<para>
- If you need to run the agent and its launcher scripts in debug mode so that the scripts and the agent itself log debug messages, define the environment variable <envar>RHQ_AGENT_DEBUG</envar> to "true". To disable debug mode, unset the <literal>RHQ_AGENT_DEBUG</literal> environment variable or set it to "false". You can alternatively use the agent's <command>debug</command> prompt command, in order to toggle the debug mode while the agent is running (specifically <command>debug --file</command> - execute <command>help debug</command> from the agent prompt for more information on this command).
+ If you have previously installed a JON Agent on a machine and need to wipe all of its old persistent configuration data, start with a clean JON Agent by passing in the command line option <option>-l</option>, or <option>--cleanconfig</option>. This forces the agent to enter setup mode. If at any time, you need to start the JON Agent in setup mode, specify the <option>-s</option>, or <option>--setup</option>, command line option.
</para>
-
-
-
</formalpara>
-
- </section>
-
- <section id="Installation_Guide-JON_Agent_Installation-Running_on_Windows">
- <title>Running on Windows</title>
- <!--> Run the <filename>rhq-agent.bat</filename> script in a console to enter into setup mode. The 'setup' mode will prompt you to enter several preference values needed by the JON Agent to function properly. Please read the on-screen instructions for details. By default, the following basic setup questions are asked:-->
+ <para>
+ If you only want to reconfigure one or a few agent settings, you have a couple of options:
+ </para>
-
- <section id="JON_Agent_Guide-Running_on_Windows-Running_in_a_Windows_Console">
- <title>Running in a Windows Console</title>
-
- <para>
- To run the JON Agent in a console, execute the <filename>rhq-agent.bat</filename> script found in the <filename><replaceable><agent-install-dir></replaceable>\bin</filename> directory of the distribution. You can pass in any of the command line options that are described in <xref linkend="JON_Installation_Guide-JON_Agent_Installation-Command_Line_Options"/>.
- </para>
- <para>
- The <filename>rhq-server.bat</filename> script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the JON Server at a new JVM or you can define VM options. The comments at the top of the <filename>rhq-server.bat</filename> file contain a detailed list of these environment variables. You do not have to set any specific variables to get the JON Server to run; sensible defaults are used.
- </para>
- <para>
- Do not edit the <filename>rhq-agent.bat</filename> file. If you need to customize the launch parameters of the Agent, either set the environment variables at the command prompt, or edit the values in the <filename>rhq-agent-env.bat</filename>.
- </para>
- </section>
-
- <section id="JON_Agent_Guide-Running_on_Windows-Installing_and_Running_as_a_Windows_Service">
- <title>Installing and running as a Windows service</title>
-
-
- <important>
- <para>
- The agent will not ask for the configuration when installing as a Windows service. This means that you need to either pre-configure the agent, which means you pass all required information to the agent via the agent's configuration file, or you can run the agent in standard (non-service) mode once (as the user the service will run as) in order to answer all the setup questions prior to installing it as service.
-
- </para>
- </important>
-
-
-
-
- <para>
- If you wish to run the JON Agent at boot time, you can install the JON Agent as a Windows Service. To do so, you use the <filename>rhq-agent-wrapper.bat</filename> file. This script file accepts any of the following command line options:
- </para>
-
- <itemizedlist>
+ <orderedlist>
<listitem>
<para>
- <command>install</command> - this will install the JON Agent as a Windows Service. When you do this, you will be prompted for the password of the user that the service will run as. Information on how to define what user the service will run as is outlined below. The Windows Service will be installed to automatically start at boot time. You can change this behavior by modifying the wrapper configuration file as described below.</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <command>start</command> - this will start the Windows Service, effectively starting the JON Agent. You must have installed the Windows Service first in order to be able to start it. Note that you can also start the JON Agent by using the Windows Services Administrative Tool instead.</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <command>stop</command> - this will stop the Windows Service, effectively stopping the JON Agent. You need to have the Windows Service installed and started to stop it. Note that you can also stop the JON Agent by using the Windows Services Administrative Tool instead.</para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <command>remove</command> - this will remove the Windows Service from your Windows operating system. If the service was running, it will first be stopped. Once the service is removed, it will no longer be started at boot time and you can no longer start it with this wrapper script.
+ Assuming the agent is imported in inventory, you can reconfigure the agent using Jopr itself. Go to the agent's "Configuration tab" in the UI and you can change the agent's configuration there.
+
</para>
</listitem>
- </itemizedlist>
- <itemizedlist>
<listitem>
- <para>
- <command>status</command> - this simply tells you if the service is installed or not; if it is installed, it will tell you if it is currently running or not.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Two environment variables need to be explicitly mentioned here since they are important and have security implications.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <envar>RHQ_AGENT_RUN_AS</envar> - if this variable is set, its value will be the domain\username of the user account that the JON Agent Windows Service will be run as. The format of this variable's value must match that which Windows expects for a user account - specifically the Windows domain name followed by a backslash followed by the username. An example would be <envar>MYDOMAIN\john</envar>. This variable is used when you install the service via <command>rhq-agent-wrapper.bat install</command>.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <envar>RHQ_AGENT_RUN_AS_ME</envar> - if this variable is defined, it forces the user account to be that of the current user (specifically "<envar>.\ %USERNAME%</envar>)". The variable's value does not have to be anything in particular; as long as it is defined to something, it will take effect. If this variable is defined, it will override the <envar>RHQ_AGENT_RUN_AS</envar> environment variable. This variable is used when you install the service via <command>rhq-agent-wrapper.bat install </command>.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Refer to the comments at the top of the <filename>rhq-agent-wrapper.bat</filename> script file for the full list of variables you can set and the documentation on what they control.
- </para>
-
- <important>
- <para>
-
- If you do not pass the agent a file containing its required configuration then you <emphasis role="bold">must</emphasis> specify one of the two environment variables mentioned above in order for the agent to properly initialize itself.
-
- If you specify <envar>RHQ_AGENT_RUN_AS_ME</envar> then you must have previously run the agent at least once in standard (interactive) mode as the current user before installing it as a service.
- </para>
-
-
<para>
- If you specify <envar>RHQ_AGENT_RUN_AS</envar> then you must have previously run the agent at least once in standard (interactive) mode as the user specified by <envar>RHQ_AGENT_RUN_AS</envar> before installing it as a service.
- </para>
-
- <para>
- If neither of the above two environment variables are set, the JON Agent Windows Service will run as the System account. In this scenario the information the agent needs must be specified in its configuration file.
- </para>
-
- </important>
-
-
-
- <important>
-
- <para>
- If you specify either <envar>RHQ_AGENT_RUN_AS_ME</envar> or <envar>RHQ_AGENT_RUN_AS</envar> then you need to make sure that the selected user can actually start services in Windows. Do this by setting the "Logon as Service" right. Go to the Administrative Tools folder in your control panel. Open the Local Security Policy applet. Expand Local Policy and then click on User Rights Assignment. On the right side of your page, there is a logon as service policy where you can add the selected user.
- </para>
- </important>
-
- <para>
-
- In addition to setting the wrapper script file's environment variables, you can also further configure the JON Agent Windows Service by modifying the service wrapper configuration file - this file is located in the agent's distribution, specifically at <filename>bin\wrapper\rhq-agent-wrapper.conf</filename>. This configuration file sets some Java Service Wrapper configuration items (<ulink url="http://wrapper.tanukisoftware.org">Java Service Wrapper</ulink> is the utility that <filename>rhq-agent-wrapper.bat</filename> script uses to install and control the Windows Service). If you wish to add, remove or modify some <filename>wrapper.*</filename> settings, it is recommended that you read the Java Service Wrapper's <ulink url="http://wrapper.tanukisoftware.org/doc/english/properties.html">configuration properties documentation</ulink>.
- </para>
-
- <warning>
- <para>
- In JON 2.0.1 it is necessary to add the following to the '# Additional JVM parameters' section of <filename>bin\wrapper\rhq-agent-wrapper.conf</filename> in order for the agent to run correctly as a windows service. This will be fixed in the JON 2.1 release.
-
-<screen>
-wrapper.java.additional.6=-Djava.endorsed.dirs=%RHQ_AGENT_HOME%/lib/endorsed
-</screen>
- </para>
- </warning>
-
- <para>
- A few common settings you may wish to modify are:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <filename>wrapper.app.parameter.#</filename> - these are command line options you can pass to the JON Agent itself. Refer to the <citetitle>JON Agent Guide</citetitle> for information on agent command line options. Note that each individual option and their values must be given their own wrapper configuration property and each property must be placed in numerical order. You cannot change the <filename>wrapper.app.parameter.1</filename> or <filename>wrapper.app.parameter.2</filename> properties - start with <filename>wrapper.app.parameter.3</filename> and increment up from there. Starting from the last unused number in the sequence, option numbers should increase sequentially. For example:
- </para>
-<screen>
-wrapper.app.parameter.3=--config
-wrapper.app.parameter.4=C:\my-configs\my-agent-config.xml
-</screen>
-
+ Use the <command>setconfig</command> agent prompt command. This will set the new configuration setting and persisted it so it survives agent restarts.
+ </para>
</listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <filename>wrapper.java.additional.#</filename> - these are additional VM options you can pass directly to the VM (such as -Xmx or -D). As with the <filename>wrapper.app.parameter.#</filename> properties, you must increment each option in numerical order. You should leave <filename>wrapper.java.additional.1</filename> alone unless you want to point to your own log configuration file. You can add, remove or modify others, but make sure you know what you are doing. For example:
- </para>
-<screen>
-wrapper.java.additional.2=-Xms256m
-wrapper.java.additional.3=-Xmx800m
-wrapper.java.additional.4=-XX:+DisableExplicitGC
-</screen>
-
- </listitem>
- </itemizedlist>
- <itemizedlist>
- <listitem>
- <para>
- <filename>wrapper.ntservice.starttype</filename> - by default, this is set to <envar>AUTO_START</envar>, meaning the JON Agent's service will be started automatically at boot time. If you prefer to force a manual start of the service, you can set this to <envar>DEMAND_START</envar>.
- </para>
- </listitem>
- </itemizedlist>
-
+ </orderedlist>
+
+ <important>
<para>
- There are many other Java Service Wrapper configuration properties you can set. For more information, please refer to the Java Service Wrapper documentation.
+ Just changing <filename>agent-configuration.xml</filename> will <emphasis role="bold">not</emphasis> affect the agent. A fully configured agent will ignore <filename>agent-configuration.xml</filename>; only if you restart an agent with <command>--cleanconfig</command> will the agent reload <filename>agent-configuration.xml</filename>.
</para>
-
- </section>
+ </important>
- </section>
-
- <section id="Installation_Guide-JON_Agent_Installation-Running_on_UNIX">
- <title>Running on <trademark class="registered">UNIX</trademark></title>
- <para>
- The JON Agent can be run directly from a console window or it can be installed as an init.d process such that it starts up when the computer boots up.
- </para>
- <section id="JON_Agent_Guide-Running_on_UNIX-Running_in_a_Console">
- <title>Running in a console</title>
-
+ <formalpara>
+ <title>Configuring the Jopr Agent Runtime Environment</title>
+
+
<para>
- To run the JON Agent in a console, please execute the <filename>rhq-agent.sh</filename> script found in the <filename>/bin</filename> directory of the distribution. You can pass in any of the command line options that are described in the <citetitle>JON Agent Guide</citetitle>. There are a few environment variables that this <filename>rhq-agent.sh</filename> script looks for to allow you to run custom operations such as explicitly pointing to a specific JVM that you want the agent to run with or defining what VM options you would like to pass in. Please refer to the comments in <filename>rhq-agent-env.sh</filename> for the list of these environment variables. You do not have to set any specific environment variables to get the JON Agent to run under most circumstances; sensible defaults will be used. You should not edit <filename>rhq-agent.sh</filename> - if you need to customize the launch parameters of the Agent, either set the environment variables in your shell that!
you use to run <filename>rhq-agent.sh</filename> or edit the values in <filename>rhq-agent-env.sh</filename>.
- </para>
+ The agent has an environment script that is read when the agent is started up. This file is called <filename>rhq-agent-env.bat</filename> on Windows and <filename>rhq-agent-env.sh</filename> on UNIX. Edit this file to change the environment of the agent. The comments in that file document the different settings. Some of the settings are also explained in the Running the Jopr Agent pages.
+ </para>
- </section>
+ </formalpara>
- <section id="JON_Agent_Guide-Running_on_UNIX-Running_as_a_daemon">
- <title>Running as a daemon</title>
- <para>
- The JON Agent script <filename>rhq-agent-wrapper.sh</filename> located in the <filename>/bin</filename> directory can be used to run the Agent as a daemon. There are two distinct scenarios in which you can run the agent as a daemon:</para>
- <orderedlist>
- <listitem>
- <para>
- <emphasis role="bold">If you previously run the agent in a console</emphasis>: Assuming you run <filename>rhq-agent-wrapper.sh</filename> as the same user you initially ran the agent as, then all you should have to do is to execute <command>rhq-agent-wrapper.sh start</command> and the agent will start up in daemon mode.
- </para>
+ <formalpara>
+ <title>Debug mode</title>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">If you have never previously run the agent</emphasis>: In this case you need the tweak <filename>rhq-agent-wrapper.sh</filename> file and also ensure you use a fully configured agent configuration file. This is necessary because you will not be able to answer the questions the agent asks when it first starts up, so these settings need to be specified in the configuration file
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- In the agent-configuration.xml make sure the agent has all the correct settings it needs to connect to the agent. For example:
- </para>
-<screen><entry key="rhq.agent.name" value="my-agent-name"/>
-<entry key="rhq.agent.server.bind-address" value="jon-server.mycompany.com" />
-</screen>
-
- <para>
- With these files setup correctly you should be able to start the agent in daemon mode with <command>rhq-agent-wrapper.sh start</command>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </orderedlist>
-
- <note>
<para>
- You can set environment variables to control the behavior of the agent - see the <filename>rhq-agent-env.sh</filename> script for the different variables you can set.
- </para>
- </note>
+ If you need to run the agent and its launcher scripts in debug mode so that the scripts and the agent itself log debug messages, define the environment variable <envar>RHQ_AGENT_DEBUG</envar> to "true". To disable debug mode, unset the <literal>RHQ_AGENT_DEBUG</literal> environment variable or set it to "false". You can alternatively use the agent's <command>debug</command> prompt command, in order to toggle the debug mode while the agent is running (specifically <command>debug --file</command> - execute <command>help debug</command> from the agent prompt for more information on this command).
+ </para>
- <important>
- <para>
- Unlike the wrapper script on Windows, the <filename>rhq-agent-wrapper.sh</filename> script does not utilize the Java Service Wrapper utility.
- </para>
- </important>
+ </formalpara>
- <important>
- <para>
- Solaris Admins: Symbolically linking the rhq agent binaries requires invocation of <emphasis role="bold">readlink</emphasis> in <filename>rhq-agent-wrapper.sh</filename>. However, <emphasis role="bold">readlink</emphasis> is not supplied by default in some Solaris installations. Solaris users must either download <emphasis role="bold">readlink</emphasis> from a third party provider, such as Sunfreeware, or refrain from symbolically linking the agent binaries when using the wrapper script.
- </para>
- </important>
+ </section>
+
+
+ <section id="Installation_Guide-JON_Agent_Installation-Preparing_the_Agent">
+ <title>Preparing the Agent for Auto-Update</title>
- </section>
+ <para>
+ With the introduction of High Availability (HA), your environment can now support multiple agents. How you manage those agents now becomes very important. The agent auto-update feature introduced in JBoss ON 2.2 allows your agents to automatically update themselves, without the need for an administrator to manually log onto every agent box and do it by hand.
+ </para>
- <section id="JON_Agent_Guide-Running_on_UNIX-Running_with_init">
- <title>Running with init.d</title>
-
<para>
- To run the JON Agent at boot time, you will need to complete some additional steps. You will need either root or sudo root access to perform parts of this installation.
+ In order for your agent to be auto-updateable, you must keep a few rules in mind. If you following these recommendations, you should be able to update your agents to new versions easily, without any additional manual configuration necessary. If you do not follow these recommendations, you will still be able to have your agent update itself, but you will most likely need to perform some additional manual administration tasks in order for your agent to start back up in the same configuration it was in before the update.
</para>
-
+
+
<important>
<para>
- Solaris Admins: Symbolically linking the rhq agent binaries requires invocation of <emphasis role="bold">readlink</emphasis> in <filename>rhq-agent-wrapper.sh</filename>. However, <emphasis role="bold">readlink</emphasis> is not supplied by default in some Solaris installations. Solaris users must either download <emphasis role="bold">readlink</emphasis> from a third party provider, such as Sunfreeware, or refrain from symbolically linking the agent binaries when using the wrapper script.
+ Agent auto-updates are only available when going from JBoss ON version 2.2 to a later version. You cannot auto-update agents from any previous JBoss ON version.
</para>
</important>
-
-
- <section id="JON_Agent_Guide-Running_with_init-Configuration_Parameters">
- <title>Configuration</title>
-
+ <section id="Installation_Guide-Preparing_the_Agent-Start_the_Agent">
+ <title>Starting the Agent using the wrapper service</title>
- <formalpara>
- <title>Configuration Parameters</title>
-
<para>
- Below are the configuration parameters that appear at the top of the JON Agent script <filename>rhq-agent-wrapper.sh</filename> located in the <filename>/bin</filename> directory
- </para>
-
- </formalpara>
-
-<para>
-<screen>
-# RHQ_AGENT_HOME=/path/to/agent/installation
-# export RHQ_AGENT_DEBUG=true
-# export RHQ_AGENT_JAVA_HOME=/path/to/JDK/
-# export RHQ_AGENT_JAVA_EXE_FILE_PATH=/path/directly/to/java/executable
-# export RHQ_AGENT_JAVA_OPTS=VM options
-# export RHQ_AGENT_ADDITIONAL_JAVA_OPTS=additional VM options
-# PIDFILEDIR=/path/to/writable/directory
-</screen>
-</para>
-
-
-
-
- <para>
- Information preceded by the <literal>#</literal> symbol is commented out and not enabled. To run the JON Agent at boot time you will need to enable some of these parameters by removing the <literal>#</literal> symbol that appears at the start of each line. The following three parameters are <emphasis role="bold">mandatory</emphasis> and must be uncommented:
- </para>
-
-
- <orderedlist>
- <listitem>
- <para>
- <envar>RHQ_AGENT_HOME</envar>=<filename>/path/to/agent/installation</filename> - This is the directory above your Agent installation's bin directory.</para>
- </listitem>
-
-
- <listitem>
- <para>
- export <envar>RHQ_AGENT_JAVA_HOME</envar>=<filename>/path/to/JDK/</filename> - This is the directory above the JDK's bin folder.</para>
- </listitem>
-
+ On any platform (Windows or UNIX), the agent can be started in two basic ways:
+ </para>
- <listitem>
- <para>
- <envar>PIDFILEDIR</envar>=<filename>/path/to/writable/directory</filename> - A directory writable by the user you run the Agent as. It defaults to <filename>/var/run</filename>. If <filename>/var/run</filename> is not writable, use <envar>$RHQ_AGENT_HOME/bin</envar>. Please note that this is only applicable for versions 2.1.2SP1. and earlier of the JON Agent. Changes have been made in subsequent versions of the agent that will fall back to a writable directory. </para>
- </listitem>
- </orderedlist>
-
-
- <important>
- <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ in a console; or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ as a background daemon.
+ </para>
+ </listitem>
+ </orderedlist>
- </para>
- <para>
- If you change <envar># PIDFILEDIR</envar>=<filename>/path/to/writable/directory</filename>, and you are using RHEL, you will need to make a parallel change to the chkconfig "pidfile" location at the very top of the Agent wrapper script.
- </para>
- </important>
-
- <para>
- The following are optional parameters:
- </para>
-
- <orderedlist>
- <listitem>
<para>
- <envar>export RHQ_AGENT_DEBUG=true</envar> - This will turn Agent debug on. Turn this off when finished debugging.</para>
- </listitem>
-
-
- <listitem>
+ To run the agent in a console, you use <filename>rhq-agent.sh</filename> or the <filename>rhq-agent.bat</filename> directly - this provides you with a command prompt allowing you to type commands to the agent from your keyboard. To run the agent as a background daemon process, you use <filename>rhq-agent-wrapper.sh</filename> or <filename>rhq-agent-wrapper.bat</filename>. The <filename>rhq-agent-wrapper.sh</filename> and <filename>rhq-agent-wrapper.bat</filename> is called the <filename>wrapper</filename> script and it runs the agent as a service with no console input (just like any other service such as "sshd"). On Windows platforms, this wrapper script installs and runs the agent as an actual Windows Service.
+ </para>
+
<para>
- <envar>export RHQ_AGENT_JAVA_EXE_FILE_PATH</envar>=<filename>/path/directly/to/java/executable</filename> - You can enable this if you need to specify a java executable. This is an optional configuration item.</para>
- </listitem>
+ In almost all production environments, you will want to start the agent as a background daemon process. On UNIX, this means you usually run the agent at boot time from init.d. On Windows, this means you install the agent as a Windows Service that automatically starts at boot time. The agent auto-update feature assumes you start your agent in this way. If you do not, and the agent auto-updates itself, the old agent running in the console will be shutdown and the new agent will be restarted as a background service if at all possible (caveat: on Windows, if the agent is not installed as a Windows Service, the agent will attempt to be restarted in a console window).
+ </para>
+
+ </section>
- <listitem>
+ <section id="Installation_Guide-Preparing_the_Agent-Launcher_Scripts">
+ <title>Do not alter the launcher scripts</title>
+
+
<para>
- <envar>export RHQ_AGENT_JAVA_OPTS</envar>=<filename>VM options</filename> - Pass additional VM options. This is an optional configuration item.</para>
- </listitem>
-
- <listitem>
- <para>
- <envar>export RHQ_AGENT_ADDITIONAL_JAVA_OPTS</envar>=<filename>additional VM options</filename> - Pass additional java options. This is an optional configuration item.</para>
- </listitem>
-
-
-
- </orderedlist>
-
-
-
-</section>
-
-<section id="JON_Agent_Guide-Running_with_init-Installation">
- <title>Installation</title>
-
-<formalpara><title>Red Hat Enterprise Linux (RHEL) using chkconfig
-</title>
- <para>
-
- The rhq-agent-wrapper script contains standard <emphasis role="bold">chkconfig</emphasis> options that can be used by the chkconfig init script management system. You will need to be root or have sudo root access to perform these steps.
-
+ The agent ships with several launcher scripts along with several support scripts in the /bin directory. You must not change the launcher scripts. If you need to customize the agent's configuration, you can do so by editing the support scripts that are used by the launcher scripts for their configuration. Therefore, you must not edit <filename>rhq-agent.sh</filename>, <filename>rhq-agent.bat</filename>, <filename>rhq-agent-wrapper.sh</filename> or <filename>rhq-agent-wrapper.bat</filename>. You can edit the others. Below are the script files that are used by the agent; those listed in <emphasis role="bold">bold italic</emphasis> are the launcher scripts that must not be changed, the others are the support scripts that can be modified:
</para>
-
- </formalpara>
-
- <orderedlist>
- <listitem>
- <para>
- Symlink your edited <filename>rhq-agent-wrapper.sh file</filename> to <filename>/etc/init.d/</filename>. Example command:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <command>
- ln -s /path/to/agent/installation/bin/rhq-agent-wrapper.sh /etc/init.d/rhq-agent-wrapper.sh
- </command>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- Register rhq-agent-wrapper.sh with the chkconfig system by entering the following command:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <command>
- /sbin/chkconfig --add rhq-agent-wrapper.sh
- </command>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- Enable the Agent service at boot time and have it stop gracefully at shutdown/reboot by entering the following command:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <command>
- /sbin/chkconfig rhq-agent-wrapper.sh on
- </command>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- If you need to disable the Agent boot-time service enter the following command:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <command>
- /sbin/chkconfig rhq-agent-wrapper.sh off
-
- </command>
- </para>
- </listitem>
- </itemizedlist>
-
- </listitem>
-
-
- </orderedlist>
- <formalpara>
- <title>
- Other UNIX-like operating systems
- </title>
-
- <para>
- Please consult your system administrator for instructions on how to install and configure the Agent init script with your init system.
- </para>
-
- </formalpara>
-
- </section>
- </section>
- </section>
-
- <section id="JON_Installation_Guide-JON_Agent_Installation-Command_Line_Options">
- <title>Command line options</title>
-
- <para>
- The <filename>rhq-agent.bat</filename> and <filename>rhq-agent.sh</filename> scripts can both take the following command line options.
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colname="c1"/>
- <colspec colname="c2"/>
+ <table id="tabl-Installation_Guide-The_JON_Agent_Script_Files">
+ <title>Script Files</title>
+ <tgroup cols="2">
<thead>
<row>
- <entry>Option</entry>
+ <entry>Script File</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
- <para>
- <emphasis role="bold">-a, --advanced</emphasis>
- </para>
+ <para><emphasis role="bold">rhq-agent.sh</emphasis></para>
</entry>
<entry>
- <para>If setup is needed at startup, the advanced setup is run, rather than the basic</para>
+ <para>Launcher script to start the agent in a console window on UNIX</para>
</entry>
</row>
<row>
<entry>
- <para>
- <emphasis role="bold">-c, --config=<filename></emphasis>
- </para>
+ <para><emphasis role="bold">rhq-agent.bat</emphasis></para>
</entry>
<entry>
- <para>explicitly specifies the configuration file the agent is to use for its configuration; if the preferences node in the file is different than "default", you must specify that preference node name via --pref</para>
+ <para>Launcher script to start the agent in a console window on Windows</para>
</entry>
</row>
<row>
<entry>
- <para>
- <emphasis role="bold">-d, --daemon</emphasis>
- </para>
+ <para><emphasis role="bold">rhq-agent-wrapper.sh</emphasis></para>
</entry>
<entry>
- <para>if specified, keyboard input will not be read by the agent. If the --input switch is used to specify a file, it will be processed</para>
+ <para>Launcher script to start the agent as a background daemon on UNIX</para>
</entry>
</row>
<row>
<entry>
- <para>
- <emphasis role="bold">-D<name>[=<value>]</emphasis>
- </para>
+ <para><emphasis role="bold">rhq-agent-wrapper.bat</emphasis></para>
</entry>
<entry>
- <para>overrides a configuration preference with the given name with the given value. This also sets the JVM's system property with the same name/value pair (which does not necessarily have to map to a valid agent configuration preference)</para>
- </entry>
- </row>
- <row>
- <entry>
<para>
- <emphasis role="bold">-h, --help</emphasis>
+ Launcher script to start the agent as a Windows Service on Windows
</para>
</entry>
- <entry>
- <para>displays the help text for the command line arguments of the agent</para>
- </entry>
</row>
<row>
<entry>
- <para>
- <emphasis role="bold">-i, --input=<filename></emphasis>
- </para>
+ <para>rhq-agent-env.sh</para>
</entry>
<entry>
- <para>specifies an input script containing agent prompt commands that the agent should execute upon startup; if not specified, keyboard input will be read</para>
- </entry>
- </row>
- <row>
- <entry>
<para>
- <emphasis role="bold">-l, --cleanconfig</emphasis>
+ Script to setup the agent environment on UNIX
</para>
</entry>
- <entry>
- <para>Clears out any existing configuration and purges the agent's persisted data so the agent starts with a clean slate. The default configuration file will be loaded if <emphasis>--config</emphasis> is not specified. If you only wish to purge the agent's persisted data, without cleaning its configuration settings, use <emphasis>--purgedata</emphasis>.</para>
- </entry>
</row>
+
<row>
<entry>
- <para>
- <emphasis role="bold">-n, --nostart</emphasis>
- </para>
+ <para>rhq-agent-env.bat</para>
</entry>
<entry>
- <para>If specified, the agent will not be automatically started</para>
- </entry>
- </row>
- <row>
- <entry>
<para>
- <emphasis role="bold">-o, --output=<filename></emphasis>
+ Script to setup the agent environment on Windows
</para>
</entry>
- <entry>
- <para>specifies an output file that all non-log output will be written to. This does not affect the log messages - those go to the file as specified in the log4j.xml configuration</para>
- </entry>
</row>
+
<row>
<entry>
- <para>
- <emphasis role="bold">-p, --pref=<preferences name></emphasis>
- </para>
+ <para>wrapper/rhq-agent-wrapper.conf</para>
</entry>
<entry>
- <para>defines the preferences node name that the agent's configuration is known as. This allows the agent to reuse persisted preferences under this preferences name (and is how you can have multiple configuration sets defined and start the agent with one of them)</para>
- </entry>
- </row>
- <row>
- <entry>
<para>
- <emphasis role="bold">-s, --setup</emphasis>
+ Configuration for the agent's Windows Service on Windows
</para>
</entry>
- <entry>
- <para>Forces the agent to ask basic setup questions, even if the agent has already been fully configured. If <emphasis>--advanced</emphasis> was also specified, the advanced setup questions will be asked.</para>
- </entry>
</row>
+
<row>
<entry>
+ <para>wrapper/rhq-agent-wrapper.env *</para>
+ </entry>
+ <entry>
<para>
- <emphasis role="bold">-t, --nonative</emphasis>
+ Sets up additional environment variables for the Windows Service on Windows
</para>
+ <para>
+ *This do not exist out of the box when you install an agent but you can create and configure it when appropriate. Most people, however, will not need this.
+ </para>
</entry>
- <entry>
- <para>Forces the agent to disable the native system, even if the agent was configured for it.</para>
- </entry>
</row>
+
+
<row>
<entry>
+ <para>wrapper/rhq-agent-wrapper.inc *</para>
+ </entry>
+ <entry>
<para>
- <emphasis role="bold">-u, --purgedata</emphasis>
+ Overrides or adds Windows Service configuration settings on Windows
</para>
+ <para>
+ *This do not exist out of the box when you install an agent but you can create and configure it when appropriate. Most people, however, will not need this.
+ </para>
+
</entry>
- <entry>
- <para>Purges the agent's persistent inventory and other data files. This does not erase the agent's configuration settings, use <emphasis>--cleanconfig</emphasis> if you wish to clean the agent's configuration along with purging its persisted data.</para>
- </entry>
</row>
+
+
+
</tbody>
</tgroup>
- </informaltable>
-
- </section>
-
-
-
- <section id="JON_Agent_Guide-Running_the_JON_Agent-Running_Embedded_in_a_JON_Server">
- <title>Running embedded in a JON Server</title>
-
-
- <warning>
- <para>
- Running an embedded Agent in production is not recommended and, therefore, it is <emphasis role="bold">not</emphasis> currently supported. There are some known issues with managing certain resources with the embedded agent.
- </para>
- </warning>
-
- <para>
- There is actually a third way you can run the JON Agent, and that is embedded in a JON Server. For those platforms that are running your JON Server, you have the option to either run a standalone JON Agent normally (as described in the sections above) or you can run the JON Agent embedded in the JON Server itself. This allows you to manage the JON Server platform and all the products running on that platform (including the JON Server itself) by simply starting the JON Server and having it start a JON Agent for you. This feature is to enable testing and demo'ing JON without needing to install and run a separate, standalone agent. It is not recommended to deploy in this way in a production JON environment.
- </para>
-
- <para>
- The JON Server disables the Embedded JON Agent by default - you have to explicitly enable the Embedded JON Agent in order to run it. Refer to the section on <citetitle>Running the Embedded JON Agent</citetitle> in the <citetitle>JON Server Guide</citetitle> for information on how you can enable and configure the Embedded JON Agent.
- </para>
-
- <para>
- The Embedded JON Agent implicitly runs in <emphasis>daemon</emphasis> mode, which means it has no command line interface. Its log file is located in <filename>$RHQ_SERVER_HOME/logs/embedded-agent.log</filename>.
- </para>
-
- </section>
-
- <section id="Installation_Guide-JON_Agent_Installation_Guide-Upgrading_JON_Agents">
- <title>Manually Upgrading the JON Agent</title>
-
-
- <important>
+ </table>
+
+
<para>
- Upgrading from JON 1.x or the JON 2.0 Beta or CR releases is not supported.
+ If you change the support scripts, the agent-auto-update will keep your files and reuse them in your new agent. If you change the launcher scripts, the agent-auto-update will first back them up but then overwrite them with the new scripts found in the update.
</para>
-
- </important>
-
- <important>
- <para>To ensure compatibility with the JON Server, each Agent must be upgraded to the same version of JON as the Server.</para>
-
- </important>
-
- <important>
- <title>
- Agent Auto-Updating
- </title>
- <para>
- Since Jopr 2.2, agents have the ability to auto-update themselves. So, under most conditions, it isn't necessary to manually upgrade agents. However, if the auto-update fails for some reason or you disabled agent auto-update and you want to manually upgrade yourself, you need to follow the steps below.
- </para>
- </important>
+ </section>
-
+
+ <section id="Installation_Guide-Preparing_the_Agent-Configure_Agent_using_support_scripts">
+ <title>Configuring the Agent using support scripts</title>
+
<para>
- If you need to manually upgrade a JBoss ON Agent (i.e. you do not want or cannot utilize the agent auto-ugprade capabilities), then follow these steps below. You will need to follow these steps if you are upgrading the Jopr Agent to version 2.2.
+ Do not rely on any shell environment variables that existed at the time you started the agent. If, for example, you started the agent from within a command line shell and prior to starting the agent you had exported the <envar>RHQ_AGENT_HOME</envar> environment variable in that shell, the agent will use that value. However, once the agent is shutdown and restarted (as what happens after an auto-update completes) that setting will be lost. If you need to customize the settings that your agent uses at startup (e.g. <envar>RHQ_AGENT_HOME</envar> or <envar>RHQ_AGENT_ADDITIONAL_JAVA_OPTS</envar>, to name a few), you should do so by editing the support scripts and setting the values in there. This persists the settings and can therefore be picked up the next time the agent restarts. This provides the added benefit of being able to configure, reconfigure and track/rollback configurations using the agent resource's Configuration tab in the GUI.
</para>
-
<para>
- Note that all agents must be upgraded at the same time, having agents of different versions in your Jopr environment is not supported.
+ You must also ensure that the agent has been fully configured prior to running it the very first time. This means you must either start the agent in a console to answer the setup questions or you must fully configure the agent's configuration file so it can start up without needing additional input from an administrator (i.e. so it does not have to ask the initial setup questions). Once fully configured, you can start the agent as a background daemon thereafter.
</para>
+ <para>
+ You can fully configure the agent by changing the support scripts/configuration files directly. But if you have the agent imported into inventory, you can optionally use the GUI to configure the agent (in effect, we are using Jopr to manage Jopr).
+ </para>
+
+ </section>
-
+ <section id="Installation_Guide-Preparing_the_Agent-Installing_Keystores_and_Truststores">
+ <title>Installing Keystores and Truststores</title>
+
+
+
+ <para>
+ If you configured your old agent with SSL such that it uses your own custom keystores and truststores, you must ensure that you install those stores in the following manner:
+ </para>
+
+
<orderedlist>
<listitem>
<para>
- Shutdown your Jopr Agent.
+ The keystore files must have the word "keystore" in their filenames. For example, "my-agent-keystore.dat".
</para>
</listitem>
- <listitem>
- <para>
- If you are running the Agent on Windows and installed the original Agent as a Windows service, uninstall the Windows service:
- </para>
-<screen>
-cd <old-agent-install-dir>/bin
-./rhq-agent-wrapper.bat remove
-</screen>
-
- </listitem>
<listitem>
- <para>
- Upgrade the JON Server. The JON Server must be upgraded before any Agents are upgraded. Please shut down all agents and wait until all agents show red availability in the GUI before shutting down the server. On completing this procedure, please follow the <emphasis>Upgrading the JON Server</emphasis> instructions to upgrade the JON server.
- </para>
- </listitem>
-
- <listitem>
<para>
- Restart your upgraded Jopr Servers if they are not yet started.
+ The truststore files must have the word "truststore" in their filenames. For example, "my-agent-truststore.dat"
</para>
</listitem>
<listitem>
<para>
- If the current Jopr Agent that is to be upgraded is at version 2.2 or newer:
+ You must have your keystore and truststore files in the agent's <agent-install-dir>/data directory.
</para>
- <itemizedlist>
- <listitem>
- <para>
- Download the agent update binary from the server
- </para>
- </listitem>
- <listitem>
+ </listitem>
+ </orderedlist>
+
<para>
- Copy the agent update binary .jar file into the parent directory where your agent is installed. For example, if your agent is installed in /opt/rhq-agent-parent/rhq-agent, copy the agent update binary .jar file to the /opt/rhq-agent-parent directory.
+ If you follow those three simple rules, then your new, updated agent will remain fully secured just as your old agent was. This is because your keystore and truststore files will be copied directly from your old agent to your new agent.
</para>
- </listitem>
- <listitem>
+
+
+ </section>
+
+
+ <section id="Installation_Guide-Preparing_the_Agent-Installing_the_Agent_in_a_writable_directory">
+ <title>Installing the Agent in a writable directory</title>
+
<para>
- Extract the new Jopr Agent from the agent update binary by running the following command:
+ During the update process, files will need to be written in the directory where the agent is currently installed. This means that the parent directory of the agent's install directory must be writable by the user that is running the agent. As an example, if the agent's <envar>$RHQ_AGENT_HOME</envar> (i.e. where the agent is installed) is the directory called <filename>/opt/rhq-agent-parent/rhq-agent</filename>, the agent will need to write files to the <filename>/opt/rhq-agent-parent</filename> directory and therefore must have write permissions there.
+
</para>
-<screen>
-java -jar <agent-update-binary.jar> --upgrade
-</screen>
-
-<para>
-This will tell the agent update binary to extract the Jopr Agent distribution and update your currently existing agent that is found in "rhq-agent" subdirectory. At this point, you will have a fully upgraded Jopr Agent located in the original "rhq-agent" directory. The old agent has been backed up to the "rhq-agent-old" directory. If the upgrade encounters errors, you'll find log files that contain log messages that can help to diagnose the problem.
-</para>
-
- </listitem>
- </itemizedlist>
-</listitem>
-
-<listitem>
- <para>
- If the current Jopr Agent that is to be upgraded is older than version 2.2:
-
- </para>
-<itemizedlist>
- <listitem>
+
+ </section>
+ </section>
+
+
+ <section id="Installation_Guide-JON_Agent_Installation-Agent_Auto_Update">
+ <title>Agent Auto-Update</title>
+
<para>
- Follow the instructions to install a Jopr Agent here: Jopr Agent Installation
+ There is really nothing you have to do when an agent needs to be updated and it is able to auto-update itself. As long as you have configured your server and agents to allow for auto-agent updates (they are configured this way by default), it all happens automatically at the appropriate time.
</para>
- </listitem>
-
- <listitem>
+
<para>
- If you had your own keystore and truststore files, make sure you copy them over from the old agent installation to the new agent installation
- </para>
-</listitem>
- <listitem>
+ When a new agent update has been released, it is placed in the server making it available for download by the old, existing agents running in the network. The server will notify the agent that it needs to update as soon as the server detects that the agent is of an older version. Once the agent knows it needs to update itself, it will stop everything it is doing, download the agent update binary, spawn a new Java process that is responsible for applying the update and then kill itself. That new Java process will update the existing agent and then restart the now updated agent. The old, existing agent will be backed up in case it needs to be rolled back (in the event the update fails for some reason).
+ </para>
+ <para>
+ If you wish to immediately tell the agent to update itself (or just to see if the agent needs to update or is even allowed/enabled to update), use the prompt command "update". Execute the agent prompt command "help update" for more information on that command.
+ </para>
+
+ <important>
<para>
-
- If you had your own customizations to the agent script files, you will need to merge them into the new agent scripts. Note that you should no longer modify rhq-agent.bat,sh or rhq-agent-wrapper.bat,sh - instead, any environment modifications should be made to rhq-agent-env.bat,sh. This is discussed further here and here, but in short, any customizations you need to make to the agent launcher scripts should be done in rhq-agent-env.bat,sh.
- </para>
-</listitem>
-</itemizedlist>
-</listitem>
-
-<listitem>
- <para>
- (optional) If you need to reconfigure the Jopr Agent before you restart it, read the documentation at Jopr Agent Installation that talks about configuring and reconfiguring the agent. Typically, you won't have to reconfigure the agent - the agent will pick up its previous configuration and update it as necessary.
- </para>
-</listitem>
-<listitem>
- <para>
- Finally, start the Jopr Agent.
- </para>
-</listitem>
- </orderedlist>
-
-
+ You may notice that it takes several minutes for an agent to fully complete its update. The agent has many threads running in it that need to be gracefully shutdown, it then has to download and verify the integrity of the new agent update binary and then it must actually apply the update before being able to restart. Depending on the situation, it's possible several minutes could elapse before the new agent is fully functional again.
+ </para>
+ </important>
+
</section>
-
-
-
-
-
-
-
-
-
-
- <!--
- <section id="Installation_Guide-Upgrading_JON_Agents-Install_the_New_Agents">
- <title>Install the new Agents</title>
-
- <para>Once the JON Server has been upgraded, install the new version of JON Agent to each machine where an existing JON Agent is installed. Please upgrade each JON Agent as follows:</para>
+ <section id="Installation_Guide-JON_Agent_Installation_Guide-Upgrading_JON_Agents">
+ <title>Manually Upgrading the JON Agent</title>
+
+ <important>
+ <para>
+ Upgrading from JON 1.x or the JON 2.0 Beta or CR releases is not supported.
+ </para>
+
+ </important>
+
+ <important>
+
+ <para>To ensure compatibility with the JON Server, each Agent must be upgraded to the same version of JON as the Server.</para>
+
+ </important>
+
+ <important>
+ <title>
+ Agent Auto-Updating
+ </title>
+ <para>
+ Since Jopr 2.2, agents have the ability to auto-update themselves. So, under most conditions, it isn't necessary to manually upgrade agents. However, if the auto-update fails for some reason or you disabled agent auto-update and you want to manually upgrade yourself, you need to follow the steps below.
+ </para>
+ </important>
+
+
+ <para>
+ If you need to manually upgrade a JBoss ON Agent (i.e. you do not want or cannot utilize the agent auto-ugprade capabilities), then follow these steps below. You will need to follow these steps if you are upgrading the Jopr Agent to version 2.2.
+ </para>
+
+ <para>
+ Note that all agents must be upgraded at the same time, having agents of different versions in your Jopr environment is not supported.
+ </para>
+
+
<orderedlist>
<listitem>
- <para> Make sure the old Agent is not running. Do not delete the old Agent's directory yet.</para>
+ <para>
+ Shutdown your Jopr Agent.
+ </para>
</listitem>
-
<listitem>
- <para> If you are running the Agent on Windows and installed the original Agent as a Windows service, uninstall the Windows service: </para>
-<screen>
-cd <old-agent-install-dir>/bin
-./rhq-agent-wrapper.bat remove
-</screen>
+ <para>
+ If you are running the Agent on Windows and installed the original Agent as a Windows service, uninstall the Windows service:
+ </para>
+ <screen>
+ cd <old-agent-install-dir>/bin
+ ./rhq-agent-wrapper.bat remove
+ </screen>
+ </listitem>
+ <listitem>
+ <para>
+ Upgrade the JON Server. The JON Server must be upgraded before any Agents are upgraded. Please shut down all agents and wait until all agents show red availability in the GUI before shutting down the server. On completing this procedure, please follow the <emphasis>Upgrading the JON Server</emphasis> instructions to upgrade the JON server.
+ </para>
</listitem>
+
<listitem>
- <para> Follow the usual <xref linkend="Installation_Guide-JON_Agent_Installation"/> to install the new Agent. Note, you should not be prompted by the Agent with setup questions at the initial startup, as the setup preferences from the original Agent's installation will be found, and upgraded as needed.</para>
+ <para>
+ Restart your upgraded Jopr Servers if they are not yet started.
+ </para>
</listitem>
+
<listitem>
- <para> Verify the new Agent install. Start the Agent, open the JON GUI and make sure the Platform corresponding to the Agent and all its descendant Resources are still in inventory and have the expected Availability.</para>
+ <para>
+ If the current Jopr Agent that is to be upgraded is at version 2.2 or newer:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Download the agent update binary from the server
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Copy the agent update binary .jar file into the parent directory where your agent is installed. For example, if your agent is installed in /opt/rhq-agent-parent/rhq-agent, copy the agent update binary .jar file to the /opt/rhq-agent-parent directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Extract the new Jopr Agent from the agent update binary by running the following command:
+ </para>
+ <screen>
+ java -jar <agent-update-binary.jar> --upgrade
+ </screen>
+
+ <para>
+ This will tell the agent update binary to extract the Jopr Agent distribution and update your currently existing agent that is found in "rhq-agent" subdirectory. At this point, you will have a fully upgraded Jopr Agent located in the original "rhq-agent" directory. The old agent has been backed up to the "rhq-agent-old" directory. If the upgrade encounters errors, you'll find log files that contain log messages that can help to diagnose the problem.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the current Jopr Agent that is to be upgraded is older than version 2.2:
+
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Follow the instructions to install a Jopr Agent here: Jopr Agent Installation
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you had your own keystore and truststore files, make sure you copy them over from the old agent installation to the new agent installation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
+ If you had your own customizations to the agent script files, you will need to merge them into the new agent scripts. Note that you should no longer modify rhq-agent.bat,sh or rhq-agent-wrapper.bat,sh - instead, any environment modifications should be made to rhq-agent-env.bat,sh. This is discussed further here and here, but in short, any customizations you need to make to the agent launcher scripts should be done in rhq-agent-env.bat,sh.
+ </para>
+ </listitem>
+ </itemizedlist>
</listitem>
+
<listitem>
- <para> Once you have verified the new Agent is operational, you can delete the old Agent's installation directory.</para>
+ <para>
+ (optional) If you need to reconfigure the Jopr Agent before you restart it, read the documentation at Jopr Agent Installation that talks about configuring and reconfiguring the agent. Typically, you won't have to reconfigure the agent - the agent will pick up its previous configuration and update it as necessary.
+ </para>
</listitem>
+ <listitem>
+ <para>
+ Finally, start the Jopr Agent.
+ </para>
+ </listitem>
</orderedlist>
-
- </section>
+
+ </section>
-</section>-->
+ <!--
+ <section id="Installation_Guide-Upgrading_JON_Agents-Install_the_New_Agents">
+ <title>Install the new Agents</title>
+
+ <para>Once the JON Server has been upgraded, install the new version of JON Agent to each machine where an existing JON Agent is installed. Please upgrade each JON Agent as follows:</para>
+
+ <orderedlist>
+ <listitem>
+ <para> Make sure the old Agent is not running. Do not delete the old Agent's directory yet.</para>
+ </listitem>
+
+ <listitem>
+ <para> If you are running the Agent on Windows and installed the original Agent as a Windows service, uninstall the Windows service: </para>
+ <screen>
+ cd <old-agent-install-dir>/bin
+ ./rhq-agent-wrapper.bat remove
+ </screen>
+
+ </listitem>
+ <listitem>
+ <para> Follow the usual <xref linkend="Installation_Guide-JON_Agent_Installation"/> to install the new Agent. Note, you should not be prompted by the Agent with setup questions at the initial startup, as the setup preferences from the original Agent's installation will be found, and upgraded as needed.</para>
+ </listitem>
+ <listitem>
+ <para> Verify the new Agent install. Start the Agent, open the JON GUI and make sure the Platform corresponding to the Agent and all its descendant Resources are still in inventory and have the expected Availability.</para>
+ </listitem>
+ <listitem>
+ <para> Once you have verified the new Agent is operational, you can delete the old Agent's installation directory.</para>
+ </listitem>
+ </orderedlist>
+
+
+ </section>
+
+ </section>-->
+
+ <section id="Installation_Guide-JON_Agent_Installation_Guide-Preconfiguring_the_JON_Agent">
+ <title>Preconfiguring the JON Agent</title>
+
+ <para>
+ 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 <filename>agent-configuration.xml</filename> (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.
+ </para>
+
+ <section id="Installation_Guide-Preconfiguring_the_JON_Agent-Preparing_the_Agent_configuration">
+ <title>Preparing the Agent configuration</title>
+
+ <para>
+ 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 <filename>agent-configuration.xml</filename> and be sure to set the configuration preference <envar>rhq.agent.configuration-setup-flag</envar> to <envar>true</envar>. When this is true, the agent will assume it is fully configured and will not ask setup questions when it starts up.
+ </para>
+
+ <note>
+ <para>
+ 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 will have to 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.
+ </para>
+ </note>
+
+ <para>
+
+ You cannot set <envar>rhq.agent.configuration-setup-flag</envar> to <envar>true</envar> if the agent's fully qualified domain name cannot 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.
+ </para>
+ <para>
+ You can not set <envar>rhq.agent.configuration-setup-flag</envar> to <envar>true</envar> if the agent's default IP address is not reachable by the JBoss ON Server (or all of the servers in a JBoss ON High Availability cloud). The agent's default IP address will be the default value used for the agent public endpoint that all JBoss ON Servers will use to communicate with the agent.
+ </para>
+
+ <para>
+ The following properties found in <filename>agent-configuration.xml</filename> define the JBoss ON Server to be contacted by the JBoss ON Agent when it needs to perform its initial registration. These must be preconfigured appropriately in <filename>agent-configuration.xml</filename>:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ rhq.agent.server.transport
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rhq.agent.server.bind-address
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rhq.agent.server.bind-port
+ </para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>
+ 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:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ rhq.communications.connector.bind-port
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ 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).
+ </para>
+
+ </section>
+
+
+ <section id="Installation_Guide-Preconfiguring_the_JON_Agent-Building_the_Preconfigured_Agent_Bundle">
+ <title>Building the Preconfigured Agent Bundle</title>
+
+ <para>
+ After you have preconfigured the <filename>agent-configuration.xml</filename> 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 JBoss ON 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 JBoss ON Server has your preconfigured agent update binary, everyone who gets the agent from your JBoss ON Servers will get your preconfigured agents.
+ </para>
+ <para>
+ To preconfigure the agent update binary is conceptually very simple. You simply overwrite the default <filename>agent-configuration.xml</filename> 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:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Find the existing agent update binary jar that already exists in the JBoss ON Server. The agent update binary is the only <filename>.jar</filename> file found here: <<replaceable>server-install-dir</replaceable>>/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-agent (note that if you have not run the JBoss ON Server installer yet, the <filename>.ear</filename> directory will be named <filename>rhq.ear.rej</filename>). The agent update binary filename is usually something like <filename>rhq-enterprise-agent-#.#.#.jar</filename>. These instructions will refer to this jar file as <<filename>agent-update-binary.jar</filename>>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Use <filename>jar tf <agent-update-binary.jar></filename> to find the name of the agent distribution <filename>.zip</filename> found at the top root directory inside of the <filename>.jar</filename>. The name of this agent distribution <filename>.zip</filename> is typically the same name as the <filename>.jar</filename> itself, except it will have a <filename>.zip</filename> extension instead of <filename>.jar</filename>. For example, <filename>rhq-enterprise-agent-#.#.#.zip</filename>. These instructions will refer to this agent distribution <filename>.zip</filename> file as <<filename>agent-distro.zip</filename>>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Extract the <<filename>agent-distro.zip</filename>> by unjar'ing it from the <<filename>agent-update-binary.jar</filename>>
+
+ <screen>
+ jar xvf <agent-update-binary.jar> <agent-distro.zip>
+ </screen>
+
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you have a preconfigured <filename>agent-configuration.xml</filename>, place a copy of it under the directory <filename>rhq-agent/conf</filename> next to your <<filename>agent-distro.zip</filename>> that you just extracted. If you do not yet have your own preconfigured <filename>agent-configuration.xml</filename>, you can extract the default configuration file from the <<filename>agent-distro.zip</filename>>:
+
+ <screen>
+ jar xvf <agent-distro.zip> rhq-agent/conf/agent-configuration.xml
+ </screen>
+
+ </para>
+ <para>
+ Once you get the <filename>rhq-agent/conf/agent-configuration.xml</filename>, you can edit it appropriately with all of your desired preconfigured settings (see the previous section for more information on this).
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ Update the agent distribution <filename>.zip</filename> with your custom, preconfigured <filename>rhq-agent/conf/agent-configuration.xml</filename> file:
+
+ <screen>
+ jar uvf <agent-distro.zip> rhq-agent/conf/agent-configuration.xml
+ </screen>
+
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ Update the agent update binary <filename>.jar</filename> with your new, preconfigured agent distribution <filename>.zip</filename>:
+
+
+
+ <screen>
+ jar uvf <agent-update-binary.jar> <agent-distro.zip>
+ </screen>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Make sure your new, preconfigured <<filename>agent-update-binary.jar</filename>> is copied into <<replaceable>server-install-dir</replaceable>><filename>/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-agent</filename> (overwriting the old agent update binary that used to be there) and make sure it is the only <filename>.jar</filename> file found in that directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If one exists, delete any existing <filename>*.properties</filename> file you find in the JBoss ON Server at <<replaceable>server-install-dir</replaceable>><filename>/jbossas/server/default/deploy/rhq.ear/rhq-downloads/rhq-agent</filename>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you have more than one JBoss ON Server in your JBoss ON Server cloud, make sure you distribute your <<filename>agent-update-binary.jar</filename>> to all of your JBoss ON Servers - placing it in the same <filename>rhq-downloads/rhq-agent</filename> subdirectory as mentioned above.
+ </para>
+ </listitem>
+
+
+ </orderedlist>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ </section>
+ </section>
+
+
+
+
</chapter>
-
+
More information about the jopr-commits
mailing list