[jopr-commits] JOPR SVN: r1139 - docs/enterprise/JON/2.3/FAQ/en-US.
jopr-commits at lists.jboss.org
jopr-commits at lists.jboss.org
Wed Sep 2 01:12:25 EDT 2009
Author: smeehan
Date: 2009-09-02 01:12:25 -0400 (Wed, 02 Sep 2009)
New Revision: 1139
Modified:
docs/enterprise/JON/2.3/FAQ/en-US/Book_Info.xml
docs/enterprise/JON/2.3/FAQ/en-US/Chapter.xml
Log:
Updated FAQs chapter with new sections contained within jopr wiki
Modified: docs/enterprise/JON/2.3/FAQ/en-US/Book_Info.xml
===================================================================
--- docs/enterprise/JON/2.3/FAQ/en-US/Book_Info.xml 2009-09-01 22:59:07 UTC (rev 1138)
+++ docs/enterprise/JON/2.3/FAQ/en-US/Book_Info.xml 2009-09-02 05:12:25 UTC (rev 1139)
@@ -8,7 +8,7 @@
<productname>JBoss Operations Network</productname>
<productnumber>2.3</productnumber>
<edition>1</edition>
- <pubsnumber>5</pubsnumber>
+ <pubsnumber>6</pubsnumber>
<abstract>
<para>Frequently Asked Questions for JBoss Operations Network</para>
</abstract>
Modified: docs/enterprise/JON/2.3/FAQ/en-US/Chapter.xml
===================================================================
--- docs/enterprise/JON/2.3/FAQ/en-US/Chapter.xml 2009-09-01 22:59:07 UTC (rev 1138)
+++ docs/enterprise/JON/2.3/FAQ/en-US/Chapter.xml 2009-09-02 05:12:25 UTC (rev 1139)
@@ -74,9 +74,61 @@
<title>Is XXX database supported?</title>
<para>
- No. PostgreSQL and Oracle are the only supported databases. There are currently no plans to add support for additional databases.
+ No. PostgreSQL, versions 8.2.4 and later, and Oracle 10g are the only supported databases. There are currently no plans to add support for additional databases.
</para>
</section>
+
+ <section id="sect-FAQs-General-What_is_the_syntax_for_regular_expressions_used_within_JON">
+ <title>What is the syntax for regular expressions used within JON?</title>
+
+ <para>
+ JON uses regular expressions in several places. When you encounter a place (user interface, configuration file, etc) that requires you to enter a regular expression, consult Java's javadoc documentation for the syntax rules. Below are the Javadocs for regular expression syntax and date/time syntax for Java5 and Java6:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Java 5:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">regex syntax</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html">date/time format syntax</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>Java 6:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html">regex syntax</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://java.sun.com/javase/6/docs/api/java/text/SimpleDateFormat.html">date/time format syntax</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+
+
+ </section>
</section>
@@ -395,8 +447,130 @@
This is not Jopr specific - its JBoss/Remoting failing. See: <ulink url="http://jira.jboss.org/jira/browse/JBREM-769">http://jira.jboss.org/jira/browse/JBREM-769</ulink>. The core issue (that is hidden from you, because JBoss/Remoting isn't bubbling up the real error message, as per that JIRA) is typically because your hostname is not resolvable. Make sure your hostname (as reported to you in that exception message, e.g. "my.host.name.com" is a valid hostname and make sure it is resolvable by your machine (i.e. is it in /etc/hosts?? can you get an IP for it via nslookup??)
</para>
</section>
+
+
+
+ <section id="sect-FAQs-Server-My_Server_logs_are_showing">
+ <title>My server logs are showing the message "Have not heard from agent ... Will be backfilled since we suspect it is down". What does that mean?</title>
+
+ <para>
+ When you see the following:
+ </para>
+
+<screen>
+[org.rhq.enterprise.server.core.AgentManagerBean] Have not heard from agent [<some agent name>]
+since [<some date/time>]. Will be backfilled since we suspect it is down
+</screen>
+
+<para>
+ This means that the agent did not send its availability report in the required amount of time (which is 2 minutes by default by is configurable in the <application>Administration</application> > <application>SystemConfiguration</application> > <application>Settings</application> page). When this happens, the server gets worried and suspects that agent is down - at which time it "backfills" the availability of ALL resources managed by that agent to DOWN (you will see the availabilities turn RED).
+</para>
+
+<para>
+ This can happen for a number of reasons:
+</para>
+
+<orderedlist>
+ <listitem>
+ <para>
+ The agent really did shutdown or crash.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The machine the agent is running on completely shutdown or crashed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The network between the agent and server went down, thus prohibiting the agent from connecting to the server and sending the availability report.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The machine the agent is running on is bogged down thus slowing up the agent and prohibiting the agent from being able to send up reports fast enough.
+ </para>
+ </listitem>
+
+</orderedlist>
+
+
</section>
+<section id="sect-FAQs-Server-Ports_Firewall">
+ <title>What ports do I have to be concerned about when setting up a firewall between servers and agents?</title>
+
+
+<note>
+ <title>
+ Note
+ </title>
+ <para>
+ The following refers to out-of-box defaults. If you configured your JON Servers or JON Agents to use different ports than their out-of-box defaults, you will have to use your custom port numbers.
+ </para>
+</note>
+
+<para>
+
+ The agent is configured to talk to one or more JBoss ON Server endpoints. Each JBoss ON Server endpoint includes the port. This port is typically over 7080 (non-secure) or 7443 (SSL-secured). So, when the agent starts up, it will try to communicate to a JBoss ON Server over one of those two ports (an agent will only need to go over one of those ports to talk to a single Jboss ON Server - it depends on the transport used). If your server expects to be communicated to via the "servlet" transport, that is unsecured over 7080 by default; if it uses "sslservlet" transport, that is ssh-secured and is over 7443 by default.
+</para>
+
+ <para>
+ That is the only port from agent to server.
+ </para>
+
+ <para>
+ When the server needs to talk to the agent, the server talks over the bind port that the agent was configured for. Out of box, that is 16163 (and that can be the same port whether the server talks to the agent over the socket or sslsocket transport - in other words, it doesn't matter if its secured or not, by default out of box its port is 16163).
+ </para>
+
+ <para>
+ That is the only port from server to agent.
+ </para>
+
+ <para>
+ Of course, the server needs to talk to its database too - so make sure any ports that your database requires to be open are actually open to the server - otherwise, the server will not be able to talk to the database.
+ </para>
+
+
+ <note>
+ <title>
+ Note
+ </title>
+ <para>
+ Servers do not talk to one another directly - there are no ports required for server-to-server links because there is no communication like that going on.
+ </para>
+</note>
+
+ <para>
+ So in summary:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ server -> agent : port 16163
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ agent -> server : port 7080 (unsecure) OR 7443 (secure)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ server -> database : specific to your database and its configuration
+ </para>
+ </listitem>
+ </itemizedlist>
+
+
+ </section>
+</section>
+
<section id="sect-FAQs-Chapter-Agent">
<title>Agent</title>
@@ -591,9 +765,72 @@
</para>
</section>
+
+ <section id="sect-FAQs-Agent-Explain_how_the_agent_scans_for_resources">
+ <title>Explain how the agent scans for resources</title>
+
+
+<para>
+ A <emphasis role="bold">server scan</emphasis> detects top-level servers that run on your platform - things like JBossAS servers, Postgres databases and the like. These scans run by default every 15 minutes. The setting that controls this is "rhq.agent.plugins.server-discovery.period-secs".
+
+</para>
+
+<para>
+ A <emphasis role="bold">service scan</emphasis> detects lower-level and more fine-grained services that are running in already detected and imported top-level servers. Things like EJBs running in JBossAS, tables in a Postgres database or VHosts in Apache. These scans run by default every 24 hours (i.e. 1 day). You must have already imported the servers in inventory before services can be discovered! These types of scans are normally very "expensive" to perform since they do probing inside the managed resource, so we don't do it often (which is why its defaulted to 24 hours). The setting that controls this is <emphasis role="bold">rhq.agent.plugins.service-discovery.period-secs</emphasis>.
+
+</para>
+
</section>
-
+<section id="sect-FAQs-Agent-Persisted_Configuration">
+ <title>How can I see the agent persisted configuration?</title>
+
+<para>
+ The agent's configuration is initially read from agent-configuration.xml and overlaid with values you enter at the setup prompts at startup. After the agent is initially configured, it will persist that configuration and never look at agent-configuration.xml (unless you clear the configuration). For more details, read the comments at the top of the agent-configuration.xml file. Please see the <emphasis>Installation Guide</emphasis> for more information.
+</para>
+
+<para>
+ There are several ways in which you can view the agent's persisted configuration.
+</para>
+
+<orderedlist>
+ <listitem>
+ <para>
+ If the agent is in your JON inventory, simply go to your agent's <application>Configuration</application> tab to view its live configuration (this is the same configuration that is persisted).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the agent is currently running in non-daemon mode (i.e. you have the agent prompt on your console), you can use the "getconfig" or "config" prompt commands to view the live configuration. Type "help getconfig" or "help config" for more information.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the agent is in your JON inventory, you can execute the "Execute Prompt Command" operation and invoke the "getconfig" prompt command to view one or more preferences.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Because the agent configuration is stored in the standard <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/preferences/index.html">Java Preferences API</ulink> backing store, you can use any tool that can examine Java Preferences. One such tool is the <ulink url="http://javaprefs.googlepages.com/">Java Preferences Tool</ulink>. This is a GUI tool that can give you a "file system" like view into your Java Preferences. The agent preferences are stored in the "User" preferences node under the node name "rhq-agent". Depending on the -p option that is passed to the agent when it is started, the actual configuration settings are found under a sub-node under "rhq-agent". The default preferences node is called "default" so typically your agent's persisted configuration is found in the user preferences under "rhq-agent/default".
+ </para>
+ </listitem>
+</orderedlist>
+
+
+<warning>
+ <title>
+ Warning
+ </title>
+ <para>
+ Do not attempt to change the values of the preferences using third-party tools like this without knowing what you are doing - you could render the agent useless if you change the wrong preference to the wrong value. Use this mechanism only to view your agent's configuration
+ </para>
+</warning>
+
+
+
+</section>
+</section>
+
<section id="sect-FAQs-Chapter-Log_Messages">
<title>Log Messages</title>
@@ -651,6 +888,7 @@
<title>Plugins</title>
+
<section id="sect-FAQs-Plugins-JBossAS_Plugin">
<title>JBossAS Plugin</title>
@@ -752,6 +990,32 @@
</section>
</section>
+
+ <section id="sect-FAQs-Plugins-Augeas_based_Plugins">
+ <title>Augeas-based Plugins</title>
+
+
+ <section id="sect-FAQs-Apache_Plugin-What_is_Augeas">
+ <title>What is the augeas plugin?</title>
+
+ <para>
+ The augeas plugin is an "abstract" plugin that exists solely as an extension point for other plugins to extend. The augeas plugin provides the Java JNI classes necessary for other dependent plugins to use to access the Augeas native library. For example, the opensshd plugin depends on the augeas plugin because it uses the Augeas library to access the OpenSSH daemon configuration. The other JBoss ON plugins known to use this augeas plugin are: hosts, grub and apt.
+ </para>
+
+ </section>
+
+ <section id="sect-FAQs-Apache_Plugin-Agent_log">
+ <title>Why does my agent log have this in it: "java.lang.UnsatisfiedLinkError: Unable to load library 'augeas': libaugeas.so: cannot open shared object file: No such file or directory"</title>
+
+ <para>
+ This occurs when you have deployed one or more augeas-based plugins but your Linux machine does not have the augeas native library installed. See <ulink url="http://augeas.net/">http://augeas.net</ulink> for more information on Augeas and how you can install it on your machine.
+ </para>
+
+ </section>
+ </section>
+
+
+
<section id="sect-FAQs-Plugins-Extend_JON">
<title>How can I extend JON?</title>
@@ -957,6 +1221,124 @@
Note: With JON 2.0.0 and 2.0.1 if the system property com.sun.management.jmxremote is also specified this will <emphasis role="bold">prevent</emphasis> the JVM resources being discovered by JON. Removing this property will allow those resources to be found. In JON 2.0.1 this restriction is lifted and even if the system property com.sun.management.jmxremote is specified JVM resources should still be added to the JON inventory.
</para>
</section>
+
+ <section id="sect-FAQs-Troubleshooting-debug_JDBC">
+ <title>How can I debug JDBC access and trace SQL?</title>
+
+<para>
+
+ Use <ulink url="http://code.google.com/p/log4jdbc/">log4jdbc</ulink>.
+</para>
+
+</section>
+
+
+<section id="sect-FAQs-Troubleshooting-stop_agent">
+ <title>How can I stop my agent from thinking the server keeps going up and down when the server has remained running the whole time?</title>
+
+<para>
+ If you see information like this in your agent logs:
+</para>
+
+<screen>
+INFO (org.rhq.enterprise.agent.AgentAutoDiscoveryListener)- {AgentAutoDiscoveryListener.server-offline}
+The Agent has auto-detected the Server going offline [InvokerLocator
+[servlet://server:7080/jboss-remoting-servlet-invoker
+/ServerInvokerServlet?rhq.communications.connector.rhqtype=server]] -
+the agent will stop sending new messages
+...
+INFO (org.rhq.enterprise.agent.AgentAutoDiscoveryListener)- {AgentAutoDiscoveryListener.server-online}
+The Agent has auto-detected the Server coming online [InvokerLocator
+[servlet://server:7080/jboss-remoting-servlet-invoker
+/ServerInvokerServlet?rhq.communications.connector.rhqtype=server]] -
+the agent will be able to start sending messages now
+</screen>
+
+<para>
+This means the agent has auto-detected its server going down and back up. This auto-detection was done through the multicast detector (it is different than the detection-via-polling, which is the second way the agent attempts to detect the server's status).
+</para>
+
+<para>
+ If you think the agent is erroneously detecting the server going up or down, it is possible your network does not support multicast traffic or the multicast network is acting abnormally. In either case, you should disable the agent multicast detector and just have the agent rely on polling to detect changes in the server status. To turn off the multicast detection, set the following agent preferences to false:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+ rhq.agent.server-auto-detection
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ rhq.communications.multicast-detector.enabled
+ </para>
+ </listitem>
+</itemizedlist>
+
+
+<para>
+ Those are the actual Java Preference names; you may often see these in the user interface as the following:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+ Auto-Detect RHQ Server?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Multicast Detector Enabled?
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+ Since you are disabling multicast detection, make sure you keep the polling detection feature enabled (i.e. rhq.agent.client.server-polling-interval-msecs should be larger than 0, typically 60000), otherwise, the agent will never be able to know when the server goes down.
+</para>
+
+<para>
+ Once you reconfigure the agent, you need to restart it so the communications subsystem can pick up the changes.
+</para>
+
+
+ </section>
+
+ <section id="sect-FAQs-Troubleshooting-Agent_fails_to_start">
+ <title>My Agent fails to start with "[: 207: ==: unexpected operator"</title>
+
+ <para>
+ This is a known bug in JBoss ON 2.2. There is a syntax error in rhq-agent.sh that causes the script to fail when executed by non-bash shells (e.g. /bin/sh on Solaris, HP-UX, or AIX). To fix the issue, edit rhq-agent.sh and change the "==" on line 207 to "=".
+ </para>
+
+</section>
+
+<section id="sect-FAQs-Troubleshooting-graphs_and_charts">
+ <title>Why are the graphs and charts on the Monitor tab in the GUI not displayed?</title>
+
+
+ <para>
+ If you see errors in the JBoss ON Server log such as:
+ </para>
+
+<screen>
+java.lang.NoClassDefFoundError: Could not initialize class org.rhq.enterprise.gui.image.chart.ColumnChart
+</screen>
+
+<para>
+It is probably because you are missing some system fonts needed by Java to generate the text in the graphs/charts. If you are on Linux, make sure you have the urw-fonts package installed. On Fedora or RHEL, use:
+</para>
+
+<screen>
+yum install urw-fonts
+</screen>
+
+
+<para>
+ If you are on another OS, make sure you have all the default fonts installed.
+</para>
+
+</section>
</section>
<section id="sect-FAQs-Chapter-JON_1_._x">
More information about the jopr-commits
mailing list